mirror of
https://github.com/python/cpython.git
synced 2025-10-31 10:26:02 +00:00
541 lines
22 KiB
Text
541 lines
22 KiB
Text
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__
|