• Choose a category
• All
• Classic-Fiction

As summarized in Table 15-1, there are a variety of places to look for information on Python, with generally increasing verbosity. Because documentation is such a crucial tool in practical programming, we’ll explore each of these categories in the sections that follow.

Table 15-1. Python documentation sources

Form

Role

# comments

In-file documentation

The dir function

Lists of attributes available in objects

Docstrings: __doc__

In-file documentation attached to objects

PyDoc: The help function

Interactive help for objects

PyDoc: HTML reports

Module documentation in a browser

The standard manual set

Official language and library descriptions

Web resources

Online tutorials, examples, and so on

Published books

Commercially available reference texts

# Comments

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 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”). More on docstrings in a moment.

The dir Function

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 on any object that has attributes. For example, to find out what’s available in the standard library’s sys module, import it and pass it to dir (these results are from Python 3.0; they might vary slightly on 2.6):

>>> import sys

>>> dir(sys)

['__displayhook__', '__doc__', '__excepthook__', '__name__', '__package__',

'__stderr__', '__stdin__', '__stdout__', '_clear_type_cache', '_current_frames',

'_getframe', 'api_version', 'argv', 'builtin_module_names', 'byteorder',

'call_tracing', 'callstats', 'copyright', 'displayhook', 'dllhandle',

'dont_write_bytecode', 'exc_info', 'excepthook', 'exec_prefix', 'executable',

'exit', 'flags', 'float_info', 'getcheckinterval', 'getdefaultencoding',

...more names omitted...]

Only some of the many names are displayed here; run these statements on your machine to see the full list.

To find out what attributes are provided in built-in object types, run dir on a literal (or 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', 'count', 'extend', 'index', 'insert', 'pop', 'remove',

'reverse', 'sort']

>>> dir('')

['__add__', '__class__', '__contains__', ...more...

'capitalize', 'center', 'count', 'encode', 'endswith', 'expandtabs',

'find', 'format', 'index', 'isalnum', 'isalpha', 'isdecimal',

'isdigit', 'isidentifier', 'islower', 'isnumeric', 'isprintable',

'isspace', 'istitle', 'isupper', 'join', 'ljust', 'lower', 'lstrip', '

maketrans', 'partition', 'replace', 'rfind', 'rindex', 'rjust',

...more names omitted...]

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); they all begin and end with double underscores to make them distinct, and you can safely ignore them at this point in the book.

Incidentally, you can achieve the same effect by passing a type name to dir instead of a literal:

>>> dir(str) == dir('') # Same result as prior example

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