Python 2.1 Quick Reference

Contents

• Front matter
• Invocation Options
• Environment Variables
• Lexical Entities : keywords, identifiers, strings, numbers, sequences, dictionaries, operators
• Basic Types And Their Operations
• Advanced Types
• Statements
• Built In Functions
• Built In Exceptions
• Standard methods & operators redefinition in user-created Classes
• Special informative state attributes for some types
• Important Modules : sys, os, posix, posixpath, shutil, time, string, re, math, getopt
• List of modules In base distribution
• Workspace Exploration And Idiom Hints
• Python Mode for Emacs
• The Python Debugger

NB: features added in 2.1 since 2.0 are coloured dark green.

NB: features added in 2.0 since 1.5.2 are coloured dark magenta.

Based on:
    Python Bestiary, Author: Ken Manheimer, ken.manheimer@nist.gov
    Python manuals, Authors: Guido van Rossum and Fred Drake
    What's new in Python 2.0, Authors: A.M. Kuchling and Moshe Zadka
    python-mode.el, Author: Tim Peters, tim_one@email.msn.com
    and the readers of comp.lang.python
Python's nest: http://www.python.org
Development: http://python.sourceforge.net/
ActivePython : http://www.ActiveState.com/ASPN/Python/
newsgroup: comp.lang.python
Help desk: help@python.org
Resources: http://starship.python.net/ and http://www.vex.net/parnassus/
Full documentation: http://www.python.org/doc/
An excellent Python reference book: Python Essential Reference by David Beazley (New Riders)

Invocation Options

• Available IDEs in std distrib: IDLE (tkinter based, portable), Pythonwin (Windows).

Environment variables

Notable lexical entities

Keywords

and       del       for       is        raise
assert    elif      from      lambda    return
break     else      global    not       try
class     except    if        or        while
continue  exec      import    pass
def       finally   in        print

• (list of keywords in std module: keyword)
• Illegitimate Tokens (only valid in strings): @ $ ?
• A statement must all be on a single line. To break a statement over multiple lines use "\", as with the C preprocessor.
• 
  Exception: can always break when inside any (), [], or {} pair, or in triple-quoted strings.
• More than one statement can appear on a line if they are separated with semicolons (";").
• Comments start with "#" and continue to end of line.

Identifiers

• Python identifiers keywords, attributes, etc. are case-sensitive.
• Special forms: _ident (not imported by 'from module import *'); __ident__ (system defined name);
• 
             __ident (class-private name mangling)

• Use \ at end of line to continue a string on next line.
• adjacent strings are concatened, e.g. 'Monty' ' Python' is the same as 'Monty Python'.
• u'hello' + ' world'  --> u'hello world'   (coerced to unicode)

• NUL byte (\000) is NOT an end-of-string marker; NULs may be embedded in strings.
• Strings (and tuples) are immutable: they cannot be modified.

Numbers

• Decimal integer: 1234, 1234567890546378940L        (or l)
• Octal integer: 0177, 0177777777777777777L (begin with a 0)
• Hex integer: 0xFF, 0XFFFFffffFFFFFFFFFFL (begin with 0x or 0X)
• Long integer (unlimited precision): 1234567890123456L (ends with L or l)
• Float (double precision): 3.14e-10, .001, 10., 1E3
• Complex: 1J, 2+3J, 4+5j (ends with J or j, + separates (float) real and imaginary parts)

Sequences

• String of length 0, 1, 2 (see above)
• '', '1', "12", 'hello\n'
• Tuple of length 0, 1, 2, etc:
• () (1,) (1,2)     # parentheses are optional if len > 0
• List of length 0, 1, 2, etc:
• [] [1] [1,2]

Sequence slicing [starting-at-index : but-less-than-index]. Start defaults to '0'; End defaults to 'sequence-length'.

Dictionaries (Mappings)

Dictionary of length 0, 1, 2, etc:
{} {1 : 'first'} {1 : 'first',  'next': 'second'}

Operators and their evaluation order

• Alternate names are defined in module operator (e.g. __add__ and add for +)
• Most operators are overridable
• 
  

Basic Types and Their Operations

Comparisons (defined between *any* types)

Boolean values and operators

None

None is used as default return value on functions. Built-in single object with type NoneType.
Input that evaluates to None does not print when running Python interactively.

Numeric types

Floats, integers and long integers.

Floats are implemented with C doubles.
Integers are implemented with C longs.
Long integers have unlimited size (only limit is system resources)

Operators on all numeric types

Bit operators on integers and long integers

Complex Numbers

• represented as a pair of machine-level double precision floating point numbers.
• The real and imaginary value of a complex number z can be retrieved through
• 
  the attributes z.real and z.imag.

Numeric exceptions

TypeError

raised on application of arithmetic operation to non-number

OverflowError

 numeric bounds exceeded

ZeroDivisionError

 raised when zero second argument of div or modulo op

Operations on all sequence types (lists, tuples, strings)

Notes :

Operations on mutable (=modifiable) sequences (lists)

Notes :
    (1) raise a ValueError exception when x is not found in s (i.e. out of range).
     (2) The sort() method takes an optional argument specifying a comparison fct of 2 arguments (list items) which should
          return -1, 0, or 1 depending on whether the 1st argument is considered smaller than, equal to, or larger than the 2nd
          argument. Note that this slows the sorting process down considerably.
     (3) The sort() and reverse() methods modify the list in place for economy of space when sorting or reversing a large list.
           They don't return the sorted or reversed list to remind you of this side effect.
     (4) The pop() method is not supported by mutable sequence types other than lists.
          The optional  argument i defaults to -1, so that by default the last item is removed and returned.
     (5) Raises an exception when x is not a list object.
 
 

Operations on mappings (dictionaries)

Notes :
  TypeError is raised if key is not acceptable
  (1) KeyError is raised if key k is not in the map
  (2) Keys and values are listed in random order
  (3) d2 must be of the same type as d1
  (4) Never raises an exception if k is not in the map, instead it returns defaultVal. defaultVal is optional, when not provided and k is not in the map, None is returned.
  (5) Never raises an exception if k is not in the map, instead it returns defaultVal, and adds k to map with value defaultVal. defaultVal is optional. When not provided and k is not in the map, None is returned and added to map.

Operations on strings

Notes :
    (1) Padding is done using spaces.
    (2) If optional argument start is supplied, substring s[start:] is processed. If optional arguments start and end are supplied, substring s[start:end] is processed.
    (3) Optional argument errors may be given to set a different error handling scheme. The default for errors is 'strict', meaning that encoding errors raise a ValueError. Other possible values are 'ignore' and 'replace'.
    (4) If optional argument tabsize is not given, a tab size of 8 characters is assumed.
    (5) Returns false if string s does not contain at least one character.
    (6) Returns false if string s does not contain at least one cased character.
    (7) A titlecased string is a string in which uppercase characters may only follow uncased characters and lowercase characters only cased ones.
    (8) s is returned if width is less than len(s).
    (9) If the optional argument maxsplit is given, only the first maxsplit occurrences are replaced.
    (10) If sep is not specified or None, any whitespace string is a separator. If maxsplit is given, at most maxsplit splits are done.
    (11) Line breaks are not included in the resulting list unless keepends is given and true.
    (12) table must be a string of length 256. All characters occurring in the optional argument deletechars are removed prior to translation.

String formatting with the % operator

• formatString uses C printf format codes : %, c, s, i, d, u, o, x, X, e, E, f, g, G, r (details below).
• Width and precision may be a * to specify that an integer argument gives the actual width or precision.
• The flag characters -, +, blank, # and 0 are understood. (details below)
• %s will convert any type argument to string (uses str() function)
• args may be a single arg or a tuple of args

        '%s has %03d quote types.' % ('Python', 2)  # => 'Python has 002 quote types.'

• Right-hand-side can also be a mapping:

        a = '%(lang)s has %(c)03d quote types.' % {'c':2, 'lang':'Python}

File Objects

Operators on file objects

File Exceptions

  EOFError

 End-of-file hit when reading (may be raised many times, e.g. if f is a tty).

  IOError

 Other I/O-related I/O operation failure

Advanced Types

• Module objects
• Class objects
• Class instance objects
• Type objects (see module: types)
• File objects (see above)
• Slice objects
• XRange objects
• Callable types:
• • User-defined (written in Python):
  • • User-defined Function objects
    • User-defined Method objects
  • Built-in (written in C):
  • • Built-in Function objects
    • Built-in Method objects
• Internal Types:
• • Code objects (byte-compile executable Python code: bytecode)
  • Frame objects (execution frames)
  • Traceback objects (stack trace of an exception)

Statements

Assignment operators

• An exception is either a string (object) or (preferably) a class instance.
• 
    Can create a new one simply by creating a new string:

              my_exception = 'You did something wrong'
      try:
                   if bad:
              raise my_exception, bad
      except my_exception, value:
                    print 'Oops', value
 

• Exception classes must be derived from the predefined class: Exception, e.g.:

            class text_exception(Exception): pass
            try:
                if bad:
                    raise text_exception()
                    # This is a shorthand for the form
                    # "raise <class>, <instance>"
             except Exception:
                 print 'Oops'
                 # This will be printed because
                 # text_exception is a subclass of Exception
When an error message is printed for an unhandled exception which is a
class, the class name is printed, then a colon and a space, and
finally the instance converted to a string using the built-in function
str().

All built-in exception classes derives from StandardError, itself
derived from Exception.

Name Space Statements

Packages (>1.5): a package is a name space which maps to a directory including
                module(s) and the special initialization module '__init__.py'
                (possibly empty). Packages/dirs can be nested. You address a
                module's symbol via '[package.[package...]module.symbol's.

Function Definition

def func_id ([param_list]): suite
                -- Creates a function object & binds it to name func_id.

param_list ::= [id [, id]*]
id ::= value | id = value | *id | **id

[Args are passed by value.Thus only args representing a mutable object
can be modified (are inout parameters). Use a tuple to return more than
one value]

Example:
    def test (p1, p2 = 1+1, *rest, **keywords):
            -- Parameters with "=" have default value (v is
               evaluated when function defined).
               If list has "*id" then id is assigned a tuple of
               all remaining args passed to function (like C vararg)
               If list has "**id" then id is assigned a dictionary of
               all extra arguments passed as keywords.

Class Definition

class <class_id> [(<super_class1> [,<super_class2>]*)]: <suite>
        -- Creates a class object and assigns it name <class_id>
           <suite> may contain local "defs" of class methods and
           assignments to class attributes.
Example:
    class my_class (class1, class_list[3]): ...
                  Creates a class object inheriting from both "class1" and whatever
                  class object "class_list[3]" evaluates to. Assigns new
                  class object to name "my_class".
        - First arg to class methods is always instance object, called 'self'
          by convention.
        - Special method __init__() is called when instance is created.
        - Special method __del__() called when no more reference to object.
        - Create instance by "calling" class object, possibly with arg
          (thus instance=apply(aClassObject, args...) creates an instance!)
        - In current implementation, can't subclass off built-in
          classes. But can "wrap" them, see UserDict & UserList modules,
          and see __getattr__() below.
Example:
     class c (c_parent):
           def __init__(self, name): self.name = name
           def print_name(self): print "I'm", self.name
           def call_parent(self): c_parent.print_name(self)
           instance = c('tom')
           print instance.name
           'tom'
           instance.print_name()
           "I'm tom"
        Call parent's super class by accessing parent's method
        directly and passing "self" explicitly (see "call_parent"
        in example above).
        Many other special methods available for implementing
        arithmetic operators, sequence, mapping indexing, etc.

Documentation Strings

Example:
     class C:
            "A description of C"
            def __init__(self):
                "A description of the constructor"
                # etc.
Then c.__doc__ == "A description of C".
Then c.__init__.__doc__ == "A description of the constructor".

Others

lambda [param_list]: returnedExpr
                -- Creates an anonymous function. returnedExpr must be
                   an expression, not a statement (e.g., not "if xx:...",
                   "print xxx", etc.) and thus can't contain newlines.
                   Used mostly for filter(), map(), reduce() functions, and GUI callbacks..

result = [expression for item1 in sequence1  [if condition1]
                        [for item2 in sequence2 ... for itemN in sequenceN]
                      ]

result = []
for item1 in sequence1:
    for item2 in sequence2:
    ...
        for itemN in sequenceN:
             if (condition1) and further conditions:
                  result.append(expression)

Built-In Functions

Built-In Exceptions

Exception

         Root class for all exceptions

    SystemExit

         On 'sys.exit()'

    StandardError

                 Base class for all built-in exceptions; derived from Exception root class.

        ArithmeticError

                 Base class for OverflowError, ZeroDivisionError, FloatingPointError

            FloatingPointError

                       When a floating point operation fails.

            OverflowError

                        On excessively large arithmetic operation

            ZeroDivisionError

              On division or modulo operation with 0 as 2nd arg

        AssertionError

                When an assert statement fails.

        AttributeError

                On attribute reference or assignment failure

        EnvironmentError    [new in 1.5.2]

                On error outside Python; error arg tuple is (errno, errMsg...)

            IOError    [changed in 1.5.2]

           I/O-related operation failure

            OSError    [new in 1.5.2]

           used by the os module's os.error exception.

        EOFError

                Immediate end-of-file hit by input() or raw_input()

        ImportError

     On failure of `import' to find module or name

        KeyboardInterrupt

     On user entry of the interrupt key (often `Control-C')

        LookupError

                base class for IndexError, KeyError

            IndexError

             On out-of-range sequence subscript

            KeyError

             On reference to a non-existent mapping (dict) key

        MemoryError

     On recoverable memory exhaustion

        NameError

     On failure to find a local or global (unqualified) name

        RuntimeError

     Obsolete catch-all; define a suitable error instead

      NotImplementedError   [new in 1.5.2]

            On method not implemented

        SyntaxError

     On parser encountering a syntax error

   IndentationError

       On parser encountering an indentation syntax error

   TabError

       On parser encountering an indentation syntax error

        SystemError

     On non-fatal interpreter error - bug - report it

        TypeError

     On passing inappropriate type to built-in op or func

        ValueError

     On arg error not covered by TypeError or more precise

Standard methods & operators redefinition in classes

Standard methods & operators map to special '__methods__' and thus may be
 redefined (mostly in in user-defined classes), e.g.:
    class x:
         def __init__(self, v): self.value = v
         def __add__(self, r): return self.value + r
    a = x(3) # sort of like calling x.__init__(a, 3)
    a + 4    # is equivalent to a.__add__(4)

Operators

See list in the operator module. Operator function names are provided with 2 variants, with or without leading & trailing '__' (eg. __add__ or add).

Special informative state attributes for some types:

Important Modules

Handles Unicode strings. Implemented in new module sre, re now a mere front-end for compatibility.
Patterns are specified as strings. Tip: Use raw strings (e.g. r'\w*') to litteralize backslashes.
 

Regular Expression Objects

Match Objects

Variables:

pi
e

acos(x)
asin(x)
atan(x)
atan2(x, y)
ceil(x)
cos(x)
cosh(x)
exp(x)
fabs(x)
floor(x)
fmod(x, y)
frexp(x)        -- Unlike C: (float, int) = frexp(float)
ldexp(x, y)
log(x)
log10(x)
modf(x)         -- Unlike C: (float, float) = modf(float)
pow(x, y)
sin(x)
sinh(x)
sqrt(x)
tan(x)
tanh(x)

Functions:

getopt(list, optstr)    -- Similar to C. <optstr> is option
                           letters to look for. Put ':' after letter
                           if option takes arg. E.g.
    # invocation was "python test.py -c hi -a arg1 arg2"
       opts, args =  getopt.getopt(sys.argv[1:], 'ab:c:')
    # opts would be
       [('-c', 'hi'), ('-a', '')]
    # args would be
       ['arg1', 'arg2']

List of modules and packages in base distribution

(built-ins and content of python Lib directory)
(Python NT distribution, may be slightly different in other distributions)

(following list not revised)

* Built-ins *

            sys                 Interpreter state vars and functions
            __built-in__        Access to all built-in python identifiers
            __main__            Scope of the interpreters main program, script or stdin
            array               Obj efficiently representing arrays of basic values
            math                Math functions of C standard
            time                Time-related functions
            regex               Regular expression matching operations
            marshal             Read and write some python values in binary format
            struct              Convert between python values and C structs

* Standard *

            getopt              Parse cmd line args in sys.argv.  A la UNIX 'getopt'.
            os                  A more portable interface to OS dependent functionality
            re                  Functions useful for working with regular expressions
            string              Useful string and characters functions and exceptions
            whrandom            Wichmann-Hill pseudo-random number generator
            thread              Low-level primitives for working with process threads
            threading           idem, new recommanded interface.

* Unix/Posix *

            dbm                 Interface to Unix ndbm database library
            grp                 Interface to Unix group database
            posix               OS functionality standardized by C and POSIX standards
            posixpath           POSIX pathname functions
            pwd                 Access to the Unix password database
            select              Access to Unix select multiplex file synchronization
            socket              Access to BSD socket interface

* Tk User-interface Toolkit *

            tkinter             Main interface to Tk

* Multimedia *

            audioop             Useful operations on sound fragments
            imageop             Useful operations on images
            jpeg                Access to jpeg image compressor and decompressor
            rgbimg              Access SGI imglib image files

* Cryptographic Extensions *

            md5                 Interface to RSA's MD5 message digest algorithm
            mpz                 Interface to int part of GNU multiple precision library
            rotor               Implementation of a rotor-based encryption algorithm

* Stdwin * Standard Window System

            stdwin              Standard Window System interface
            stdwinevents        Stdwin event, command, and selection constants
            rect                Rectangle manipulation operations

* SGI IRIX * (4 & 5)

            al          SGI audio facilities
            AL          al constants
            fl          Interface to FORMS library
            FL          fl constants
            flp Functions for form designer
            fm          Access to font manager library
            gl          Access to graphics library
            GL          Constants for gl
            DEVICE      More constants for gl
            imgfile     Imglib image file interface

* Suns *

            sunaudiodev Access to sun audio interface

Workspace exploration and idiom hints

        dir(<module>)                                list functions, variables in <module>
        dir();                                       get object keys, defaults to local name space
        X.__methods__;                               list of methods supported by X (if any)
        X.__members__                                List of X's data attributes
        if __name__ == '__main__': main()            invoke main if running as script
        map(None, lst1, lst2, ...)                   merge lists
        b = a[:]                                     create copy of seq structure
        _                                            in interactive mode, is last value printed

Python Mode for Emacs

(Not revised, possibly not up to date)

Type C-c ? when in python-mode for extensive help.
INDENTATION
Primarily for entering new code:
        TAB      indent line appropriately
        LFD      insert newline, then indent
        DEL      reduce indentation, or delete single character
Primarily for reindenting existing code:
        C-c :    guess py-indent-offset from file content; change locally
        C-u C-c :        ditto, but change globally
        C-c TAB  reindent region to match its context
        C-c <    shift region left by py-indent-offset
        C-c >    shift region right by py-indent-offset
MARKING & MANIPULATING REGIONS OF CODE
C-c C-b         mark block of lines
M-C-h           mark smallest enclosing def
C-u M-C-h       mark smallest enclosing class
C-c #           comment out region of code
C-u C-c #       uncomment region of code
MOVING POINT
C-c C-p         move to statement preceding point
C-c C-n         move to statement following point
C-c C-u         move up to start of current block
M-C-a           move to start of def
C-u M-C-a       move to start of class
M-C-e           move to end of def
C-u M-C-e       move to end of class
EXECUTING PYTHON CODE
C-c C-c sends the entire buffer to the Python interpreter
C-c |   sends the current region
C-c !   starts a Python interpreter window; this will be used by
        subsequent C-c C-c or C-c | commands
VARIABLES
py-indent-offset        indentation increment
py-block-comment-prefix comment string used by py-comment-region
py-python-command       shell command to invoke Python interpreter
py-scroll-process-buffer        t means always scroll Python process buffer
py-temp-directory       directory used for temp files (if needed)
py-beep-if-tab-change   ring the bell if tab-width is changed

The Python Debugger

(Not revised, possibly not up to date, see 1.5.2 Library Ref section 9.1; in 1.5.2, you may also use debugger integrated in IDLE)

Accessing

import pdb      (it's a module written in Python)
        -- defines functions :
           run(statement[,globals[, locals]])
                        -- execute statement string under debugger control, with optional
                           global & local environment.
           runeval(expression[,globals[, locals]])
                        -- same as run, but evaluate expression and return value.
           runcall(function[, argument, ...])
                        -- run function object with given arg(s)
           pm()         -- run postmortem on last exception (like debugging a core file)
           post_mortem(t)
                        -- run postmortem on traceback object <t>

        -- defines class Pdb :
           use Pdb to create reusable debugger objects. Object
           preserves state (i.e. break points) between calls.

        runs until a breakpoint hit, exception, or end of program
        If exception, variable '__exception__' holds (exception,value).

Commands

h, help
        brief reminder of commands
b, break [<arg>]
        if <arg> numeric, break at line <arg> in current file
        if <arg> is function object, break on entry to function <arg>
        if no arg, list breakpoints
cl, clear [<arg>]
        if <arg> numeric, clear breakpoint at <arg> in current file
        if no arg, clear all breakpoints after confirmation
w, where
        print current call stack
u, up
        move up one stack frame (to top-level caller)
d, down
        move down one stack frame
s, step
        advance one line in the program, stepping into calls
n, next
        advance one line, stepping over calls
r, return
        continue execution until current function returns
        (return value is saved in variable "__return__", which
        can be printed or manipulated from debugger)
c, continue
        continue until next breakpoint
a, args
        print args to current function
rv, retval
        prints return value from last function that returned
p, print <arg>
        prints value of <arg> in current stack frame
l, list [<first> [, <last>]]
               List source code for the current file.
               Without arguments, list 11 lines around the current line
               or continue the previous listing.
               With one argument, list 11 lines starting at that line.
               With two arguments, list the given range;
               if the second argument is less than the first, it is a count.
whatis <arg>
        prints type of <arg>
!
        executes rest of line as a Python statement in the current stack frame
q quit
        immediately stop execution and leave debugger
<return>
        executes last command again
Any input debugger doesn't recognize as a command is assumed to be a
Python statement to execute in the current stack frame, the same way
the exclamation mark ("!") command does.

Example

(1394) python
Python 1.0.3 (Sep 26 1994)
Copyright 1991-1994 Stichting Mathematisch Centrum, Amsterdam
>>> import rm
>>> rm.run()
Traceback (innermost last):
         File "<stdin>", line 1
         File "./rm.py", line 7
           x = div(3)
         File "./rm.py", line 2
           return a / r
ZeroDivisionError: integer division or modulo
>>> import pdb
>>> pdb.pm()
> ./rm.py(2)div: return a / r
(Pdb) list
         1     def div(a):
         2  ->     return a / r
         3
         4     def run():
         5         global r
         6         r = 0
         7         x = div(3)
         8         print x
[EOF]
(Pdb) print r
0
(Pdb) q
>>> pdb.runcall(rm.run)
etc.

Quirks

Always single-steps through top-most stack frame. That is, "c" acts like "n".