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

[Raymond Hettinger]

I'm adding section to the tutorial with a brief sampling of library
offerings and some short examples of how to use them.

My first draft included:
    copy, glob, shelve, pickle, os, re, math/cmath, urllib, smtplib

Guido's thoughts:
- copy tends to be overused by beginners
- the shelve module has pitfalls for new users
- cmath is rarely needed and some folks are scared of complex numbers
- urllib2 is be a better choice than urllib

I'm interested to know what your experiences have been with teaching
python.  Which modules are necessary to start doing real work (like
pickle and os), which are most easily grasped (like glob or random),
which have impressive examples only a few lines long (i.e. urllib), and
which might just be fun (turtle would be a candidate if it didn't have a
Tk dependency).

Note, re was included because everyone should know it's there and
everyone should get advice to not use it when string methods will
suffice.

I'm especially interested in thoughts on whether shelve should be
included.  When I first started out, I was very impressed with shelves
because they were the simplest way to add a form of persistence and
because they could be dropped in place of a dictionary in scripts that
were already built.  Also, it was trivially easy to learn based on
existing knowledge of dictionaries.  OTOH, that existing knowledge is
what makes the pitfalls so surprising.

Likewise, I was impressed with the substitutability of line lists, text
splits, file.readlines(), and urlopen().

While I think of copy() and deepcopy() as builtins that got tucked away
in module, Guido is right about their rarity in well-crafted code.

Some other candidates (let's pick just a two or three):

- csv (basic tool for sharing data with other applications)
- datetime (comes up frequently in real apps and admin tasks)
- ftplib (because the examples are so brief)
- getopt or optparse (because the task is common)
- operator (because otherwise, the functionals can be a PITA)
- pprint (because beauty counts)
- struct (because fixed record layouts are common)
- threading/Queue (because without direction people grab thread and
mutexes)
- timeit (because it answers most performance questions in a jiffy)
- unittest (because TDD folks like myself live by it)

I've avoided XML because it is a can of worms and because short examples
don't do it justice.  OTOH, it *is* the hot topic of the day and seems
to be taking over the world one angle bracket at a time.

Ideally, the new section should be relatively short but leave a reader
with a reasonable foundation for crafting non-toy scripts.  A secondary
goal is to show-off the included batteries -- I think it is common for
someone to download several languages and choose between them based on
their tutorial experiences (so, a little flash and sizzle might be
warranted).


Raymond