This is Info file pylibi, produced by Makeinfo-1.55 from the input file lib.texi. This file describes the built-in types, exceptions and functions and the standard modules that come with the Python system. It assumes basic knowledge about the Python language. For an informal introduction to the language, see the Python Tutorial. The Python Reference Manual gives a more formal definition of the language. (These manuals are not yet available in INFO or Texinfo format.) Copyright 1991-1995 by Stichting Mathematisch Centrum, Amsterdam, The Netherlands. All Rights Reserved Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the names of Stichting Mathematisch Centrum or CWI or Corporation for National Research Initiatives or CNRI not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. While CWI is the initial source for this software, a modified version is made available by the Corporation for National Research Initiatives (CNRI) at the Internet address ftp://ftp.python.org. STICHTING MATHEMATISCH CENTRUM AND CNRI DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM OR CNRI BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. File: pylibi, Node: Built-in Functions, Prev: Exceptions, Up: Built-in Objects Built-in Functions ================== The Python interpreter has a number of functions built into it that are always available. They are listed here in alphabetical order. - built-in function: abs (X) Return the absolute value of a number. The argument may be a plain or long integer or a floating point number. - built-in function: apply (FUNCTION, ARGS[, KEYWORDS]) The FUNCTION argument must be a callable object (a user-defined or built-in function or method, or a class object) and the ARGS argument must be a tuple. The FUNCTION is called with ARGS as argument list; the number of arguments is the the length of the tuple. (This is different from just calling `FUNC(ARGS)', since in that case there is always exactly one argument.) If the optional KEYWORDS argument is present, it must be a dictionary whose keys are strings. It specifies keyword arguments to be added to the end of the the argument list. - built-in function: chr (I) Return a string of one character whose ASCII code is the integer I, e.g., `chr(97)' returns the string `'a''. This is the inverse of `ord()'. The argument must be in the range [0..255], inclusive. - built-in function: cmp (X, Y) Compare the two objects X and Y and return an integer according to the outcome. The return value is negative if `X < Y', zero if `X == Y' and strictly positive if `X > Y'. - built-in function: coerce (X, Y) Return a tuple consisting of the two numeric arguments converted to a common type, using the same rules as used by arithmetic operations. - built-in function: compile (STRING, FILENAME, KIND) Compile the STRING into a code object. Code objects can be executed by an `exec' statement or evaluated by a call to `eval()'. The FILENAME argument should give the file from which the code was read; pass e.g. `''' if it wasn't read from a file. The KIND argument specifies what kind of code must be compiled; it can be `'exec'' if STRING consists of a sequence of statements, `'eval'' if it consists of a single expression, or `'single'' if it consists of a single interactive statement (in the latter case, expression statements that evaluate to something else than `None' will printed). - built-in function: delattr (OBJECT, NAME) This is a relative of `setattr'. The arguments are an object and a string. The string must be the name of one of the object's attributes. The function deletes the named attribute, provided the object allows it. For example, `delattr(X, 'FOOBAR')' is equivalent to `del X.FOOBAR'. - built-in function: dir () Without arguments, return the list of names in the current local symbol table. With a module, class or class instance object as argument (or anything else that has a `__dict__' attribute), returns the list of names in that object's attribute dictionary. The resulting list is sorted. For example: >>> import sys >>> dir() ['sys'] >>> dir(sys) ['argv', 'exit', 'modules', 'path', 'stderr', 'stdin', 'stdout'] >>> - built-in function: divmod (A, B) Take two numbers as arguments and return a pair of integers consisting of their integer quotient and remainder. With mixed operand types, the rules for binary arithmetic operators apply. For plain and long integers, the result is the same as `(A / B, A % B)'. For floating point numbers the result is the same as `(math.floor(A / B), A % B)'. - built-in function: eval (EXPRESSION[, GLOBALS[, LOCALS]]) The arguments are a string and two optional dictionaries. The EXPRESSION argument is parsed and evaluated as a Python expression (technically speaking, a condition list) using the GLOBALS and LOCALS dictionaries as global and local name space. If the LOCALS dictionary is omitted it defaults to the GLOBALS dictionary. If both dictionaries are omitted, the expression is executed in the environment where `eval' is called. The return value is the result of the evaluated expression. Syntax errors are reported as exceptions. Example: >>> x = 1 >>> print eval('x+1') 2 >>> This function can also be used to execute arbitrary code objects (e.g. created by `compile()'). In this case pass a code object instead of a string. The code object must have been compiled passing `'eval'' to the KIND argument. Hints: dynamic execution of statements is supported by the `exec' statement. Execution of statements from a file is supported by the `execfile()' function. The `globals()' and `locals()' functions returns the current global and local dictionary, respectively, which may be useful to pass around for use by `eval()' or `execfile()'. - built-in function: execfile (FILE[, GLOBALS[, LOCALS]]) This function is similar to the `exec' statement, but parses a file instead of a string. It is different from the `import' statement in that it does not use the module administration -- it reads the file unconditionally and does not create a new module.(1) The arguments are a file name and two optional dictionaries. The file is parsed and evaluated as a sequence of Python statements (similarly to a module) using the GLOBALS and LOCALS dictionaries as global and local name space. If the LOCALS dictionary is omitted it defaults to the GLOBALS dictionary. If both dictionaries are omitted, the expression is executed in the environment where `execfile()' is called. The return value is `None'. - built-in function: filter (FUNCTION, LIST) Construct a list from those elements of LIST for which FUNCTION returns true. If LIST is a string or a tuple, the result also has that type; otherwise it is always a list. If FUNCTION is `None', the identity function is assumed, i.e. all elements of LIST that are false (zero or empty) are removed. - built-in function: float (X) Convert a number to floating point. The argument may be a plain or long integer or a floating point number. - built-in function: getattr (OBJECT, NAME) The arguments are an object and a string. The string must be the name of one of the object's attributes. The result is the value of that attribute. For example, `getattr(X, 'FOOBAR')' is equivalent to `X.FOOBAR'. - built-in function: globals () Return a dictionary representing the current global symbol table. This is always the dictionary of the current module (inside a function or method, this is the module where it is defined, not the module from which it is called). - built-in function: hasattr (OBJECT, NAME) The arguments are an object and a string. The result is 1 if the string is the name of one of the object's attributes, 0 if not. (This is implemented by calling `getattr(object, name)' and seeing whether it raises an exception or not.) - built-in function: hash (OBJECT) Return the hash value of the object (if it has one). Hash values are 32-bit integers. They are used to quickly compare dictionary keys during a dictionary lookup. Numeric values that compare equal have the same hash value (even if they are of different types, e.g. 1 and 1.0). - built-in function: hex (X) Convert an integer number (of any size) to a hexadecimal string. The result is a valid Python expression. - built-in function: id (OBJECT) Return the `identity' of an object. This is an integer which is guaranteed to be unique and constant for this object during its lifetime. (Two objects whose lifetimes are disjunct may have the same id() value.) (Implementation note: this is the address of the object.) - built-in function: input ([PROMPT]) Almost equivalent to `eval(raw_input(PROMPT))'. Like `raw_input()', the PROMPT argument is optional. The difference is that a long input expression may be broken over multiple lines using the backslash convention. - built-in function: int (X) Convert a number to a plain integer. The argument may be a plain or long integer or a floating point number. Conversion of floating point numbers to integers is defined by the C semantics; normally the conversion truncates towards zero.(2) - built-in function: len (S) Return the length (the number of items) of an object. The argument may be a sequence (string, tuple or list) or a mapping (dictionary). - built-in function: locals () Return a dictionary representing the current local symbol table. Inside a function, modifying this dictionary does not always have the desired effect. - built-in function: long (X) Convert a number to a long integer. The argument may be a plain or long integer or a floating point number. - built-in function: map (FUNCTION, LIST, ...) Apply FUNCTION to every item of LIST and return a list of the results. If additional LIST arguments are passed, FUNCTION must take that many arguments and is applied to the items of all lists in parallel; if a list is shorter than another it is assumed to be extended with `None' items. If FUNCTION is `None', the identity function is assumed; if there are multiple list arguments, `map' returns a list consisting of tuples containing the corresponding items from all lists (i.e. a kind of transpose operation). The LIST arguments may be any kind of sequence; the result is always a list. - built-in function: max (S) Return the largest item of a non-empty sequence (string, tuple or list). - built-in function: min (S) Return the smallest item of a non-empty sequence (string, tuple or list). - built-in function: oct (X) Convert an integer number (of any size) to an octal string. The result is a valid Python expression. - built-in function: open (FILENAME[, MODE[, BUFSIZE]]) Return a new file object (described earlier under Built-in Types). The first two arguments are the same as for `stdio''s `fopen()': FILENAME is the file name to be opened, MODE indicates how the file is to be opened: `'r'' for reading, `'w'' for writing (truncating an existing file), and `'a'' opens it for appending (which on *some* UNIX systems means that *all* writes append to the end of the file, regardless of the current seek position). Modes `'r+'', `'w+'' and `'a+'' open the file for updating, provided the underlying `stdio' library understands this. On systems that differentiate between binary and text files, `'b'' appended to the mode opens the file in binary mode. If the file cannot be opened, `IOError' is raised. If MODE is omitted, it defaults to `'r''. The optional BUFSIZE argument specifies the file's desired buffer size: 0 means unbuffered, 1 means line buffered, any other positive value means use a buffer of (approximately) that size. A negative BUFSIZE means to use the system default, which is usually line buffered for for tty devices and fully buffered for other files.(3) - built-in function: ord (C) Return the ASCII value of a string of one character. E.g., `ord('a')' returns the integer `97'. This is the inverse of `chr()'. - built-in function: pow (X, Y[, Z]) Return X to the power Y; if Z is present, return X to the power Y, modulo Z (computed more efficiently than `pow(X, Y) % Z'). The arguments must have numeric types. With mixed operand types, the rules for binary arithmetic operators apply. The effective operand type is also the type of the result; if the result is not expressible in this type, the function raises an exception; e.g., `pow(2, -1)' or `pow(2, 35000)' is not allowed. - built-in function: range ([START,] END[, STEP]) This is a versatile function to create lists containing arithmetic progressions. It is most often used in `for' loops. The arguments must be plain integers. If the STEP argument is omitted, it defaults to `1'. If the START argument is omitted, it defaults to `0'. The full form returns a list of plain integers `[START, START + STEP, START + 2 * STEP, ...]'. If STEP is positive, the last element is the largest `START + I * STEP' less than END; if STEP is negative, the last element is the largest `START + I * STEP' greater than END. STEP must not be zero (or else an exception is raised). Example: >>> range(10) [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] >>> range(1, 11) [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] >>> range(0, 30, 5) [0, 5, 10, 15, 20, 25] >>> range(0, 10, 3) [0, 3, 6, 9] >>> range(0, -10, -1) [0, -1, -2, -3, -4, -5, -6, -7, -8, -9] >>> range(0) [] >>> range(1, 0) [] >>> - built-in function: raw_input ([PROMPT]) If the PROMPT argument is present, it is written to standard output without a trailing newline. The function then reads a line from input, converts it to a string (stripping a trailing newline), and returns that. When EOF is read, `EOFError' is raised. Example: >>> s = raw_input('--> ') --> Monty Python's Flying Circus >>> s "Monty Python's Flying Circus" >>> - built-in function: reduce (FUNCTION, LIST[, INITIALIZER]) Apply the binary FUNCTION to the items of LIST so as to reduce the list to a single value. E.g., `reduce(lambda x, y: x*y, LIST, 1)' returns the product of the elements of LIST. The optional INITIALIZER can be thought of as being prepended to LIST so as to allow reduction of an empty LIST. The LIST arguments may be any kind of sequence. - built-in function: reload (MODULE) Re-parse and re-initialize an already imported MODULE. The argument must be a module object, so it must have been successfully imported before. This is useful if you have edited the module source file using an external editor and want to try out the new version without leaving the Python interpreter. The return value is the module object (i.e. the same as the MODULE argument). There are a number of caveats: If a module is syntactically correct but its initialization fails, the first `import' statement for it does not bind its name locally, but does store a (partially initialized) module object in `sys.modules'. To reload the module you must first `import' it again (this will bind the name to the partially initialized module object) before you can `reload()' it. When a module is reloaded, its dictionary (containing the module's global variables) is retained. Redefinitions of names will override the old definitions, so this is generally not a problem. If the new version of a module does not define a name that was defined by the old version, the old definition remains. This feature can be used to the module's advantage if it maintains a global table or cache of objects -- with a `try' statement it can test for the table's presence and skip its initialization if desired. It is legal though generally not very useful to reload built-in or dynamically loaded modules, except for `sys', `__main__' and `__builtin__'. In certain cases, however, extension modules are not designed to be initialized more than once, and may fail in arbitrary ways when reloaded. If a module imports objects from another module using `from' ... `import' ..., calling `reload()' for the other module does not redefine the objects imported from it -- one way around this is to re-execute the `from' statement, another is to use `import' and qualified names (MODULE.NAME) instead. If a module instantiates instances of a class, reloading the module that defines the class does not affect the method definitions of the instances -- they continue to use the old class definition. The same is true for derived classes. - built-in function: repr (OBJECT) Return a string containing a printable representation of an object. This is the same value yielded by conversions (reverse quotes). It is sometimes useful to be able to access this operation as an ordinary function. For many types, this function makes an attempt to return a string that would yield an object with the same value when passed to `eval()'. - built-in function: round (X, N) Return the floating point value X rounded to N digits after the decimal point. If N is omitted, it defaults to zero. The result is a floating point number. Values are rounded to the closest multiple of 10 to the power minus N; if two multiples are equally close, rounding is done away from 0 (so e.g. `round(0.5)' is `1.0' and `round(-0.5)' is `-1.0'). - built-in function: setattr (OBJECT, NAME, VALUE) This is the counterpart of `getattr'. The arguments are an object, a string and an arbitrary value. The string must be the name of one of the object's attributes. The function assigns the value to the attribute, provided the object allows it. For example, `setattr(X, 'FOOBAR', 123)' is equivalent to `X.FOOBAR = 123'. - built-in function: str (OBJECT) Return a string containing a nicely printable representation of an object. For strings, this returns the string itself. The difference with `repr(OBJECT)' is that `str(OBJECT)' does not always attempt to return a string that is acceptable to `eval()'; its goal is to return a printable string. - built-in function: tuple (SEQUENCE) Return a tuple whose items are the same and in the same order as SEQUENCE's items. If SEQUENCE is alread a tuple, it is returned unchanged. For instance, `tuple('abc')' returns returns `('a', 'b', 'c')' and `tuple([1, 2, 3])' returns `(1, 2, 3)'. - built-in function: type (OBJECT) Return the type of an OBJECT. The return value is a type object. The standard module `types' defines names for all built-in types. For instance: >>> import types >>> if type(x) == types.StringType: print "It's a string" - built-in function: vars ([OBJECT]) Without arguments, return a dictionary corresponding to the current local symbol table. With a module, class or class instance object as argument (or anything else that has a `__dict__' attribute), returns a dictionary corresponding to the object's symbol table. The returned dictionary should not be modified: the effects on the corresponding symbol table are undefined.(4) - built-in function: xrange ([START,] END[, STEP]) This function is very similar to `range()', but returns an "xrange object" instead of a list. This is an opaque sequence type which yields the same values as the corresponding list, without actually storing them all simultaneously. The advantage of `xrange()' over `range()' is minimal (since `xrange()' still has to create the values when asked for them) except when a very large range is used on a memory-starved machine (e.g. MS-DOS) or when all of the range's elements are never used (e.g. when the loop is usually terminated with `break'). ---------- Footnotes ---------- (1) It is used relatively rarely so does not warrant being made into a statement. (2) This is ugly -- the language definition should require truncation towards zero. (3) Specifying a buffer size currently has no effect on systems that don't have `setvbuf()'. The interface to specify the buffer size is not done using a method that calls `setvbuf()', because that may dump core when called after any I/O has been performed, and there's no reliable way to determine whether this is the case. (4) In the current implementation, local variable bindings cannot normally be affected this way, but variables retrieved from other scopes (e.g. modules) can be. This may change. File: pylibi, Node: Python Services, Next: String Services, Prev: Built-in Objects, Up: Top Python Services *************** The modules described in this chapter provide a wide range of services related to the Python interpreter and its interaction with its environment. Here's an overview: -- Access system specific parameters and functions. types -- Names for all built-in types. traceback -- Print or retrieve a stack traceback. pickle -- Convert Python objects to streams of bytes and back. shelve -- Python object persistency. -- Shallow and deep copy operations. marshal -- Convert Python objects to streams of bytes and back (with different constraints). -- Access the implementation of the `import' statement. parser -- Retrieve and submit parse trees from and to the runtime support environment. __builtin__ -- The set of built-in functions. __main__ -- The environment where the top-level script is run. * Menu: * sys:: * types:: * traceback:: * pickle:: * shelve:: * copy:: * marshal:: * imp:: * __builtin__:: * __main__:: File: pylibi, Node: sys, Next: types, Prev: Python Services, Up: Python Services Built-in Module `sys' ===================== This module provides access to some variables used or maintained by the interpreter and to functions that interact strongly with the interpreter. It is always available. - data of module sys: argv The list of command line arguments passed to a Python script. `sys.argv[0]' is the script name (it is operating system dependent whether this is a full pathname or not). If the command was executed using the `-c' command line option to the interpreter, `sys.argv[0]' is set to the string `"-c"'. If no script name was passed to the Python interpreter, `sys.argv' has zero length. - data of module sys: builtin_module_names A list of strings giving the names of all modules that are compiled into this Python interpreter. (This information is not available in any other way -- `sys.modules.keys()' only lists the imported modules.) - data of module sys: exc_type - data of module sys: exc_value - data of module sys: exc_traceback These three variables are not always defined; they are set when an exception handler (an `except' clause of a `try' statement) is invoked. Their meaning is: `exc_type' gets the exception type of the exception being handled; `exc_value' gets the exception parameter (its "associated value" or the second argument to `raise'); `exc_traceback' gets a traceback object (see the Reference Manual) which encapsulates the call stack at the point where the exception originally occurred. - function of module sys: exit (N) Exit from Python with numeric exit status N. This is implemented by raising the `SystemExit' exception, so cleanup actions specified by `finally' clauses of `try' statements are honored, and it is possible to catch the exit attempt at an outer level. - data of module sys: exitfunc This value is not actually defined by the module, but can be set by the user (or by a program) to specify a clean-up action at program exit. When set, it should be a parameterless function. This function will be called when the interpreter exits in any way (except when a fatal error occurs: in that case the interpreter's internal state cannot be trusted). - data of module sys: last_type - data of module sys: last_value - data of module sys: last_traceback These three variables are not always defined; they are set when an exception is not handled and the interpreter prints an error message and a stack traceback. Their intended use is to allow an interactive user to import a debugger module and engage in post-mortem debugging without having to re-execute the command that caused the error (which may be hard to reproduce). The meaning of the variables is the same as that of `exc_type', `exc_value' and `exc_tracaback', respectively. - data of module sys: modules Gives the list of modules that have already been loaded. This can be manipulated to force reloading of modules and other tricks. - data of module sys: path A list of strings that specifies the search path for modules. Initialized from the environment variable `PYTHONPATH', or an installation-dependent default. - data of module sys: platform This string contains a platform identifier. This can be used to append platform-specific components to `sys.path', for instance. - data of module sys: ps1 - data of module sys: ps2 Strings specifying the primary and secondary prompt of the interpreter. These are only defined if the interpreter is in interactive mode. Their initial values in this case are `'>>> '' and `'... ''. - function of module sys: setcheckinterval (INTERVAL) Set the interpreter's "check interval". This integer value determines how often the interpreter checks for periodic things such as thread switches and signal handlers. The default is 10, meaning the check is performed every 10 Python virtual instructions. Setting it to a larger value may increase performance for programs using threads. Setting it to a value checks every virtual instruction, maximizing responsiveness as well as overhead. - function of module sys: settrace (TRACEFUNC) Set the system's trace function, which allows you to implement a Python source code debugger in Python. See section "How It Works" in the chapter on the Python Debugger. - function of module sys: setprofile (PROFILEFUNC) Set the system's profile function, which allows you to implement a Python source code profiler in Python. See the chapter on the Python Profiler. The system's profile function is called similarly to the system's trace function (see `sys.settrace'), but it isn't called for each executed line of code (only on call and return and when an exception occurs). Also, its return value is not used, so it can just return `None'. - data of module sys: stdin - data of module sys: stdout - data of module sys: stderr File objects corresponding to the interpreter's standard input, output and error streams. `sys.stdin' is used for all interpreter input except for scripts but including calls to `input()' and `raw_input()'. `sys.stdout' is used for the output of `print' and expression statements and for the prompts of `input()' and `raw_input()'. The interpreter's own prompts and (almost all of) its error messages go to `sys.stderr'. `sys.stdout' and `sys.stderr' needn't be built-in file objects: any object is acceptable as long as it has a `write' method that takes a string argument. (Changing these objects doesn't affect the standard I/O streams of processes executed by `popen()', `system()' or the `exec*()' family of functions in the `os' module.) - data of module sys: tracebacklimit When this variable is set to an integer value, it determines the maximum number of levels of traceback information printed when an unhandled exception occurs. The default is 1000. When set to 0 or less, all traceback information is suppressed and only the exception type and value are printed. File: pylibi, Node: types, Next: traceback, Prev: sys, Up: Python Services Standard Module `types' ======================= This module defines names for all object types that are used by the standard Python interpreter (but not for the types defined by various extension modules). It is safe to use "`from types import *'" -- the module does not export any other names besides the ones listed here. New names exported by future versions of this module will all end in `Type'. Typical use is for functions that do different things depending on their argument types, like the following: from types import * def delete(list, item): if type(item) is IntType: del list[item] else: list.remove(item) The module defines the following names: - data of module types: NoneType The type of `None'. - data of module types: TypeType The type of type objects (such as returned by `type()'). - data of module types: IntType The type of integers (e.g. `1'). - data of module types: LongType The type of long integers (e.g. `1L'). - data of module types: FloatType The type of floating point numbers (e.g. `1.0'). - data of module types: StringType The type of character strings (e.g. `'Spam''). - data of module types: TupleType The type of tuples (e.g. `(1, 2, 3, 'Spam')'). - data of module types: ListType The type of lists (e.g. `[0, 1, 2, 3]'). - data of module types: DictType The type of dictionaries (e.g. `{'Bacon': 1, 'Ham': 0}'). - data of module types: DictionaryType An alternative name for `DictType'. - data of module types: FunctionType The type of user-defined functions and lambdas. - data of module types: LambdaType An alternative name for `FunctionType'. - data of module types: CodeType The type for code objects such as returned by `compile()'. - data of module types: ClassType The type of user-defined classes. - data of module types: InstanceType The type of instances of user-defined classes. - data of module types: MethodType The type of methods of user-defined class instances. - data of module types: UnboundMethodType An alternative name for `MethodType'. - data of module types: BuiltinFunctionType The type of built-in functions like `len' or `sys.exit'. - data of module types: BuiltinMethodType An alternative name for `BuiltinFunction'. - data of module types: ModuleType The type of modules. - data of module types: FileType The type of open file objects such as `sys.stdout'. - data of module types: XRangeType The type of range objects returned by `xrange()'. - data of module types: TracebackType The type of traceback objects such as found in `sys.exc_traceback'. - data of module types: FrameType The type of frame objects such as found in `tb.tb_frame' if `tb' is a traceback object. File: pylibi, Node: traceback, Next: pickle, Prev: types, Up: Python Services Standard Module `traceback' =========================== This module provides a standard interface to format and print stack traces of Python programs. It exactly mimics the behavior of the Python interpreter when it prints a stack trace. This is useful when you want to print stack traces under program control, e.g. in a "wrapper" around the interpreter. The module uses traceback objects -- this is the object type that is stored in the variables `sys.exc_traceback' and `sys.last_traceback'. The module defines the following functions: - function of module traceback: print_tb (TRACEBACK[, LIMIT]) Print up to LIMIT stack trace entries from TRACEBACK. If LIMIT is omitted or `None', all entries are printed. - function of module traceback: extract_tb (TRACEBACK[, LIMIT]) Return a list of up to LIMIT "pre-processed" stack trace entries extracted from TRACEBACK. It is useful for alternate formatting of stack traces. If LIMIT is omitted or `None', all entries are extracted. A "pre-processed" stack trace entry is a quadruple (FILENAME, LINE NUMBER, FUNCTION NAME, LINE TEXT) representing the information that is usually printed for a stack trace. The LINE TEXT is a string with leading and trailing whitespace stripped; if the source is not available it is `None'. - function of module traceback: print_exception (TYPE, VALUE, TRACEBACK[, LIMIT]) Print exception information and up to LIMIT stack trace entries from TRACEBACK. This differs from `print_tb' in the following ways: (1) if TRACEBACK is not `None', it prints a header "`Traceback (innermost last):'"; (2) it prints the exception TYPE and VALUE after the stack trace; (3) if TYPE is `SyntaxError' and VALUE has the appropriate format, it prints the line where the syntax error occurred with a caret indication the approximate position of the error. - function of module traceback: print_exc ([LIMIT]) This is a shorthand for `print_exception(sys.exc_type,' `sys.exc_value,' `sys.exc_traceback,' `limit)'. - function of module traceback: print_last ([LIMIT]) This is a shorthand for `print_exception(sys.last_type,' `sys.last_value,' `sys.last_traceback,' `limit)'. File: pylibi, Node: pickle, Next: shelve, Prev: traceback, Up: Python Services Standard Module `pickle' ======================== The `pickle' module implements a basic but powerful algorithm for "pickling" (a.k.a. serializing, marshalling or flattening) nearly arbitrary Python objects. This is the act of converting objects to a stream of bytes (and back: "unpickling"). This is a more primitive notion than persistency -- although `pickle' reads and writes file objects, it does not handle the issue of naming persistent objects, nor the (even more complicated) area of concurrent access to persistent objects. The `pickle' module can transform a complex object into a byte stream and it can transform the byte stream into an object with the same internal structure. The most obvious thing to do with these byte streams is to write them onto a file, but it is also conceivable to send them across a network or store them in a database. The module `shelve' provides a simple interface to pickle and unpickle objects on "dbm"-style database files. Unlike the built-in module `marshal', `pickle' handles the following correctly: * recursive objects (objects containing references to themselves) * object sharing (references to the same object in different places) * user-defined classes and their instances The data format used by `pickle' is Python-specific. This has the advantage that there are no restrictions imposed by external standards such as CORBA (which probably can't represent pointer sharing or recursive objects); however it means that non-Python programs may not be able to reconstruct pickled Python objects. The `pickle' data format uses a printable ASCII representation. This is slightly more voluminous than a binary representation. However, small integers actually take *less* space when represented as minimal-size decimal strings than when represented as 32-bit binary numbers, and strings are only much longer if they contain many control characters or 8-bit characters. The big advantage of using printable ASCII (and of some other characteristics of `pickle''s representation) is that for debugging or recovery purposes it is possible for a human to read the pickled file with a standard text editor. (I could have gone a step further and used a notation like S-expressions, but the parser (currently written in Python) would have been considerably more complicated and slower, and the files would probably have become much larger.) The `pickle' module doesn't handle code objects, which the `marshal' module does. I suppose `pickle' could, and maybe it should, but there's probably no great need for it right now (as long as `marshal' continues to be used for reading and writing code objects), and at least this avoids the possibility of smuggling Trojan horses into a program. For the benefit of persistency modules written using `pickle', it supports the notion of a reference to an object outside the pickled data stream. Such objects are referenced by a name, which is an arbitrary string of printable ASCII characters. The resolution of such names is not defined by the `pickle' module -- the persistent object module will have to implement a method `persistent_load'. To write references to persistent objects, the persistent module must define a method `persistent_id' which returns either `None' or the persistent ID of the object. There are some restrictions on the pickling of class instances. First of all, the class must be defined at the top level in a module. Next, it must normally be possible to create class instances by calling the class without arguments. Usually, this is best accomplished by providing default values for all arguments to its `__init__' method (if it has one). If this is undesirable, the class can define a method `__getinitargs__()', which should return a *tuple* containing the arguments to be passed to the class constructor (`__init__()'). Classes can further influence how their instances are pickled -- if the class defines the method `__getstate__()', it is called and the return state is pickled as the contents for the instance, and if the class defines the method `__setstate__()', it is called with the unpickled state. (Note that these methods can also be used to implement copying class instances.) If there is no `__getstate__()' method, the instance's `__dict__' is pickled. If there is no `__setstate__()' method, the pickled object must be a dictionary and its items are assigned to the new instance's dictionary. (If a class defines both `__getstate__()' and `__setstate__()', the state object needn't be a dictionary -- these methods can do what they want.) This protocol is also used by the shallow and deep copying operations defined in the `copy' module. Note that when class instances are pickled, their class's code and data are not pickled along with them. Only the instance data are pickled. This is done on purpose, so you can fix bugs in a class or add methods and still load objects that were created with an earlier version of the class. If you plan to have long-lived objects that will see many versions of a class, it may be worthwhile to put a version number in the objects so that suitable conversions can be made by the class's `__setstate__()' method. When a class itself is pickled, only its name is pickled -- the class definition is not pickled, but re-imported by the unpickling process. Therefore, the restriction that the class must be defined at the top level in a module applies to pickled classes as well. The interface can be summarized as follows. To pickle an object `x' onto a file `f', open for writing: p = pickle.Pickler(f) p.dump(x) A shorthand for this is: pickle.dump(x, f) To unpickle an object `x' from a file `f', open for reading: u = pickle.Unpickler(f) x = u.load() A shorthand is: x = pickle.load(f) The `Pickler' class only calls the method `f.write' with a string argument. The `Unpickler' calls the methods `f.read' (with an integer argument) and `f.readline' (without argument), both returning a string. It is explicitly allowed to pass non-file objects here, as long as they have the right methods. The following types can be pickled: * `None' * integers, long integers, floating point numbers * strings * tuples, lists and dictionaries containing only picklable objects * classes that are defined at the top level in a module * instances of such classes whose `__dict__' or `__setstate__()' is picklable Attempts to pickle unpicklable objects will raise the `PicklingError' exception; when this happens, an unspecified number of bytes may have been written to the file. It is possible to make multiple calls to the `dump()' method of the same `Pickler' instance. These must then be matched to the same number of calls to the `load()' instance of the corresponding `Unpickler' instance. If the same object is pickled by multiple `dump()' calls, the `load()' will all yield references to the same object. *Warning*: this is intended for pickling multiple objects without intervening modifications to the objects or their parts. If you modify an object and then pickle it again using the same `Pickler' instance, the object is not pickled again -- a reference to it is pickled and the `Unpickler' will return the old value, not the modified one. (There are two problems here: (a) detecting changes, and (b) marshalling a minimal set of changes. I have no answers. Garbage Collection may also become a problem here.) Apart from the `Pickler' and `Unpickler' classes, the module defines the following functions, and an exception: - function of module pickle: dump (OBJECT, FILE) Write a pickled representation of OBECT to the open file object FILE. This is equivalent to `Pickler(file).dump(object)'. - function of module pickle: load (FILE) Read a pickled object from the open file object FILE. This is equivalent to `Unpickler(file).load()'. - function of module pickle: dumps (OBJECT) Return the pickled representation of the object as a string, instead of writing it to a file. - function of module pickle: loads (STRING) Read a pickled object from a string instead of a file. Characters in the string past the pickled object's representation are ignored. - exception of module pickle: PicklingError This exception is raised when an unpicklable object is passed to `Pickler.dump()'. File: pylibi, Node: shelve, Next: copy, Prev: pickle, Up: Python Services Standard Module `shelve' ======================== A "shelf" is a persistent, dictionary-like object. The difference with "dbm" databases is that the values (not the keys!) in a shelf can be essentially arbitrary Python objects -- anything that the `pickle' module can handle. This includes most class instances, recursive data types, and objects containing lots of shared sub-objects. The keys are ordinary strings. To summarize the interface (`key' is a string, `data' is an arbitrary object): import shelve d = shelve.open(filename) # open, with (g)dbm filename -- no suffix d[key] = data # store data at key (overwrites old data if # using an existing key) data = d[key] # retrieve data at key (raise KeyError if no # such key) del d[key] # delete data stored at key (raises KeyError # if no such key) flag = d.has_key(key) # true if the key exists list = d.keys() # a list of all existing keys (slow!) d.close() # close it Restrictions: * The choice of which database package will be used (e.g. dbm or gdbm) depends on which interface is available. Therefore it isn't safe to open the database directly using dbm. The database is also (unfortunately) subject to the limitations of dbm, if it is used -- this means that (the pickled representation of) the objects stored in the database should be fairly small, and in rare cases key collisions may cause the database to refuse updates. * Dependent on the implementation, closing a persistent dictionary may or may not be necessary to flush changes to disk. * The `shelve' module does not support *concurrent* read/write access to shelved objects. (Multiple simultaneous read accesses are safe.) When a program has a shelf open for writing, no other program should have it open for reading or writing. UNIX file locking can be used to solve this, but this differs across UNIX versions and requires knowledge about the database implementation used. File: pylibi, Node: copy, Next: marshal, Prev: shelve, Up: Python Services Standard Module `copy' ====================== This module provides generic (shallow and deep) copying operations. Interface summary: import copy x = copy.copy(y) # make a shallow copy of y x = copy.deepcopy(y) # make a deep copy of y For module specific errors, `copy.error' is raised. The difference between shallow and deep copying is only relevant for compound objects (objects that contain other objects, like lists or class instances): * A *shallow copy* constructs a new compound object and then (to the extent possible) inserts *references* into it to the objects found in the original. * A *deep copy* constructs a new compound object and then, recursively, inserts *copies* into it of the objects found in the original. Two problems often exist with deep copy operations that don't exist with shallow copy operations: * Recursive objects (compound objects that, directly or indirectly, contain a reference to themselves) may cause a recursive loop. * Because deep copy copies *everything* it may copy too much, e.g. administrative data structures that should be shared even between copies. Python's `deepcopy()' operation avoids these problems by: * keeping a table of objects already copied during the current copying pass; and * letting user-defined classes override the copying operation or the set of components copied. This version does not copy types like module, class, function, method, nor stack trace, stack frame, nor file, socket, window, nor array, nor any similar types. Classes can use the same interfaces to control copying that they use to control pickling: they can define methods called `__getinitargs__()', `__getstate__()' and `__setstate__()'. See the description of module `pickle' for information on these methods.