Python 2.5 Quick Reference

Style chooser: Modern, Modern B&W, Classic, High contrast or Printing
[Hint: Use styles Modern B&W or Printing to print. If you get problems, try printing the PDF versions instead]

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, set, date/time
• Advanced types
• Statements: assignment, conditional expressions, control flow, exceptions, name space, function def, class def
• Iterators; Generators; Descriptors; Decorators
• 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

Last modified on Aug 1st, 2008

14 Dec 2006,

upgraded by Richard Gruet for Python 2.5

17 Feb 2005,

upgraded by Richard Gruet for Python 2.4

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.5 since 2.4
Features added in 2.4 since 2.3
Features added in 2.3 since 2.2
Features added in 2.2 since 2.1

• 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/   [Module index; Language Reference]
• Other doc & free books: FAQs, Faqts, Dive into Python, Python Cookbook, Thinking in Python, Text processing in Python
• Getting started: Official site, 7mn to Hello World (windows)
• Topics: Databases, Web programming, XML, Web Services, Parsers, Scientific Computing, GUI programming, Distributing
• Where to find packages: Easy Install, Python Package Index (PyPI), Vaults of Parnassus, SourceForge (search "python"), Python Eggs, 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, PEAK
• Python Development: http://www.python.org/dev/
• Jython - Java implementation of Python: http://www.jython.org/
• IronPython - Python on .Net: http://www.codeplex.com/Wiki/View.aspx?ProjectName=IronPython
• ActivePython: http://www.ActiveState.com/ASPN/Python/
• Help desk: help@python.org
• 2 excellent Python reference books: Python Essential Reference by David Beazley & Guido Van Rossum (Other New Riders) and Python in a nutshell by Alex martelli (O'Reilly).
• Python 2.4 Reference Card (cheatsheet) by Laurent Pointal, designed for printing (15 pages).
• Online Python 2.2 Quick Reference by the New Mexico Tech Computer Center.

Tip: From within the Python interpreter, type help, help(object) or help("name") to get help.

Invocation Options

python[w] [-dEhimOQStuUvVWxX?] [-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: IPython (enhanced interactive Python shell), Eric, SPE, BOA constructor, PyDev (Eclipse plugin).
• 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.
  
• It's now a syntax error if a module contains string literals with 8-bit characters but doesn't have an encoding declaration (was a warning before).
• Since 2.5, from __future__ import feature statements must be declared at beginning of source file.
• Site customization: File sitecustomize.py is automatically loaded by Python if it exists in the Python path (ideally located in ${PYTHONHOME}/lib/site-packages/).
• Tip: when launching a Python script on Windows,
  

  <pythonHome>\python myScript.py args ... can be reduced to :
  myScript.py args ... if <pythonHome> is in the PATH envt variable, and further reduced to :
  myScript args ... provided that .py;.pyw;.pyc;.pyo is added to the PATHEXT envt variable.

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

• (List of keywords available in std module: keyword)
• Illegitimate Tokens (only valid in strings): $ ? (plus @ before 2.4)
• 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 (since 2.2.1)

• True
• False

In 2.2.1, 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 (types str and unicode) 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', 'two': 2, key:value}

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.
• None is now a constant; trying to bind a value to the name "None" is now a syntax error.

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, long integers, Decimals.

• 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. Overflowing operations such as 2<<32 no longer trigger FutureWarning and return a long integer.
• Since 2.4, new type Decimal introduced (see module: decimal) to compensate for some limitations of the floating point type, in particular with fractions. Unlike floats, decimal numbers can be represented exactly; exactness is preserved in calculations; precision is user settable via the Context type [PEP 327].

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 j 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 cmp specifying a comparison function takings 2 list items and returning -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. Since 2.4, the cmp argument may be specified as a keyword, and 2 optional keywords args are added: key is a fct that takes a list item and returns the key to use in the comparison (faster than cmp); reverse: If True, reverse the sense of the comparison used.
  Since Python 2.3, the sort is guaranteed "stable". This means that two entries with equal keys will be returned in the same order as they were input. For example, you can sort a list of people by name, and then sort the list by age, resulting in a list sorted by age where people with the same age are in name-sorted order.
• (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) 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.
• (4) Never raises an exception if k is not in the map, instead 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 (types str & unicode)

• (1) Padding is done using spaces or the given character.
• (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) Default encoding is sys.getdefaultencoding(), can be changed via sys.setdefaultencoding(). 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'. See also module codecs.
• (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 maxCount is given, only the first maxCount occurrences are replaced.
• (10) If separator 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 mixes normal text with C printf format fields :

  %[flag][width][.precision] formatCode

  where formatCode is one of c, s, i, d, u, o, x, X, e, E, f, g, G, r, % (see table below).
• The flag characters -, +, blank, # and 0 are understood (see table below).
• Width and precision may be a * to specify that an integer argument gives the actual width or precision. Examples of width and precision :
  

  Examples

  Format string	Result
  '%3d' % 2	' 2'
  '%*d' % (3, 2)	' 2'
  '%-3d' % 2	'2 '
  '%03d' % 2	'002'
  '% d' % 2	' 2'
  '%+d' % 2	'+2'
  '%+3d' % -2	' -2'
  '%- 5d' % 2	' 2 '
  '%.4f' % 2	'2.0000'
  '%.*f' % (4, 2)	'2.0000'
  '%0*.*f' % (10, 4, 2)	'00002.0000'
  '%10.4f' % 2	' 2.0000'
  '%010.4f' % 2	'00002.0000'

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

String templating

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

Date/Time

• time: time access and conversions
• datetime: classes date, time, datetime, timedelta, tzinfo.

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 = l[0:2]    # equivalent to: first=l[0]; second=l[1]
[f, s] = range(2)    # equivalent to: f=0; s=1
c1,c2,c3 = 'abc'    # equivalent to: c1='a'; c2='b'; c3='c'
(a, b), c, (d, e, f) = ['ab', 'c', 'def']    # equivalent to: a='a'; b='b'; c='c'; d='d'; e='e'; f='f'


  Tip: x,y = y,x swaps x and y.
• (2) Multiple assignment possible:
  

  a = b = c = 0
list1 = list2 = [1, 2, 3]    # list1 and list2 points to the same list (l1 is l2)


• (3) Not exactly equivalent - a is evaluated only once. Also, where possible, operation performed in-place - a is modified rather than replaced.

Conditional Expressions

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.
  
• [PEP 352]: Exceptions can now be new-style classes, and all built-in ones are. Built-in exception hierarchy slightly reorganized with the introduction of base class BaseException. Raising strings as exceptions is now deprecated (warning).

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/directories can be nested. You address a module's symbol via [package.[package...].module.symbol.
[1.51: On Mac & Windows, the case of module file names must now match the case as used in the import statement]

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 funcName ([paramList]):
    suite

Creates a function object and binds it to name funcName.

paramList ::= [param [, param]*]
param ::= value | id=value | *id | **id

• Args are passed by value, so only args representing a mutable object can be modified (are inout parameters).
• Use return to return (None) from the function, or return value to return value. Use a tuple to return more than one value, e.g. return 1,2,3
• Keyword arguments arg=value specify a default value (evaluated at function def. time). They can only appear last in the param list, e.g. foo(x, y=1, s='')
• Pseudo-arg *args captures a tuple of all remaining non-keyword args passed to the function, e.g. if def foo(x, *args): ... is called foo(1, 2, 3), then args will contain (2,3).
• Pseudo-arg **kwargs captures a dictionary of all extra keyword arguments, e.g. if def foo(x, **kwargs): ... is called foo(1, y=2, z=3), then kwargs will contain {'y':2, 'z':3}. if def foo(x, *args, **kwargs): ... is called foo(1, 2, 3, y=4, z=5), then args will contain (2, 3), and kwargs will contain {'y':4, 'z':5}
• args and kwargs are conventional names, but other names may be used as well.
• *args and **kwargs can be "forwarded" (individually or together) to another function, e.g.
  def f1(x, *args, **kwargs):
  f2(*args, **kwargs)
• See also Anonymous functions (lambdas).

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): ...
  Creates a class object inheriting from both class1 and class2. Assigns new class object to name MyClass.

class MyClass: ...
  Creates a base class object (inheriting from nothing). Assigns new class object to name MyClass. Since 2.5 the equivalent syntax class MyClass(): ... is allowed.

class MyClass (object): ...
  Creates a new-style class (inheriting from object makes a class a new-style class -available since Python 2.2-). Assigns new class object to name MyClass.

• First arg to class instance methods (operations) is always the target instance object, called 'self' by convention.
• Special static method __new__(cls[,...]) called when instance is created. 1st arg is a class, others are args to __init__(), more details here
• 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.
• You can build a list or a tuple from an iterator, e.g. list(anIterator)
• Python implicitly uses 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 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. Fancier applications like nanothreads are also possible.
• In 2.2, the feature needs to be enabled by the statement: from __future__ import generators (not required since 2.3+)
• 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.
• 2.4 introduces generator expressions [PEP 289] similar to list comprehensions, except that they create a generator that will return elements one by one, which is suitable for long sequences :
    linkGenerator = (link for link in get_all_links() if not link.followed)
  for link in linkGenerator:
    ...process link...
  Generator expressions must appear between parentheses.
• [PEP342] Generators before 2.5 could only produce output. Now values can be passed to generators via their method send(value). yield is now an expression returning a value, so val = (yield i) will yield i to the caller, and will reciprocally evaluate to the value "sent" back by the caller, or None.
  Two other new generator methods allow for additional control:
  • throw(type, value=None, traceback=None) is used to raise an exception inside the generator (appears as raised by the yield expression).
  • close() raises a new GeneratorExit exception inside the generator to terminate the iteration.

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