| A Python Bestiary | |
| Itemizing Python Objects and Nuances | |
| $Revision$ $Date$ ken.manheimer@nist.gov | |
| 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__ |