A Python Bestiary

Itemizing Python Objects and Nuances

$Revision$ $Date$ [email protected]

Notable lexical entities

========================

Keywords

access and break class

continue def del elif

else except exec finally

for from global if

import in is lambda

not or pass print

raise return try while

String Literal Escapes

\newline Ignored (escape newline)

\\ Backslash (\) \e Escape (ESC) \v Vertical Tab (VT)

\' Single quote (') \f Formfeed (FF) \0XX char with

\" Double quote (") \n Linefeed (LF) octal value XX

\a Bell (BEL) \r Carriage Return (CR) \xXX char with

\b Backspace (BS) \t Horizontal Tab (TAB) hex value XX

Illegitimate Tokens (only valid in strings): @ $ ?

Operating environment (Unix)

Shell environment vars:

PYTHONPATH: dirs to be prepended to module search path; a la shell PATH

PYTHONSTARTUP: names path of file to be loaded on interactive startup

Internal (module sys) vars ('import sys' to refer to them):

argv - list of command and arguments passed to python script

builtin_module_names - list of names of modules compiled in to python

( exc_* values are set only during handling of a raised exception)

exc_type - type of exception being handled

exc_value - exception's parameter ('raise's 2nd arg)

exc_traceback - exception's traceback obj

exit(N) - exit from python with status N, by raising SystemExit

exitfunc - function hook, to be called on exit if set

last_type - type of last unhandled exception

last_value - value of last unhandled exception

last_traceback - traceback of last unhandled exception

modules - list of modules already loaded

path - list of strings specifying module-load search path

ps1='>>>' - string specifying primary prompt, iff interactive

ps2='...' - string specifying secondary prompt, iff interactive

settrace - system trace function, used by debuggers, etc

setprofile - system profile function

stdin - standard input file object

stdout - standard output file object

stderr - standard error file object

tracebacklimit=1000 - maximum number of traceback levels to print

Objects - behaviors, special attributes, operations, statements, etc

====================================================================

General object aspects

Boolean values and operators

False values: None, numeric zeros, empty sequences and mappings

True values: all other values

not X: if X is false then 1, else 0

( 'or', 'and' evaluate second arg only if necessary to determine outcome)

X or Y: if X is false then Y, else X

X and Y: if X is false then X, else Y

Special methods for any type (s: self)

id(obj) unique identifier for object (currently, its address)

__init__(s, args) object instantiation - see Classes, below

__del__(s) object demise

__repr__(s) repr() and `...` conversions

__str__(s) str() and 'print' statement

__cmp__(s) implements <, ==, >, <=, <>, !=, >=, is [not]

__hash__(s) hash() and dictionary operations

Special informative state attributes for some types:

X.__dict__ dict used to store object's writeable attributes

X.__methods__ list of X's methods; on many built-in types.

X.__members__ lists of X's data attributes

X.__class__ class to which X belongs

X.__bases__ tuple of X base classes

General Name Space behavior and binding

Name space search order: local, global, builtin

"global" name space = file = module

"local" name space = function or method

Code Block scopes (ns = name space, cb = containing block)

( global ns generally is containing module, unless overriden by args)

Code block type Local ns Notes

--------------- -------- -----

Module same as global ns

Script same as global ns global ns is __main__

Interactive cmd same as global ns global ns is __main__

Class def new ns

Function body new ns

'exec' string local ns of cb (or args)

'eval' string local ns of caller (or args)

'execfile' file local ns of caller (or args)

'input' expr local ns of caller

Binding operations and exceptions:

~ SyntaxError: on attempt to bind to literals or other non-bindables

~ NameError: on attempt to evaluate unbound atom

( for object attribute functions, obj: object, nm: string, val: any value)

getattr(obj, nm) get value of obj.nm

hasattr(obj, nm) true if obj has nm attribute

setattr(obj, nm, val) set obj.nm to val

assignment statement: targ1, targ2, ,,, = obj1, obj2, ,,,

deletion statement: del obj1, obj2, ...

for loop target identifiers, 'except' clauses (see Statements, below)

formal params (see Callables, below)

import statement (see Modules objects, below)

class and func defs (see Callables, below)

Name space linkage

global statement: global var, ... # Interpret 'var's as globals

X access statement: access ... # control inst and class vars access

@ Built-in Exceptions

AttributeError On attribute reference or assignment failure

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

IOError I/O-related I/O operation failure

ImportError On failure of `import' to find module or name

IndexError On out-of-range sequence subscript

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

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

MemoryError On recoverable memory exhaustion

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

OverflowError On excessively large arithmetic operation

RuntimeError Obsolete catch-all; define a suitable error instead

SyntaxError On parser encountering a syntax error

SystemError On non-fatal interpreter error - bug - report it

SystemExit On `sys.exit()'

TypeError On passing inappropriate type to built-in op or func

ValueError On arg error not covered by TypeError or more precise

ZeroDivisionError On division or modulo operation with 0 as 2nd arg

**** Numbers ****

@ Integers: 'C' long, >= 32 bits precision; OverflowError if bounds exceeded

@ Long Integers: unlimited precision - '2147483648L'

@ Floating point: machine double-precision floating point - '2147483648.0'

Numeric operations vs special methods (s = self, o = other)

s+o = __add__(s,o) s-o = __sub__(s,o)

s*o = __mul__(s,o) s/o = __div__(s,o)

s%o = __mod__(s,o) divmod(s,o) = __divmod__(s,o)

pow(s,o) = __pow__(s,o)

s&o = __and__(s,o)

s^o = __xor__(s,o) s|o = __xor__(s,o)

s<<o = __lshift__(s,o) s>>o = __rshift__(s,o)

nonzero(s) = __nonzero__(s) coerce(s,o) = __coerce__(s,o)

-s = __neg__(s) +s = __pos__(s)

abs(s) = __abs__(s) ~s = __invert__(s) (bitwise)

int(s) = __int__(s) long(s) = __long__(s)

float(s) = __float__(s)

oct(s) = __oct__(s) hex(s) = __hex__(s)

Numeric functions:

range(start=0,end,step=1) create arithmetic progression list

round(x, n=0) round floating point x to n decimal places

xrange(start=0,end,step=1) create virtual arithmetic progressions tuple

Numeric exceptions:

~ TypeError: raised on application of arithemetic opertion to non-number

~ OverflowError: numeric bounds exceeded

~ ZeroDivisionError: raised when zero second argument of div or modulo op

**** Collections - Sequences and Mappings ****

Collections general operations vs methods (s: self, i: index or key)

len(s) = __len__(s) length of object, >= 0. Length 0 == false

s[i] = __getitem__(s,i) Element at index/key i, origin 0

Sequences

@ String (immutable sequence): 'string contents'

'this is a string'

"and so is this"

''' and this begins a 'multi-line' string with embedded quotes...

and this is the end of that string.'''

`expr` = __repr__(expr), converts arbitrary expr to string

chr(int) string of ascii letter at ordinate in (0 <= int < 256)

ord(string) ascii ordinate of string (string must be length 1)

string % arg format operator, a la C sprintf

arg for single directive can be any (suitable) type

arg for multiple directives must be tuple or dict

dict (mapping) arg uses parenthesized directives that are keys into it

supports %, c, s, i, d, u, o, x, X, e, E, f, g, G directives

* can be width and precision; directs use of corresponding (int) args

* can not be used with dict args

flag characters -, +, blank, #, and 0 understood.

%s conversion takes any python object, converts using `str()'

ANSI directives %p and %n not supported

%s conversions do *not* take \000 as end of string

@ Tuples (immutable sequence): (oneelem, another, etc)

parens may be left off all but empty tuples

singletons represented by affixing a comma to an expr

empty tuple represented using empty parens

@ Lists (mutable sequence): [oneelem, another, etc]

assignment - must be 1-1 map of items in target and object sequences

deletion - similar rules as for assignment

List special methods: see mutable sequence ops vs methods, below

Sequences general ops vs methods (s: self, i,j: indices, v: val)

All collections general methods, plus:

s[i:j] __getslice__(s,i,j), all s[k] s.t. i <= k < j

min(s) smallest item of s

max(s) largest item of s

v [not] in s 1 if v [not] equal to an item in s, else 0

s + seq concatenation of s and seq

s * num num copies of s concatenated, also, `num * s'

Immutable sequence ops vs methods (s: self, i,j: indices, v: val)

All collections and sequences general methods, plus:

s[i:j] __getslice__(s,i,j), all s[k] s.t. i <= k < j

( For s[i:j], len(self) is intrinsically added to i, j < 0)

( Complex elems of immutable seqs may be mutable, see dictionaries, below)

Mutable sequence ops vs methods (s: self, i,j: indices, v: val)

All sequences' general methods, plus:

( for non-slice refs, i < 0 intrinsically has len(s) added)

( For slice refs, len(s) *is not* intrinsically added to i, j < 0)

( for assignment/deletion, index refs must point to existing items

s[i]=v = __setitem__(s,i,v)

del s[i] = __delitem__(s,i)

s[i:j] = __getslice__(s,i,j)

s[i:j]=seq = __setslice__(s,i,j,seq)

del s[i:j] = __delslice__(s,i,j) == s[i:j] = []

s.append(seq) == `s[len(seq):len(seq)] = seq' (but faster)

s.count(v) number of i's for which `s[i] == v'

s.index(v) first i such that `s[i] == v', or IndexError if none

s.insert(i, v) == `s[i:i] = [v]'

s.remove(v) == `del s[s.index(v)]', or IndexError if v not in s

s.reverse() reverse the items of s in place

s.sort() permute s items so s[i] <= s[j], for i < j

Mappings

@ Dictionaries: {key1: val1, key2: val2, ...}

built-in types as keys must be unalterable: obj & all contents immutable

User-defined classes as keys must have __hash__() and __cmp__() methods

~ TypeError is raised if key not acceptable

~ KeyError is raised if reference made using non-existent key

key types may vary (contrary to ref man)

Dictionaries ops vs methods (s: self, k: key, v: val)

all collections general ops, plus:

hash(s) = __hash__(s) - hash value for dictionary references

s[k]=v = __setitem__(s,k,v)

del s[k] = __delitem__(s,k)

s.items() = a list copy of s's (key, item) pairs

s.keys() = a list copy of s's keys

s.values() = a list copy of s's values

s.has_keys(k) = 1 if s has key k, else 0

( s.items, .keys, and .values yield random but mutually consistent order)

**** Callables ****

@ User defined functions: 'def name (param-list): suite'

suite is not evaluated at statement execution, but at function invocation

function parameters, comma separated on param-list:

func_code: special attr, code object representing compiled function body

func_globals: special attr, ref to global dict of funcs definition module

func(arg-list) invocation

@ User defined methods: like functions, with extra implicit arg

Same as functions, but passed class instance as additional first argument

im_self: special attr, method's class instance object

im_func: special attr, function object

mthd(args) invocation, same as mthd.im_func(mthd.im_self, args)

@ Classes: 'class name[ (inheritance)]: suite'

inheritance list is evaluated, if any, to identify base classes for name

suite is executed in new local name space, which goes to the class object

class name is bound in encompassing local name space

container for dictionary containing class's ns dictionary

__dict__: ro attr, class ns as dictionary object

__bases__: ro attr, class' base classes in tuple

__init__(self, args..): implements object instantiation

__del__(self): implements impending object deletion

@ Class instances

__dict__: ro attr, class' attribute dictionary

__class__: ro attr, instance's class object

Callables special method vs ops (f: function)

apply(f, args-tuple) call f with args-tuple as arg list

compile(str, flnm, kind) compile string into exectuable code object

eval(str, glbls=, lcls=) evaluate string as expression (cond_list)

filter(f, seq) => seq of seq elems for which f is true

map(f, lst, [lst2, ...]) => list of f applied to succesive lsts elems

reduce(f, lst, initlzr) => value of f applied to elems and cume result

@ **** Null object: `None' ****

@ **** Type objects, print as: <type 'int'> ****

( '<...>' form is only for printing - cannot be entered that way,

accessed via built-in func 'type()'

( equal only when identical (same id()),

so can't just use the string name, must use object with the same str val)

@ **** Modules ****

functions and methods in a module share module's ("global") namespace

function uses "global" statement to instantiate var in global context

Modules use "import" to incorp other module's names - see Name Spaces

Special attrs, methods, and operations

__dict__: attr, module's ns as dictionary; can modify vals but not sruct

__name__: ro attr, module's name as string

import Instantiate module or module components within another

reload(amod) Reread an imported module

@ **** Files ****

wrapper around a C stdio file pointer

sys.stdin, sys.stdout, sys.stderr are standard io-stream file objects

File operations:

open(nm, mode='r', bufsize=sysdef) return new file object

close() A closed file cannot be read or written anymore.

flush() Flush the internal buffer, like stdio's `fflush()'.

isatty() 1 if file connected to a tty(-like) device, else 0.

read(SIZE) Read up to SIZE bytes frm file, less on EOF or no data

readline() Read one entire line from the file.

readlines() `readline()' til EOF and return list of lines read.

seek(OFFSET,WHENCE) Set file's current position, like stdio's `fseek()'

tell() Return file's current position, like stdio's `ftell()'.

write(STR) Write a string to the file. There is no return value.

File functions:

input(prompt='') like raw input but accept '\' line continuations

print exp, exp2, ... Write values to stdout

raw_input(prompt='') prompt then read single line of input

**** Internal types ****

@ Code objects - represent exectuable code - function obj sans context

@ Frame objects - represent executable frames - may occur in traceback objs

@ Traceback objects - stack trace of an exception

Control statements

==================

* Calls and Evaluation *

( See also Callables, in Objects section above, for ops and methods.)

exec: exec expr [ in expr2 [, expr3]] # Dynamic execution of python code

return: return [expr] # Leave current func call with expr value

* Conditionals and Loops *

( See also Boolean values, above)

break: break # Terminate nearest enclosing loop

continue: continue # Continue next cycle of enclosing loop

if: if cond: suite [\n elif cond: suite \n ...] [\n else: suite]

for: for targs in conds: suite [ \n else: suite ]

while: while cond: suite [ \n else : suite ]

* Exceptions *

raise: raise expr [, expr2] # Raise exception expr, passing expr2 if any

try... # Handle exceptions:

try: suite [\n except [cond [, targ]]: suite \n ... \n] [else: suite]

try: suite \n finally: suite # Specify a 'cleanup' handler

( two 'try' forms cannot be mixed together)

System modules

==============

@ * Built-ins *

sys Interpreter state (see Operating Environment, above)

__builtin__ 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

strop Miscellaneous string operations

struct Convert between python values and C structs

@ * Standard *

getopt Parse cmd line args in sys.argv. A la UNIX 'getopt'.

os Portable interface to OS dependent functionality

pdb text-oriented debugger

rand Pseudo-random generator, like C rand()

regsub Functions useful for working with regular expressions

string Useful string and characters functions and exceptions

wdb window-oriented debugger

whrandom Wichmann-Hill pseudo-random number generator

@ * Miscellaneous *

dis Python disassembler

glob Filename globbing (a la unix shell)

grep File string search

posixpath Common operations on POSIX pathnames

profile Python code profiler

repr `...` repr operator with presentation constraints

string All of builtin 'strop', plus

tb Traceback browser and printer

tempfile Produce a temporary-file name

util Miscellaneous functions that don't belong elsewhere

@ * Unix *

dbm Dict/file-like interface to Unix ndbm database library

grp Interface to Unix group database

posix Standardized UNIX OS functionality - see 'os', above

posixpath POSIX pathname functions - see 'os', above

pwd Access to the Unix password database

select Access to Unix select multiplex file synchronization

socket Access to BSD socket interface

thread Low-level primitives for working with process threads

@ * 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

@ * Contrib *

syslog

metalbase

Idioms and hints

================

Invoke main if running as script: if __name__ == '__main__': main()

General object-type miscellany

What type is someobj; eg, a list: if type(someobj) == type([]):

Convert number to hex or octal string: hex(122) => '0x7a'

Convert string to number: eval('0x7a') => 122

Sequence Slice conceptualization:

+---+---+---+---+---+ Indices point ~between~ chars:

| s | t | u | f | f | - first char's left edge = 0,

+---+---+---+---+---+ - nth char's right edge = n.

0 1 2 3 4 5 (Note that -0 == 0, so it does

-5 -4 -3 -2 -1 not count from right.)

Sequences miscellany:

Create merge of lists: map(None, lst1, lst2, ...)

It's faster to list.append(elem) than to list[len(list):] = [elem]

Copy structure of seq a to b: b = a[:]

Comma (tuple vs expression grouping) nuances:

to specify a tuple of one element: ('element',)

to specify a tuple containing 1 tuple: (('contained', 'tuple'),)

"TypeError: call of non-function" often means a list missing a comma

Namespace and object surveillance:

get dictful object keys/key-vals: dir(), vars()

Current context globals: eval(__name__ + '.__dict__')

Current context locals: vars()

Methods supported by X (some objs): X.__methods__

X's data attributes (some objs): X.__members__