Python-by-example - new online guide to Python Standard Library

[AK]

Hello,

I find that I learn easier when I go from specific examples to a more
general explanation of function's utility and I made a reference guide
that will eventually document all functions, classes and methods in
Python's Standard Library. For now, I covered about 20 most important
modules. I will be adding more modules and eventually I'll cover
everything. Here's my progress so far, let me know if this is useful;
I'll be glad to hear comments/suggestions/etc:

http://www.lightbird.net/py-by-example/

--
-ak
Tobu | http://www.lightbird.net/tobu/ | Freeform DB / Tagger / PIM

[GHUM]

Tobu,

I like this idea. Deducting from an example is really another way to
wisdom.

What struck me as most diffuclt to understand:

abs(-5.5) - 5.5

-> you are using "-" as symbol for "will give the result", which is
really, really hard to parse. Take something else, please. Unicode has
THAT many cool symbols. Or just -> or -=> or whatever.

Thanks for sharing that work!

Harald

[tatu....@gmail.com]

Or just use comments to indicate text that tells what the code does.

I too agree you need to change the '-'.

[sjf]

Indeed, the first thing I saw on the front page was "math.sqrt(9) -
3.0". Ok, I thought, random arithmetic expression, so what?
There is already a standard way of showing a piece of code and its
results. It's the interactive prompt:

>>> import math
>>> math.sqrt(9)
3.0
>>>

Tada!

[Panzerlurch]

Why don't use the normal Python shell syntax as used by doctest?

>>> abs(-5.5)
5.5

That would be much more readable.

[ajaksu]

On Apr 1, 10:15 pm, AK <andrei....@gmail.com> wrote:
> Hello,
Hiya

> I find that I learn easier when I go from specific examples to a more
> general explanation of function's utility and I made a reference guide
> that will eventually document all functions, classes and methods in
> Python's Standard Library.

Thanks a lot, this is a great resource.

> For now, I covered about 20 most important
> modules. I will be adding more modules and eventually I'll cover
> everything. Here's my progress so far, let me know if this is useful;
> I'll be glad to hear comments/suggestions/etc:
>
> http://www.lightbird.net/py-by-example/
>

Content is nice, presentation can be tweaked towards making examples
easier to understand and run on the interactive console. I suggest
taking a look at PyMOTW[1] and Crunchy[2][3] for nice ideas.

Best regards,
Daniel

[1] http://www.doughellmann.com/projects/PyMOTW/
[2] http://code.google.com/p/crunchy/
[3] http://us.pycon.org/2008/conference/schedule/event/46/

[Terry Reedy]

"AK" <andre...@gmail.com> wrote in message
news:47f2d018$0$6517$4c36...@roadrunner.com...

|| I'll be glad to hear comments/suggestions/etc:
|
| http://www.lightbird.net/py-by-example/

Using - as the example/return delimiter does not work.
If you do not want to substantially lengthen the document by going to

>>> sqrt(9)
3

then use Python's a comment symbol.

sqrt(9) # 3
-or-
sqrt(9) # returns 3 (but I think I prefer the first)

which clearly is not an arithmetic expression and which can be
cut-and-pasted into the interactive interpreter. This also works nicely
for invalid examples.

sqrt(-9) # raises ValueError

Terry Jan Reedy

[AK]

Thanks to everybody who replied, I will implement the change as per
Terry's advice. I'm still considering whether to use the standard
interpreter syntax, i.e. >>> ... \n result; my reason for not doing that
is that I will often have a whole screen of function / result lines and
if I were to add a new line for the result, that'd make two pages out of
one, which I think is a bit too much. In current docs there are not so
many examples, so that space is not multiplied quite so much, and using
interactive interpreter way of showing result is not nearly as much of
a problem. However, I'm still thinking this over and it seems that
almost everyone wants to see it done in that way, I might still go for
two lines. I'll also be posting updates as the work progresses..

thx,

--
-ak
Tobu | http://www.lightbird.net/tobu/ | Freeform DB / Tagger / PIM

Python-by-Example | http://www.lightbird.net/py-by-example/ | Guide
to LibRef

[CM]

On Apr 2, 2:50 pm, AK <andrei....@gmail.com> wrote:
> Terry Reedy wrote:
> > "AK" <andrei....@gmail.com> wrote in message

You should also change the look of the page to be more high-contrast.
The grayish text in a gray box and the light green text...all too
subtle to see. Not easy for well-sighted people let alone those with
poorer vision. Try make things visually very obvious, bolded headers,
etc. If so, and with the change of showing the result not with an "-"
symbol, it will be much stronger. Thank you for doing it.

[AK]

Okay, will do. In fact this is the second time in as many days that I
get a comment on my proposed designs to use more contrasted text vs.
background (in fact, for the other design about 3-4 people mentioned
this topic). I really had no idea many people have trouble with that. To
me, less contrasted text looks smoother and more aesthetically pleasing
to the eye, unless I have to read 3 pages or more of condensed text. I
also do eye excercises religiously every day:-), so this may train the
eyes to see small details better, but I design for other people to use,
therefore I will of course try to make it as easy to read for as many
people as possible.. Thanks for the comment! I will update the site
tomorrow morning with all the changes..

[AK]

AK wrote:
> Hello,
>
> I find that I learn easier when I go from specific examples to a more
> general explanation of function's utility and I made a reference guide
> that will eventually document all functions, classes and methods in
> Python's Standard Library. For now, I covered about 20 most important
> modules. I will be adding more modules and eventually I'll cover
> everything. Here's my progress so far, let me know if this is useful;
> I'll be glad to hear comments/suggestions/etc:
>
> http://www.lightbird.net/py-by-example/
>

I uploaded an updated site incorporating most of the suggestions I
received and fixing some errors along the way. I will be adding more
examples to modules that are already covered and will try to add more
modules during the following week. Thanks again to all who posted advice
and comments!

--
-ak
Tobu | http://www.lightbird.net/tobu/ | Freeform DB / Tagger / PIM

[AK]

AK wrote:
>
> I uploaded an updated site incorporating most of the suggestions I
> received and fixing some errors along the way. I will be adding more
> examples to modules that are already covered and will try to add more
> modules during the following week. Thanks again to all who posted advice
> and comments!
>

I also mapped the site to a subdomain so that it's easier to access
quickly: http://pbe.lightbird.net/ where 'pbe' stands for
'Python-by-Example'.

--
-ak
Tobu | http://tobu.lightbird.net/ | Freeform DB / Tagger / PIM
Python-by-Example | http://pbe.lightbird.net/ | Guide to LibRef

[Giampaolo Rodola']

Great idea!
Thanks a lot for you work.

--- Giampaolo
http://code.google.com/p/pyftpdlib

[shurik]

that's great! thanks for putting this together. what about the inspect
module? and particularly getsource :)

[AK]

shurik wrote:
> that's great! thanks for putting this together. what about the inspect
> module? and particularly getsource :)
>

Glad you like it! I will add every module eventually, but I'll put
inspect up on top of todo list.

[ivan]

Very cool.
Have you thought about making a printable version that doesn't wrap
any lines that shouldn't be and has page breaks at good spots?

--
ivan

[AK]

Hi ivan, I will work on that after I finalize modules that are already
there. I think this would be better than having people print out the
guide and then either have print out again in a couple of weeks or stuck
with using a very outdated guide. So, I think it will be one to three
weeks at most before printable version is available..

Glad you like Python by Example!

thx,

[Gerard Flanagan]

On Apr 3, 8:33 pm, AK <andrei....@gmail.com> wrote:
> AK wrote:
> > Hello,
>
> > I find that I learn easier when I go from specific examples to a more
> > general explanation of function's utility and I made a reference guide
> > that will eventually document all functions, classes and methods in
> > Python's Standard Library. For now, I covered about 20 most important
> > modules. I will be adding more modules and eventually I'll cover
> > everything. Here's my progress so far, let me know if this is useful;
> > I'll be glad to hear comments/suggestions/etc:
>
> >http://www.lightbird.net/py-by-example/
>
> I uploaded an updated site incorporating most of the suggestions I
> received and fixing some errors along the way. I will be adding more
> examples to modules that are already covered and will try to add more
> modules during the following week. Thanks again to all who posted advice
> and comments!
>

I don't know if you've heard of Sphinx, it's being used to generate
the Python 2.6 docs but can also be used standalone. It may have
benefits for a project like yours, particularly with regard to
collaboration and maintainability over the long-term. I've been
playing about with it myself and put together a `very` basic site
using a few of the pages from your site:

The generated html is here:

http://gflanagan.net/site/python/pbe/pbe-sphinx-skeleton-build-0.1.tar.gz
http://gflanagan.net/site/python/pbe/pbe-sphinx-skeleton-build-0.1.zip

And the actual Sphinx 'app':

http://gflanagan.net/site/python/pbe/pbe-sphinx-skeleton-0.1.tar.gz
http://gflanagan.net/site/python/pbe/pbe-sphinx-skeleton-0.1.zip

For which you would need Sphinx (obviously): http://sphinx.pocoo.org/
which depends on docutils: http://docutils.sourceforge.net/
and pygments: http://pygments.org/

There's a make.bat for windows and a MakeFile for unix but the latter
is untested.

I've no time to spend on it further, but you're welcome to what's
there if you've any interest. (I repeat, it's just a proof of concept
- don't expect too much.)

As you might see, I preferred 'doctest' style code rather than the
commented results, but each to their own.

Sphinx uses ReST as its input format - below is what I cooked up for
'restifying' your html, not perfect but a brave attempt!

All the best.

Gerard

------------------------------------------------------------------

import textwrap
import re
import os
from BeautifulSoup import BeautifulSoup

def onmatch(m):
return '\nRESULT' + m.group(2)

result = re.compile('<span class="result">(# )?(.*?)</span>',
re.DOTALL | re.MULTILINE)
src = 'c:/workspace/pbe/orig/'

for infile in os.listdir(src):
if not infile.endswith('-module.html'):
continue
title = infile[:-5]
infile = src + infile
outfile = infile[:-4] + 'rst'
out = open(outfile, 'wb')
out.write(title + '\n')
out.write('='*len(title) + '\n\n')

soup = BeautifulSoup(open(infile).read())

for p in soup.findAll('ul'):
print >> out
for line in textwrap.wrap(p.span.contents[0], 79):
print >> out, line.lstrip()
#code = ''.join(comment.sub(onmatch, str(p.pre)))
code = result.sub(onmatch, str(p.pre)).splitlines()[1:-1]
if code:
print >> out
print >> out, '::'
print >> out
for line in code:
line = line.strip()
if line:
leader = ' '
if line.startswith('RESULT'):
line = line[len('RESULT'):]
else:
leader += '>>> '
print >> out, leader + line
else:
print >> out
print >> out

out.close()
------------------------------------------------------------------