Python Documentation Sources

As we’ve learned, hash-mark comments are the most basic way to document your code. Python simply ignores all the text following a # (as long as it’s not inside a string literal), so you can follow this character with any words and descriptions meaningful to programmers. Such comments are accessible only in your source files, though; to code comments that are more widely available, you’ll need to use docstrings.

In fact, current best practice generally dictates that docstrings are best for larger functional documentation (e.g., “my file does this”), and # comments are best limited to smaller code documentation (e.g., “this strange expression does that”) and are best limited in scope to a statement or small group of statements within a script or function. More on docstrings in a moment; first, let’s see how to explore objects.

As we’ve also seen, the built-in dir function is an easy way to grab a list of all the attributes available inside an object (i.e., its methods and simpler data items). It can be called with no arguments to list variables in the caller’s scope. More usefully, it can also be called on any object that has attributes, including imported modules and built-in types, as well as the name of a data type. For example, to find out what’s available in a module such as the standard library’s sys, import it and pass it to dir:

>>> import sys
>>> dir(sys)
['__displayhook__', ...more names omitted..., 'winver']

These results are from Python 3.3, and I’m omitting most returned names because they vary slightly elsewhere; run this on your own for a better look. In fact, there are currently 78 attributes in sys, though we generally care only about the 69 that do not have leading double underscores (two usually means interpreter-related) or the 62 that have no leading underscore at all (one underscore usually means informal implementation private)—a prime example of the preceding chapter’s list comprehension at work:

>>> len(dir(sys))                                             # Number names in sys
78
>>> len([x for x in dir(sys) if not x.startswith('__')])      # Non __X names only
69
>>> len([x for x in dir(sys) if not x[0] == '_'])             # Non underscore names
62

To find out what attributes are provided in objects of built-in types, run dir on a literal or an existing instance of the desired type. For example, to see list and string attributes, you can pass empty objects:

>>> dir([])
['__add__', '__class__', '__contains__', ...more..., 'append', 'clear', 'copy',
'count', 'extend', 'index', 'insert', 'pop', 'remove', 'reverse', 'sort']

>>> dir('')
['__add__', '__class__', '__contains__', ...more..., 'split', 'splitlines',
'startswith','strip', 'swapcase', 'title', 'translate', 'upper', 'zfill']

The dir results for any built-in type include a set of attributes that are related to the implementation of that type (technically, operator overloading methods); much as in modules they all begin and end with double underscores to make them distinct, and you can safely ignore them at this point in the book (they are used for OOP). For instance, there are 45 list attributes, but only 11 that correspond to named methods:

>>> len(dir([])), len([x for x in dir([]) if not x.startswith('__')])
(45, 11)
>>> len(dir('')), len([x for x in dir('') if not x.startswith('__')])
(76, 44)

In fact, to filter out double-underscored items that are not of common program interest, run the same list comprehensions but print the attributes. For instance, here are the named attributes in lists and dictionaries in Python 3.3:

>>> [a for a in dir(list) if not a.startswith('__')]
['append', 'clear', 'copy', 'count', 'extend', 'index', 'insert', 'pop',
'remove', 'reverse', 'sort']

>>> [a for a in dir(dict) if not a.startswith('__')]
['clear', 'copy', 'fromkeys', 'get', 'items', 'keys', 'pop', 'popitem',
'setdefault', 'update', 'values']

This may seem like a lot to type to get an attribute list, but beginning in the next chapter we’ll learn how to wrap such code in an importable and reusable function so we don’t need to type it again:

>>> def dir1(x): return [a for a in dir(x) if not a.startswith('__')]  # See Part IV
...
>>> dir1(tuple)
['count', 'index']

Notice that you can list built-in type attributes by passing a type name to dir instead of a literal:

>>> dir(str) == dir('')           # Same result, type name or literal
True
>>> dir(list) == dir([])
True

This works because names like str and list that were once type converter functions are actually names of types in Python today; calling one of these invokes its constructor to generate an instance of that type. Part VI will have more to say about constructors and operator overloading methods when we discuss classes.

The dir function serves as a sort of memory-jogger—it provides a list of attribute names, but it does not tell you anything about what those names mean. For such extra information, we need to move on to the next documentation source.

Besides # comments, Python supports documentation that is automatically attached to objects and retained at runtime for inspection. Syntactically, such comments are coded as strings at the tops of module files and function and class statements, before any other executable code (# comments, including Unix-stye #! lines are OK before them). Python automatically stuffs the text of these strings, known informally as docstrings, into the __doc__ attributes of the corresponding objects.

"""
Module documentation
Words Go Here
"""

spam = 40

def square(x):
    """
    function documentation
    can we have your liver then?
    """
    return x ** 2          # square

class Employee:
    "class documentation"
    pass

print(square(4))
print(square.__doc__)

>>> import docstrings
16

    function documentation
    can we have your liver then?

>>> print(docstrings.__doc__)

Module documentation
Words Go Here

>>> print(docstrings.square.__doc__)

    function documentation
    can we have your liver then?

>>> print(docstrings.Employee.__doc__)
    class documentation

>>> import sys
>>> print(sys.__doc__)
This module provides access to some objects used or maintained by the
interpreter and to functions that interact strongly with the interpreter.

Dynamic objects:

argv -- command line arguments; argv[0] is the script pathname if known
path -- module search path; path[0] is the script directory, else ''
modules -- dictionary of loaded modules
...more text omitted...

>>> print(sys.getrefcount.__doc__)
getrefcount(object) -> integer

Return the reference count of object.  The count returned is generally
one higher than you might expect, because it includes the (temporary)
reference as an argument to getrefcount().

>>> print(int.__doc__)
int(x[, base]) -> integer

Convert a string or number to an integer, if possible.  A floating
point argument will be truncated towards zero (this does not include a
...more text omitted...

>>> print(map.__doc__)
map(func, *iterables) --> map object

Make an iterator that computes the function using arguments from
each of the iterables.  Stops when the shortest iterable is exhausted.

The docstring technique proved to be so useful that Python eventually added a tool that makes docstrings even easier to display. The standard PyDoc tool is Python code that knows how to extract docstrings and associated structural information and format them into nicely arranged reports of various types. Additional tools for extracting and formatting docstrings are available in the open source domain (including tools that may support structured text—search the Web for pointers), but Python ships with PyDoc in its standard library.

There are a variety of ways to launch PyDoc, including command-line script options that can save the resulting documentation for later viewing (described both ahead and in the Python library manual). Perhaps the two most prominent PyDoc interfaces are the built-in help function and the PyDoc GUI- and web-based HTML report interfaces. We met the help function briefly in Chapter 4; it invokes PyDoc to generate a simple textual report for any Python object. In this mode, help text looks much like a “manpage” on Unix-like systems, and in fact pages the same way as a Unix “more” outside GUIs like IDLE when there are multiple pages of text—press the space bar to move to the next page, Enter to go to the next line, and Q to quit:

>>> import sys
>>> help(sys.getrefcount)
Help on built-in function getrefcount in module sys:

getrefcount(...)
    getrefcount(object) -> integer

    Return the reference count of object.  The count returned is generally
    one higher than you might expect, because it includes the (temporary)
    reference as an argument to getrefcount().

Note that you do not have to import sys in order to call help, but you do have to import sys to get help on sys this way; it expects an object reference to be passed in. In Pythons 3.3 and 2.7, you can get help for a module you have not imported by quoting the module’s name as a string—for example, help('re'), help('email.message')—but support for this and other modes may differ across Python versions.

For larger objects such as modules and classes, the help display is broken down into multiple sections, the preambles of which are shown here. Run this interactively to see the full report (I’m running this on 3.3):

>>> help(sys)
Help on built-in module sys:

NAME
    sys

MODULE REFERENCE
    http://docs.python.org/3.3/library/sys
    ...more omitted...

DESCRIPTION
    This module provides access to some objects used or maintained by the
    interpreter and to functions that interact strongly with the interpreter.
    ...more omitted...

FUNCTIONS
    __displayhook__ = displayhook(...)
        displayhook(object) -> None
    ...more omitted...

DATA
    __stderr__ = <_io.TextIOWrapper name='<stderr>' mode='w' encoding='cp4...
    __stdin__ = <_io.TextIOWrapper name='<stdin>' mode='r' encoding='cp437...
    __stdout__ = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='cp4...
    ...more omitted...

FILE
    (built-in)

Some of the information in this report is docstrings, and some of it (e.g., function call patterns) is structural information that PyDoc gleans automatically by inspecting objects’ internals, when available.

Besides modules, you can also use help on built-in functions, methods, and types. Usage varies slightly across Python versions, but to get help for a built-in type, try either the type name (e.g., dict for dictionary, str for string, list for list); an actual object of the type (e.g., {}, '', []); or a method of an actual object or type name (e.g., str.join, 's'.join).^[32] You’ll get a large display that describes all the methods available for that type or the usage of that method:

>>> help(dict)
Help on class dict in module builtins:

class dict(object)
 |  dict() -> new empty dictionary.
 |  dict(mapping) -> new dictionary initialized from a mapping object's
 ...more omitted...

>>> help(str.replace)
Help on method_descriptor:

replace(...)
    S.replace (old, new[, count]) -> str

    Return a copy of S with all occurrences of substring
    ...more omitted...

>>> help(''.replace)
...similar to prior result...

>>> help(ord)
Help on built-in function ord in module builtins:

ord(...)
    ord(c) -> integer

    Return the integer ordinal of a one-character string.

Finally, the help function works just as well on your modules as it does on built-ins. Here it is reporting on the docstrings.py file we coded earlier. Again, some of this is docstrings, and some is information automatically extracted by inspecting objects’ structures:

>>> import docstrings
>>> help(docstrings.square)
Help on function square in module docstrings:

square(x)
    function documentation
    can we have your liver then?

>>> help(docstrings.Employee)
Help on class Employee in module docstrings:

class Employee(builtins.object)
 |  class documentation
 |
 ...more omitted...

>>> help(docstrings)
Help on module docstrings:

NAME
    docstrings

DESCRIPTION
    Module documentation
    Words Go Here

CLASSES
    builtins.object
        Employee

    class Employee(builtins.object)
     |  class documentation
     |
     ...more omitted...

FUNCTIONS
    square(x)
        function documentation
        can we have your liver then?

DATA
    spam = 40

FILE
    c:\code\docstrings.py

The text displays of the help function are adequate in many contexts, especially at the interactive prompt. To readers who’ve grown accustomed to richer presentation mediums, though, they may seem a bit primitive. This section presents the HTML-based flavor of PyDoc, which renders module documentation more graphically for viewing in a web browser, and can even open one automatically for you. The way this is run has changed as of Python 3.3:

Because this book’s audience is both users of the latest-and-greatest as well as the masses still using older tried-and-true Pythons, we’ll explore both schemes here. As we do, keep in mind that the way these schemes differ pertains only to the top level of their user interfaces. Their documentation displays are nearly identical, and under either regime PyDoc can also be used to generate both text in a console, and HTML files for later viewing in whatever manner you wish.

Python 3.2 and later: PyDoc’s all-browser mode

As of Python 3.3 the original GUI client mode of PyDoc, present in 2.X and earlier 3.X releases, is no longer available. This mode is present through Python 3.2 with the “Module Docs” Start button entry on Windows 7 and earlier, and via the pydoc -g command line. This GUI mode was reportedly deprecated in 3.2, though you had to look closely to notice—it works fine and without warning on 3.2 on my machine.

In 3.3, though, this mode goes away altogether, and is replaced with a pydoc -b command line, which instead spawns both a locally running documentation server, as well as a web browser that functions as both search engine client and page display. The browser is initially opened on a module index page with enhanced functionality. There are additional ways to use PyDoc (e.g., to save the HTML page to a file for later viewing, as described ahead), so this is a relatively minor operational change.

To launch the newer browser-only mode of PyDoc in Python 3.2 and later, a command-line like any of the following suffice: they all use the –m Python command-line argument for convenience to locate PyDoc’s module file on your module import search path. The first assumes Python is on your system path; the second employs Python 3.3’s new Windows launcher; and the third gives the full path to your Python if the other two schemes won’t work. See Appendix A for more on –m, and Appendix B for coverage of the Windows launcher.

c:\code> python -m pydoc -b
Server ready at http://localhost:62135/
Server commands: [b]rowser, [q]uit
server> q
Server stopped

c:\code> py −3 -m pydoc -b
Server ready at http://localhost:62144/
Server commands: [b]rowser, [q]uit
server> q
Server stopped

c:\code> C:\python33\python -m pydoc -b
Server ready at http://localhost:62153/
Server commands: [b]rowser, [q]uit
server> q
Server stopped

However you run this command line, the effect is to start PyDoc as a locally running web server on a dedicated (but by default arbitrary unused) port, and pop up a web browser to act as client, displaying a page giving links to documentation for all the modules importable on your module search path (including the directory where PyDoc is launched). PyDoc’s top-level web page interface is captured in Figure 15-1.

Figure 15-1. The top-level index start page of the all-browser PyDoc HTML interface in Python 3.2 and later, which as of 3.3 replaces the former GUI client in earlier Pythons.

Besides the module index, PyDoc’s web page also includes input fields at the top to request a specific module’s documentation page (Get) and search for related entries (Search), which stand in for the prior interface’s GUI client fields. You can also click on this page’s links to go to the Module Index (the start page), Topics (general Python subjects), and Keywords (overviews of statements and some expressions).

Notice that the index page in Figure 15-1 lists both modules and top-level scripts in the current directory—the book’s C:\code, where PyDoc was started by the earlier command lines. PyDoc is mostly intended for documenting importable modules, but can sometimes be used to show documentation for scripts too. A selected file must be imported in order to render its documentation, and as we’ve learned, importing runs a file’s code. Modules normally just define tools when run, so this is usually irrelevant.

If you ask for documentation for a top-level script file, though, the shell window where you launched PyDoc serves as the script’s standard input and output for any user interaction. The net effect is that the documentation page for a script will appear after it runs, and after its printed output shows up in the shell window. This may work better for some scripts than others, though; interactive input, for example, may interleave oddly with PyDoc’s own server command prompts.

Once you get past the new start page in Figure 15-1, the documentation pages for specific modules are essentially the same in both the newer all-browser mode and the earlier GUI-client scheme, apart from the additional input fields at the top of page in the former. For instance, Figure 15-2 shows the new documentation display pages—opened on two user-defined modules we’ll be writing in the next part of this book, as part of Chapter 21’s benchmarking case study. In either scheme, documentation pages contain automatically created hyperlinks that allow you to click your way through the documentation of related components in your application. For instance, you’ll find links to open imported modules’ pages too.

Figure 15-2. PyDoc’s module display page in Python 3.2 and later with input fields at the top, displaying two modules we will be coding in the next part of this book (Chapter 21).

Because of the similarity in their display pages, the next section on pre-3.2 PyDoc and its screen shots largely apply after 3.2 too, so be sure to read ahead for additional notes even if you’re using more recent Python. In effect, 3.3’s PyDoc simply cuts out the pre-3.2 GUI client “middleman,” while retaining its browser and server.

PyDoc in Python 3.3 also still supports other former usage modes. For instance, pydoc –p port can be used to set its PyDoc server port, and pydoc -w module still writes a module’s HTML documentation to a file named module.html for later viewing. Only the pydoc -g GUI client mode is removed and replaced by pydoc -b. You can also run PyDoc to generate a plain-text form of the documentation (its Unix “manpage” flavor shown earlier in this chapter)—the following command line is equivalent to the help call at an interactive Python prompt:

c:\code> py −3 -m pydoc timeit            # Command-line text help

c:\code> py −3
>>> help("timeit")                        # Interactive prompt text help

As an interactive system, your best bet is to take PyDoc’s web-based interface for a test drive, so we’ll cut its usage details short here; see Python’s manuals for additional details and command-line options. Also note that PyDoc’s server and browser functionality come largely “for free” from tools that automate such utility in the portable modules of Python’s standard library (e.g., webbrowser, http.server). Consult PyDoc’s Python code in the standard library file pydoc.py for additional details and inspiration.

Changing PyDoc’s Colors

You won’t be able to tell in the paper version of this book, but if you have an ebook or start PyDoc live, you’ll notice that it chooses colors that may or may not be to your liking. Unfortunately, there presently is no easy way to customize PyDoc’s colors. They are hardcoded deep in its source code, and can’t be passed in as arguments to functions or command lines, or changed in configuration files or global variables in the PyDoc module itself.

Except that, in an open source system, you can always change the code—PyDoc lives in the file pydoc.py in Python’s standard library, which is directory C:\Python33\Lib on Windows for Python 3.3. Its colors are hardcoded RGB value hex strings embedded throughout its code. For instance, its string '#eeaa77' specifies 2-byte (16-bit) values for red, green, and blue levels (decimal 238, 170, and 119), yielding a shade of orange for function banners. The string '#ee77aa' similarly renders the dark pinkish color used in nine places, including class and index page banners.

To tailor, search for these color value strings and replace them with your preferences. In IDLE, an Edit/Find for regular expression #\w{6} will locate color strings (this matches six alphanumeric characters after a # per Python’s re module pattern syntax; see the library manual for details).

To pick colors, in most programs with color selection dialogs you can map to and from RGB values; the book’s examples include a GUI script setcolor.py that does the same. In my copy of PyDoc, I replaced all #ee77aa with #008080 (teal) to banish the dark pink. Replacing #ffc8d8 with #c0c0c0 (grey) does similar for the light pink background of class docstrings.

Such surgery isn’t for the faint of heart—PyDoc’s file is currently 2,600 lines long—but makes for a fair exercise in code maintenance. Be cautious when replacing colors like #ffffff and #000000 (white and black), and be sure to make a backup copy of pydoc.py first so you have a fallback. This file uses tools we haven’t yet met, but you can safely ignore the rest of its code while you make your tactical changes.

Be sure to watch for PyDoc changes on the configurations front; this seems a prime candidate for improvement. In fact, there already is an effort under way: issue 10716 on the Python developers’ list seeks to make PyDoc more user-customizable by changing it to support CSS style sheets. If successful, this may allow users to make color and other display choices in external CSS files instead of PyDoc’s source code.

On the other hand, this is currently not planned to appear until Python 3.4, and will require PyDoc’s users to also be proficient with CSS code—which unfortunately has a nontrivial structure all its own that many people using Python may not understand well enough to change. As I write this, for example, the proposed PyDoc CSS file is already 234 lines of code that probably won’t mean much to people not already familiar with web development (and it hardly seems reasonable to ask them to learn a web development tool just to tailor PyDoc!).

Today’s PyDoc in 3.3 already supports a CSS style sheet that offers some customization options, but only half-heartedly, and ships with one that is empty. Until this is hashed out, code changes seem the best option. In any event, CSS style sheets are well beyond this Python book’s scope—see the Web for details, and check future Python release notes for PyDoc developments.

Python 3.2 and earlier: GUI client

This section documents the original GUI client mode of PyDoc, for readers using 3.2 and earlier, and gives some addition PyDoc context in general. It builds on the basics covered in the prior section, which aren’t repeated here, so be sure to at least scan the prior section if you’re using an older Python.

As mentioned, through Python 3.2, PyDoc provides a top-level GUI interface—a simple but portable Python/tkinter script for submitting requests—as well as a documentation server. Requests in the client are routed to the server, which produces reports displayed in a popped-up web browser. Apart from your having to submit search requests, this process is largely automatic.

To start PyDoc in this mode, you generally first launch the search engine GUI captured in Figure 15-3. You can start this either by selecting the Module Docs item in Python’s Start button menu on Windows 7 and earlier, or by launching the pydoc.py script in Python’s standard library directory with a -g command-line argument: it lives in Lib on Windows, but you can use Python’s –m flag to avoid typing script paths here too:

c:\code> c:\python32\python -m pydoc -g        # Explicit Python path
c:\code> py −3.2 -m pydoc -g                   # Windows 3.3+ launcher version

Enter the name of a module you’re interested in, and press the Enter key; PyDoc will march down your module import search path (sys.path), looking for the requested module and references to it.

Figure 15-3. The PyDoc top-level search engine GUI client in 3.2 and earlier: type the name of a module you want documentation for, press Enter, select the module, and then press “go to selected” (or omit the module name and press “open browser” to see all available modules).

Once you’ve found a promising entry, select it and click “go to selected.” PyDoc will spawn a web browser on your machine to display the report rendered in HTML format. Figure 15-4 shows the information PyDoc displays for the built-in glob module. Notice the hyperlinks in the Modules section of this page—you can click these to jump to the PyDoc pages for related (imported) modules. For larger pages, PyDoc also generates hyperlinks to sections within the page.

Figure 15-4. When you find a module in the Figure 15-3 GUI (such as this built-in standard library module) and press “go to selected,” the module’s documentation is rendered in HTML and displayed in a web browser window like this one.

Like the help function interface, the GUI interface works on user-defined modules as well as built-ins. Figure 15-5 shows the page generated for our docstrings.py module file coded earlier.

Make sure that the directory containing your module is on your module import search path—as mentioned, PyDoc must be able to import a file to render its documentation. This includes the current working directory—PyDoc might not check the directory it was launched from (which is probably meaningless when started from the Windows Start button anyhow), so you may need to extend your PYTHONPATH setting to get this to work. On Pythons 3.2 and 2.7, I had to add “.” to my PYTHONPATH to get PyDoc’s GUI client mode to look in the directory it was started from by command line:

c:\code> set PYTHONPATH=.;%PYTYONPATH%
c:\code> py −3.2 -m pydoc -g

This setting was also required to see the current directory for the new all-browser pydoc -b mode in 3.2. However, Python 3.3 automatically includes “.” in its index list, so no path setting is required to view files in the directory where PyDoc is started—a minor but noteworthy improvement.

Figure 15-5. PyDoc can serve up documentation pages for both built-in and user-coded modules on the module search path. Here is the page for a user-defined module, showing all its documentation strings (docstrings) extracted from the source file.

PyDoc can be customized and launched in various ways we won’t cover here; see its entry in Python’s standard library manual for more details. The main thing to take away from this section is that PyDoc essentially gives you implementation reports “for free”—if you are good about using docstrings in your files, PyDoc does all the work of collecting and formatting them for display. PyDoc helps only for objects like functions and modules, but it provides an easy way to access a middle level of documentation for such tools—its reports are more useful than raw attribute lists, and less exhaustive than the standard manuals.

PyDoc can also be run to save the HTML documentation for a module in a file for later viewing or printing; see the preceding section for pointers. Also, note that PyDoc might not work well if run on scripts that read from standard input—PyDoc imports the target module to inspect its contents, and there may be no connection for standard input text when it is run in GUI mode, especially if run from the Windows Start button. Modules that can be imported without immediate input requirements will always work under PyDoc, though. See also the preceding section’s notes regarding scripts in PyDoc’s -b mode in 3.2 and later; launching PyDoc’s GUI mode by command line works the same—you interact in the launch window.

Note

PyDoc GUI client trick of the day: If you press the “open browser” button in Figure 15-3’s window, PyDoc will produce an index page containing a hyperlink to every module you can possibly import on your computer. This includes Python standard library modules, modules of installed third-party extensions, user-defined modules on your import search path, and even statically or dynamically linked-in C-coded modules. Such information is hard to come by otherwise without writing code that inspects all module sources. On Python 3.2, you’ll want to do this immediately after the GUI opens, as it may not fully work after searches. Also note that in PyDoc’s all-browser –b interface in 3.2 and later, you get the same index functionality on its top-level start page of Figure 15-1.

If you’re looking for a way to document your Python system in a more sophisticated way, you may wish to check out Sphinx (currently at http://sphinx-doc.org). Sphinx is used by the standard Python documentation described in the next section, and many other projects. It uses simple reStructuredText as its markup language, and inherits much from the Docutils suite of reStructuredText parsing and translating tools.

Among other things, Sphinx supports a variety of output formats (HTML including Windows HTML Help, LaTeX for printable PDF versions, manual pages, and plain text); extensive and automatic cross-references; hierarchical structure with automatic links to relatives; automatic indexes; automatic code highlighting using Pygments (itself a notable Python tool); and more. This is probably overkill for smaller programs where docstrings and PyDoc may suffice, but can yield professional-grade documentation for large projects. See the Web for more details on Sphinx and its related tools.

For the complete and most up-to-date description of the language and its toolset, Python’s standard manuals stand ready to serve. Python’s manuals ship in HTML and other formats, and they are installed with the Python system on Windows—they are available in your Start button’s menu for Python on Windows 7 and earlier, and they can also be opened from the Help menu within IDLE. You can also fetch the manual set separately from http://www.python.org in a variety of formats, or read it online at that site (follow the Documentation link). On Windows, the manuals are a compiled help file to support searches, and the online versions at the Python website include a web-based search page.

When opened, the Windows format of the manuals displays a root page like that in Figure 15-6, showing the local copy on Windows. The two most important entries here are most likely the Library Reference (which documents built-in types, functions, exceptions, and standard library modules) and the Language Reference (which provides a formal description of language-level details). The tutorial listed on this page also provides a brief introduction for newcomers, which you’re probably already beyond.

Of notable interest, the What’s New documents in this standard manual set chronicle Python changes made in each release beginning with Python 2.0, which came out in late 2000—useful for those porting older Python code, or older Python skills. These documents are especially useful for uncovering additional details on the differences in the Python 2.X and 3.X language lines covered in this book, as well as in their standard libraries.

Figure 15-6. Python’s standard manual set, available online at http://www.python.org, from IDLE’s Help menu, and in the Windows 7 and earlier Start button menu. It’s a searchable help file on Windows, and there is a search engine for the online version. Of these, the Library Reference is the one you’ll want to use most of the time.

At the official Python website (http://www.python.org), you’ll find links to various Python resources, some of which cover special topics or domains. Click the Documentation link to access an online tutorial and the Beginners Guide to Python. The site also lists non-English Python resources, and introductions scaled to different target audiences.

Today you will also find numerous Python wikis, blogs, websites, and a host of other resources on the Web at large. To sample the online community, try searching for a term like “Python programming” in Google, or search on any topic of interest; chances are good you’ll find ample material to browse.

As a final resource, you can choose from a collection of professionally edited and published reference books for Python. Bear in mind that books tend to lag behind the cutting edge of Python changes, partly because of the work involved in writing, and partly because of the natural delays built into the publishing cycle. Usually, by the time a book comes out, it’s three or more months behind the current Python state (trust me on that—my books have a nasty habit of falling out of date in minor ways between the time I write them and the time they hit the shelves!). Unlike standard manuals, books are also generally not free.

Still, for many, the convenience and quality of a professionally published text is worth the cost. Moreover, Python changes so slowly that books are usually still relevant years after they are published, especially if their authors post updates on the Web. See the preface for pointers to other Python books.