[Python-Dev] Tutorial: Brief Introduction to the Standard Libary

[Edward Loper]

> Attached is a revised draft.  Comments, suggestions, nitpicks,
> complaints, and accolades are welcome.

General comments:
   - Overall, it looks very good. :)
   - Since your descriptions are so brief, you should probably provide
     links to the reference documentation for each module/function that
     you reference.
   - You might also want to mention pydoc.  Not only is it a very useful
     module for beginners in its own right, but it would give them a way
     to learn more about the other modules that you describe.

> >>>import os
> >>>os.system('copy /data/mydata.fil /backup/mydata.fil')
> 0
> 
> >>>os.getcwd() 
> 'C:\\Python24'
> 
> >>>os.chdir('/server/accesslogs')

You might want to add short "#" comments for these, saying what they do. 
  (Some novices won't recognize what system() is doing; and not everyone 
immediately associates cwd with current working directory.)  Nothing 
fancy, just something like:

   >>> os.getcwd()    # Return the current working directory

> Be sure to use the "import os" style instead of "from os import *".  
> This will keep os.open() from shadowing __builtin__.open()  which 
> operates much differently.

This sentence would be more accessible to beginners if you said "from 
shadowing the builtin open() function, which operates much differently."

>>>>optlist, args = getopt.getopt(sys.argv[1:], 'abc:d:')

It might be worth including an option that doesn't get used, just to 
show that they're optional.

> because they are easier to read and debug.  For more sophisticated applications,

I would replace s/For/But for/

> >>>import urllib

That should be "import urllib2"

> For example, it may be tempting to use the tuple packing and unpacking feature
> instead of the traditional approach to swapping arguments.  The timeit module
> quickly demonstrates that the traditional approach is faster:

I think that you should add a caveat here. Something along the lines of 
"But the tuple method is much easier to read, and not much faster, so 
unless it's in a really tight loop where speed is critical, you should 
use the tuple method."

> In contrast to timeit's fine level of granularity, the profile and pstats modules
> provide tools for identifying time critical sections of larger blocks of code.

I think it's worth noting that profile & pstats are generally much more 
useful for optimizing code than timeit is.  (That fact might not be 
obvious to beginners.)

> Batteries Included
> 
> Python has a "batteries included" philosophy.  The is best seen through the
> sophisticated and robust capabilites of its larger packages:

s/packages:/packages, including:/

Also, I'm not sure if the meaning of "batteries included" will be 
obvious to people who haven't seen the term before.  Perhaps you could 
steal some text from PEP 206; so something like:

   Python has a "batteries included" philosophy -- it includes
   a rich and versatile standard library which is immediately available,
   without making the user download separate packages.  The is best seen
   through the sophisticated and robust capabilites of its larger
   packages, including:

-Edward