This is /home/pdm/install/Python-2.1/Doc/lib/python-lib.info, produced by makeinfo version 4.0 from lib.texi. April 15, 2001 2.1  File: python-lib.info, Node: Classes and functions, Next: interpreter stack, Prev: Retrieving source code, Up: inspect Classes and functions --------------------- `getclasstree(classes[, unique])' Arrange the given list of classes into a hierarchy of nested lists. Where a nested list appears, it contains classes derived from the class whose entry immediately precedes the list. Each entry is a 2-tuple containing a class and a tuple of its base classes. If the UNIQUE argument is true, exactly one entry appears in the returned structure for each class in the given list. Otherwise, classes using multiple inheritance and their descendants will appear multiple times. `getargspec(func)' Get the names and default values of a function's arguments. A tuple of four things is returned: `(ARGS, VARARGS, VARKW, DEFAULTS)'. ARGS is a list of the argument names (it may contain nested lists). VARARGS and VARKW are the names of the `*' and `**' arguments or `None'. DEFAULTS is a tuple of default argument values; if this tuple has N elements, they correspond to the last N elements listed in ARGS. `getargvalues(frame)' Get information about arguments passed into a particular frame. A tuple of four things is returned: `(ARGS, VARARGS, VARKW, LOCALS)'. ARGS is a list of the argument names (it may contain nested lists). VARARGS and VARKW are the names of the `*' and `**' arguments or `None'. LOCALS is the locals dictionary of the given frame. `formatargspec(args[, varargs, varkw, defaults, argformat, varargsformat, varkwformat, defaultformat])' Format a pretty argument spec from the four values returned by `getargspec()'. The other four arguments are the corresponding optional formatting functions that are called to turn names and values into strings. `formatargvalues(args[, varargs, varkw, locals, argformat, varargsformat, varkwformat, valueformat])' Format a pretty argument spec from the four values returned by `getargvalues()'. The other four arguments are the corresponding optional formatting functions that are called to turn names and values into strings.  File: python-lib.info, Node: interpreter stack, Prev: Classes and functions, Up: inspect The interpreter stack --------------------- When the following functions return "frame records," each record is a tuple of six items: the frame object, the filename, the line number of the current line, the function name, a list of lines of context from the source code, and the index of the current line within that list. The optional CONTEXT argument specifies the number of lines of context to return, which are centered around the current line. `getouterframes(frame[, context])' Get a list of frame records for a frame and all higher (calling) frames. `getinnerframes(traceback[, context])' Get a list of frame records for a traceback's frame and all lower frames. `currentframe()' Return the frame object for the caller's stack frame. `stack([context])' Return a list of frame records for the stack above the caller's frame. `trace([context])' Return a list of frame records for the stack below the current exception.  File: python-lib.info, Node: traceback, Next: linecache, Prev: inspect, Up: Python Runtime Services Print or retrieve a stack traceback =================================== Print or retrieve a stack traceback. This module provides a standard interface to extract, 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' and returned as the third item from `sys.exc_info()'. The module defines the following functions: `print_tb(traceback[, limit[, file]])' Print up to LIMIT stack trace entries from TRACEBACK. If LIMIT is omitted or `None', all entries are printed. If FILE is omitted or `None', the output goes to `sys.stderr'; otherwise it should be an open file or file-like object to receive the output. `print_exception(type, value, traceback[, limit[, file]])' Print exception information and up to LIMIT stack trace entries from TRACEBACK to FILE. This differs from `print_tb()' in the following ways: (1) if TRACEBACK is not `None', it prints a header `Traceback (most recent call 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 indicating the approximate position of the error. `print_exc([limit[, file]])' This is a shorthand for ``print_exception(sys.exc_type,' `sys.exc_value,' `sys.exc_traceback,' LIMIT`,' FILE`)''. (In fact, it uses `sys.exc_info()' to retrieve the same information in a thread-safe way.) `print_last([limit[, file]])' This is a shorthand for ``print_exception(sys.last_type,' `sys.last_value,' `sys.last_traceback,' LIMIT`,' FILE`)''. `print_stack([f[, limit[, file]]])' This function prints a stack trace from its invocation point. The optional F argument can be used to specify an alternate stack frame to start. The optional LIMIT and FILE arguments have the same meaning as for `print_exception()'. `extract_tb(traceback[, limit])' Return a list of up to LIMIT "pre-processed" stack trace entries extracted from the traceback object 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, TEXT) representing the information that is usually printed for a stack trace. The TEXT is a string with leading and trailing whitespace stripped; if the source is not available it is `None'. `extract_stack([f[, limit]])' Extract the raw traceback from the current stack frame. The return value has the same format as for `extract_tb()'. The optional F and LIMIT arguments have the same meaning as for `print_stack()'. `format_list(list)' Given a list of tuples as returned by `extract_tb()' or `extract_stack()', return a list of strings ready for printing. Each string in the resulting list corresponds to the item with the same index in the argument list. Each string ends in a newline; the strings may contain internal newlines as well, for those items whose source text line is not `None'. `format_exception_only(type, value)' Format the exception part of a traceback. The arguments are the exception type and value such as given by `sys.last_type' and `sys.last_value'. The return value is a list of strings, each ending in a newline. Normally, the list contains a single string; however, for `SyntaxError' exceptions, it contains several lines that (when printed) display detailed information about where the syntax error occurred. The message indicating which exception occurred is the always last string in the list. `format_exception(type, value, tb[, limit])' Format a stack trace and the exception information. The arguments have the same meaning as the corresponding arguments to `print_exception()'. The return value is a list of strings, each ending in a newline and some containing internal newlines. When these lines are concatenated and printed, exactly the same text is printed as does `print_exception()'. `format_tb(tb[, limit])' A shorthand for `format_list(extract_tb(TB, LIMIT))'. `format_stack([f[, limit]])' A shorthand for `format_list(extract_stack(F, LIMIT))'. `tb_lineno(tb)' This function returns the current line number set in the traceback object. This is normally the same as the `TB.tb_lineno' field of the object, but when optimization is used (the -O flag) this field is not updated correctly; this function calculates the correct value. * Menu: * Traceback Example::  File: python-lib.info, Node: Traceback Example, Prev: traceback, Up: traceback Traceback Example ----------------- This simple example implements a basic read-eval-print loop, similar to (but less useful than) the standard Python interactive interpreter loop. For a more complete implementation of the interpreter loop, refer to the `code' module. import sys, traceback def run_user_code(envdir): source = raw_input(">>> ") try: exec source in envdir except: print "Exception in user code:" print '-'*60 traceback.print_exc(file=sys.stdout) print '-'*60 envdir = {} while 1: run_user_code(envdir)  File: python-lib.info, Node: linecache, Next: pickle, Prev: traceback, Up: Python Runtime Services Random access to text lines =========================== This section was written by Moshe Zadka . This module provides random access to individual lines from text files. The `linecache' module allows one to get any line from any file, while attempting to optimize internally, using a cache, the common case where many lines are read from a single file. This is used by the `traceback' module to retrieve source lines for inclusion in the formatted traceback. The `linecache' module defines the following functions: `getline(filename, lineno)' Get line LINENO from file named FILENAME. This function will never throw an exception -- it will return `''' on errors (the terminating newline character will be included for lines that are found). If a file named FILENAME is not found, the function will look for it in the module search path, `sys.path'. `clearcache()' Clear the cache. Use this function if you no longer need lines from files previously read using `getline()'. `checkcache()' Check the cache for validity. Use this function if files in the cache may have changed on disk, and you require the updated version. Example: >>> import linecache >>> linecache.getline('/etc/passwd', 4) 'sys:x:3:3:sys:/dev:/bin/sh\n'  File: python-lib.info, Node: pickle, Next: cPickle, Prev: linecache, Up: Python Runtime Services Python object serialization =========================== Convert Python objects to streams of bytes and back. 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 persistence -- 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. *Note:* The `pickle' module is rather slow. A reimplementation of the same algorithm in C, which is up to 1000 times faster, is available as the `cPickle' module. This has the same interface except that `Pickler' and `Unpickler' are factory functions, not classes (so they cannot be used as base classes for inheritance). Although the `pickle' module can use the built-in module `marshal' internally, it differs from `marshal' in the way it handles certain kinds of data: * Recursive objects (objects containing references to themselves): `pickle' keeps track of the objects it has already serialized, so later references to the same object won't be serialized again. (The `marshal' module breaks for this.) * Object sharing (references to the same object in different places): This is similar to self-referencing objects; `pickle' stores the object once, and ensures that all other references point to the master copy. Shared objects remain shared, which can be very important for mutable objects. * User-defined classes and their instances: `marshal' does not support these at all, but `pickle' can save and restore class instances transparently. The class definition must be importable and live in the same module as when the object was stored. The data format used by `pickle' is Python-specific. This has the advantage that there are no restrictions imposed by external standards such as XDR (which can't represent pointer sharing); however it means that non-Python programs may not be able to reconstruct pickled Python objects. By default, the `pickle' data format uses a printable ASCII representation. This is slightly more voluminous than a binary representation. 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. A binary format, which is slightly more efficient, can be chosen by specifying a nonzero (true) value for the BIN argument to the `Pickler' constructor or the `dump()' and `dumps()' functions. The binary format is not the default because of backwards compatibility with the Python 1.4 pickle module. In a future version, the default may change to binary. 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 persistence 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. Furthermore, all its instance variables must be picklable. When a pickled class instance is unpickled, its `__init__()' method is normally _not_ invoked. *Note:* This is a deviation from previous versions of this module; the change was introduced in Python 1.5b2. The reason for the change is that in many cases it is desirable to have a constructor that requires arguments; it is a (minor) nuisance to have to provide a `__getinitargs__()' method. If it is desirable that the `__init__()' method be called on unpickling, a class can define a method `__getinitargs__()', which should return a _tuple_ containing the arguments to be passed to the class constructor (`__init__()'). This method is called at pickle time; the tuple it returns is incorporated in the pickle for the instance. 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 constructor for the `Pickler' class has an optional second argument, BIN. If this is present and true, the binary pickle format is used; if it is absent or false, the (less efficient, but backwards compatible) text pickle format is used. The `Unpickler' class does not have an argument to distinguish between binary and text pickle formats; it accepts either format. The following types can be pickled: * `None' * integers, long integers, floating point numbers * normal and Unicode strings * tuples, lists and dictionaries containing only picklable objects * functions defined at the top level of a module (by name reference, not storage of the implementation) * built-in functions * 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()' method 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: `dump(object, file[, bin])' Write a pickled representation of OBJECT to the open file object FILE. This is equivalent to `Pickler(FILE, BIN).dump(OBJECT)'. If the optional BIN argument is present and nonzero, the binary pickle format is used; if it is zero or absent, the (less efficient) text pickle format is used. `load(file)' Read a pickled object from the open file object FILE. This is equivalent to `Unpickler(FILE).load()'. `dumps(object[, bin])' Return the pickled representation of the object as a string, instead of writing it to a file. If the optional BIN argument is present and nonzero, the binary pickle format is used; if it is zero or absent, the (less efficient) text pickle format is used. `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. `PicklingError' This exception is raised when an unpicklable object is passed to `Pickler.dump()'. See also: *Note copy_reg:: Pickle interface constructor registration for extension types. *Note shelve:: Indexed databases of objects; uses `pickle'. *Note copy:: Shallow and deep object copying. *Note marshal:: High-performance serialization of built-in types. * Menu: * Example 3::  File: python-lib.info, Node: Example 3, Prev: pickle, Up: pickle Example ------- Here's a simple example of how to modify pickling behavior for a class. The `TextReader' class opens a text file, and returns the line number and line contents each time its `readline()' method is called. If a `TextReader' instance is pickled, all attributes _except_ the file object member are saved. When the instance is unpickled, the file is reopened, and reading resumes from the last location. The `__setstate__()' and `__getstate__()' methods are used to implement this behavior. # illustrate __setstate__ and __getstate__ methods # used in pickling. class TextReader: "Print and number lines in a text file." def __init__(self,file): self.file = file self.fh = open(file,'r') self.lineno = 0 def readline(self): self.lineno = self.lineno + 1 line = self.fh.readline() if not line: return None return "%d: %s" % (self.lineno,line[:-1]) # return data representation for pickled object def __getstate__(self): odict = self.__dict__ # get attribute dictionary del odict['fh'] # remove filehandle entry return odict # restore object state from data representation generated # by __getstate__ def __setstate__(self,dict): fh = open(dict['file']) # reopen file count = dict['lineno'] # read from file... while count: # until line count is restored fh.readline() count = count - 1 dict['fh'] = fh # create filehandle entry self.__dict__ = dict # make dict our attribute dictionary A sample usage might be something like this: >>> import TextReader >>> obj = TextReader.TextReader("TextReader.py") >>> obj.readline() '1: #!/usr/local/bin/python' >>> # (more invocations of obj.readline() here) ... obj.readline() '7: class TextReader:' >>> import pickle >>> pickle.dump(obj,open('save.p','w')) (start another Python session) >>> import pickle >>> reader = pickle.load(open('save.p')) >>> reader.readline() '8: "Print and number lines in a text file."'  File: python-lib.info, Node: cPickle, Next: copy_reg, Prev: pickle, Up: Python Runtime Services Alternate implementation of `pickle' ==================================== Faster version of `pickle', but not subclassable. This module was documented by Jim Fulton . This section was written by Fred L. Drake, Jr. . The `cPickle' module provides a similar interface and identical functionality as the `pickle' module, but can be up to 1000 times faster since it is implemented in C. The only other important difference to note is that `Pickler()' and `Unpickler()' are functions and not classes, and so cannot be subclassed. This should not be an issue in most cases. The format of the pickle data is identical to that produced using the `pickle' module, so it is possible to use `pickle' and `cPickle' interchangeably with existing pickles. (Since the pickle data format is actually a tiny stack-oriented programming language, and there are some freedoms in the encodings of certain objects, it's possible that the two modules produce different pickled data for the same input objects; however they will always be able to read each other's pickles back in.)  File: python-lib.info, Node: copy_reg, Next: shelve, Prev: cPickle, Up: Python Runtime Services Register `pickle' support functions =================================== Register `pickle' support functions. The `copy_reg' module provides support for the `pickle' and `cPickle' modules. The `copy' module is likely to use this in the future as well. It provides configuration information about object constructors which are not classes. Such constructors may be factory functions or class instances. `constructor(object)' Declares OBJECT to be a valid constructor. If OBJECT is not callable (and hence not valid as a constructor), raises `TypeError'. `pickle(type, function[, constructor])' Declares that FUNCTION should be used as a "reduction" function for objects of type TYPE; TYPE should not a class object. FUNCTION should return either a string or a tuple. The optional CONSTRUCTOR parameter, if provided, is a callable object which can be used to reconstruct the object when called with the tuple of arguments returned by FUNCTION at pickling time. `TypeError' will be raised if OBJECT is a class or CONSTRUCTOR is not callable.  File: python-lib.info, Node: shelve, Next: copy, Prev: copy_reg, Up: Python Runtime Services Python object persistence ========================= Python object persistence. 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 is not 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. See also: *Note anydbm:: Generic interface to `dbm'-style databases. *Note dbhash:: BSD `db' database interface. *Note dbm:: Standard UNIX database interface. *Note dumbdbm:: Portable implementation of the `dbm' interface. *Note gdbm:: GNU database interface, based on the `dbm' interface. *Note pickle:: Object serialization used by `shelve'. *Note cPickle:: High-performance version of `pickle'.  File: python-lib.info, Node: copy, Next: marshal, Prev: shelve, Up: Python Runtime Services Shallow and deep copy operations ================================ Shallow and deep copy operations. 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. The `deepcopy()' function avoids these problems by: * keeping a "memo" dictionary 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, stack trace, stack frame, file, socket, window, array, or 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. The `copy' module does not use the `copy_reg' registration module. In order for a class to define its own copy implementation, it can define special methods `__copy__()' and `__deepcopy__()'. The former is called to implement the shallow copy operation; no additional arguments are passed. The latter is called to implement the deep copy operation; it is passed one argument, the memo dictionary. If the `__deepcopy__()' implementation needs to make a deep copy of a component, it should call the `deepcopy()' function with the component as first argument and the memo dictionary as second argument. See also: *Note pickle:: Discussion of the special methods used to support object state retrieval and restoration.  File: python-lib.info, Node: marshal, Next: warnings, Prev: copy, Up: Python Runtime Services Alternate Python object serialization ===================================== Convert Python objects to streams of bytes and back (with different constraints). This module contains functions that can read and write Python values in a binary format. The format is specific to Python, but independent of machine architecture issues (e.g., you can write a Python value to a file on a PC, transport the file to a Sun, and read it back there). Details of the format are undocumented on purpose; it may change between Python versions (although it rarely does).(1) This is not a general "persistence" module. For general persistence and transfer of Python objects through RPC calls, see the modules `pickle' and `shelve'. The `marshal' module exists mainly to support reading and writing the "pseudo-compiled" code for Python modules of `.pyc' files. Not all Python object types are supported; in general, only objects whose value is independent from a particular invocation of Python can be written and read by this module. The following types are supported: `None', integers, long integers, floating point numbers, strings, Unicode objects, tuples, lists, dictionaries, and code objects, where it should be understood that tuples, lists and dictionaries are only supported as long as the values contained therein are themselves supported; and recursive lists and dictionaries should not be written (they will cause infinite loops). *Caveat:* On machines where C's `long int' type has more than 32 bits (such as the DEC Alpha), it is possible to create plain Python integers that are longer than 32 bits. Since the current `marshal' module uses 32 bits to transfer plain Python integers, such values are silently truncated. This particularly affects the use of very long integer literals in Python modules -- these will be accepted by the parser on such machines, but will be silently be truncated when the module is read from the `.pyc' instead.(2) There are functions that read/write files as well as functions operating on strings. The module defines these functions: `dump(value, file)' Write the value on the open file. The value must be a supported type. The file must be an open file object such as `sys.stdout' or returned by `open()' or `posix.popen()'. It must be opened in binary mode (`'wb'' or `'w+b''). If the value has (or contains an object that has) an unsupported type, a `ValueError' exception is raised -- but garbage data will also be written to the file. The object will not be properly read back by `load()'. `load(file)' Read one value from the open file and return it. If no valid value is read, raise `EOFError', `ValueError' or `TypeError'. The file must be an open file object opened in binary mode (`'rb'' or `'r+b''). *Warning:* If an object containing an unsupported type was marshalled with `dump()', `load()' will substitute `None' for the unmarshallable type. `dumps(value)' Return the string that would be written to a file by `dump(VALUE, FILE)'. The value must be a supported type. Raise a `ValueError' exception if value has (or contains an object that has) an unsupported type. `loads(string)' Convert the string to a value. If no valid value is found, raise `EOFError', `ValueError' or `TypeError'. Extra characters in the string are ignored. ---------- Footnotes ---------- (1) The name of this module stems from a bit of terminology used by the designers of Modula-3 (amongst others), who use the term "marshalling" for shipping of data around in a self-contained form. Strictly speaking, "to marshal" means to convert some data from internal to external form (in an RPC buffer for instance) and "unmarshalling" for the reverse process. (2) A solution would be to refuse such literals in the parser, since they are inherently non-portable. Another solution would be to let the `marshal' module raise an exception when an integer value would be truncated. At least one of these solutions will be implemented in a future version.  File: python-lib.info, Node: warnings, Next: imp, Prev: marshal, Up: Python Runtime Services Warning control =============== Issue warning messages and control their disposition. _Added in Python version 2.1_ Warning messages are typically issued in situations where it is useful to alert the user of some condition in a program, where that condition (normally) doesn't warrant raising an exception and terminating the program. For example, one might want to issue a warning when a program uses an obsolete module. Python programmers issue warnings by calling the `warn()' function defined in this module. (C programmers use `PyErr_Warn()'; see the for details). Warning messages are normally written to `sys.stderr', but their disposition can be changed flexibly, from ignoring all warnings to turning them into exceptions. The disposition of warnings can vary based on the warning category (see below), the text of the warning message, and the source location where it is issued. Repetitions of a particular warning for the same source location are typically suppressed. There are two stages in warning control: first, each time a warning is issued, a determination is made whether a message should be issued or not; next, if a message is to be issued, it is formatted and printed using a user-settable hook. The determination whether to issue a warning message is controlled by the warning filter, which is a sequence of matching rules and actions. Rules can be added to the filter by calling `filterwarnings()' and reset to its default state by calling `resetwarnings()'. The printing of warning messages is done by calling `showwarning()', which may be overidden; the default implementation of this function formats the message by calling `formatwarning()', which is also available for use by custom implementations. * Menu: * Warning Categories:: * Warnings Filter:: * Available Functions::  File: python-lib.info, Node: Warning Categories, Next: Warnings Filter, Prev: warnings, Up: warnings Warning Categories ------------------ There are a number of built-in exceptions that represent warning categories. This categorization is useful to be able to filter out groups of warnings. The following warnings category classes are currently defined: Class Description ------ ----- Warning This is the base class of all warning category classes. It itself a subclass of Exception. UserWarning The default category for `warn()'. DeprecationWarning Base category for warnings about deprecated features. SyntaxWarning Base category for warnings about dubious syntactic features. RuntimeWarning Base category for warnings about dubious runtime features. While these are technically built-in exceptions, they are documented here, because conceptually they belong to the warnings mechanism. User code can define additional warning categories by subclassing one of the standard warning categories. A warning category must always be a subclass of the `Warning' class.  File: python-lib.info, Node: Warnings Filter, Next: Available Functions, Prev: Warning Categories, Up: warnings The Warnings Filter ------------------- The warnings filter controls whether warnings are ignored, displayed, or turned into errors (raising an exception). Conceptually, the warnings filter maintains an ordered list of filter specifications; any specific warning is matched against each filter specification in the list in turn until a match is found; the match determines the disposition of the match. Each entry is a tuple of the form (ACTION, MESSAGE, CATEGORY, MODULE, LINENO), where: * ACTION is one of the following strings: Value Disposition ------ ----- "error" turn matching warnings into exceptions "ignore" never print matching warnings "always" always print matching warnings "default" print the first occurrence of matching warnings for each location where the warning is issued "module" print the first occurrence of matching warnings for each module where the warning is issued "once" print only the first occurrence of matching warnings, regardless of location * MESSAGE is a compiled regular expression that the warning message must match (the match is case-insensitive) * CATEGORY is a class (a subclass of `Warning') of which the warning category must be a subclass in order to match * MODULE is a compiled regular expression that the module name must match * LINENO is an integer that the line number where the warning occurred must match, or `0' to match all line numbers Since the `Warning' class is derived from the built-in `Exception' class, to turn a warning into an error we simply raise `category(message)'. The warnings filter is initialized by `-W' options passed to the Python interpreter command line. The interpreter saves the arguments for all `-W' options without interpretation in `sys.warnoptions'; the `warnings' module parses these when it is first imported (invalid options are ignored, after printing a message to `sys.stderr').  File: python-lib.info, Node: Available Functions, Prev: Warnings Filter, Up: warnings Available Functions ------------------- `warn(message[, category[, stacklevel]])' Issue a warning, or maybe ignore it or raise an exception. The CATEGORY argument, if given, must be a warning category class (see above); it defaults to `UserWarning'. This function raises an exception if the particular warning issued is changed into an error by the warnings filter see above. The STACKLEVEL argument can be used by wrapper functions written in Python, like this: def deprecation(message): warnings.warn(message, DeprecationWarning, level=2) This makes the warning refer to `deprecation()''s caller, rather than to the source of `deprecation()' itself (since the latter would defeat the purpose of the warning message). `warn_explicit(message, category, filename, lineno[, module[, registry]])' This is a low-level interface to the functionality of `warn()', passing in explicitly the message, category, filename and line number, and optionally the module name and the registry (which should be the `__warningregistry__' dictionary of the module). The module name defaults to the filename with `.py' stripped; if no registry is passed, the warning is never suppressed. `showwarning(message, category, filename, lineno[, file])' Write a warning to a file. The default implementation calls `showwarning(MESSAGE, CATEGORY, FILENAME, LINENO)' and writes the resulting string to FILE, which defaults to `sys.stderr'. You may replace this function with an alternative implementation by assigning to `warnings.showwarning'. `formatwarning(message, category, filename, lineno)' Format a warning the standard way. This returns a string which may contain embedded newlines and ends in a newline. `filterwarnings(action[, message[, category[, module[, lineno[, append]]]]])' Insert an entry into the list of warnings filters. The entry is inserted at the front by default; if APPEND is true, it is inserted at the end. This checks the types of the arguments, compiles the message and module regular expressions, and inserts them as a tuple in front of the warnings filter. Entries inserted later override entries inserted earlier, if both match a particular warning. Omitted arguments default to a value that matches everything. `resetwarnings()' Reset the warnings filter. This discards the effect of all previous calls to `filterwarnings()', including that of the `-W' command line options.