0.4 Conventions Used in This Book

Several typographic conventions are used in main text to guide the readers eye. Both block and inline literals are presented in a fixed font, including names of utilities, URLs, variable names, and code samples. Names of objects in the standard library, however, are presented in italics. Names of modules and packages are printed in a sans serif typeface. Heading come in several different fonts, depending on their level and purpose.

All constants, functions, and classes in discussions and cross-references will be explicitly prepended with their namespace (module). Methods will additionally be prepended with their class. In some cases, code examples will use the local namespace, but a preference for explicit namespace identification will be present in sample code also. For example, a reference might read:

SEE ALSO: email.Generator.DecodedGenerator.flatten() 351; raw_input() 446; tempfile.mktemp() 71;

The first is a class method in the email.Generator module; the second, a built-in function; the last, a function in the tempfile module.

In the special case of built-in methods on types, the expression for an empty type object will be used in the style of a namespace modifier. For example:

Methods of built-in types include [].sort(), " ".islower(), {}.keys(), and (lambda:1).func_code.

The file object type will be indicated by the name FILE in capitals. A reference to a file object method will appear as, for example:

SEE ALSO: FILE.flush() 16;

Brief inline illustrations of Python concepts and usage will be taken from the Python interactive shell. This approach allows readers to see the immediate evaluation of constructs, much as they might explore Python themselves. Moreover, examples presented in this manner will be self-sufficient (not requiring external data), and may be entered with variations by readers trying to get a grasp on a concept. For example:

 >>> 13/7 # integer division 1 >>> 13/7. # float division 1.8571428571428572 

In documentation of module functions, where named arguments are available, they are listed with their default value. Optional arguments are listed in square brackets. These conventions are also used in the Python Library Reference. For example:

 foobar.spam(s, val=23 [,taste="spicy"]) 

The function foobar.spam() uses the argument s to ...

If a named argument does not have a specifiable default value, the argument is listed followed by an equal sign and ellipsis. For example:

 foobar.baz(string=..., maxlen=... ) 

The foobar.baz() function ...

With the introduction of Unicode support to Python, an equivalence between a character and a byte no longer holds in all cases. Where an operation takes a numeric argument affecting a string-like object, the documentation will specify whether characters or bytes are being counted. For example:

Operation A reads num bytes from the buffer. Operation B reads num characters from the buffer.

The first operation indicates a number of actual 8-bit bytes affected. The second operation indicates an indefinite number of bytes are affected, but that they compose a number of (maybe multibyte) characters.