Python 2.4 Quick Reference Card Styles : keyword function/method type replaced_expression Types basestring1 bool buffer complex dict exception file float ©2005-2007 — Laurent Pointal — License CC [by nc sa] variable literal module module_filename language_syntax Notations : frozenset int list long object set slice str tuple type unicode xrange CARD CONTENT f(…)→ return value f(…)➤ return nothing (procedure) 1 basestring is virtual superclass of str and unicode. [x] for a list of x data, (x) for a tuple of x data, may have x{n}→ Environment Variables...... 1 Copying Containers...... 8 This doc uses string when unicode and str can apply. Command-line Options...... 1 Overriding Containers Operations...... 8 n times x data. Files Extensions...... 1 Sequences...... 8 Functions Language Keywords...... 1 Lists & Tuples...... 8 ENVIRONMENT VARIABLES Constructor functions of builtin types are directly accessible in Builtins...... 1 Operations on Sequences...... 8 1 Types...... 1 Indexing...... 8 PYTHONCASEOK no case distinction in module→file mapping builtins. 1 1 Functions...... 1 Operations on mutable sequences...... 8 PYTHONDEBUG = -d command-line option __import__ abs apply callable chr classmethod cmp coerce Statements...... 1 Overriding Sequences Operations...... 8 PYTHONHOME Modify standard Python libs prefix and exec compile delattr dir divmod enumerate eval execfile Blocks...... 1 Mappings (dictionaries)...... 8 prefix locations. Use [:]. filter getattr globals hasattr hash help hex id input 2 Assignment Shortcuts...... 1 Operations on Mappings...... 8 PYTHONINSPECT 1 = -i command-line option intern isinstance issubclass iter len locals map max min Console & Interactive Input/Output.... 2 Overriding Mapping Operations...... 8 PYTHONOPTIMIZE 1 = -O command-line option oct open ord pow property range raw_input reduce reload Objects, Names and Namespaces...... 2 Other Mappings...... 9 repr reversed round setattr sorted staticmethod sum Identifiers...... 2 Sets...... 9 PYTHONPATH Directories where Python search when importing modules/packages. Separator : super unichr vars zip Objects and Names, Reference Operations on Sets...... 9 1 Counting...... 2 Other Containers Structures, (posix) or ; (windows). Under windows use Use f(*args,**kargs) in place of apply(f,args,kargs). 2 Mutable/Immutable Objects...... 2 Algorithms...... 9 registry HKLM\Sofware\…. Don't use intern. Namespaces...... 2 Array...... 9 PYTHONSTARTUP File to load at begining of interactive sessions. Constants, Enumerations...... 2 Queue...... 9 STATEMENTS PYTHONUNBUFFERE 1 = -u command-line option Flow Control...... 2 Priority Queues...... 9 One statement per line1. Can continue on next line if an expression Condition...... 2 Sorted List...... 9 D Loop...... 2 Iteration Tools...... 9 PYTHONVERBOSE 1 = -v command-line option or a string is not finished ( ( [ { """ ''' not closed), or with a \ at Functions/methods exit...... 2 Date & Time...... 9 1 If set to non-empty value. end of line. Exceptions...... 2 Module time...... 9 Char # start comments up to end of line. Iterable Protocol...... 2 Module datetime...... 10 COMMAND-LINE OPTIONS Interpretation / Execution...... 2 Module timeit...... 10 pass Null statement. Functions Definitions & Usage...... 2 Other Modules...... 10 python [-dEhiOQStuUvVWx] [-c cmd | -m mod | file | -] [args] assert expr[,message] Assertion check expression true. Parameters / Return value...... 2 Files...... 10 -d Output debugging infos from parser. del name[,…] Remove name → object binding. Lambda functions...... 2 File Objects...... 10 -E Ignore environment variables. print [>>obj,][expr[,…][,] Write expr to sys.stdout2. Callable Objects...... 2 Low-level Files...... 10 -h Print help and exit. Calling Functions...... 3 Pipes...... 10 exec expr [in globals [, Execute expr in namespaces. -i Force interactive mode with prompt (even after script locals]] Functions Control...... 3 In-memory Files...... 10 execution). Decorators...... 3 Files Informations...... 11 fct([expr[,…]], Call any callable object fct with given -O Optimize generated bytecode, remove checks. Types/Classes & Objects...... 3 Terminal Operations...... 11 assert [ n ame = expr [,…]] arguments (see Functions Definitions -OO As -O and remove documentation strings. Class Definition...... 3 Temporary Files...... 11 [,*args][,**kwargs]) & Usage - p2). Object Creation...... 3 Path Manipulations...... 11 -Q arg Division option, arg in [old(default),warn,warnall,new]. name[,…] = expr Assignment operator3. Classes & Objects Relations...... 3 Directories...... 11 -S Don't import site.py definitions module. Attributes Manipulation...... 3 Special Files...... 12 -t Warn inconsistent tab/space usage (-tt exit with error). 1 Multiple statements on same line using ; separator - avoid if not Special Methods...... 3 Copying, Moving, Removing...... 12 -u Use unbuffered binary output for stdout and stderr. necessary. Descriptors protocol...... 3 Encoded Files...... 12 2 Copying Objects...... 3 Serialization...... 12 -U Force use of unicode literals for strings. Write to any specified object following file interface (write Introspection...... 3 Persistence...... 12 -v Trace imports. method). Modules and Packages...... 3 Configuration Files...... 12 -V Print version number and exit. Write space between expressions, line-return at end of line except Source encodings...... 3 Exceptions...... 12 -W arg Emit warning for arg with a final ,. Special Attributes...... 3 Standard Exception Classes...... 12 "action:message:category:module:lineno" 3 Left part name can be container expression. If expr is a sequence Main Execution / Script Parameters.... 4 Warnings...... 13 Operators...... 4 Exceptions Processing...... 13 -x Skip first line of source (fort non-Unix forms of #!cmd). of multiple values, can unpack into multiple names. Can have Priority...... 4 Encoding - Decoding...... 13 -c cmd Execute cmd. multiple assignments of same value on same line : a = b = c = Arithmetic Operators...... 4 Threads & Synchronization...... 13 -m mod Search module mod in sys.path and runs it as main script. expr. Comparison Operators...... 4 Threading Functions...... 13 file Python script file to execute. Other statements (loops, conditions…) introduced in respective Operators as Functions...... 4 Threads...... 13 args Command-line arguments for cmd/file, available in parts. Booleans...... 4 Mutual Exclusion...... 13 sys.argv[1:]. Numbers...... 4 Events...... 13 Blocks Operators...... 4 Semaphores...... 13 FILES EXTENSIONS A : between statements defines dependant statements, written on Functions...... 4 Condition Variables...... 13 same line or written on following line(s) with deeper indentation. Bit Level Operations...... 5 Synchronized Queues...... 13 .py=source, .pyc=bytecode, .pyo=bytecode optimized, .pyd=binary Blocks of statements are simply lines at same indentation level. Operators...... 5 Process...... 13 module, .dll/.so=dynamic library. Strings...... 5 Current Process...... 13 if x<=0 : return 1 .pyw=source associated to pythonw.exe on Windows platform, to Escape sequences...... 5 Signal Handling...... 14 if asin(v)>pi/4 : Unicode strings...... 5 Simple External Process Control...... 14 run without opening a console. a = pi/2 Methods and Functions...... 5 Advanced External Process Control.... 15 b = -pi/2 ANGUAGE EYWORDS Formating...... 6 XML Processing...... 15 L K else : Constants...... 6 SAX - Event-driven...... 15 List of keywords in standard module keyword. a = asin(v) Regular Expressions...... 6 DOM - In-memory Tree...... 16 and as1 assert break class continue def del elif else b = pi/2-a Localization...... 7 Databases...... 17 Multilingual Support...... 7 Generic access to DBM-style DBs...... 17 except exec finally for from global if import in is Statement continuation lines don't care indentation. Containers...... 8 Standard DB API for SQL databases....17 lambda not or pass print raise return try while yield To avoid problems, configure your editor to use 4 spaces in place Operations on Containers...... 8 Bulk...... 18 1 not reserved, but avoid to redefine it. of tabs. Don't redefine these constants : None, True, False. Assignment Shortcuts BUILTINS a += b a -= b a *= b a /= b a //= b a %= b a **= b Available directly everywhere with no specific import. Defined also a &= b a |= b a ^= b a >>= b a <<= b in module __builtins__. Evaluate a once, and assign to a the result of operator before =

1a 1b 1c applied to current a and b. Example : a%=b ≈ a=a%b globals() → dict: identifier→value of global namespace iter(callable,sentinel) → iterator returning callable() values up to locals() → dict: identifier→value of local namespace sentinel CONSOLE & INTERACTIVE INPUT/OUTPUT Current scope → names directly usable. Searched in locals, then enumerate(iterable)→ iterator returning tuples (index,value) from iterable print expression[,…] locals from enclosing definitions, then globals, then builtins. Iterators Objects Interface input([prompt]) → evaluation of user input (typed data) Out-of-scope name → use the dotted attribute notation x.y (maybe next(self)→ next item1 raw_input([prompt]) → str: user input as a raw string x.y.z.t)… where x is a name visible within the current scope. __iter__(self)→ iterator object itself Direct manipulation (redefinition) of stdin/stdout/stderr via sys 1 module : Class namespace → names defined in a class (class members). When reach end of collection, raise StopIteration exception on sys.stdin sys.stdout sys.stderr Object namespace → names usable with object.name notation subsequent calls (ie. iterator usable only one time on a collection). sys.__stdin__ sys.__stdout__ sys.__stderr__ (attributes, methods). Generators All are files or files-like objects. The __xxx__ forms keep access to Namespaces can be nested, inner namespaces hidding identical Functions retaining their state between two calls. Return values original standard IO streams. names from outer namespaces. using yield. Stop generation via simple return or via raise [object] → : names defined in object namespace1 Ctrl-C raises KeyboardInterrupt exception. dir( ) list StopIteration. [object] → 2: identifier:value of object as a namespace1 _ → value of last expression evaluation vars( ) dict 1) build generator from function : gen=generatorfct(args) help([object]) ➤ print online documentation 1 if object not specified use nearest namespace (locals). 2 2) use gen.next() values until StopIteration is raised. sys.displayhook → (rw) fct(value) called to display value must not be modified. Generator iterable expressions with : (x for x in iterable where sys.__displayhook__ → backup of original displayhook function Constants, Enumerations cond) sys.ps1 → str: primary interpreter prompt Use uppercase and _ for constants identifiers (good practice). May sys.ps2 → str: secondary (continuation) interpreter prompt define namespaces to group constants. Cannot avoid global/local Operations with/on Iterable See external package ipython for an enhanced interactive Python name redefinition (can eventually define namespaces as classes See Operations on Containers (p8). shell. with attributes access control - not in Python spirit, and execution cost). See Iteration Tools (p9). OBJECTS, NAMES AND NAMESPACES See third party modules for strict enum-like namespace. pyenum INTERPRETATION / EXECUTION Identifiers FLOW CONTROL compile(string1,filename,kind2[,flags3[,dont_inherit3]]) → code object Use : [a-zA-Z_][a-zA-Z0-9_]* eval(expression[,globals[,locals]]) → value: evaluation4 of expression Condition Loop Special usage for underscore : string _xxx global not imported by import * if cond : inst for var[,…] in iterable : inst eval(code_object[,globals[,locals]]) → value: evaluation4 of code_object _xxx implementation detail, for internal use (good [ elif cond : inst ] [ else : inst ] exec5 statements [in globals[,locals]] ➤ statements string1 executed4 practice) [ else : inst ] filename[ globals[ locals]] ➤ file filename interpreted4 while cond : inst execfile( , , ) __xxx 'private' class members, defined as 1 There is no 'switch' or [ inst ] Multi-line statements in source code must use \n as newline, and _ClassName__xxx else : 'case'. must be terminated by a newline. __xxx__ normally reserved by Python Exit loop with break. Can use if elif elif… else. 2 Kind relative to string content, 'exec' → sequence of statements, Case is significant : This_Name != THIS_NAME. Can use a mapping with Go to next iteration with continue. 'eval' → single expression, 'single' → single interactive functions bound to cases. Objects and Names, Reference Counting Loops else blocs only executed when statement. Data are typed objects (all data), names are dynamically bound to loop exit normally (without break). 3 Flags and dont_inherit are for future statements (see doc). 4 objects. Functions/methods exit In context of globals and locals namespaces. assignment statement bind result of right part evaluation into left 5 Exec is a langage statement, others are builtin functions. = Exit function/method with return [value] part name(s)/container(s). Examples : Exit from generator body with yield value a = 3*c+5 a,b = ("Hello","World") x,y,tabz[i] = fct(i) FUNCTIONS DEFINITIONS & USAGE Multiple returned values using tuple data. s = "Hello" pi,e = 3.14,2.71 a,b = b,a def fctname([ p aramname [ = defau ltvalue ] [,…]] [,*args][,**kwargs]) : Cannot yield within a try/finally block. When an object is no longer referenced (by names or by instructions Exceptions containers), it is destroyed (its __del__ method is then called). new.function(code,globals[,name[,argdefs]]) → python function (see try : inst docs) sys.getrefcount(object)→ int: current reference counter of object except [ excep t_class [ , valu e ]] : ins t Parameters / Return value Standard module weakref define tools to allow objects to be … Parameters are passed by references to objects. garbage collected when necessary and dynamically re-created on- [ else : inst ] You can modify values of mutable objects types. demand. Can have a tuple of classes for except_class. Not specifying a class You cannot modify values of immutable objects types - as if they catch all exceptions. Mutable/Immutable Objects were passed by value. Block executed when block exit normally. Mutable objects can be modified in place. Immutable objects cannot else try Notation * → variable list of anonymous parameters in a tuple. be modified (must build a new object with new value). try : inst Notation ** → variable list of named parameters in a dict. Immutable : bool, int, long, float, complex, string, unicode, finally : inst Return value(s) with return [value[,…]] tuple, frozenset, buffer, slice. Process finally block in all execution paths (normal or exception). For multiple values, return a tuple. If no return value specified or if Mutable : list, set, dict and other high level class objects. raise exception_class[,value[,traceback]] end of function definition reached, return None value. There is no constant definition. Just use uppercase names to identify raise exception_object Lambda functions symbols which must not be modified. raise lambda param[,…] : expression Namespaces Last form re-raise the currently catched exception in an exception Anonymous functions defined inline. Result of expression evaluation Places where Python found names. handler. is returned (it must be an expression, no loop, no condition). Builtins namespace → names from module __builtins__, already Iterable Protocol Expression uses values known at definition time (except for available. Generic and simple protocol allowing to iterate on any collection of params). Global namespace → names defined at module level (zero data. Callable Objects indentation). Objects of class defining __iter__ or __getitem__ are iterable Local namespace → names defined in methods/functions. Objects having a __call__ method can be used as functions. (directly usable in for loops). Methods bound to objects can be used as functions : f = o.meth name ➤ remove existing name from namespace (remove object del __iter__(self) → iterator on self callable(x) → bool: test x callable with x(…) binding) iter(object) → iterator on iterable object 2a 2b 2c Calling Functions Attributes Manipulation default values are None and empty list. [name=] fctname([expr[,…]][,name=expr[,…][,*args][,**args]) object.name = value Copy Protocol Anonymous parameters passed in parameters order declaration. setattr(object,name,value) ➤ object attribute set to value __copy__(self)→ value: shallow copy of self, called by Params having default value can be omitted. object.name → value of object attribute copy.copy(…) Notation * → pass variable list of anonymous parameters in a getattr(object,name[,default])→ value of object attribute __deepcopy__(self,memo)→ value: deep copy of self, called by tuple. del object.name copy.deepcopy(…) Notation ** → pass variable list of named parameters in a dict. object name ➤ object attribute removed delattr( , ) For copying, objects can define pickling protocol too (see Files - Functions Control Special Methods Serialization - p12), in place of __copy__ and __deepcopy__. → : current recursion limit for functions sys.getrecursionlimit() int Other special overridable __xxx___ methods are listed in respective Introspection sys.setrecursionlimit(limit) ➤ set recursion limit for functions sections. Beyond this documentation. Many __xxx___ attributes are defined, Decorators Object Life some are writable (see other docs). Glue code (functions) called at functions and methods definitions __new__(classref,initargs…)→ object of classref type, already See standard module inspect to manipulate these data. time, return the final function/method (generally with wrapping 1 initialized Example of Introspection Attributes code). __init__ (self,initargs…)➤ called to initialize object with initargs Note: classes are objects too! @ de coratorname [ ( de corator_arguments ) ] […] __del__ (self)➤ called when object will be destroyed __base__ → list: parent classes of a class def fct(fct_rguments):… 1 If don't return a classref object, then object.__init__ is called with __slots__ → tuple: allowed objects attributes names1 of a class @dec1 @dec2(args) @dec3 def fct(…):… initargs. __class__ → class/type: object's class def fct(…):… like fct = dec1(dec2(args)(dec3(fct)))) Object Cast ➤ __dict__ → dict: defined attributes (object namespace) of an instance See page PythonDecoratorLibrary in python.org Wiki for some __repr__(self)→ str: called for repr(self) and `self` __doc__ → string: documentation string of a package, module, class, decorators definitions. __str__(self) → str: called for str(self) and print self function __coerce__(self,other) → value, called for coerce(self,other) __name__ → str: object definition name of a function TYPES/CLASSES & OBJECTS __file__ → string: pathname of loaded module .pyc, .pyo or .pyd Object Hash Key 1 All data are typed objects relying to classes. List of allowed attributes names. Usage discouraged. __hash__(self)→ int: 32 bits hash code for object, used for type(o) → type: type object of o hash(obj)and quick dict mapping keys comparison - default Standard module types define type objects for builtins types. implementation use hash(id(self)) MODULES AND PACKAGES Class Definition Attributes access File gabuzo.py ➤ module gabuzo. class classname [(parentclass[,…])] : Directory kramed/ with a file __init__.py ➤ package . See also "Descriptors protocol" infra. kramed varname = expr ➤ varname defined in classname namespace Can have sub-packages (subdirectories having __init__.py file). __getattr__(self,name)→ value, called for undefined attributes def metname(self[,…]): ➤ define methods like functions Searched in the Python PATH. __getattribute__(self, name)→ value, always called Support multiple inheritance. Can inherit from builtin class. Current Python PATH stored in sys.path list. Contains directories __setattr__(self, name, value) ➤ called for obj.name=value Inherit at least from object base class => Python 'new style class'. and .zip files paths. Built from location of standard Python modules, __delattr__(self, name) ➤ called for del obj.name First parameter of methods is target object, standard use self PYTHONPATH environment variable, directory of main module given name. __call__(self, *args, **kwargs)→ value, called for obj(…) on command line, data specified in lines of .pth files found in Python Access class members via class name, object members via self. Static method / Class method home directory, and data specified in registry under Windows. This doc consider you use new style class (inheriting from object). Use standard decorators (see Decorators p3). Current list of loaded modules stored in sys.modules map (main new.classobj(name,baseclasses,dict) → new class (see docs) class ClassName : module is under key __main__). new.instancemethod(fct,instance,class) → new method: bound to @staticmethod import modul e [ as a lias ] [,…] instance it it is not None, see docs def methodname(…): … from module import name [ as al ias ] [,…] Metaclass @classmethod from module import * def methodname(classref,…): … reload(module) ➤ module is reloaded (but existing references still refer Class definition create a new type. It can be done 'by hand' with : old module content) x = type('classname',( par entclass , […]),{varname:expr[,…]} Descriptors protocol new.module(name[,doc]) → new module object. def metname(self[,…]): Descriptors are attribute objects controling access to attributes Import can use package path (ex:from encoding.aliases x.metname = metname values. They must define some of following methods : import…). This allow creation of metaclass class (class building other class). __get__(self,obj,ownerclass)→ attribute value for obj Direct import from a package use definitions from __init__.py file. __set__(self,obj,value) ➤ modify attribute in obj, set to value Object Creation Very careful with import * as imported names override names __delete__(self,obj) ➤ remove attribute from obj obj = ClassName(initargs…) already defined. In these methods self is the descriptor object, and obj is the target In case of exception during initialization, object is destroyed when To limit your modules names exported and visible by import *, object which attribute is manipulated. exiting init code (reference counter reach zero). define module global __all__ with list of exported names (or use new.instance(class[,dict]) → object: create new class instance without Properties global names _xxx). calling __init__ method, dict is initial object attributes A descriptor to directly bind methods/functions to control attribute See __import__ builtin function, and modules imp, ihooks. Classes & Objects Relations access. Use builtin type property with init args. __import__(modulename[, globals[,locals[,lnameslist]]]) isinstance(obj,classinfo) → bool: test object kind of type/class class MyClass : Source encodings classinfo attributename = property(getter,setter,deleter,description) See PEP 263. Declare source files encoding in first or second line in issubclass(aclass,aparent) → bool: test same class or parent Each init arg default to None (ie. undefined). a special comment. relationship Copying Objects # -*- coding: encoding_name -*- Prefer isinstance() to type() for type checking. Assignment only duplicate references. To shallow copy an object If this is not specified, Python use sys.getdefaultencoding() Parent class methods are not automatically called if overriden in (build a new one with same values - referencing same content), or value (see modules sitecustomize.py and user.py). subclass - they must be explicitly called if necessary. to deep copy an object (deep-copying referenced content), see It is important to specify encoding of your modules as u"…" strings Call parent methods via super function : object copy methods, and functions in standard module copy. use it to correctly build unicode literals. super(ThisClass,self).methodname(self,args…) copy.copy(object)→ value: shallow copy of object Special Attributes 1 Or the old way, via parent class namespace : copy.deepcopy(object[[,memo],_nil])→ value: deep copy of object __name__ → str: module name, '__main__' for command-line called 1 ParentClass.methodname(self,args…) Params memo and nil are used in recursive deepcopy, their script 3a 3b 3c __file__ → string: pathname of compiled module loaded xt. True : if not false. True → 1. Builtin function cmp(o1,o2) → -1 (o1 < o2), 0 (o1 == o2), 1 (o1 > o2) bool(expr) → True | False MAIN EXECUTION / SCRIPT PARAMETERS Comparison Overriding Logical not : not expr The 'main' module is the module called via command-line (or 1 Logical and : expr1 and expr2 executed by shell with first script line #! /bin/env python). __lt__(self, other)→ bool : called for self < other 1 Logical or : expr1 or expr2 Command-line parameters are available in sys.argv (a python __le__(self, other)→ bool : called for self <= other 1 Logical and and or use short path evaluation. list). __gt__(self, other)→ bool : called for self > other 1 Bool Cast Overriding At end of module, we may have : __ge__(self, other)→ bool : called for self >= other 1 1 if __name__=='__main__' : __eq__(self, other)→ bool : called for self == other __nonzero__(self) → bool: test object itself # main code __ne__(self, other)→ bool1: called for self != other 1 If __nonzero__ undefined, look at __len__, else object is true. # generally call a 'main' function: and for self <> other UMBERS mainfunction(sys.argv[1:]) __cmp__(self,other)→ int: called for self compared to other, N # or in lib modules, execute test/demo code... selfother→value>0 Builtin integer types : int (like C long), long (unlimited integer) 1 Execution exit after last main module instruction (in multithread, Any value usable as boolean value, or a NotImplemented value if int(expr[,base=10]) → int: cast of expr wait also for end of non-daemon threads), unless interactive mode cannot compare with such other type. long(expr[,base=10]) → long: cast of expr is forced. Operators as Functions Builtin floating point types : float (like C double), complex (real and imaginary parts are float). Can force exit with calling sys.exit(code), which raise a Operators are also defined as functions in standard operator expr → : representation of expr SystemExit exception - see Current Process - Exiting (p13). module. float( ) float complex(x[,y]) → complex: number: x+yj OPERATORS Comparison [x+]yj → complex: number, ex: 3+4j -8.2j Deal with arithmetic, boolean logic, bit level, indexing and slicing. lt(a,b) = __lt__(a,b) ne(a,b) = __ne__(a,b) c.real → float: real part of complex number Priority le(a,b) = __le__(a,b) ge(a,b) = __ge__(a,b) c.img → float: imaginary part of complex number eq(a,b) = __eq__(a,b) gt(a,b) = __gt__(a,b) c.conjugate() → complex: conjugate of complex number (real,-img) 1 ( a , … ) [ a , … ] 6 x + y 11 x < y x <= y x > y x >= y x == y x != y Logical / Boolean Maximum int integer in sys.maxint. { a : b , … } ` … ` x - y x <> y x is y x is not y x in s Automatic conversions between numeric types. x not in s not_(o) = __not__(o) and_(a,b) = __and__(a,b) Automatic conversions from int to long when result overflow max 2 s [ i ] s [ i : j ] 7 x<> y is_( , ) xor( , ) __xor__( , ) Direct conversions from/to strings from/to int, long… via types is_not(a,b) constructors. 3 + x - x ~ x 8 x & y 13 x and y Arithmetic Type Decimal defined in standard module decimal. 4 x ** y 9 x ^ y 14 x or y Base fixed type compact storage arrays in standard module array. abs(o) = __abs__(o) truediv(a,b) = __truediv__(a,b) 5 x * y x / y x % y 10 x | y 15 lambda args : expr add(a,b) = __add__(a,b) floordiv(a,b) = __floordiv__(a,b) Operators Arithmetic Operators sub(a,b) = __sub__(a,b) neg(o) = __neg__(o) -x +x x+y x-y x*y x/y 1 x//y 1 x%y 2 x**y 2 1 Can be defined for any data type. mul(a,b) = __mul__(a,b) pos(o) = __pos__(o) With from __future__ import division, / is true division a b = a b a b = a b (1/2→0.5), and // is floor division (1//2→0). Else for integers / is Arithmetic Overriding div( , ) __div__( , ) pow( , ) __pow__( , ) mod(a,b) = __mod__(a,b) still floor division. __add__(self,other) → value: called for self + other 2 is remainder operator, is power elevation operator (same as Bit Level % ** __sub__(self,other) → value: called for self - other pow). __mul__(self,other) → value: called for self * other lshift(a,b) = __lshift__(a,b) Functions __div__(self,other) → value: called1 for self / other rshift(a,b) = __rshift__(a,b) Some functions in builtins. __truediv__(self,other) → value: called2 for self / other inv(o) = invert(o) = __inv__(o) = __invert__(o) abs(x) → absolute value of x __floordiv__(self,other) → value: called for self // other Sequences x y → x/y x%y __mod__(self,other) → value: called for self % other divmod( , ) ( , ) concat(a,b) = __concat__(a,b) integer → : octal representation of integer number __divmod__(self,other) → value: called for divmod(self,other) oct( ) str contains(a,b) = __contains__(a,b) integer __pow__(self,other) → value: called for self ** other hex( ) → str: hexadecimal representation of integer number countOf(a,b) __nonzero__(self)→ value: called for nonzero(self) Representation formating functions in strings Formating (p6) and indexOf(a,b) Localization (p7). __neg__(self) → value: called for -self repeat(a,b) = __repeat__(a,b) __pos__(self) → value: called for +self Math Functions setitem(a,b,c) = __setitem__(a,b,c) __abs__(self) → value: called for abs(self) getitem(a,b) = __getitem__(a,b) Standard floating point functions/data in standard math module. __iadd__(self,other) ➤ called for self += other delitem(a,b) = __delitem__(a,b) acos(x) → float: radians angle for x cosinus value : [-1…1] →[0…π] __isub__(self,other) ➤ called for self -= other setslice(a,b,c,v) = __setslice__(a,b,c,v) asin(x) → float: radians angle for x sinus value : [-1…1] →[-π/2…+π/2] __imul__(self,other) ➤ called for self *= other getslice(a,b,c) = __getslice__(a,b,c) atan(x) → float: radians angle for x tangent value : [-∞…∞] →]-π/2… __idiv__(self,other) ➤ called1 for self /= other delslice(a,b,c) = __delslice__(a,b,c) +π/2[ other ➤ called2 for other __itruediv__(self, ) self /= atan2(x,y) → float: randians angle for x/y tangent value __ifloordiv__(self, other) ➤ called for self //= other Type Testing ceil(x) → float: smallest integral value >= x __imod__(self,other) ➤ called for self %= other These functions must be considered as not reliable. cos(x) → float: cosinus value for radians angle x __ipow__(self,other) ➤ called for self **= other isMappingType(o) 1 2 cosh(x) → float: hyperbolic cosinus value for radians angle x without / with from __futur__ import division isNumberType(o) x x Binary operators __xxx__ have also __rxxx__ forms, called when isSequenceType(o) exp( ) → float: exponential of x = e target object is on right side. fabs(x) → float: absolute value of x Attribute and Item Lookup x → : largest integral value <= x Comparison Operators floor( ) float attrgetter(attr) → fct: where fct(x)→x.attr x y → : modulo = remainder of x/y Operators can compare any data types. fmod( , ) float itemgetter(item) → fct: where fct(x)→x[item] x Compare values with < <= > >= == != <>. frexp( ) → (float,int): (m,y) m mantissa of x, y exponent of x — where x=m*2y Test objects identity with is and is not (compare on id(obj)). BOOLEANS i Direct composition of comparators is allowed in expressions : ldepx(x,i) → float: x multiplied by 2 raised to i power: x * 2 False : None, zero numbers, empty containers. False → 0. log(x) → float: neperian logarithm of x 4a 4b 4c log10(x) → float: decimal logarithm of x Advanced binary structures mapping and manipulation in third decimal(unichr[,default]) → int: decimal value - may raise ValueError modf(x) → (float{2}): (f,i) f signed fractional part of x, i signed integer party modules : ctypes, xstruct, pyconstruct, … digit(unichr[,default]) → int: digit value - may raise ValueError part of x Bit Level Overriding numeric(unichr[,default]) → float: numeric value - may raise pow(x,y) → float: x raised to y power (xy) ValueError __and__(self,other) → value: for self & other x → : sinus value for radians angle x category(unichr) → str: general unicode category of char sin( ) float __or__(self,other) → value: for self | other bidirectional(unichr) → str: bidir category of char, may be empty sinh(x) → float: hyperbolic sinus value for radians angle x other → value: for other __xor__(self, ) self ^ string sqrt(x) → float: square root of x (√x) other → value: for other __lshift__(self, ) self << combining(unichr) → str/0: canonical combining class of char as integer tan(x) → float: tangent value for radians angle x other → value: for other __rshift__(self, ) self >> east_asian_width(unichr) → str: east asian width tanh(x) → float: hyperbolic tangent value for radians angle x → value: for __invert__(self) ~self mirrored(unichr) → int: mirrored property in bidi text, 1 if mirrored else pi → float: value of π (pi=3.1415926535897931) __iand__(self,other) ➤ called for self &= other 0 e → float: value of neperian logarithms base __ior__(self,other) ➤ called for self |= other decomposition(unichr) → str: decomposition mapping, may be empty (e= ) 2.7182818284590451 __ixor__(self,other) ➤ called for self ^= other str Module provides similar functions for numbers. cmath complex __ilshift__(self,other) ➤ called for self <<= other normalize(form, unistr) → str: normal form of string - form in 'NFC', Random Numbers __irshift__(self,other) ➤ called for self >>= other 'NFKC', 'NFD', 'NFKD' → : version of Unicode database used Randomization functions in standard random module. Module STRINGS unidata_version str functions use an hidden, shared state, Random type generator Methods and Functions Simple quoted 'Hello' or double-quoted "Hello". (uniform distribution). Use triple [simple|double] quotes for multi-lines strings : From builtins (see also oct and hex functions for integers to Functions also available as methods of Random objects. """Hello, strings) : [x] ➤ initialize random number generator seed( ) how are you ?""" len(s) → int: number of chars in the string random()→ float: random value in [0.0, 1.0[ Strings are immutable (once created a string cannot be modified in Most string methods are also available as functions in the standard randint(a,b)→ int: random value in [a, b] place). string module. uniform(a, b)→ float: random value in [a, b[ Strings can contain binary data, including null chars (chars of code s.capitalize() → string with first char capitalized1 getrandbits(k)→ long: with k random bits 0). s.center(width[,fillchar]) → string centered randrange([start,]stop[,step])→ int: random value in range(start, Strings are sequences, see Indexing (p8) for chars indexation s.count(sub[,start[,end]]) → int: count sub occurences stop, step) (slicing) and other operations. s.decode([encoding[,errors]]) → unicode: text decoded - see encodings choice(seq)→ value: random item from seq sequence chr(code)→ str: string of one char (p13) shuffle(x[,rndfct]) ➤ items of x randomly reordered using rndfct() ord(char)→ int: code s.encode([encoding[,errors]]) → str: text encoded - see encodings sample(population,k)→ list: k random items from polulation str(expr)→ str: readable textual representation of expr - if available (p13) Alternate random distributions : betavariate(alpha,beta), `expr` → str: readable textual representation of expr - if available s.endswith(suffix[,start[,end]]) → bool: test text ending expovariate(lambd), gammavariate(alpha,beta), repr(expr)→ str: evaluable textual representation of expr - if available s.expandtabs([tabsize]) → string with tabs replaced by spaces gauss(mu,sigma), lognormvariate(mu, sigma), Escape sequences s.find(sub[,start[,end]]) → int/-1: offset of sub normalvariate(mu,sigma), vonmisesvariate(mu,kappa), s.index(sub[,start[,end]]) → int: offset of sub - may raise ValueError \a - bell \v - vertical tab paretovariate(alpha), weibullvariate(alpha,beta). s.isalnum() → bool: non empty string with all alphanumeric chars1 \b - backspace \' - single quote Alternate random generator WichmannHill class. s.isalpha() → bool: non empty string with all alphabetic chars1 \e - escape \" - double quote Direct generator manipulation : getstate(), setstate(state), s.isdigit() → bool: non empty string with all digit chars1 \f - form feed \\ - backslash jumpahead(n). s.islower() → bool: non empty string with all lower chars1 \n - new line \ooo - char by octal ooo value In module os, see : s.isspace() → bool: non empty string with all space chars1 \r - carriage return \xhh - char by hexadecimal hh value os.urandom(n) → str: n random bytes suitable for cryptographic use s.istitle() → bool: non empty string with titlecase words1 \t - horizontal tab \ - continue string on next line. 1 Other Math Modules s.isupper() → bool: non empty string with all upper chars And for Unicode strings : s.join(seq) → string: seq[0]+s+seq[1]+s+…+seq[n-1] Advanced matrix, algorithms and number crunching in third party \uxxxx - unicode char by 16 bits hexadecimal xxxx value. s.ljust(width[,fillchar]) → text string left aligned2 modules like numpy (evolution of numarray / Numeric), gmpy \Uxxxxxxxx - unicode char by 32 bits hexadecimal xxxxxxxx value. s.lower() → text string lowered1 (multiprecision arithmetic), DecInt, scipy, pyarray, … \N{name} - unicode char by name in the Unicode database. s.lstrip([chars]) → string text with leading chars2 removed See sites SciPy, BioPython, PyScience,… Keep \ escape chars by prefixing string literals with a r (or R) - for s.replace(old,new[,count]) → string with count firsts old replaced by Numbers Casts Overriding 'raw' strings (note : cannot terminate a raw string with a \). new Unicode strings s.rfind(sub[,start[,end]]) → int/-1: last offset of sub __int__(self) → int: called for int(self) s.rindex(sub[,start[end]])→ int: last offset of sub - may raise __long__(self) → long: called for long(self) Quoted as for str, but with a u (or U) prefix before the string : ValueError __float__(self) → float: called for float(self) u"Voiçi" s.rjust(width[,fillchar]) → string text right aligned2 __complex__(self) → complex: called for complex(self) U"""Une bonne journée en perspective.""" s.rsplit([sep[,maxsplit]])→ [string]: rightmost words delim. by sep2 __oct__(self) → str: called for oct(self) Can mix strings prefixs r (or R) and u (or U). s.rstrip([chars]) → string with trailing chars2 removed __hex__(self) → str: called for hex(self) You must define your source file encoding so that Python knows s.split([sep[,maxsplit]]) → [string]: words delimited by sep2 __coerce__(self,other) → value: called for coerce(self,other) how to convert your source literal strings into internal unicode s.splitlines([keepends]) → [string]: list of text lines BIT LEVEL OPERATIONS strings. s.startswith(suffix[,start[,end]]) → bool: test text begining unichr(code) → unicode: string of one char s.strip([chars]) → string text with leading+trailing chars2 removed Work with int and long data. ord(unicode char) → int: unicode code s.swapcase() → string with case switched1 Operators unicode(object[,encoding[,errors]]) → unicode: unicode s.title() → string with words capitalized1 ~x → inverted bits of x sys.maxunicode → int: maximum unicode code=fct(compile time s.translate(table[,deletechars]) → string: cleaned, converted3 x^y → bitwise exclusive or on x and y option) s.upper() → string uppered1 x&y → bitwise and on x and y Unicode Chars Informations s.zfill(witdh) → string: string prefixed with zeroes to match width x|y → bitwise or on x and y 1 Locale dependant for 8 bits strings. Module unicodedata contains informations about Unicode chars x<>n → x shifted right by n bits (zeroes inserted) 3 For str table must be a string of 256 chars - see lookup(name) → unicode: unicode char from its name string.maketrans(). For Unicode no deletechars, and table must Binary structures manipulations in standard module struct. name(unichr[,default]) → str: unicode name - may raise ValueError 5a 5b 5c be a map of unicode ordinals to unicode ordinals. lowercase → str: lowercase a-z chars1 \d ➤ match char class decimal digit [0-9] Formating octdigits → str: 0-7 octal digit chars \D ➤ match char class non-digit [^0-9] → : ascii chars considered as punctuation in C locale ➤ match char class whitespace Use % operator between format string and arguments : string%args punctuation str \s [ \t\n\r\f\v] → : printable chars ➤ match char class non-whitespace Formating string contains %[(name)][flag][width][.precision]code printable str \S [^ \t\n\r\f\v] → : uppercase A-Z chars1 ➤ match char class alphanumeric If not use %(name)… → args = single value or tuple of values. uppercase str \w [a-zA-Z0-9_] whitespace → str: whitespace chars (spc, tab, cr, lf, ff, vt) \W ➤ match char class non-alphanumeric [^a-zA-Z0-9_] If use %(name)… → args = mapping with name as keys. capwords(s) → str: split → capitalize → join \Z ➤ match end of string For mapping, args can be an object with __getitem__ method - see from to → translation table usable in str.translate - from and ➤ same as string escapes Overriding Mapping Operations (p8). maketrans( , ) \a \b \f \n \r \t \v \x \\ to must have same length \c ➤ for other c chars, match char c Format char codes 1 Definition is locale dependant. 1 Depends on UNICODE flag. d signed int. decimal : -324 i signed int. decimal : -324 Regular Expressions 2 Depends on LOCALE flag. o unsigned octal : 774 u unsigned decimal 6953 Standard module re has a powerfull regexp engine. See regexp 3 When out of char class definition ([…]) x unsigned hexa : f3a X unsigned hexa : F3A HOWTO at http://www.amk.ca/python/howto/regex/. Flag Options e float. point exp. : -3.256e-12 E float. point exp. : -3.256E-12 Use raw string r"…" notation. IGNORECASE (I) : case insensitive expression - not locale dependant. f float. point dec. : -0.0000032 F float. point dec. : -0.0000032 See also external projects pyparsing, PLY (Python Lex-Yacc), tpg ( ) : make locale dependant. g like e or f G like E or F (Toy Parser Generator)… LOCALE L \w \W \b \B c character (1 char str or code) % %% → % MULTILINE (M) : ^ and $ match begining/end of string and lines. Else Expressions r object format like repr(object) s object format like str(object) ^ and $ match only beginning and end of string. Metacharacters : . ^ $ * + ? { } [ ] \ | ( ), may use \ DOTALL (S) : make . match any char including newline. Else newline Templates escape. excluded. With string.Template objects. Use common $ syntax : $$ ➤ single . ➤ match any character except a newline (including newline with DOTALL UNICODE (U) : make \w \W \b \B unicode dependant. $ ; $name or ${name} ➤ value for name. option) VERBOSE (X) : ignore whitespaces and make # starting comments tmpl = string.Template(template_string) ^ ➤ match start of string (and start of lines with MULTILINE option) (except when space and # are escaped or in char class). tmpl. mapping[ kwargs]) → string: template filled substitute( ,** $ ➤ match end of string (and end of lines with MULTILINE option) Matching and Searching tmpl.safe_substitute(mapping[,**kwargs]) → string: template filled expr* ➤ match 0 or more repetitions of expr (as much as possible) tmpl.template → string expr+ ➤ match 1 or more repetitions of expr (as much as possible) Can use re functions, or compile expressions into SRE_Pattern Can subclass Template to build your own templating (see doc, expr? ➤ match 0 or 1 expr objects and use their methods. See Flag Options supra for flags parameters. sources). expr*? ➤ match like expr* but as few as possible search(pattern,string[,flags])→ MatchObject/None: scan throught See also modules formatter. expr+? ➤ match like expr+ but as few as possible string to find substrings matching pattern expr?? ➤ match like expr? but as few as possible Wrapping match(pattern,string[,flags])→ MatchObject/None: try to match string expr{m} ➤ match m repetitions of expr Module textwrap has a TextWrapper class and tool functions. with pattern expr{[m],[n]} ➤ match from m to n repetitions of expr, missing m default tw = textwrap.TextWrapper([…]) → new text wrapper using named split(pattern,string[,maxsplit=0])→ [string]: split string by occurences to 0 and missing n default to infinite params as corresponding attributes values of pattern - if maxsplit specified, remainder is put in last item of list expr{[m],[n]}? ➤ match like expr{[m],[n]} but as few as possible tw.width → int: max length of wrapped lines (default 70) findall(pattern,string[,flags])→ [string]/[(string)]: find non- [set] ➤ match one char in the set defined by : tw.expand_tabs → bool: replace tabs by text.expandtabs() (default overlapping substrings matching pattern - eventually empty matchs - ^ → at begining, invert set definition True) return list of tuples if pattern has groups x-y → chars from x to y tw.replace_whitespace → bool: replace each whitespace by space finditer(pattern,string[,flags])→ iterator over [MatchObject] - same \x → see Escape sequences for strings (p5) (default True) as findall but with an iterator \- , \] → chars - and ] (- and ] at the beginning match - and ] tw.initial_indent → string: prepend to first wrapped line (default '') sub(pattern,repl,string[,count=0])→ string: replace substrings matching chars) 1 tw.subsequent_indent → string: prepend to other wrapped lines pattern by repl - repl as string can contain back references to identified x → char x (including other re metacharacters) (default '') substring - repl as fct(MatchObject) return replacement string - pattern exprA|exprB ➤ match exprA or exprB, short path evaluation tw.fix_sentence_endings → bool: try to separate sentences by two may be RE_Pattern object (expr) ➤ match expr and build a numbered group nd spaces (default False) subn(pattern,repl,string[,count=0])→ (string,int): same as sub, 2 (?[i][L][m][s][u][x]) ➤ (at least one ot iLmsux char) group match empty tw.break_long_words → bool: break words longer than width (default item is count of substitutions string, modify options flags for entire expression - see I L M S U X True) escape(string)→ string: non-alphanumerics backslashed options tw.initial_indent → string: prepend to first wrapped line (default '') (?:expr) ➤ match expr but dont build a group If you need to reuse a pattern, compile it one time for all. tw.wrap(text) → [string]: list of text lines, each with max width length - pat pattern[ flags] → object (?Pexpr) ➤ match expr and build a group numbered and named = re.compile( , ) RE_Pattern no final newline 2 (name must be valid Python identifier) pat.match(string[,pos[,endpos]]) → same as match function tw.fill(text) → string: whole text, lines wrapped using newlines 2 (?P=name) ➤ match text matched by earlier group named name pat.search(string[,pos[,endpos]]) → same as search function Two convenient functions use temporary TextWrapper, built using 2 (?#text) ➤ no match, text is just a comment pat.split(string[,maxsplit=0])→ same as split function named parameters corresponding to attributes. 2 (?=expr) ➤ match if match expr but don't consume input pat.findall(string[,pos[,endpos]])→ same as findall function wrap(text[,width=70[,…]]) → [string] 2 (?!expr) ➤ match if doesn't match expr but don't consume input pat.finditer(string[,pos[,endpos]])→ same as finditer function fill(text[,width=70[,…]]) → string (?<=expr) ➤ match if current position is immediatly preceded by a match pat.sub(repl,string[,count=0])→ same as sub function dedent(text) → string: remove uniform whitespaces at beginning of text for fixed length pattern expr pat.subn(pattern,repl,string[,count=0])→ same as subn function lines (? and \g. domain to localedir directory if specified (used when searching for .mo 1 Using part of string between pos and endpos. YESEXPR regular expression (of C library!) usable for yes files) reply Group number 0 correspond to entire matching. bind_textdomain_codeset(domain[,codeset])→ codeset binding: bind NOEXPR regular expression (of C library!) usable for no Localization domain to codeset if specified - change xxgettext() returned strings reply encoding Standard module locale provide posix locale service (internationa- CRNCYSTR currency symbol, preceded by - if should appear textdomain([domain])→ global domain: set global domain if specified lization). before the value, by + if should appear after the and not None setlocale(category[,locale]) → current/new settings: if locale specified value, by . if should replace radix character message → string: localized translation of message - based on (as string or as tuple(language code, encoding)) then modify locale gettext( ) ERA era - generally not defined - same as E format in current global domain, language, and locale directory - usually aliased as _ settings for category and return new one - if locale not specified or None, strftime() in local namespace return current locale - not thread safe ERA_YEAR year in era lgettext(message)→ string: like gettext(), using preferred encoding localeconv()→ dict: database of local conventions ERA_D_T_FMT dgettext(domain,message)→ string: like gettext(), looking in nl_langinfo(option)→ string: locale-specific informations - not available usable as format for strftime() for date and specified domain. on all systems - options may vary on systems - see options p7 time with era ldgettext(domain,message)→ string: like dgettext(), using preferred getdefaultlocale([envvars])→(language code, encoding): try to ERA_D_FMT usable as format for strftime() for date with encoding determine default locale settings era ngettext(singular,plural,n)→ string: like gettext(), but consider plural getlocale([category])→ current LC_* setting for category - category ALT_DIGITS up to 100 values representing 0 to 99 forms (see Python and GNU gettext docs) default to LC_CTYPE - for language code and ancoding it may be None localeconv keys lngettext(singular,plural,n)→ string: like ngettext(), using preferred getpreferredencoding([do_setlocale])→ str: user preffered encoding key meaning encoding for text data - set do_setlocale to False to avoid possible call to currency_symbol Local currency symbol for monetary values. dngettext(domain,singular,plural,n)→ string: like ngettext(), looking setlocale() decimal_point Decimal point character for numbers. in specified domain. normalize(localename)→ normalized locale code for localename - usable frac_digits Number of fractional digits used in local ldngettext(domain,singular,plural,n)→ string: like dngettext(), with setlocale() - return localename if normalization fails formatting of monetary values. using preferred encoding resetlocale([category]) ➤ reset locale for category to default setting - grouping [int]: relative positions of 'thousands_sep' Generally _ is bound to gettext.gettext, and translatable strings category default to LC_ALL in numbers. CHAR_MAX at the end stop are written in sources using _('thestring'). See docs for usage strcoll(s1,s2)→ int: compare two strings - follow LC_COLLATE setting grouping. 0 at the end repeat last group. examples. - return 0 if s1==s2, <0 if s10 if s1>s2 int_curr_symbol International currency symbol of monetary strxfrm(string)→ string:transform string for locale-aware comparison Class based API values. format(format,val[,grouping])→ string:convert val float using format (% The recommended way. Module gettext defines a class int_frac_digits Number of fractional digits used in operator conventions) - follow LC_NUMERIC settings (decimal point, + Translations, dealing with .mo translation files and supporting international formatting of monetary grouping if it is true) str/unicode strings. values. str(float)→ string: convert float - follow LC_NUMERIC settings (decimal find(domain[,localedir[,languages[,all]]])→ str/None: .mo file name mon_decimal_point Decimal point used for monetary values. point) for translations (search in localedir/language/LC_MESSAGES/domain.mo) mon_grouping Equivalent to 'grouping', used for monetary atof(string)→ float: convert string to float - follow LC_NUMERIC settings translation(domain[,localedir[,languages[,class_[,fallback[,codeset] values. atoi(string)→ int: convert string to integer - follow LC_NUMERIC settings ]]]])→Translations: object from class class_ (default to mon_thousands_sep Group separator used for monetary values. CHAR_MAX → symbolic constant used by localeconv() GNUTranslations, constructor take file object as parameter) - if true n_cs_precedes True if currency symbol preceed negative fallback allow to return a NullTranslations if no .mo file is found, Categories monetary values, false if it follow. default to false (raise IOError) - codeset change charset used to encode → character type - case change behaviour n_sep_by_space True if there is a space between currency LC_CTYPE translated strings → strings sorting - and () functions symbol and negative monetary value. LC_COLLATE strcoll() strxfrm install(domain[,localedir[,unicode[,codeset]]]) ➤ install _ function in → time formating - n_sign_posn Position of negative sign for monetary LC_TIME time.strftime() Python's builtin namespace, to use _('thestring') LC_MONETARY → monetary values formating - options from localeconv() values1. LC_MESSAGES → messages display - os.strerror() - not for Python negative_sign Symbol used to annotate a negative Null Translations messages monetary value. The NullTranslations is a base class for all Translations. LC_NUMERIC → numbers formatting - format(), atoi(), atof() and p_cs_precedes True if currency symbol preceed positive t.__init__([fp]) ➤ initialize translations: fp is a file object - call str() of this module (dont modify normal Python number formating) monetary values, false if it follow. _parse(fp) if it is not None LC_ALL → all locales - used to change/retrieve the locale for all categories p_sep_by_space True if there is a space between currency t._parse(fp) ➤ nothing: subclasses override to read data from the file symbol and positive monetary value. nl_langinfo options t.add_fallback(fallback) ➤ add fallback used if cannot found p_sign_posn Position of positive sign for monetary translation for a message key nl_langinfo() value usage 1 values . Define methods gettext, lgettext, ngettext, lngettext as in the CODESET name of character encoding positive_sign Symbol used to annotate a positive base API. And define speciale methods ugettext and ungettext D_T_FMT usable as format for strftime() for time and monetary value. returning unicode strings (other forms return encoded str strings). date thousands_sep Character used between groups of digits in 7a 7b 7c Return translated message, forwarding to fallback if it is defined. Unless using a sequence as a mapping key, or ensuring it is seq.insert(index,item) ➤ item inserted at index Overriden in subclasses. immutable data, prefer list to tuple. seq.remove(expr) ➤ remove first expr item from sequence t.info()→ return protected _info attribute 1 Use in place of range to avoid building huge lists just for indexing. seq.pop([index]) → item: remove and return item at index (default -1) t.charset()→ return protected _charset attribute Operations on Sequences seq.reverse() ➤ items reversed in place → return protected attribute t.output_charset() _output_charset See Operations on Containers (p8) too. seq.sort([cmp][,key][,reverse]) ➤ items sorted in place - cmp : (defining encoding used to return translated messages) seq1 + seq2 → concatenation of seq1 and seq2 custom comparison fct(a,b), retval <0 or = 0 or >0 - key : name of items t.set_output_charset(charset) ➤ set _output_charset attribute sequence * n → concatenation of sequence duplicated n times attribute to compare - reverse : bool t.install([unicode]) ➤ bind _ in builtin namespace to n * sequence → concatenation of sequence duplicated n times del seq[index] ➤ remove item from sequence self.gettext() or self.ugettext() upon unicode (default to false) reversed(sequence)→ iterator throught sequence in reverse order del seq[start:stop[:step]] ➤ remove items from sequence GNU Translations sorted(sequence[,cmp[,key[,reverse]]])→ list: new list, sorted items Overriding Sequences Operations The GNUTranslations class (subclass of NullTranslations) is from iterable - see list.sorted() __getitem__(self,index2)→ value: item at index, called for based on GNU gettext and .mo files. filter1(fct,sequence)→ list: new list where fct(item) is True. Use None self[index] Messages ids and texts are coerced to unicode. fct for a boolean test on items __setitem__1(self,index2,value) ➤ set item at index to value, called 1 th th Protected _info attribute contains message translations. map (fct,sequence,…)→ list: new list where i item is fct(i items of for self[index]=value Translation for empty string return meta-data (see doc). sequence(s)) __delitem__1(self,index2) ➤ remove item at index, called for Define methods gettext, lgettext, ugettext, ngettext, reduce(fct,sequence[,initializer])→ value: fct applied cumulatively to del self[index] lngettext, ungettext as in NullTranslations interface - same sequence items, f(f(…f(f(f(initializer,a),b),c,…) 1 Only for mutable sequences. th th rules for return values (str/unicode). Message translations are zip1(sequence,…)→ list: list of tuples, i tuple contains i items of each 2 Parameter index can be a slice [start,stop,step] - replace old searched in catalog, then in fallback if defined, and if no translation sequences __getslice__, __setslice__, __delslice__. is found, message itself is returned (for n… methods, return 1 See Iteration Tools (p9) as replacement (avoid creating a new Can also override arithmetic operations __add__ (concatenation ) singular forms if n=1 else plural forms). list). and __mul__ (repetition ), container operations and object operations. CONTAINERS Indexing Use index [i] and slice [i:j[:step]] syntax. Indexs zero-based. Basic containers kind : MAPPINGS (DICTIONARIES) Negative indexs indexing from end. Default step is 1, can use -sequences (ordered collections) : list, tuple,str, any iterable,… Builtin type dict. Store key:value pairs. negative steps. -mappings (unordered key/value) : dict… Declare a dictionary : key va lue [ …] Sub-sequences indexs between items. { : , } {} -sets (unordered collections) : set, frozenset… dict()→ dict: empty dictionary (like {}) l = [e1,e2,e3,…,en-2,en-1,en] dict(**kwargs)→ dict: from named parameters and their values Operations on Containers l[0]→ e1 l[0:n]→[e1,e2,e3,…,en-2,en-1,en] dict(iterable)→ dict: from (key,value) by iterable For strings, items are chars. For mappings, items are keys. l[1]→ e2 l[:]→[e1,e2,e3,…,en-2,en-1,en] 1 dict(otherdict)→ dict: duplicated fro another one (first level) item in container → bool: test item ∈ container l[-2]→ en-1 l[i:]→[ei+1,ei+2,ei+3,…,en-1,en] 1 item not in container → bool: test item ∉ container l[-1]→ en l[:i]→[e1,e2,…,ei-2,ei-1,ei] Operations on Mappings for var in container: … ➤ iterate var over items of container items indexs len(container) → int: count number of items in container2 See Operations on Containers (p8) too, considering operations on -n -n+1 -n+2 … -2 -1 max(container) → value: biggest item in container keys. 1 min(container) → value: smallest item in container 0 1 2 … n-2 n-1 d[key]→ value for key sum(container) → value: sum of items (items must be number-compatible) d[key]=value ➤ set d[key] to value 1 1 For strings test if expr is a substring of sequence. e1 e2 e3 …item… en-1 en del d[key] ➤ removes d[key] from d 2 Container must provide direct length method - no generator. d.fromkeys(iterable[,value=None]) → dict: with keys from iterable and 0 1 2 3 … n-2 n-1 n Copying Containers all same value d ➤ removes all items from d Default containers constructors build new container with references -n -n+1 -n+2 -n+3 … -2 -1 .clear() d.copy() → dict: hallow copy of d to existing objects (shallow copy). To duplicate content too, use slicing indexs standard module copy. See Copying Objects (p3). d.has_key(k)→ bool: test key presence - same as k in d Slice objects d.items()→ list: copy of d's list of (key, item) pairs Overriding Containers Operations Defines index range objects, usable in [] notation. d.keys()→ list: copy of d's list of keys → : called for __len__(self) int len(self) slice([start,]stop[,step])→ slice object d.update(otherd) ➤ copy otherd pairs into d → : called for [ ] __contains__(self,item) bool item not in self slice.indices(len)→ (int{3}): (start,stop,stride) d.update(iterable) ➤ copy (key,value) pairs into d You can override iterable protocol on containers too. Ordered sets of data indexed from 0. Members start, stop, step. d.update(**kwargs) ➤ copy name=value pairs into d d.values()→ list: copy of d's list of values SEQUENCES Extended Slicing d.get(key,defval)→ value: d[key] if key∈d, else defval Sequences are ordered collections : str, unicode, list, tuple, Multiple slices notation - corresponding to a selection in a multi- d.setdefault(key[,defval=None]) → value: if key∉d set d[key]=defval, buffer, xrange, array.array… any user class defining sequences dimension data - can be written using notation like return d[key] interface, or any iterable data. [ a , x:y:z , : , : , : , m:n ]. d.iteritems()→ iterator over (key, value) pairs Ellipsis notation can be used to fill multiple missing slices, like Lists & Tuples d.iterkeys()→ iterator over keys [ a , x:y:z , ... , m:n ]. See docs. Builtin types list and tuple store sequences of any objects. d.itervalues()→ iterator over values Lists are mutable, tuples are immutable. Three dot notation ... is replaced internally by Ellipsis object. d.pop(key[,defval]) → value: del key and returns the corresponding Declare a list : [item[,…]] Operations on mutable sequences value. If key is not found, defval is returned if given, otherwise KeyError Declare a tuple : (item[,…]) Mutable sequences (ex. list) can be modified in place. is raised Notes : [] ➤ empty list ;() ➤ empty tuple ; (item,) ➤ one item Can use mutable sequence indexing in left part of assignment to d.popitem() → removes and returns an arbitrary (key, value) pair from d 1 tuple. modify its items : seq[index]=expr ; seq[start:stop]=expr ; If key doesn't exist, raise KeyError exception. list(object) → list: new list (cast from object / duplicate existing) seq[start:stop:step]=expr Overriding Mapping Operations tuple(object) → tuple: new tuple (cast from object / duplicate existing) seq.append(item) ➤ add item at end of sequence __getitem__(self,key)→ value for key, called for self[key] range([start,]stop[,step])→ [int]: list, arithmetic progression of seq.extend(otherseq) ➤ concatenate otherseq at end of sequence __setitem__(self,key,value) ➤ set value for key, called for integers seq.count(expr) → int: number of expr items in sequence self[key]=value 1 [start ]stop[ step] → : object generating arithmetic xrange ( , , ) xrange seq.index(expr[,start[,stop]])→ int: first index of expr item __delitem__(self,key,value) ➤ remove value for key, called for progression of integers 8a 8b 8c del self[key] a.fromfile(f,n) ➤ append n items read from real binary file f1 islice(iterable,[start,]stop[,step])→ iterator over items at slice3 indexs Can also override container operations and object operations. a.tofile(f) ➤ write all items to real binary file f from iterable, None stop goes up to end Other Mappings a.fromlist(list) ➤ extend array from values in list izip(iterable[,…])→ iterator over tuple(items at same index from a → : items in a list iterables) For on-disk mappings, see standard module shelve, and database .tolist() list object[ count] → iterator returning object over and over again, up modules . a.fromstring(s) ➤ extend array from values in binary buffer s (string) repeat( , ) to count times (default to infinite) For ordered mappings see third party modules OrderedDict. a.tostring() → str: items in binary representation a.fromunicode(s) ➤ extend 'u' array from data in unicode stirng starmap(function,iterable)→ iterator over function(*tuple item from SETS a.tounicode() → unicode: convert 'u' array to unicode string iterable) 1 takewhile(predicatefct,iterable)→ iterator over items of iterable where Unordered collections of unique items. Frozen sets are immutable If less items than needed, get available ones then raise predicatefct(item) is true once created. EOFError. tee(iterable[,n]) → n independent iterators from same iterable4, default set([iterable]) → set: using values from iterable Old methods read and write replaced by fromfile and tofile. n=2 frozenset([iterable]) → frozenset: using values from iterable Queue 1 Group of items is internally used - must save it as list if needed Operations on Sets Standard module collections provides queues management. after current iteration. See Operations on Containers (p8) too. deque([iterable])→ deque: initialized from iterable 2 Stop at end of shorter iterable. s.issubset(others)→ bool: test s ⊂ others q.append(x) ➤ add x to right side of deque 3 Slice parameters cannot be negative. s.issuperset(others)→ bool: test others ⊂ s q.appendleft(x) ➤ add x to left side of deque 4 Don't use iterable out of tee created iterators. s.add(item) ➤ add item to set q.clear() ➤ remove all elements from deque DATE & TIME s.remove(item) ➤ remove item from set1 q.extend(iterable) ➤ extend right side of deque with iterable items q.extendleft(iterable) ➤ extend left side of the deque with iterable s.clear() ➤ emoves all items from (not forzen) set Module time s.intersection(others)→ set: s ∩ others items q → item: pop and return item from dequeue right side Standard module time defines common functions and data. s & others → set: s ∩ others .pop() q → item: pop and return item from dequeue left side Date & Time Data s.union(others) → set: s ∪ others .popleft() q n ➤ rotate deque from n steps, to right if n>0, to left if n<0 s | others → set: s ∪ others .rotate( ) • float_time = float containing seconds from 'epoch' (january 1 Can also use standard operations on sequences : q s.difference(others) → set: [x / x∈s and x∉others] len( ), 1970 on Unix - see gmtime(0)), with sub-second precision in q q , q , item q, q , s - others → set: [x / x∈s and x∉others] reversed( ), copy.copy( ) copy.deepcopy( ) in [-1] decimal part. and serialization via pickling protocol. s.symmetric_difference(others)→ set: [x / x∈s xor x∈others] • tuple_time = tuple containing 9 int (see table). s ^ others → set: [x / x∈s xor x∈others] Priority Queues • struct_time = tuple/object with int attributes (see table). s.copy()→ set: shallow copy of s Standard module heapq. Structure a list as a priority queue. # attribute value # attribute value s.update(iterable) ➤ adds all values from iterable to s heapify(x) ➤ transform list x into heap 0 tm_year int 5 tm_sec 0…61 1 Raise KeyError if object not in set. heappush(heap,item) ➤ push item onto heap 1 tm_mon 1…12 6 tm_wday 0…6 (monday=0) Results set have same type as s object (set/frozenset). heappop(heap)→ item: pop and return smallest item from the heap 2 tm_mday 1…31 7 tm_yday 0…366 heapreplace(heap,newitem)→ item: pop and return smallest item from 3 tm_hour 0…23 8 tm_isdst 0 (no) OTHER CONTAINERS STRUCTURES, ALGORITHMS the heap, push newitem 4 tm_min 0…59 1 (yes) Generally containers follow Python idioms, you can use : len(cont), nlargest(n,iterable)→ list: n largest from iterable -1 (unknown) cont[i], for item in cont:… nsmallest(n,iterable)→ list: n smallest items from iterable • float_delay = float containing seconds, with sub-second Array Sorted List precision. Standard module array provides efficient array of basic types. It Standard module bisect maintains lists sorted (via basic bisection DST is local time, UTC is universal (GMT) time. uses compact storage for elements of same type. algo). accept2dyear → [rw] bool: accept two-digit year values (default true), modifiable via environment var PYTHONY2K Type Codes bisect_left(list,item[,lo[,hi]])→ int: index to insert item at leftmost sorted position1 altzone → int: offset (pos/neg) in seconds of DST relatively to UTC, in n tc C type py type n tc C py type bisect_right(list,item[,lo[,hi]])→ int: index to insert item at seconds, use only if daylight is true 1 'b' signed char int 1 'B' unsigned char int rightmost sorted position1 daylight → int: ≠0 if a DST timezone is defined 1 'c' char str 2 'u' unicode char unicode bisect(…) ➤ alias for bisect_right(…) timezone → int: offset (pos/neg) in seconds of local (non DST) timezone 2 'h' signed short int 2 'H' unsigned short int insort_left(list,item[,lo[,hi]]) ➤ insert item at leftmost sorted tzname → (str{2}): names of local timezone (non-DST, DST) 1 2 'i' signed int int 2 'I' unsigned int long position Functions 4 'l' signed long int 4 'L' unsigned long long insort_right(list,item[,lo[,hi]]) ➤ insert item at rightmost sorted 2 1 asctime([t= ])→ str: build local time string from t (tuple_time or 4 'f' float float 8 'd' double float position insort(…) ➤ alias for insort_right(…) struct_time) n=size in bytes, tc=char typecode to use 1 With list previously sorted. clock()→ float: processor time in seconds, for accurate relative time Functions measurement Iteration Tools ctime([secs=2])→ str: build local time string from float_time second tc,[iterable] → : with typecode tc, initialized from iterable 2 array( ) array Standard module itertools provides some practical iterators. gmtime([secs= ])→ struct_time: convert float_time to UTC struct_time a → : typecode of a data 2 .typecode str chain(iterable[,…])→ iterator over items of several iterables localtime([secs= ])→ struct_time: convert float_time to DST a.itemsize → int: bytes size of a data count([start])→ iterator over integers from start (default 0) struct_time a.append(expr) ➤ append item expr to end of a cycle(iterable)→ iterator cycling over iterable items mktime(t)→ float_time: convert DST t (tuple_time or struct_time) to a.extend(array) ➤ append items from another array dropwhile(predicatefct,iterable)→ iterator over items of iterable where float_time - may raise OverflowError or ValueError a.count(expr) → int: number of expr items predicatefct(item) is false sleep(secs) ➤ execution suspended during secs (float_delay) times, a.index(expr) → int: first index of expr item groupby(iterable[,keyfct])→ iterator over (key value,group1 of items maybe less (signal catching), may be more (process/threads scheduling) a.insert(index,expr) ➤ expr item inserted at index where keyfct(item)=key value), default keyfct is identity strftime(format[,t=2]) → str: build time string from t (tuple_time or a.remove(expr) ➤ remove first expr item ifilter(predicate,iterable)→ iterator over items of iterable where struct_time) using format string (table infra) - may raise ValueError a.pop([index]) → value: return and remove item at index (default -1) predicatefct(item) is true - None predicate filter items being true strptime(string[,format]) → struct_time: parse string using time a.reverse() ➤ items in array are reversed ifilterfalse(predicate,iterable)→ iterator over items of iterable where format1 - may raise ValueError a.buffer_info() → (int{2}): current storage infos (address,items predicatefct(item) is false - None predicate filter items being false time() → float_time: current UTC time count) imap(function,iterable[,…])→ iterator over function(items at same index tzset() ➤ resets time conversion rules accordingly to environnment a.byteswap() ➤ swap bytes of array items from iterables2), None function return tuples items variable TZ - unix only, see docs 9a 9b 9c 1 Default format "%a %b %d %H:%M:%S %Y". Missing values f.flush() ➤ buffers written to file on disk O_RANDOM → xxxxxx (Windows) default to (1900, 1, 1, 0, 0, 0, 0, 1, -1) f.isatty() → bool: indicator file is a terminal O_SEQUENTIAL → xxxxxx (Windows) 2 Param secs default to current time, param t default to local f.read([size]) → str: block of data read from file O_TEXT → xxxxxx (Windows) current time. f.readline() → str: next line read from file, end of line removed Pipes f → string : list of all lines read from file, end of lines Time format strings .readlines() [ ] For standard process redirection using pipes, see also Simple 1 1 removed %a Abbreviated weekday name . %A Full weekday name . External Process Control (p14). f.seek(offset[,whence=0]) ➤ modify current position in file - whence: 0 %b Abbreviated month name1. %B Full month name1. os.pipe() → ((int{2}){2}): create pair (fdmaster,fdslav) of fd from start, 1 from current, 2 from end %c Appropriate date and time %d Month day [01,31]. (read,write) for a pipe 1 f → : current position in file representation . .tell() int os.mkfifo(path[,mode=0666]) ➤ create named pipe path - mode %H Hour [00,23]. %I Hour [01,12]. f.write(string) ➤ data written to file masked out with umask - don't open it (Unix) f listofstrings ➤ data written to file (no end of line added) %j Year day [001,366]. %m Month [01,12]. .writelines( ) Use os functions on file descriptors. 1 for line in f :… ➤ iterate line over lines of f %M Minute [00,59]. %p AM or PM . In-memory Files Old method xreadlines replaced by iteration on file object. %S Second [00,61]. %U Year week [00,53] (Sunday based). For optimized direct access to random lines in text files, see Memory Buffer Files module . %w Week day [0,6] (0=Sunday). %W Year week [00,53] (Monday linecache Use standard modules StringIO and cStringIO to build file-like based). Attributes objects storing data in memory. 1 %x Appropriate date %X Appropriate time representation . f = StringIO.StringIO() representation1. f.closed → bool: indicator file has been closed Build a file-like in memory. %y Year [00,99]. %Y Year (with century). f.encoding → str/None: file content encoding f.name → str: name of the file f.write(string) ➤ data written to file %Z Time zone name (no characters %% Literal % char. f …other file writing methods… if no time zone exists). f.newlines → str/tuple of str/None: encountered newlines chars . f.getvalue() → str: current data written to file 1 f.softspace → bool: indicator to use soft space with print in file Locale language representation. f.close() ➤ file no longer usable, free buffer Low-level Files cStringIO is a compiled (more efficient) version of StringIO for Module datetime Base low-level functions are in standard module os. writing. Optional argument allows to build memory files to read Standard module datetime has tools for date/time arithmetics, data Careful of clash with builtins with os.open name. from too. extraction and manipulation. open(path,flags[,mode=0777])→ int (fd): open file path - see flags infra f = cStringIO.StringIO([string]) Defines class : timedelta, time, date, datetime, [tzinfo]. - mode masked out with umask f.read([size]) → str: block of data read from 'file' (string) f.…other file reading methods… Module timeit fdopen(fd[,mode[,bufsize]]) → file: build a file connected to fd - mode and bufsize as for builtin + mode must start with or or Standard module timeit has functions to measure processing time open() r w a Memory Mapped Files (OS level) fd → (fd): duplicate file descriptor fd of code. It can be used in scripts (see docs), or directly in command dup( ) int Standard module mmap manage memory-mapped files, usable as line : dup2(fd,fd2)→ int (fd): duplicate file descriptor fd into fd2, previously file-like objects and as mutable string-like objects. python -mtimeit [-n N] [-r N] [-s S] [-t] [-c] [-h] [statement […]] closing fd2 if necessary To build a memory map : -n N / --number=N execute statement N times close(fd) ➤ close file descriptor mm = mmap.mmap(fileno,length[,tagname[,access]]) [windows] -r N / --repeat=N repeat timer N times (default 3) read(fd,n)→ str: read as most n bytes from fd file - return empty string if mm = mmap.mmap(fileno,length[,flags[,prot[,access]]]) [unix] -s S / --setup=S executed S once initially (default pass) end of file reached Use an os file descriptor (from os.open() or from file-object's fd str → : write str to fd file - return number of bytes actually -t / --time use time.time() (default except Windows) write( , ) int fileno()) for a file opened for update. -c / --clock use time.clock() (default on Windows) written Length specify amount of bytes to map. On windows, file may be -v / --verbose print raw timing results - may repeat option lseek(fd,pos,how) ➤ set file descriptor position - how: 0 from start, 1 extended to that length if it is shorter, it can't be empty, and 0 -h / --help print help and exit from current, 2 from end correspond to maximum length for the file. fdatasync(fd) ➤ flush file data to disk - don't force update metadata Other Modules Access (keyword param) : ACCESS_READ (readonly), (Unix) ACCESS_WRITE (write-through, default on Windows), or Standard module calendar has functions to build calendars. fsync(fd) ➤ force low level OS buffers to be written See also third party module mxDateTime. ACCESS_COPY (copy-on-write). ftruncate(fd,length) ➤ truncate file descriptor to at most length (Unix) On Windows, tagname allow to identify different mappings against FILES same file (default to None). Open Flags On Unix, flags : MAP_PRIVATE (copy-on-write private to process) Normal file operations use Python file objects (or file-like objects or (default). And prot (memory protection mask) : with same interface). Some functions directly manipulate files path Constants defined in os module, use bit-wise OR (x|y|z) to mix MAP_SHARED names (strings). Functions mapping low level OS handlers (mainly them. PROT_READ or PROT_WRITE, default is PROT_READ|PROT_WRITE. If those in standard os module) use numeric file descriptors (fd also O_RDONLY → read only use prot+flags params, don't use access param. known as fileno). O_WRONLY → write only mm.close() ➤ mmap file no longer usable Raw data use str type (can contain any data byte values, including O_RDWR → read/write mm.find(string[,start=0])→ int: offset / -1 0). O_APPEND → append each write to end mm.flush([offset,size]) ➤ write changes to disk O_CREAT → create new file (remove existing) mm.move(dest,src,count) ➤ copy data in file File Objects 1 O_EXCL → with O_CREAT, fail if file exist (Unix) mm.read([size])→ str: block of data read from mmap file Standard file type is builtin file. It defines the Python file protocol. 1 O_TRUNC → reset existing file to zero size mm.read_byte()→ str: next one byte from mmap file Create a file : file(filename[,mode='r'[,bufsize]]) → file object O_DSYNC → xxxxxx (Unix) mm.readline()→ str: next line read from file, end of line is not Mode flags (combinable) : 'r' read, 'w' write new, 'a' write removed1 1 2 O_RSYNC → xxxxxx (Unix) append, '+' update, 'b' binary , 'U' universal newline . O_SYNC → return from IO when data are physically written (Unix) mm.resize(newsize) ➤ writable mmap file resizer Buffer size : 0 unbuffered, 1 line buffered, >1 around that size. O_NDELAY → return immediatly (don't block caller during IO) (Unix) mm.seek(offset[,whence=0]) ➤ modify current position in mmap file - Open() is an alias for file() whence: 0 from start, 1 from current, 2 from end 1 O_NONBLOCK → same as O_NDELAY (Unix) Default text mode tries to interpret newline sequences in the file. mm.size()→ int: length of the real os file 2 Automatically choose newline sequence in CR or LF or CR+LF O_NOCTTY → terminal device file can't become process tty (Unix) → don't process end of lines (cf+lf from/to cr) (Windows) mm.tell() → int: current position in mmap file adapted from file/to platform. O_BINARY 1 O_NOINHERIT → xxxxxx (Windows) mm.write(string) ➤ data written to mmapfile Methods and Functions → xxxxxx (Windows) mm.write_byte(byte) ➤ str of one char (byte) data written to mmap O_SHORT_LIVED 1 f.close() ➤ file flushed and no longer usable O_TEMPORARY → xxxxxx (Windows) file f.fileno() → int: low level file descriptor (fd) 1 File-like methods use and move file seek position. 10a 10b 10c Files Informations # attribute usage modules. Functions to set/get files informations are in os and in os.path 2 st_dev device module, some in shutil module. Constants flags are defined in 3 st_nlink number of hard links Temporary Files standard stat module. 4 st_uid user ID of owner Use standard tempfile module. It defines several functions to make Some functions accessing process environment data (ex. current 5 st_gid group ID of owner life easier and more secure. working directory) are documented in Process section. 6 st_size size of file, in bytes TemporaryFile([mode='w+b'[,bufsize=-1[,suffix[,prefix[,dir]]]]]) os.access(path,mode)→ bool: test for path access with mode using real 7 st_atime time of most recent access → file/file-like: temp file - removed on close - not necessary visible in file- uid/gid - mode in F_OK, R_OK, W_OK, X_OK 8 st_mtime time of most recent content modification system - dir and prefix as for mkstemp os.F_OK → access mode to test path existence 9 st_ctime time of most recent metadata change on Unix, time of NamedTemporaryFile([mode='w+b'[,bufsize=- os.R_OK → access mode to test path readable creation on Windows 1[,suffix[,prefix[,dir]]]]]) os.W_OK → access mode to test path writable st_blocks number of blocks allocated for file (Unix) → file/file-like: like TemporaryFile - file visible in file-system os.X_OK → access mode to test path executable st_blksize filesystem blocksize (Unix) mkstemp([suffix[,prefix[,dir[,text]]]])→ (int,str): (fd,path) of new os.chmod(path,mode) ➤ change mode of path - mode use stat.S_* st_rdev type of device if an inode device (Unix) temporaty file - no race condition - only creator can read/write - no constants st_rsize size of resource fork, in bytes(MacOS) executable bit - not automatically deleted - binary mode unless text path uid gid ➤ change path owner and group (Unix) os.chown( , , ) st_creator file creator code (MacOS) specified os.lchown(path, uid, gid) ➤ change path owner and group - don't st_type file type code (MacOS) mkdtemp([suffix[,prefix[,dir]]])→ str: path of new temporary directory follow symlinks(Unix) created - no race condition - only creator can read/write/search - not os.fstat(fd)→ int: status for file descriptor statvfs_result is returned by fstatvfsand statvfs functions, automatically deleted os.fstatvfs(fd)→ statvfs_result: informations about file system usable as a tuple (use statvfs variable indexs) and as an object gettempdir() → str: default directory for temporary files containing file descriptor (Unix) with attributes : gettempprefix() → str: default filename prefix for temporary files os.stat(path)→ stat structure object: file system informations (Unix) # attribute index var usage Other functions in tempfile and os modules are kept for code path → stat structure object: file system informations (Unix) - 0 f_bsize F_BSIZE preferred file system block size os.lstat( ) compatibility, but are considered not enough secured. Also dont follow symlinks 1 f_frsize F_FRSIZE fundamental file system block size tempdir and template data in tempfile - which should not be [newvalue] → : test/set function time 2 total number of blocks in the filesystem os.stat_float_times( ) bool stat f_blocks F_BLOCKS used directly. stamps data type - avoid setting new value 3 f_bfree F_BFREE total number of free blocks Path Manipulations os.statvfs(path)→ statvfs_result: informations about file system 4 f_bavail F_BAVAIL free blocks available to non-super user containing path (Unix) 5 f_files F_FILES total number of file nodes Path manipulation functions are in standard os.path module. → : unicode usable for file names os.utime(path,times) ➤ set access and modification times of file path - 6 f_ffree F_FFREE total number of free file nodes supports_unicode_filenames bool times=(atime,mtime) (numbers) - times=None use current time abspath(path)→ str: normalized absolutized pathname 7 f_favail F_FAVAIL free nodes available to non-super user os.fpathconf(fd,name) → str / int: system configuration information basename(path)→ str: file name part of path 8 f_flag F_FLAG flags - see host statvfs() man page about file referenced by file descriptor - see platform documentation and commonprefix(pathlist) → str: longest common path prefix (char-by- 9 f_namemax F_NAMEMAX maximum file name length pathconf_names variable - name str or int (Unix) char) os.pathconf(path,name)→ str / int: system configuration information Stat Constants dirname(path)→ str: directory name of pathname about file referenced by file descriptor - see platform documentation and Defined in standard stat module. join(path[,…])→ str: concatenate path components pathconf_names variable - name str or int (Unix) S_ISUID → xxxxx normcase(path)→ str: normalize path case for platform (see doc) os.pathconf_names → dict: name → index - names accepted by S_ISGID → xxxxx normpath(path)→ str: normalize path (// /./ /../), on windows /→ \ pathconf and fpathconf → corresponding index on host (Unix) S_ENFMT → xxxxx realpath(path)→ str: canonical path (remove symlinks) (unix) os.path.exists(path)→ bool: test existing path - no broken symlinks S_ISVTX → xxxxx split(path)→ (str{2}): split into (head, last pathname component) os.path.lexists(path)→ bool: test existing path - allow broken S_IREAD → 00400 user can read splitdrive(path)→ (str{2}): split into (drive, tail) symlinks S_IWRITE → 00200 user can write splitext(path)→ (str{2}): split into (root, ext) path → float_time: last access time of path os.path.getatime( ) S_IEXEC → 00100 user can execute Host Specific Path Data path → float_time: last modification time of path os.path.getmtime( ) S_IRWXU → 00700 user can read+write+execute path → float_time: creation time (windows) or last sys.getfilesystemencoding() → str: name of encoding used by os.path.getctime( ) S_IRUSR → 00400 user can read modification time (unix) of path system for filenames S_IWUSR → 00200 user can write os.path.getsize(path)→ int: bytes size of path file Following data are in os and in os.path. S_IXUSR → 00100 user can execute os.path.isabs(path)→ bool: test absolute curdir → str: string used to refer to current directory S_IRWXG → 00070 group can read+write+execute os.path.isfile(path)→ bool: test regular file (follow symlinks) pardir → str: string used to refer to parent directory S_IRGRP → 00040 group can read os.path.isdir(path)→ bool: test existing directory (follow symlinks) sep → str: char used to separate pathname components S_IWGRP → 00020 group can write os.path.islink(path)→ bool: test symlink altsep → str: alternative char used to separate pathname components S_IXGRP → 00010 group can execute os.path.ismount(path)→ bool: test mount point extsep → str: char used to separate base filename from extension S_IRWXO → 00007 everybody can read+write+execute os.path.samefile(path1,path2)→ bool: test refer to same real file pathsep → str: conventional char to separate different paths S_IROTH → 00004 everybody can read (unix,macos) Directories S_IWOTH → 00002 everybody can write os.path.sameopenfile(f1,f2)→ bool: test opened files refer to same S_IXOTH → 00001 everybody can execute os.listdir(path)→ [str]/[unicode]: list names in path directory - real file (unix,macos) without . and .. - arbitrary order - path string type → item strings type Terminal Operations os.path.samestat(stat1,stat2)→ bool: test stat tuples refer to same os.mkdir(path[,mode=0777]) ➤ create directory path - mode masked 1 file (unix,macos) os.openpty()→ (int{2}): open pseudo-terminal pair out with umask shutil.copymode(srcpath,dstpath) ➤ copy normal file permission bits (fdmaster,fdslave)=(pty,tty) (Unix) os.makedirs(path[,mode=0777]) ➤ create directory path, recursively - shutil.copystat(srcpath,dstpath) ➤ copy normal file permission bits os.ttyname(fd)→ str: terminal device associated to fd (Unix) mode masked out with umask - don't handle Windows' UNC path and last access and modification times os.isatty(fd)→ bool: test file descriptor is a tty-like (Unix) os.rmdir(path) ➤ remove directory path Stat Structures os.tcsetpgrp(fd,pg) ➤ set process group id associted with terminal fd os.removedirs(path) ➤ remove directories, recursively (Unix) top[ topdown= [ onerror=None]] → iterable: go throught stat_result is returned by stat and lstat functions, usable as a os.walk( , True , ) os.tcgetpgrp(fd)→ int: process group associated with terminal fd dirs under top, for each dir yield tuple(dirpath, dirnames, filenames) - tuple and as object with attributes : (Unix) # attribute usage onerror=fct(os.error) - see docs path visit arg ➤ call visit(arg,dirname,names) for dirs 0 st_mode protection bits See also standard modules tty and pty. For user-interface control os.path.walk( , , ) rooted at path - may modify names (files list) to influence walk, may prefer 1 st_ino inode number on text terminal , see standard package curses and its sub- to use os.walk 11a 11b 11c Special Files independant binary format - but can broke format between raw and vars as in get() os.link(src,dst) ➤ create hard link named dst referencing src (Unix) releases). Safe Interface os.symlink(src,dst) ➤ create symbolic link named dst pointing to src Persistence sp.set(section,option,value) ➤ set value string for section and option (Unix) Standard module shelve use pickling protocol to store objects in os.readlink(path)→ str: path pointed to by symbolic link DBM files (see p17) and access them via a dictionnary-like Exceptions os.mknod(path[,mode=0666,device]) ➤ create FS node (file, device interface with keys as str. (Exception) special file, named pipe) - mode = permissions | nodetype - node type in open(filename[,flag[,protocol[,writeback[,binary]]]])→ dictionary-like Error S_IFREG, S_IFREG, S_IFCHR, S_IFBLK, and S_IFIFO defined in stat object - flag as anydbm.open (p17), default to 'c' - protocol default to 0 ParsingError module (ascii format) - writeback: cache accessed entries in memory and written NoSectionError os.major(device) → int: raw device major number them back at close time, default to False - binary is deprecated, use DuplicateSectionError os.minor(device) → int: raw device minor number protocol. MissingSectionHeaderError os.makedev(major,minor) ➤ compose raw device from major and minor NoOptionError Configuration Files numbers InterpolationError Standard module ConfigParser. It uses standard .INI files to store InterpolationDepthError Copying, Moving, Removing configudation data : InterpolationMissingOptionError os.remove(path) ➤ remove file path (not directory) [section] Values can contain %(name)s references which InterpolationSyntaxError src dst ➤ rename src to dst - on same filesystem- may os.rename( , ) name:value may be expanded using values in same section For similar file format supporting nested subsections, see remove existing dst file name=value or in defaults ConfigObj config parser. For windows users, standard module os.renames(old,new) ➤ rename old to new, recursively - try to create # and ; start comment lines. _winreg. intermediate directories Module defines 3 configuration classes with different data access For text-file configs, can use XML tools, and see also third party os.unlink(path) ➤ remove file path (not directory) - same as remove level : YAML parsers like PyYaml. Standard module shutil provides high level functions on files and RawConfigParser directories. ConfigParser EXCEPTIONS 2 SafeConfigParser copyfile(src,dst) ➤ copy normal file content - overwrite destination . Standard exceptions defined in exceptions module, and available rp=RawConfigParser([defaults]) → RawConfigParser copyfileobj(fsrc,fdst[,length=16kb]) ➤ copy file-like object content by in current scope. cp=ConfigParser([defaults]) → ConfigParser blocks of length size (<0=one chunk) All exceptions must be subclasses of Exception root class. 2 sp [defaults] → copy(src,dst) ➤ copy normal file content to file/directory - in case of =SafeConfigParser( ) SafeConfigParser Use standard exceptions if their meaning correspond to you errors. directory use same basename as src - overwrite destination - copy In the three constructors, defaults is a dict of option:value for Subclass standard exceptions when needed. permission bits. references expansion. Standard Exception Classes copy2(src,dst) ➤ same as copy + copy last access and modification MAX_INTERPOLATION_DEPTH → int: max recursive depth for get() when times2. raw parameter is false Exception ― iterator's next(), no more value. copytree(src,dst[,symlinks=False]) ➤ recursively copy directory tree - DEFAULTSECT → str: name of defaut section StopIteration SystemExit ― sys.exit() called destination must be new - files copied via copy - if symlinks is False, copy Raw Interface symbolic links files content, else just make symbolic links.1 StandardError ― built-in exceptions rp.defaults()→ dict: default values for references expansion rmtree(path[,ignore_errors=False[,onerror=None]]) ➤ recursively ArithmeticError ― arithmetic errors. rp.sections()→ [string]: list sections in config (without DEFAULT) delete directory tree - onerror=fct(fctref, path, excinfo).1 FloatingPointError rp.add_section(section) ➤ add a new section - may raise move(src,dst) ➤ recursively move file or directory tree - may rename or OverflowError DuplicateSectionError copy.1 ZeroDivisionError rp.has_section(section)→ bool: test if section exists - cant test for AssertionError ― assert cond[,message] failed. 1 May raise shutil.Error exception. DEFAULT AttributeError ― attribute set/get failed. 2 Params src and dst are files path names. rp.options(section)→ [string]: list options in section EnvironmentError ― host system error - see arg tuple attribute Encoded Files rp.has_option(section,option)→ bool: test if section and option exists IOError Standard module codecs have functions and objects to rp.read([filename]/filename)→ [filename]: try to load configuration data OSError transparently process encoded files (used internally as unicode from files (continue if fail) - return names of loaded files WindowsError ― Windows error codes. files). rp.readfp(fp[,filename]) ➤ load configuration data from file/file-like EOFError ― end-of-file with input() or raw_input(). codecs.open(filename,mode[,encoding[,errors[,buffering]]])→ file-like rp.get(section,option)→ str: option value ImportError EncodedFile object with transparent encoding/decoding rp.getint(section,option)→ int: coerce option value to int KeyboardInterrupt ― user interrupt (Ctrl-C). codecs.EncodedFile(file,input[,output[,errors]]) → file-like wrapper rp.getfloat(section,option)→ float: coerce option value to float LookupError around file, decode from input encoding and encode to output encoding rp.getboolean(section,option)→ bool: coerce option value to bool - IndexError ― non-existent sequence index. codecs.BOM → str: alias for BOM_UTF16 True is strings 1 yes true on - False is strings 0 no false off - may KeyError ― non-existent mapping key. codecs.BOM_BE → str: alias for BOM_UTF16_BE raise ValueError MemoryError codecs.BOM_LE → str: alias for BOM_UTF16_LE rp.items(section)→[(name,value)]: options in the section NameError ― non-existent name in current scope. codecs.BOM_UTF8 → str: '\xef\xbb\xbf' rp.set(section,option,value) ➤ set option to string value in section - may UnboundLocalError ― reference to an unassigned local codecs.BOM_UTF16 → str: alias for BOM_UTF16_LE or BOM_UTF16_BE raise NoSectionError variable. codecs.BOM_UTF16_BE → str: '\xfe\xff' rp.write(fileobject) ➤ write configuration data to file ReferenceError ― try accessing weak-ref disposed object. codecs.BOM_UTF16_LE → str: '\xff\xfe' rp.remove_option(section,option)→ bool: return True if there was RuntimeError ― (prefer defining ad-hoc subclasses). codecs.BOM_UTF32 → str: alias for BOM_UTF32_LE or BOM_UTF32_BE such option - may raise NoSectionError NotImplementedError codecs.BOM_UTF32_BE → str: '\x00\x00\xfe\xff' rp.remove_section(section)→ bool: return True if there was such SyntaxError codecs.BOM_UTF32_LE → str: '\xff\xfe\x00\x00' section IndentationError See Encoding - Decoding (p13) for details about encoding and rp.optionxform(option)→ str: normalized internal form of option TabError errors. Normal Interface SystemError ― a bug… in Python. Serialization cp.get(section,option[,raw[,vars]])→ string: value for option in section - TypeError Standard modules pickle and cPickle (speed up to 1000x) have % interpolation expanded unless raw is true - vars is a dict of additional ValueError ― good type, but bad value. support for data serialization of objects hierarchies. defaults - reference expansion names are processed by optionxform() UnicodeError See Python documentation. for matching Warning ― warnings superclass (see Warnings infra) See also module marshal (read/write of Python data in platform cp.items(section[,raw[,vars]])→ [(name,value)]: for given section - UserWarning 12a 12b 12c PendingDeprecationWarning Threads sc.enterabs(time,priority,action,args) → evtid: schedule a new event, DeprecationWarning Class threading.Thread is used to create new execution path in will call action(*args) at time SyntaxWarning current process. It must be called with keyword arguments. Specify sc.enter(delay,priority,action,args)→ evtid: schedule a new event, will RuntimeWarning thread code with a callable target param or by overriding run call action(*args) after delay Warnings method (remember calling inherited __init__ in subclasses), give sc.cancel(evtid)➤ remove scheduled event - may raise RuntimeError arguments in args and kwargs (tuple and dict), give a name to sc.empty()→ bool: test if scheduler events queue is empty Warnings must be subclasses of Warning root class. identify the thread - group currently not used (None). sc.run()➤ run scheduled events at their scheduling time - see docs Standard warnings module control processing of warning th = threading.Thread(group,target,name,args,kwargs) exceptions. Semaphores th.start() ➤ start thread activity (in another thread) warn(message[,category[,stacklevel]]) Classes threading.Semaphore and threading.BoundedSemaphore th.run() ➤ thread code to execute - call target if not overriden warn_explicit(message,category,filename,lineno[,module[,registry] provide simple semaphore for resources counting (without/with th.join([timeout]) ➤ wait for th termination or timeout elapsed ]) counter checking). (float_delay, default to None for infinite) showwarning(message,category,filename,lineno[,file]) sem = threading.Semaphore([value=1]) ➤ semaphore with initial th.getName()→ str: thread associated name formatwarning(message,category,filename,lineno) counter th.setName(name) ➤ set thread associated name (initial name set by filterwarnings(action[,message[,category[,module[,lineno[,append] sem = threading.BoundedSemaphore([value]) class) ]]]]) sem.acquire([blocking])→ bool/None: acquire the semaphore (consume th.isAlive()→ bool: test thread alive (started and run() not terminated) resetwarnings() one resource). blocking unspecified : wait & return None ; blocking true : th → : test thread have daemon flag sys.warnoptions .isDaemon() bool wait & return True ; blocking false : don't wait (try) & return True/False th daemonic ➤ set thread daemon flag - must be called .setDaemon( ) sem.release() ➤ release the semaphore (free one resource) Exceptions Processing before start. Initial flag inherited from creating thread. Python process exit sys.exc_info()→ (type,value,traceback) for current exception1 only after last non-daemon thread termination. Condition Variables ➤ current exception related informations cleared sys.exc_clear() A thread can't be killed or paused externally by another thread. Class threading.Condition allows threads to share state (data) sys.excepthook → (rw) fct(type, value, traceback) called for uncaught protected via a Lock. Important : condition variables (lock) must exceptions Thread Local Storage be acquired when calling wait, notify or notifyAll. See Python sys.__excepthook__ → backup of original excepthook function Class threading.local attributes values are thread local. docs. sys.tracebacklimit → int: (rw) maximum levels of traceback printed, Subclass it or use it as a namespace. cond = threading.Condition([lock]) ➤ build new condition variable, <=0 for none tlsdata = threading.local() use user providen lock (Lock or RLock) else build a new RLock 1 Or (None,None,None) if no running exception. tlsdata.x = 1 cond.acquire(*args)→ value: acquire cond. var. lock, return Standard module traceback has tools to process and format these Delayed Start Thread lock.acquire() value informations. cond.release() ➤ release cond. var. lock Class threading.Timer is a subclass of Thread which effectively cond.wait([timeout]) ➤ wait until notified or timeout elapsed- timeout is NCODING ECODING run after a specified interval from its start. E - D a float_delay (default to None=infinite blocking). Release cond. var. lock t = threading.Timer(interval,function,args=[],kwargs={}) Standard module codecs provide base support for encoding / and wait for a notification/timeout then re-acquire lock. t.cancel() ➤ timer will never run - must not be already running decoding data. This is used for character encodings, but also for cond.notify() ➤ wake up one waiting thread (if any). Create a timer that will run function with arguments args and data compression (zip, bz2) or data representation (uu, hex). cond.notifyAll() ➤ wake up all waiting threads. See Unicode strings (p5), Source encodings (p3). keyword arguments kwargs, after interval seconds have passed. Synchronized Queues See functions, classes and constants for files encoding in Encoded Mutual Exclusion Module Queue provides a class Queue to store data in a Files (p12). Classes threading.Lock and threading.RLock provide mutual synchronized FIFO queue, and two exception classes Full and Module encodings.aliases. exclusion between threads. Lock doesn't allow a thread to re- Empty. In blocking mode, full queue block producers and empty acquire a lock it already owns, RLock does (reentrant-lock). THREADS & SYNCHRONIZATION queue block consumers (in non-blocking mode they raise lock = threading.Lock() exceptions). Other organization can be built with subclassing (see Python threads use native threads. A global mutex (the GIL) lock lock = threading.RLock() source for internal methods). interpreter data during Python virtual instructions execution (it is lock.acquire([blocking])→ bool/None: acquire the lock. blocking q = queue.Queue(maxsize) ➤ build new queue - infinite queue if unlocked during I/O or long computation in native code). Check for unspecified : wait & return ; blocking true : wait & return ; None True maxsize<=0 thread switching and signal processing is performed at regular blocking false : don't wait (try) & return / True False q.qsize()→ int: size of the queue - at call time interval. lock.release() ➤ unlock a previously acquired lock sys.getcheckinterval()→ int: current thread switching check q.empty()→ bool: test if queue size if 0 - at call time interval1 Must release a lock same times as it was acquired. q.full()→ bool: test if queue size is maxsize - at call time sys.setcheckinterval(interval) ➤ set hread switching check interval1 Good practice to acquire/release locks in try/finally blocks. q.put(item[,block[,timeout]]) ➤ put item in queue - block can be For portable inter-process mutex, see third party glock.py module. true/false, timeout can be None/float_delay. May raise Queue.Full 1 Expressed in number of Python virtual instructions. Events exception. Threading Functions Class threading.Event is a synchronisation flag with thread q.put_nowait(item) ➤ same as put(item,False) Use standard high level module threading which provides several blocking mechanism to wait for the flag. q.get([block[,timeout]])→ item: removed from queue - block can be classes : Thread, local (for thread local storage), Event, Lock and evt = threading.Event() ➤ new event, with internal flag set to False true/false, timeout can be None/float_delay - may raise Queue.Empty RLock (mutex), Semaphore and BoudedSemaphore, Timer. evt.isSet()→ bool: value of event internal flag exception Module threading also provides functions : evt.set() ➤ set event internal flag to true - unlock waiting threads q.get_nowait() ➤ same as get(False) activeCount()→ int: number of currently active threads evt.clear() ➤ set event internal flag to False PROCESS currentThread()→ Thread: current running thread evt.wait([timeout]) ➤ wait for event internal flag to be true - timeout is a enumerate()→ [Thread]: list of active threads float_delay (default to None=infinite blocking) Current Process settrace(func) ➤ install trace function called before threads run Standard module os has tools to get information about and methods General purpose events scheduler manipulate current process and its environment. setprofile(func) ➤ install profile function called before threads run Module sched provides such a tool, adaptable to your needs ('time' unit is methods yours). Exiting Standard module thread supports low level thread management. sc = sched.scheduler(timefunc,delayfunc) → scheduler: timefunc Normally Python process exit when there is no more non-daemon Use modules dummy_thread and dummy_threading on platforms return numbers mesuring time, delayfunc(n) wait n time (same unit as thread running. without multithreading. timefunc output) - typically sc = sys.exit([arg=0]) ➤ exit via a SystemExit exception (may be catch) - sched.scheduler(time.time,time.sleep) arg is exit code

13a 13b 13c os._exit(n) ➤ exit without cleanup getpgrp()→ int: current gid (Unix) SIGHUP terminal or control processus disconnection os.abort() ➤ exit via a SIGABRT signal (signal may be handled) getgroups()→ [int]: list of supplemental associated gid (Unix) SIGINT keyboard interrupt Following exit codes are defined in (Unix) : setgroups(groups) ➤ set list of supplemental associated gid (Unix) SIGQUIT quit request from keyboard os 1 EX_OK no error setpgrp() ➤ call system function (Unix) SIGILL illegal instruction EX_USAGE command used incorrectly getppid()→ int: parent's pid (Unix) SIGABRT abort stop signal ➤ call system function1 (Unix) floating point error EX_DATAERR incorrect input data setsid() SIGFPE pid → : process group id of process id pid (0=current) (Unix) the KILL signal EX_NOINPUT unavailable/inaccessible input getpgid( ) int SIGKILL getsid(pid) ➤ call system function1 (Unix) SIGSEGV invalid memory reference EX_NOUSER unknown user setpgid(pid,pgrp) ➤ set process pid group to pgrp1 (Unix) SIGPIPE pipe write without reader EX_NOHOST unknown host 1 SIGALRM alarm timer elapsed EX_UNAVAILABLE required service unavailable See manual for semantics. SIGTERM termination signal EX_SOFTWARE internal error Timings, Priority SIGUSR1 user signal 1 EX_OSERR OS error times()→ (ut,st,cut,cst,ert): (float_delay{5}): user time, system time, SIGUSR2 user signal 2 EX_OSFILE missing/inaccessible file children's user time, children's system time, elapsed real time SIGCHLD terminated/stopped child EX_CANTCREAT can't create output nice(increment)→ int: renice process - return new niceness (Unix) SIGCONT continue process (if stopped) EX_IOERR error during file I/O Memory SIGSTOP stop process EX_TEMPFAIL temporary failure SIGTSTP stop request from keyboard plock(op) ➤ lock program segments into memory - see for EX_PROTOCOL illegal/invalid/not understood protocol SIGTTIN read on tty while in background exchange op values (Unix) SIGTTOU write on tty while in background EX_NOPERM not enough permissions (out of file perms) Host Informations … → see your platform documentation (man 7 signal on Linux). EX_CONFIG configuration problem strerror(code)→ str: error message for the error code EX_NOTFOUND missing data Functions to send signals are in os module : uname()→ tuple: current operating system identification, (sysname, kill(pid,sig) ➤ kill process pid with signal sig (Unix) nodename, release, version, machine) (recent Unix) You can install exit functions (for normal exit) with module atexit. killpg(pgid,sig) ➤ kill process group pgid with signal sig (Unix) register(func[,*args[,**kargs]]) ➤ register function to be called with args sys.byteorder → str: host native byte order big or little Simple External Process Control sys.winver → str: version number for registry keys (Windows) and kargs Use standard module subprocess. It wraps external process sys.platform → str: platform identifier (ex. linux2) Registered functions are called in reverse order of registration. creation and control in Popen objects. Child process exceptions Bypassed when process is terminated by a signal, an internal error, Following data are in os and in os.path. raised before execution are re-raised in parent process, exceptions or an os._exit. defpath → str: search path for os.exec*p*() and os.spawn*p*() if will have child_traceback attribute (string). Environment Variables environment PATH not defined Note : subprocess tools will never call /bin/sh implicitly. linesep → str: end of line char(s) for the plaftorm environ → dict: environment variables - modification call putenv if PIPE → -1: constant value used for Popen stdin stdout stderr params devnull → str: file path of null device supported call(*args,**kwargs)→ int: run command with arguments, wait for getenv(varname[,default=None])→ str: environment variable value Python Informations completion, return retcode - convenient wrapper around Popen object putenv(varname,value) ➤ set environment variable - affect later started sys.builtin_module_names → (str): names of modules compiled into Use Popen objects as process control tools : subprocess - may cause memory leaks (see platform documentation) interpreter p = Some functions also in os.path : sys.copyright → str: copyright of interpreter Popen(args,bufsize=0,executable=None,stdin=None,stdout=None, expanduser(path)→ str: path with initial "~" or "~user" replaced sys.hexversion → int: Python version with one digit by byte stderr=None,preexec_fn=None,close_fds=False,shell=False,cwd=N expandvars(string)→ str: string with $name or ${name} environment sys.version → str: interpreter version + build + compiler one, variable replaced sys.dllhandle → int: handle of Python DLL (Windows) env=None,universal_newlines=False,startupinfo=None,creationflags= sys.executable → str: name of interpreter executable binary Directory, Files, Terminal 0) sys.prefix → str: directory prefix for platform independant Python files args is a string/list of strings ["command","arg1","arg2",…] See also Console & Interactive Input/Output (p2), and Files - sys.api_version → int: version of Python C API bufsize like for file/open functions Terminal Operations (p11). sys.version_info → (int{3},str,int): (major, minor, micro, executable can be used to provide command in place of chdir(path) ➤ change current working directory to path releaselevel, serial) - release in alpha, beta, candidate, final args[0] fchdir(fd) ➤ change current working directory to thus represented by file stdin, stdout and stderr can be PIPE to capture file and descriptor Signal Handling communicate with subprocess Standard module signal. See doc for general rules about signals getcwd()→ str: current working directory preexec_fn is called just before child process execution usage in Python. getcwdu()→ unicode: current working directory close_fds bool force subprocess inherited files to be closed, Signal handlers are callable f(signalnum,stackframe). chroot(path) ➤ change process file-system root to path (Unix) except 0 1 and 2 umask(mask)→ int: set current numeric umask and return previous one alarm(time)→ float_delay: previous alarm remaining time - request a new shell bool force execution of command throught the shell ctermid()→ str: filename of controlling terminal (Unix) SIGALRM in time seconds - cancel previous one - time≠0 (Unix) cwd string specify working directory to set for subprocess start getlogin()→ str: name of user logged on controlling terminal (Unix) alarm(0)→ float_delay: previous alarm remaining time - cancel previous env dictionnary specify environment variables for subprocess User, process, group IDs alarm (Unix) universal_newlines translate all newlines to \n (like U mode for getsignal(signalnum)→ fct: current signal handler or SIG_IGN or SIG_DFL files) pid: process id, gid: group id, uid: user id or None (handler not installed from Python) startupinfo and creationflags are optional informations for getpid()→ int: current pid pause() ➤ sleep process until a signal is received (Unix) process creation under Windows getegid()→ int: effective gid (Unix) signal(signalnum,handler)→ fct: previous handler for signal (as p.poll()→ int/None: check child process termination, return returncode setegid(egid) ➤ set process effective gid (Unix) getsignal) - install new handler (maybe SIG_IGN or SIG_DFL too) - only attribute → : effective uid (Unix) geteuid() int callable in main thread p.wait()→ int: wait for child process to terminate, return returncode seteuid(euid) ➤ set process effective uid (Unix) Following signal constants are defined : attribute getgid()→ int: real gid (Unix) p input=None → stdout stderr : send data (input SIG_DFL → 0: default signal handler function .communicate( ) ( , ) setgid(gid) ➤ set process gid (Unix) string)to stdin, read data from stdout/stderr until end-of-file, wait process SIG_IGN → 1: ignore signal handler function getuid()→ int: current process' uid (Unix) to terminate, return read values - data read is buffered in memory NSIG → int: highest signal number +1 setuid(uid) ➤ set process current uid (Unix) p.stdin → file/None: standard input from chil process if captured setregid(rgid,egid) ➤ set process real and effective gid (Unix) Module also defines signal numbers (Posix examples - runtime p.stdout → file/None: standard output from chil process if captured setreuid(ruid,euid) ➤ set process real and effective uid (Unix) definition is platform dependant) : p.stderr → file/None: error output from chil process if captured 14a 14b 14c p.pid → int: process ID of child process WSTOPSIG(status)→ int: signal having stopped process (Unix) p.reset() ➤ after close, prepare new parsing p.returncode → int/None: child process return code (None if not WTERMSIG(status)→ int: signal having exited process (Unix) 1 Feature names in xml.sax.handler as feature_xxx. terminated) - on Unix -N for subprocess terminated by signal N Pipes On Process 2 Property names in xml.sax.handler as property_xxx. Use subprocess module when possible (cleaner, simpler interface, Three functions available in popen2 module (and in os module InputSource Interface see docs for examples). See also external module pexpect. where stdin/stdout return values are inverted). Provide source of data for parser. Advanced External Process Control popen2(cmd[,bufsize[,mode]])→ (file{2}): (stdout,stdin): execute isrc.setPublicId(id) ➤ set public identifier See following functions from os module. cmd as sub-process isrc.getPublicId() → unicode: public identifier cmd[ bufsize[ mode]] → {3} : (stdout,stdin,stderr): execl(path,[arg[,…]]) popen3( , , ) (file ) isrc.setSystemId(id) ➤ set system identifier execute cmd as sub-process execle(path,[arg[,…]],env) isrc.getSystemId() → unicode: system identifier popen4(cmd[,bufsize[,mode]])→ (file{2}): stdout_stderr,stdin): execlp(file,[arg[,…]]) isrc.setEncoding(encoding) ➤ set encoding - must be a string execute cmd as sub-process execlpe(file,[arg[,…]],env) acceptable for an XML encoding declaration - ignored if InputSource Where bufsize is buffer size for I/O pipes, and mode is (binary execv(path,args) 'b' contains character stream streams) or (text streams, default). Param cmd is a string execve(path,args,env) 't' isrc.getEncoding() → str/None (if unknown) passed to - on Unix it can be a sequence of strings execvp(file,args) os.system isrc.setByteStream(bytefile) ➤ set input byte stream - ignored if execvpe(file,args,env) passed directly to the program without shell intervention. InputSource contains character stream With exec… new program replace current process (fct don't return). On Unix, popen2 module also defines Popen3 class (used in popen2 isrc.getByteStream() → byte stream 'p' versions use PATH to locate executable file. 'e' versions use a and popen3 functions) and Popen4 class (used in popen4 function) : isrc.setCharacterStream(charfile) ➤ set character (Unicode) stream dict env to setup new program environment. 'l' versions use a Popen3(cmd[,capturestderr[,bufsize]])→ Popen3: cmd: str shell isrc.getCharacterStream() → character stream positioned arg, 'v' versions use list of variable args. command, captudestderr: bool (default False) Locator Interface spawnl(mode,path,[arg[,…]])→ int Popen4(cmd[,bufsize])→ Popen4 Instances of Locator provide these methods: spawnle(mode,path,[arg[,…]],env) → int Popen3 and Popen4 objects have following attributes : loc.getColumnNumber() → int: column number where current event spawnlp(mode,file,[arg[,…]])→ int p.poll()→ int: child return code or -1 if child not terminated ends spawnlpe(mode,file,[arg[,…]],env) → int p.wait()→ int: child return code loc.getLineNumber() → int: line number where current event ends spawnv(mode,path,args) → int p.fromchild → file: output from child (stdout and stderr for Popen4) loc.getPublicId() → str: public identifier of current event spawnve(mode,path,args,env) → int p.tochild → file: input to child loc.getSystemId() → str: system identifier of current event spawnvp(mode,file,args) → int p.childerr → file: error output from child if requested else None (None spawnvpe(mode,file,args,env) → int for Popen4) Attributes Interface With spawn… new process is created. 'lpev' versions like for exec…. p.pid → int: child process pid Also implement parts mapping protocol (copy(), get(), has_key(), If mode is P_NOWAIT or P_NOWAIT0, return child pid (Unix) or process See also module commands (Unix). items(), keys(), and values()). handle (Windows). If mode is P_WAIT, wait child termination and ai.getLength() → int: number of attributes return its exit code (>0) or its killing signal (<0). On Windows XML PROCESSING ai.getNames() → [unicode]: names of attributes mode can be, P_DETACH (same as P_NOWAIT but new process Several modules to process XML are available. Some with standard ai.getType(name)→ type of attribute name - normally 'CDATA' detached from calling process console) or P_OVERLAY (current SAX and DOM interfaces, others with more Pythonic interfaces. ai.getValue(name)→ unicode: value of attribute name process is replaced). See also third party PyXML extension package. AttributesNS Interface fork()→ pid: fork a child process, return 0 in child, child pid in parent SAX - Event-driven (Unix) Also implement Attributes interface. forkpty()→ (int{2}): (pid,fd): fork using new pseudo-terminal for child - Base functions in xml.sax module. ansi.getValueByQName(name)→ unicode: value of attribute qualified pid is 0 in child, child pid in parent - fd pseudo-terminal master end (Unix) make_parser([parser_list]) → XMLReader: built from first parser name startfile(path) ➤ open file path as if double-clicked in explorer available ansi.getNameByQName(name)→ (unicode{2}): (namespace, localname) (Windows) parse(filename_or_stream,content_handler[,error_handler]) ➤ parse for qualified name system(cmd)→ value: execute string cmd in subshell - generally return document using first parser available ansi.getQNameByName(namepair)→ unicode: qualified name for (pid/status) (Unix) or status (Windows) parseString(string,content_handler[,error_handler]) ➤ parse string (namespace, localname) wait()→ (int{2}): (pid,status) wait completion of a child process (Unix) using first parser available ansi.getQNames()→ [unicode]: qualified names of all attributes - status=0xZZTT where ZZ=exit code, TT=signal num XMLReader Interface ContentHandler Interface waitpid(pid,options)→ (int{2}): (pid,status) (Unix): Defined in xml.sax.xmlreader. Defined in xml.sax.handler. Its methods are handlers called when pid>0 wait for specific process, p = xml.sax.make_parser() → XMLReader object parser find XML structures. pid=0 wait for any child in process group, p.parse(source) ➤ completly parse source - source is filename or URL or ch = MyContentHandler() → ContentHandler subclass object pid=-1 wait for any child of current process, file-like or InputSource- input byte streams (not character streams) ch. locator ➤ set locator for origin of document pid<-1 wait for any process in process group -pid setDocumentLocator( ) p.getContentHandler() → ContentHandler: current one option in WNOHANG, WCONTINUED, WUNTRACED events p.setContentHandler(handler) ➤ set current content handler ch. ➤ beginning of document status=0xZZTT where ZZ=exit code, TT=signal num startDocument() p.getDTDHandler() → DTDHandler: current one ch. ➤ end of document waitpid(pid,options)→ (int{2}): (pid,status) (Windows): pid is any endDocument() p.setDTDHandler(handler) ➤ set current DTD handler ch. prefix uri ➤ begin of a prefix-URI namespace process handle (>0) - option ignored - status=0xZZ00 where ZZ=exit startPrefixMapping( , ) p.getEntityResolver() → EntityResolver: current one code mapping - see doc p.setEntityResolver(handler) ➤ set current entity resolver ch.endPrefixMapping(prefix) ➤ end of a prefix-URI namespace mapping Status informations extraction p.getErrorHandler() → ErrorHandler: current one ch.startElement(name,attrs) ➤ start of an element - non-namespace WCOREDUMP(status)→ bool: test process generated core-dump (Unix) p.setErrorHandler(handler) ➤ set current error handler mode - attrs has an Attributes interface (may be reused - copy data) WIFCONTINUED(status)→ bool: test process continued from a job control p.setLocale(locale) ➤ set locale for errors and warnings ch.endElement(name) ➤ end of an element - non-namespace mode stop (Unix) p.getFeature(featurename) → current settings for feature1 ch.startElementNS(name,qname,attrs) ➤ start of an element - WIFSTOPPED(status)→ bool: test process stopped (Unix) p.setFeature(featurename,value) ➤ set feature to value namespace mode - name is (uri,localname) - qname is raw XML name - WIFSIGNALED(status)→ bool: test exited on signal (Unix) p.getProperty(propertyname) → current settings for property2 attrs has an AttributesNS interface (may be reused - copy data) - WIFEXITED(status)→ bool: test process exited via exit(2) system call p.setProperty(propertyname,value) ➤ set property to value qname may be None (upon feature_namespace_prefixes) (Unix) There is also an IncrementalParser subclass interface with : ch.endElementNS(name,qname) ➤ end of an element - namespace status → : if exited via exit(2), return exit parameter WEXITSTATUS( ) int p.feed(data) ➤ process a chunk of data mode (Unix) ch. content ➤ character data - content is or p.close() ➤ assume end of document, check well-formedness, cleanup characters( ) str unicode 15a 15b 15c ch.ignorableWhitespace(whitespace) ➤ whitespaces feature_validation1 → True: report all validation errors. no longer used, must call oldChild.unlink() ch.processingInstruction(target,data) ➤ processing instruction feature_external_ges1 → True: include all external general (text) o.replaceChild(newChild,oldChild) ➤ replace existing subnode with a ch.skippedEntity(name) ➤ entity not processed entities. new one 1 DTDHandler Interface feature_external_pes → True: include all external parameter entities, o.normalize() ➤ join adjacent text nodes including the external DTD subset. o.cloneNode(deep) → Node: if deep, clone subnodes too - return clone Defined in xml.sax.handler. Its methods are handlers called when all_features → list of all features NodeList parser need DTD relative work. property_lexical_handler → optional extension handler for lexical dh = MyDTDHandler() → DTDHandler subclass object events (like comments). A sequence of nodes, usable as a Python sequence (maybe dh.notationDecl(name,publicId,systemId) ➤ notation declaration property_declaration_handler → optional extension handler for DTD- modifiable upon implementation). dh.unparsedEntityDecl(name,publicId,systemId,ndata) ➤ unparsed o.length → int: number of nodes in the sequence related events other than notations and unparsed entities. th entity declaration property_dom_node1 → visited DOM node (if DOM iterator) when parsing, o.item(i) → Node/None: i item in the list EntityResolver Interface else root DOM node. DocumentType → literal string source of current event (read only Defined in xml.sax.handler. Its methods are handlers called when property_xml_string Subclass of Node. parser need external entity resolution. property). o.nodeType → DOCUMENT_TYPE_NODE → of all properties names er = MyEntityResolver() → EntityResolver interface object all_properties list o.publicId → unicode/None: public identifier for external subset of DTD er.resolveEntity(publicId,systemId) → str/InputSource: default 1 can only be read during parsing (and modified before). o.systemId → unicode/None: system identifier URI for external subset of return systemId DOM - In-memory Tree DTD o → / : complete internal subset from the Exceptions Defined in xml.dom. Two function to register/access DOM .internalSubset unicode None processors, and some constants. document - without brackets Defined in xml.sax module. o.name → unicode/None: name of root element (as given in DOCTYPE) SAXException(msg[,exception]) registerDOMImplementation(name,factory) ➤ register DOM implementation factory o.entities → NamedNodeMap/None: definition of external entities SAXParseException(msg,exception,locator) ― invalid XML o.notations → NamedNodeMap/None: definition of notations SAXNotRecognizedException(msg[,exception]) getDOMImplementation([name[,features]]) → DOM implementation - SAXNotSupportedException(msg[,exception]) name may be None - may found name in env. var PYTHON_DOM - features Document is [(featurename,version),…] ErrorHandler Interface Subclass of Node. EMPTY_NAMESPACE → no namespace associated with a node o.nodeType → DOCUMENT_NODE Defined in xml.sax.handler. Its methods are handlers called when XML_NAMESPACE → xml prefix namespace o.documentElement → Element: root element of the document parser detect an error. Their exception parameters get XMLNS_NAMESPACE → namespace URI for namespace declarations - DOM o.createElement(tagName)→ Element: new1 element node objects. SAXParseException level 2 specification definition o.createElementNS(namespaceURI,tagName)→ Element: new1 eh = MyErroHandler() → ErrorHandler interface object XHTML_NAMESPACE → URI of XHTML namespace (XHTML 1.0) element node with namespace - tagName may have prefix eh.error(exception) ➤ recovererable error - parsing will continue if DOMImplementation o.createTextNode(data) → Element: new1 text node containing data method return o.createComment(data) → Element: new1 comment node containing eh.fatalError(exception) ➤ unrecoverable error - parsing must stop impl.hasFeature(feature,version) → bool: test for supported feature in an implementation data eh.warning(exception) ➤ minor warning - parsing will continue if method o.createProcessingInstruction(target,data) → Element: new1 return Node processing instruction node containing target and data SAX Utilities Defined in xml.dom, class Node is parent of XML components nodes o.createAttribute(name) → Element: new1 attribute node Defined in xml.sax.saxutils. classes. o.createAttributeNS(namespaceURI,qualifiedName) → Element: o → : (ro) in , , 1 escape(data[,entities]) → str: & < > escaped - escape other entities .nodeType int ELEMENT_NODE ATTRIBUTE_NODE new attribute node with namespace - tagName may have prefix replacing mapping strings (keys) by corresponding identifiers TEXT_NODE, CDATA_SECTION_NODE, ENTITY_NODE, o.getElementsByTagName(tagName) → NodeList: search for all unescape(data[,entities]) → str: & < > unescaped - PROCESSING_INSTRUCTION_NODE, COMMENT_NODE, DOCUMENT_NODE, descendants (deep search) having type tagName unescape other entities replacing mapping identifiers (keys) by DOCUMENT_TYPE_NODE, NOTATION_NODE o.getElementsByTagNameNS(namespaceURI,localName) → NodeList: corresponding strings o.parentNode → Node/None: (ro) - None for Attr nodes search for all descendants (deep search) having namespaceURI and quoteattr(data[,entities]) → str: as escape + quote string to be used o.attributes → NamedNodeMap/None: attribute objects for elements, localName (part after prefix) as attribute value else None 1 New nodes are standalone - you must insert/associate them in/to prepare_input_source(source[,base]) → InputSource: source is o.previousSibling → Node/None: (ro) previous node in parent's children document parts. o → / : (ro) next node in parent's children string, file-like, or InputSource - base is an URL string - return .nextSibling Node None Element InputSource for parser o.childNodes → [Node]: (ro) list of subnodes o.firstChild → Node/None: (ro) first subnode Subclass of Node. Class XMLGenerator is a ContentHandler writing SAX events into o.lastChild → Node/None: (ro) last subnode o.nodeType → ELEMENT_NODE an XML document (ie. reproduce original document). o.localName → unicode/None: (ro) element name without namespace o.tagName → unicode: element type name - with namespace may contain XMLGenerator([out[,encoding]]) → content handler: out file-like, deault prefix colons to sys.stdout - encoding default to 'iso-8859-1' o.prefix → unicode/None: (ro) element namespace prefix - may be o.getElementsByTagName(tagName) → NodeList: search for all Class XMLFilterBase is a default pass-throught events, can be empty string or None descendants (deep search) having type tagName subclassed to modify events on-fly before their processing by o.namespaceURI → unicode/None: (ro) URI associated to element o.getElementsByTagNameNS(namespaceURI,localName) → NodeList: application handlers. namespace search for all descendants (deep search) having namespaceURI and XMLFilterBase(base) → events filter o.nodeName → unicode/None: (ro) usage specified in subclasses localName (part after prefix) o.getAttribute(attname)→ unicode: attribute value Features & Properties o.nodeValue → unicode/None: (ro) usage specified in subclasses o attrname → : attribute node o.hasAttributes() → bool: test any attribute existence .getAttributeNode( ) Attr Defined in xml.sax.handler. Dont give their value, but their o (namespaceURI localName → : attribute o.hasChildNodes() → bool: test any subnode existence .getAttributeNS , ) unicode meaning. value o.isSameNode(other) → bool: test other refers same node 1 o.getAttributeNodeNS(namespaceURI,localName)→ Attr: attribute feature_namespaces → True: perform namespace processing. False: o.appendChild(newChild) → new Child: add new child node at end of node no namespace processing (so no namespace prefixes). subnodes - return new child 1 o.removeAttribute(attname) ➤ remove attribute by name - ignore feature_namespace_prefixes → True: report original prefixed names o.insertBefore(newChild,refChild) → new Child: add new child node missing attribute and attributes used for namespace declarations. before an existing subnode - at end of subnodes if refChild is None - return 1 o oldAttr → : remove and return oldAttr feature_string_interning → True: intern all names (elements, new child .removeAttributeNode( ) Attr o namespaceURI localName ➤ remove attribute prefixes, attributes, namespace URIs, local names). o.removeChild(oldChild) → oldChild: remove a subnode, return it - when .removeAttributeNS( , ) 16a 16b 16c by namespace URI and name - ignore missing attribute exception.msg → string: message for exception InterfaceError ― problem with interface (not database) o.setAttribute(attname,value) ➤ set attribute string value DOMException DatabaseError o.setAttributeNode(newAttr)→ Attr: set attribute from a new Attr DomstringSizeErr ― implementation limit reach DataError ― problem with data processing node - return old one HierarchyRequestErr ― insert at wrong place OperationalError ― problem during database operations o newAttr → : set attribute from a new .setAttributeNodeNS( ) Attr Attr IndexSizeErr ― index range error IntegrityError node with namespace URI and local name - return old one InuseAttributeErr ― Attr node already used in tree InternalError o.setAttributeNS(namespaceURI,qname,value)→ Attr: set attribute InvalidAccessErr ― param/operation unsupported by object ProgrammingError ― SQL programming related error string value from a namespaceURI and qname (whole attribute name) - InvalidCharacterErr ― character invalid in the context NotSupportedError return old one InvalidModificationErr ― can't modify node type Exceptions classes may also be available as Connection objects Attr InvalidStateErr ― try to use an undefined/unusable object attributes (optional). Subclass of Node. NamespaceErr ― change forbidden in namespace context Connection o.nodeType → ATTRIBUTE_NODE NotFoundErr ― node don't exist in referenced context connect(dsn[,user[,password[,host[,database]]]])→ Connection object o.name → unicode: (ro) attribute full name - may have colons NotSupportedErr ― operation/type unsupported by (interface defined as a guideline) - dsn=data source name string o.localName → unicode: (ro) attribute name - part after colons implementation cx.errorhandler → fct: (optional) handler for connection errors - o.prefix → unicode: (ro) attribute prefix - part before colons - may be NoDataAllowedErr ― no data for this node errorhandler(connection, cursor/None, errorclass, errorvalue) - default empty NoModificationAllowedErr ― can't modify object handler fill cx.messages and may raise exceptions ― invalide/illegal string NamedNodeMap SyntaxErr cx.messages → [(exception class,exception value)]: (optional) WrongDocumentErr ― impl. can't migrate nodes between docs messages received from database for operations with connection A mapping of nodes - experimentally usable as a Python mapping. cx.close() ➤ terminate connection (may rollback if not commited) o.length → int: length of attributes list DATABASES cx.commit() ➤ commit pending transactions o.item(index) → Attr: attribute at index - arbitrary but consistent order See Python.org wiki for a list of database interface modules. cx.rollback() ➤ rollback pending transactions (optionnal) Comment Some interfaces are for external DB engines (MySQL, PostgreSQL, cx.cursor()→ new Cursor object Subclass of Node. Cannot have subnode. BerkeleyDB, SQLite, Metakit…), other for pure Python DB engines (gadfly, ZODB, KirkyBase, Buzhug…). Cursor o.nodeType → COMMENT_NODE cu.arraysize → int: (RW) number of rows to fetch with fetchmany - o.data → unicode: content of the comment, without Generic access to DBM-style DBs default to 1 Standard module anydbm is a front-end to some available DB Text cu.connection → Connection: (optional) connection used by cursor modules : dbhash (→bsddb→Berkeley DB), gdbm (→GNU dbm), dbm Subclasses of . Cannot have subnode. Text part in an element. cu.description → [(name, type_code, display_size, internal_size, Node (→unix dbm) and the slow portable fallback dumbdbm. precision, scale, null_ok)]/None: describe result columns o.nodeType → TEXT_NODE Data stored in DBM-style files are accessed via a dictionary-like cu.errorhandler → fct: (optional) handler for connection errors - o.data → unicode: text content interface where keys and values must be str. errorhandler(connection, cursor, errorclass, errorvalue) - default handler CDATASection filename[ flag[ mode]] → dictionary-like object: flag in (read- open( , , ) 'r' fill cx.messages and may raise exceptions - inherited from connection default), (write), (create if doesn't exist), (create new empty) Subclasses of Node. Cannot have subnode. CDATA section in a 'w' 'c' 'n' cu.lastrowid → int/None: (optional) row id of last modified column - mode is unix mode flags for creation document, may have multiple CDATASection nodes for one CDATA. cu.messages → [(exception class,exception value)]: (optional) → tuple of exception classes from DB modules (anydbm.error,…) o.nodeType → CDATA_SECTION_NODE error messages received from database for operations with cursor Uses module to identify right DB module for existing file. o.data → unicode: CDATA content whichdb cu.rowcount → int: number of rows produced/affected by last request - For new files, use first available DB module in the order of the list. -1 or None if request cant touch rows ProcessingInstruction This is used by shelve module (see Persistence, p12). cu.rownumber → int/None: (optional) 0-based index of the cursor in the Subclasses of Node. Cannot have subnode. Represents a processing DB modules can have specific functions related to their backend, result set if available instruction in the XML document; this inherits from the Node see docs. cu.callproc(procname[,parameters])→ (parameters) - (optional) call interface and cannot have child nodes. Standard DB API for SQL databases DB stored procedure - in result out and inout parameters may have been o.nodeType → PROCESSING_INSTRUCTION_NODE Generally modules for SQL databases use the Standard Python replaced by procedure o.target → unicode: (ro) processing instruction content up to first Database API v2 (defined in PEP249). cu.close()ä close the cursor whitespace cu.execute(oper[,params]) ➤ prepare and execute DB request - o.data → unicode: (ro) processing instruction content after first API Informations params1 is a sequence or a mapping (see module paramstyle variable) whitespace → : currently or - if undefined apilevel str '1.0' '2.0' '1.0' cu.executemany(oper,params_seq) ➤ like execute, with a sequence of Exceptions threadsafety → int: level of thread safety params (for multiple values) # share module share connections share cursors cu.fetchone()→ (column_value,…) / None: next row of query result, Python map DOM error codes to exceptions. 0 no no no None when no more data available DOM codes constants Exception 1 yes no no cu.fetchmany([size])→ [(column_value)]: next set of rows of query result, DOMSTRING_SIZE_ERR DomstringSizeErr 2 yes yes no empty list when no more data available - size default to cu.arraysize HIERARCHY_REQUEST_ERR HierarchyRequestErr 3 yes yes yes INDEX_SIZE_ERR IndexSizeErr cu.fetchall()→ [(column_value)]: all remaining rows of query result, paramstyle → str: parameter marker for requests INUSE_ATTRIBUTE_ERR InuseAttributeErr empty list when no more data available value params example cu.next()→ (column_value) : (optional) next row of query result, raises INVALID_ACCESS_ERR InvalidAccessErr 1 'qmark' Question mark style …WHERE name=? StopIteration when no more data available INVALID_CHARACTER_ERR InvalidCharacterErr 1 or 2 'numeric' Numeric, positional style …WHERE name=:1 cu.nextset() → True/None: (optional) discards results up to next INVALID_MODIFICATION_ERR InvalidModificationErr 2 'named' Named style …WHERE name=:name available set INVALID_STATE_ERR InvalidStateErr 1 'format' ANSI C printf format codes …WHERE name=%s cu.scroll(value[,mode]) ➤ (optional) - scroll cursor in current result set NAMESPACE_ERR NamespaceErr 2 'pyformat Python extended format codes …WHERE name=%(name)s - mode is 'relative' (default) or 'absolute'. NOT_FOUND_ERR NotFoundErr 1 Parameters as positional values in a sequence. cu.setinputsizes(sizes) ➤ predefine memory areas for executeXXX NOT_SUPPORTED_ERR NotSupportedErr 2 Parameters as named values in a map. operations parameters - sizes=[param_size,…] - param_size=Type Object NO_DATA_ALLOWED_ERR NoDataAllowedErr or int (max length of a string param) - param_size=None for no NO_MODIFICATION_ALLOWED_ERR NoModificationAllowedErr Exceptions predefinition SYNTAX_ERR SyntaxErr (StandardError) cu.setoutputsize(size[,column]) ➤ set column buffer size for fetches WRONG_DOCUMENT_ERR WrongDocumentErr Warning ― important warning of large columns (e.g. LONGs, BLOBs, etc.) by executeXXX - column is Error ― a catch all exception.code → int: DOM code corresponding to exception index in result - all columns if column not specified 17a 17b 17c cu.__iter__() → Cursor: (optional) object itself 1 Method __getitem__ is used to get values in params, using position or name. Can use tuple or dict… or your own class objects with its __getitem__. If next and __iter__ are defined, cursors are iterable. DB types Constructors Date(year,month,day)→ object to hold a date value Time(hour,minute,second)→ object to hold a time value Timestamp(year,month,day,hour,minute,second)→ object to hold a time stamp value DateFromTicks(ticks)→ object to hold a date value from a given ticks value TimeFromTicks(ticks)→ object to hold a time value from a given ticks value TimestampFromTicks(ticks)→ object to hold a time stamp value from a given ticks value Binary(string)→ object to hold a long binary string value SQL NULL values represented by Python None. DB types Typecodes STRING → string-based column (CHAR) BINARY → long binary column (LONG, RAW, BLOBs) NUMBER → numeric column DATETIME → date/time column ROWID → row ID column (CHAR) BULK Tools Batteries included: pdb (Python debugger), code bench with timeit (p10). A must have: pychecker. Take a look: pylint, psyco, pyrex, pycount, trace2html, depgraph, coverage, pycover, Pyflakes, pyreverse, HAP. Links Docs: http://www.python.org/doc/ FAQ Python: http://www.python.org/doc/faq/ PEPs: http://www.python.org/dev/peps/ (Python Enhancement Proposal) HOWTOs: http://www.amk.ca/python/howto/ Cookbook: http://aspn.activestate.com/ASPN/Python/Cookbook/ Dive Into: http://www.diveintopython.org/

©2005-2007 - Laurent Pointal V0.67 — 2007-4-29 License : Creative Commons [by nc sa]. PQRC at http://laurent.pointal.org/python/pqrc Long Python Quick Reference at http://rgruet.free.fr/ Original Python reference at http://www.python.org/doc

18a 18b 18c