Python 2.3 Quick Reference

Contents

• Front matter
• Invocation Options
• Environment variables
• Lexical entities : keywords, identifiers, string literals, boolean constants, numbers, sequences, dictionaries, operators
• Basic types and their operations: None, bool, Numeric types, sequence types, list, dictionary, string, file, sets
• Advanced types
• Statements: assignment, control flow, exceptions, name space, function def, class def
• Iterators; Generators; Descriptors
• 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 the base distribution
• Workspace exploration and idiom hints
• Python mode for Emacs

Front matter

23 Oct 2004, rev 8

updated by Richard Gruet

03 Oct 2003,

upgraded by Richard Gruet for Python 2.3

11 May 2003, rev 4

upgraded by Richard Gruet for Python 2.2 (restyled by Andrei)

7 Aug 2001

upgraded by Simon Brunning for Python 2.1

16 May 2001

upgraded by Richard Gruet and Simon Brunning for Python 2.0

18 Jun 2000

upgraded by Richard Gruet for Python 1.5.2

30 Oct 1995

created by Chris Hoffmann for Python 1.3

Features added in 2.3 since 2.2.
Features added in 2.2 since 2.1.
Features added in 2.1 since 2.0.

• Python Bestiary, author: Ken Manheimer
• Python manuals, authors: Guido van Rossum and Fred Drake
• python-mode.el, author: Tim Peters
• and the readers of comp.lang.python

• Python's nest: http://www.python.org
• Official documentation: http://www.python.org/doc/
• Other doc & books: Dive into Python , Python Cookbook , Faqts , Thinking in Python , Text processing in Python
• Packages: Python Package Index (PyPI) , Vaults of Parnassus , SourceForge (search "python") , O'Reilly Python DevCenter , Starship Python
• Wiki: moinmoin
• Newsgroups: comp.lang.python and comp.lang.python.announce
• Misc pages: Daily Python URL , Kevin Altis' WebLog
• Development: http://python.sourceforge.net/
• Jython (Java impl. of Python): http://www.jython.org/
• ActivePython: http://www.ActiveState.com/ASPN/Python/
• Help desk: help@python.org
• An excellent Python reference book: Python Essential Reference by David Beazley & Guido Van Rossum (Other New Riders)

Tip: From within the Python interpreter, use help or help(object).

Invocation Options

python[w] [-dEhiOQStuUvVWxX?] [-c command| scriptFile | - ] [args]
    (pythonw does not open a terminal/console; python does)

• Available IDEs in std distrib: IDLE (tkinter based, portable), Pythonwin (on Windows). Other free IDEs: BOA constructor, SPE.
• Typical python module header :

#!/usr/bin/env python
# -*- coding: latin1 -*-

Since 2.3 the encoding of a Python source file must be declared as one of the two first lines (or defaults to 7 bits Ascii) [PEP-0263], with the format:


# -*- coding: encoding -*-

Std encodings are defined here, e.g. ISO-8859-1 (aka latin1), iso-8859-15 (latin9), UTF-8... Not all encodings supported, in particular UTF-16 is not supported.

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      yield
        def       finally   in        print

• (List of keywords available 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

(letter | "_") (letter | digit | "_")*

• 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).

String literals

• 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.

Boolean constants

• True
• False

In 2.2, True and False are integers 1 and 0. Since 2.3, they are of new type bool.

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) or long(1234)
• 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)

Integers and long integers are unified starting from release 2.2 (the L suffix is no longer required)

Sequences

• Strings (type str) of length 0, 1, 2 (see above)
  '', '1', "12", 'hello\n'
• Tuples (type tuple) of length 0, 1, 2, etc:
  () (1,) (1,2) # parentheses are optional if len > 0
• Lists (type list) of length 0, 1, 2, etc:
  [] [1] [1,2]

• Indexing is 0-based. Negative indices (usually) mean count backwards from end of sequence.
• Sequence slicing [starting-at-index : but-less-than-index [ : step]]. Start defaults to 0, end to len(sequence), step to 1.

    a = (0,1,2,3,4,5,6,7)
    a[3] == 3
    a[-1] == 7
    a[2:4] == (2, 3)
    a[1:] == (1, 2, 3, 4, 5, 6, 7)
    a[:3] == (0, 1, 2)
    a[:] == (0,1,2,3,4,5,6,7) # makes a copy of the sequence.
    a[::2] == (0, 2, 4, 6) # Only even numbers. 
    a[::-1] = (7, 6, 5, 4, 3 , 2, 1, 0) # Reverse order.

Dictionaries (Mappings)

Dictionaries (type dict) 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)

• Comparison behavior can be overridden for a given class by defining special method __cmp__.
• (1) X < Y < Z < W has expected meaning, unlike C
• (2) Compare object identities (i.e. id(object)), not object values.

None

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

Boolean operators

• Truth testing behavior can be overridden for a given class by defining special method __nonzero__.
• (1) Evaluate second arg only if necessary to determine outcome.

Numeric types

Floats, integers and long integers.

• Floats (type float) are implemented with C doubles.
• Integers (type int) are implemented with C longs (signed 32 bits, maximum value is sys.maxint)
• Long integers (type long) have unlimited size (only limit is system resources).
• Integers and long integers are unified starting from release 2.2 (the L suffix is no longer required). int() returns a long integer instead of raising OverflowError.

Operators on all numeric types

• (1) / is still a floor division (1/2 == 0) unless validated by a from __future__ import division.
• classes may override methods __truediv__ and __floordiv__ to redefine these operators.

Bit operators on integers and long integers

Complex Numbers

• Type complex, 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)

• (1) if i or j is negative, the index is relative to the end of the string, ie len(s)+i or len(s)+j is substituted. But note that -0 is still 0.
• (2) The slice of s from i to j is defined as the sequence of items with index k such that i <= k < j.
  If i or j is greater than len(s), use len(s). If i is omitted, use len(s). If i is greater than or equal to j, the slice is empty.
• (3) For strings: before 2.3, x must be a single character string; Since 2.3, x in s is True if x is a substring of s.

Operations on mutable sequences (type list)

• (1) Raises 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 function 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 a TypeError when x is not a list object.

Operations on mappings / dictionaries (type dict)

• 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 (type str)

These string methods largely (but not completely) supersede the functions available in the string module.
The str and unicode types share a common base class basestring.

• (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 % args --> evaluates to a string

• 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'}

  (vars() function very handy to use on right-hand-side)

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

Sets

The Module sets define a new set data type implementation, via class Set for mutable sets, and class ImmutableSet for non mutable sets. Sets are unordered collections of unique (non duplicate) elements. Elements must be hashable.

Advanced Types

• Module objects
• Class objects
• Class instance objects
• Type objects (see module: types)
• File objects (see above)
• Slice objects
• Ellipsis object, used by extended slice notation (unique, named Ellipsis)
• Null object (unique, named None)
• 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 object
• Internal Types:
  • Code objects (byte-compile executable Python code: bytecode)
  • Frame objects (execution frames)
  • Traceback objects (stack trace of an exception)

Statements

Assignment operators

• (1) Can unpack tuples, lists, and strings:

  first, second = a[0:2]
  [f, s] = range(2)
  c1,c2,c3='abc'

  Tip: x,y = y,x swaps x and y.
• (2) Not exactly equivalent - a is evaluated only once. Also, where possible, operation performed in-place - a is modified rather than replaced.

Control Flow statements

Exception statements

• An exception is an instance of an exception class (before 2.0, it may also be a mere string).
• Exception classes must be derived from the predefined class: Exception, e.g.:

  class TextException(Exception): pass
  try:
      if bad:
          raise TextException()
  except Exception:
      print 'Oops'  # This will be printed because TextException is a subclass of Exception
  

• When an error message is printed for an unhandled exception, 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

import sys; print sys.argv
import package1.subpackage.module
package1.subpackage.module.foo()

from sys import argv; print argv
from package1 import module; module.foo()
from package1.module import foo; foo()

from sys import *; print argv
from package.module import *; print x

Function Definition

def func_id ([param_list]):
    suite

Creates a function object and binds it to name func_id.

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

 def test (p1, p2 =5+3, *args, **kwargs):

• args with "=" have a default value (evaluated at function definition time).
• If arg list has "*args" then args is assigned a tuple of all remaining non-keywords args passed to the function.
• If list has "**kwargs" then kwargs is assigned a dictionary of all extra arguments passed as keywords.
• args and kwargs are common names but other names may be used as well.

Class Definition

class className [(super_class1 [, super_class2]*)]:
  suite

Creates a class object and assigns it name className.
suite may contain local "defs" of class methods and assignments to class attributes.

class MyClass (class1, class2): ...

class MyClass: ...

class MyClass (object): ...

• First arg to class instance methods (operations) is always the target 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!)
• Before 2.2 it was not possible to subclass built-in classes like list, dict (you had to "wrap" them, using UserDict & UserList modules); since 2.2 you can subclass them directly (see Types/Classes unification).

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"

Types / classes unification

x = int(2) # built-in cast function now a constructor for base type
y = 3  # <=> int(3) (litterals are instances of new base types)
print type(x), type(y) # int, int

assert isinstance(x, int) # replaces isinstance(x, types.IntType)

assert issubclass(int, object) # base types derive from base class 'object'.
s = "hello" # <=> str("hello")
assert isinstance(s, str)

f = 2.3  # <=> float(2.3)
class MyInt(int): pass    # may subclass base types
x,y = MyInt(1), MyInt("2")

print x, y, x+y # => 1,2,3

class MyList(list): pass

l = MyList("hello")

print l # ['h', 'e', 'l', 'l', 'o']

Documentation Strings

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

Iterators

• An iterator enumerates elements of a collection. It is an object with a single method next() returning the next element or raising StopIteration.
• You get an iterator on obj via the new built-in function iter(obj), which calls obj.__class__.__iter__().
• A collection may be its own iterator by implementing both __iter__() and next().
• Built-in collections (lists, tuples, strings, dict) implement __iter__(); dictionaries (maps) enumerate their keys; files enumerates their lines.
• Python uses implicitely iterators wherever it has to loop :
  • for elt in collection:
  • if elt in collection:
  • when assigning tuples: x,y,z= collection

Generators

• A generator is a function that retains its state between 2 calls and produces a new value at each invocation. The values are returned (one at a time) using the new keyword yield, while return or raise StopIteration() are used to notify the end of values.
• A typical use is the production of IDs, names, or serial numbers.
• To use a generator: call the generator function to get a generator object, then call generator.next() to get the next value until StopIteration is raised.
• In 2.2, feature needs to be enabled by the statement: from __future__ import generators (not required since 2.3+)

def genID(initialValue=0):
  v = initialValue
  while v < initialValue + 1000:
    yield "ID_%05d" % v
    v += 1
  return    # or: raise StopIteration()

generator = genID() # Create a generator
for i in range(10): # Generates 10 values
  print generator.next()

Descriptors / Attribute access

• Descriptors are objects implementing at least the first of these 3 methods representing the descriptor protocol:
  • __get__(self, obj, type=None) --> value
  • __set__(self, obj, value)
  • __delete__(self, obj)
  Python now transparently uses descriptors to describe and access the attributes and methods of new-style classes (i.e. derived from object). [more info])
• Built-in descriptors now allow to define:
  • Static methods : Use staticmethod(f) to make method f(x) static (unbound).
  • Class methods: like a static but takes the Class as 1st argument => Use f = classmethod(f) to make method f(theClass, x) a class method.
  • Properties : A property is an instance of the new built-in type property, which implements the descriptor protocol for attributes => Use propertyName = property(getter=None, setter=None, deleter=None, description=None) to define a property inside or outside a class. Then access it as propertyName or obj.propertyName
  • Slots. New style classes can define a class attribute __slots__ to constrain the list of assignable attribute names, to avoid typos (which is normally not detected by Python and leads to the creation of new attributes), e.g. __slots__ = ('x', 'y')
    Note: According to recent discussions, the real purpose of slots seems still unclear (optimization?), and their use should probably be discouraged.

Misc

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.

List comprehensions

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

is equivalent to:

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

Nested scopes
In 2.2 nested scopes no longer need to be specially enabled by a from __future__ import nested_scopes directive, and are now always present.

Built-In Functions

x = 1; incr_x = eval('x + 1')

Built-In Exception classes

• StopIteration
  Raised by an iterator's next() method to signal that there are no further values.
• SystemExit
  On sys.exit()
• Warning
  Base class for warnings (see module warning)
  • UserWarning
    Warning generated by user code.
  • PendingDeprecationWarning
    Warning about future deprecated code.
  • DeprecationWarning
    Warning about deprecated code.
  • SyntaxWarning
    Warning about dubious syntax.
  • RuntimeWarning
    Warning about dubious runtime behavior.
• StandardError
  Base class for all built-in exceptions; derived from Exception root class.
  • ArithmeticError
    Base class for arithmetic errors.
    • FloatingPointError
      When a floating point operation fails.
    • OverflowError
      On excessively large arithmetic operation.
    • ZeroDivisionError
      On division or modulo operation with 0 as 2nd argument.
  • 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.
    • WindowsError
      When a Windows-specific error occurs or when the error number does not correspond to an errno value.
• 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 `CTRL-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.
  • UnboundLocalError
    On reference to an unassigned local variable.
• ReferenceError
  On attempt to access to a garbage-collected object via a weak reference proxy.
• 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 operator or function.
• ValueError
  On argument error not covered by TypeError or more precise.
  • UnicodeError
    On Unicode-related encoding or decoding error.

Standard methods & operators redefinition in classes

class C:
    def __init__(self, v): self.value = v
    def __add__(self, r): return self.value + r

a = C(3) # sort of like calling C.__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 '__' (e.g. __add__ or add).

• a + 3  calls __add__(a, 3)
• 3 + a  calls __radd__(a, 3)

Special informative state attributes for some types:

Important Modules

sys

os

posix

posixpath

shutil

time

string

re (sre)

Regular Expression Objects

Match Objects

math

getopt

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

Workspace exploration and idiom hints

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

Python Mode for Emacs

(The following has not been revised, probably not up to date - any contribution welcome -)

 
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