Linux/Unix > Python Essential Reference, Second Edition > A. The Python Library > Python Services | See All Titles

< BACK | Make Note | Bookmark | CONTINUE >

155117184014003188065099048180054212144238241179195140058238111161105083198027148244229119

### Python Services

The modules in this section are primarily used to interact with the Python interpreter and its environment.

#### `atexit`

The `atexit` module is used to register functions to execute when the Python interpreter exits. A single function is provided:

    register(func [, args [, kwargs]])

Adds function `func` to a list of functions that will execute when the interpreter exits. `args` is a tuple of arguments to pass to the function. `kwargs` is a dictionary of keyword arguments. The function is invoked as `func` `(*``args` `,**``kwargs` `)`.

##### Note

- The `atexit` module should be used instead of setting the `sys.exitfunc` variable.

? See Also sys (116).

#### `copy`

The `copy` module provides functions for making shallow and deep copies of compound objects, including lists, tuples, dictionaries, and class instances.

    copy(x)

Makes a shallow copy of `x` by creating a new compound object and duplicating the members of `x` by reference.

    deepcopy(x [, visit])

Makes a deep copy of `x` by creating a new compound object and recursively duplicating all the members of `x` . `visit` is an optional dictionary that’s used internally to detect and avoid cycles in recursively defined data structures.

A class can implement its own copy methods by implementing the methods `_ _copy_ _(``self` `)` and `_ _deepcopy_ _(``self` `,` `visit` `)`. Both methods should return a copy of the object. In addition, the `_ _deepcopy_ _()` method must accept a dictionary `visit` as described for the `deepcopy()` function. When writing `_ _deepcopy_ _()`, it’s not necessary to modify `visit` . However, `visit` should be passed to subsequent calls to `deepcopy()` (if any) performed inside the `_ _deepcopy_ _()` method.

##### Notes

- This module can be used with simple types such as integers and strings, but there’s little need to do so.

- The copy functions don’t work with modules, class objects, functions, methods, tracebacks, stack frames, files, sockets, or other similar types. When an object can’t be copied, the `copy.error` exception is raised.

- The `copy_reg` module is not used by this module.

? See Also pickle (113).

#### `copy_reg`

The `copy_reg` module extends the capabilities of the `pickle` and `cPickle` modules to handle the serialization of objects described by extension types (as defined in C extension modules). To do this, extension writers use this module to register reduction and construction functions that are used to serialize and unserialize an object, respectively.

    constructor(cfunc)

Declares `cfunc` to be a valid constructor function. `cfunc` must be a callable object that accepts the tuple of values returned by the reduction function given to the `pickle()` function.

    pickle(type, rfunc [, cfunc])

Registers `rfunc` as a reduction function for objects of type `type` . `rfunc` is a function that takes an object of the specified type and returns a tuple containing the constructor function and a tuple of arguments to pass to that function in order to reassemble the object. If supplied, `cfunc` is the constructor function that’s registered using the `constructor()` function.

##### Example

The following example shows how this module would be used to pickle complex numbers. (Note: Because complex numbers are already pickleable, this example is only intended to illustrate the use of this module.)

    # Register a method for pickling complex numbers
    import copy_reg

    # Create a complex number from two reals
    def construct_complex(real,imag):
        return complex(real,imag)        # Built-in function

    # Take a complex number 'c' and turn it into a tuple of floats
    def reduce_complex(c):
        return construct_complex, (c.real, c.imag)

    # Register our handler
    copy_reg.pickle(type(1j),reduce_complex, construct_complex)

When complex numbers are pickled, the `reduce_complex()` function is called. When the object is later unpickled, the function `construct_complex()` is called, using the tuple of values originally returned by `reduce_complex()`.

##### Notes

- `copy_reg` is a misnomer—this module isn’t used by the `copy` module.

- It’s not necessary to use this module when pickling instances of user-defined classes.

? See Also pickle (113).

#### `gc`

The `gc` module provides an interface for controlling the garbage collector used to collect cycles in objects such as lists, tuples, dictionaries, and instances. As various types of container objects are created, they’re placed on a list that’s internal to the interpreter. Whenever container objects are deallocated, they’re removed from this list. If the number of allocations exceeds the number of deallocations by a userdefinable threshold value, the garbage collector is invoked. The garbage collector works by scanning this list and identifying collections of objects that are no longer being used, but that haven’t been deallocated due to circular dependencies. In addition, the garbage collector uses a three-level generational scheme in which objects that survive the initial garbage-collection step are placed onto lists of objects that are checked less frequently. This provides better performance for programs that have a large number of long-lived objects.

    collect()

Runs a full garbage collection. This function checks all generations and returns the number of unreachable objects found.

    disable()

Disables garbage collection.

    enable()

Enables garbage collection.

    garbage

A variable containing a read-only list of the uncollectable objects that the garbage collector could not release for some reason. See notes.

    isenabled()

Returns true if garbage collection is enabled.

    set_debug(flags)

Set the garbage-collection debugging flags, which can be used to debug the behavior of the garbage collector. `flags` is the bitwise-or of the constants `DEBUG_STATS`, `DEBUG_COLLECTABLE`, `DEBUG_UNCOLLECTABLE`, `DEBUG_INSTANCES`, `DEBUG_OBJECTS`, `DEBUG_SAVEALL`, and `DEBUG_LEAK`.

    get_debug()

Returns the debugging flags currently set.

    get_threshold()

Returns the current collection threshold as a tuple.

    set_threshold(threshold0 [, threshold1[, threshold2]])

Sets the collection frequency of garbage collection. Objects are classified into three generations, where generation 0 contains the youngest objects and generation 2 contains the oldest objects. Objects that survive a garbage-collection step are moved to the next-oldest generation. Once an object reaches generation 2, it stays in that generation. `threshold0` is the difference between the number of allocations and deallocations that must be reached before garbage collection occurs in generation 0. `threshold1` is the number of collections of generation 0 that must occur before generation 1 is scanned. `threshold2` is the number of collections that must occur in generation 1 before generation 2 is collected. The default threshold is currently set to `(700,10,10)`. Setting `threshold0` to zero disables garbage collection.

##### Notes

- Circular references involving objects with a `_ _del_ _()` method are not garbage-collected and are placed on the list `gc.garbage` (uncollectable objects). These objects are not collected due to difficulties related to object finalization and the order in which `_ _del_ _()` methods should be invoked.

- To debug a leaky program, use `gc.set_debug(gc.DEBUG_LEAK)`.

- The `gc` module first appeared in Python 2.0.

#### `marshal`

The `marshal` module is used to serialize Python objects. `marshal` is similar to the `pickle` and `shelve` modules, but is less powerful and intended for use only with simple objects. It shouldn’t be used to implement persistent objects in general (use `pickle` instead).

    dump(value, file)

Writes the object `value` to the open file object `file` . If `value` is an unsupported type, a `ValueError` exception is raised.

    dumps(value)

Returns the string written by the `dump()` function. If `value` is an unsupported type, a `ValueError` exception is raised.

    load(file)

Reads and returns the next value from the open file object `file` . If no valid value is read, an `EOFError`, `ValueError`, or `TypeError` exception will be raised.

    loads(string)

Reads and returns the next value from the string `string` .

##### Notes

- Data is stored in a binary architecture-independent format.

- Only `None`, integers, long integers, floats, complex numbers, strings, Unicode strings, tuples, lists, dictionaries, and code objects are supported. Lists, tuples, and dictionaries can only contain supported objects. Class instances and recursive references in lists, tuples, and dictionaries are not supported.

- `marshal` is significantly faster than `pickle`, but isn’t as flexible.

? See Also pickle (113), shelve (153).

#### `new`

The `new` module is used to create various types of objects used by the interpreter. The primary use of this module is by applications that need to create objects in a nonstandard manner (such as when unmarshalling data).

    instance(class, dict)

Creates a class instance of `class` with dictionary `dict` without calling the `_ _init_ _()` method.

    instancemethod(function, instance, class)

Creates a method object, bound to `instance` . `function` must be a callable object. If `instance` is `None`, an unbound instance method is created.

    function(code, globals [, name [, argdefs]])

Creates a function object with the given `code` object and global namespace. `name` is the name of the function or `None` (in which case the function name is taken from `code` `.co_name`). `argdefs` is a tuple containing default parameter values.

    code(argcount, nlocals, stacksize, flags, codestring, constants, names, varnames,
    filename, name, firstlineno, lnotab)

Creates a new `code` object. See the section “Code Objects” in Chapter 3 for a description of the arguments.

    module(name)

Creates a new module object. `name` is the module name.

    classobj(name, baseclasses, dict)

Creates a new class object. `name` is the class name, `baseclasses` is a tuple of base classes, and `dict` is a dictionary defining the class namespace.

? See Also Chapter 3.

#### `operator`

The `operator` module provides functions that access the built-in operators and special methods of the interpreter described in Chapter 3. For example, `add(3, 4)` is the same as `3 + 4`. When the name of a function matches the name of a special method, it can also be invoked using its name with double underscores—for example, `_ _add_ _(3, 4)`.

Function | Description
--- | ---
`add(``a` `,` `b` `)` | Returns `a` `+` `b` for numbers
`sub(``a` `,` `b` `)` | Returns `a` `-` `b`
`mul(``a` `,` `b` `)` | Returns `a` `*` `b` for numbers
`div(``a` `,` `b` `)` | Returns `a` `/` `b`
`mod(``a` `,` `b` `)` | Returns `a` `%` `b`
`neg(``a` `)` | Returns `-``a`
`pos(``a` `)` | Returns `+``a`
`abs(``a` `)` | Returns the absolute value of `a`
`inv(``a` `)` | Returns the inverse of `a`
`lshift(``a` `,` `b` `)` | Returns `a` `<<` `b`
`rshift(``a` `,` `b` `)` | Returns `a` `>>` `b`
`and_(``a` `,` `b` `)` | Returns `a` `&` `b` (bitwise and)
`or_(``a` `,` `b` `)` | Returns `a` `|` `b` (bitwise or)
`xor(``a` `,` `b` `)` | Returns `a` `^` `b` (bitwise xor)
`not_(``a` `)` | Returns not `a`
`truth(``a` `)` | Returns `1` if `a` is true, `0` otherwise
`concat(``a` `,` `b` `)` | Returns `a` `+` `b` for sequences
`repeat(``a` `,` `b` `)` | Returns `a` `*` `b` for a sequence `a` and integer `b`
`contains(``a` `,` `b` `)` | Returns the result of `b` in `a`
`sequenceIncludes(``a` `,` `b` `)` | Returns the result of `b` in `a` (deprecated)
`countOf(``a` `,` `b` `)` | Returns the number of occurrences of `b` in `a`
`indexOf(``a` `,` `b` `)` | Returns the index of the first occurrence of `b` in `a`
`getitem(``a` `,` `b` `)` | Returns `a` `[``b` `]`
`setitem(``a` `,` `b` `,` `c` `)` | `a` `[``b` `] =` `c`
`delitem(``a` `,` `b` `)` | `del` `a` `[``b` `]`
`getslice(``a` `,` `b` `,` `c` `)` | Returns `a` `[``b` `:``c` `]`
`setslice(``a` `,` `b` `,` `c` `,` `v` `)` | Sets `a` `[``b` `:``c` `] =` `v`
`delslice(``a` `,` `b` `,` `c` `)` | `del` `a` `[``b` `:``c` `]`

In addition, the `operator` module defines the following functions for testing object properties. Note: These functions are not entirely reliable for user-defined instances, since they don’t perform an exhaustive test of the interface to see whether all functions are implemented.

Function | Description
--- | ---
`isMappingType(``o` `)` | Tests whether `o` supports the mapping interface
`isNumberType(``o` `)` | Tests whether `o` supports the number interface
`isSequenceType(``o` `)` | Tests whether `o` supports the sequence interface

? See Also “Special Methods” in Chapter 3.

#### `pickle` and `cPickle`

The `pickle` and `cPickle` modules are used to serialize Python objects into a stream of bytes suitable for storing in a file, transferring across a network, or placing in a database. This process is variously called pickling, serializing, marshalling, or flattening. The resulting byte stream can also be converted back into a series of Python objects using an unpickling process.

The pickling and unpickling process is controlled by using `Pickler` and `Unpickler` objects as created by the following two functions:

    Pickler(file [, bin])

Creates a pickling object that writes data to the file object `file` . `bin` specifies that data should be written in binary format. By default, a less efficient—but readable—text format is used.

    Unpickler(file)

Creates an unpickling object that reads data from the file object `file` . The unpickler automatically detects whether the incoming data is in binary or text format.

To serialize an object `x` onto a file `f` , the `dump()` method of the `pickler` object is used. For example:

    f = open('myfile', 'w')
    p = pickle.Pickler(f)     # Send pickled data to file f
    p.dump(x)                  # Dump x

To later unpickle the object from the file, do the following:

    f = open('myfile')
    u = pickle.Unpickler(f)
    x = u.load()               # Restore x from file f

Multiple calls to the `dump()` and `load()` methods are allowed, provided that the sequence of `load()` calls used to restore a collection of previously stored objects matches the sequence of `dump()` calls used during the pickling process.

The following functions are available as shortcuts to common pickling operations:

    dump(object, file [, bin])

Dumps a pickled representation of `object` to the file object `file` . Same as `Pickler(``file` `,` `bin` `).dump(``object` `)`.

    dumps(object [, bin])

Same as `dump()`, but returns a string containing the pickled data.

    load(file)

Loads a pickled representation of an object from the file object `file` . Same as `Unpickler(``file` `).load()`.

    loads(string)

Same as `load()`, but reads the pickled representation of an object from a string.

The following objects can be pickled:

- `None`

- Integers, long integers, floating-point numbers, and complex numbers

- Tuples, lists, and dictionaries containing only pickleable objects

- Normal and Unicode strings

- Classes defined at the top level of a module

- Instances of classes defined at the top level of a module

When class instances are pickled, their corresponding class definition must appear at the top level of a module (that is, no nested classes). When instances are unpickled, the module in which their class definition appeared is automatically imported. In addition, when instances are re-created, their `_ _init_ _()` method is not invoked. If it’s necessary to call `_ _init_ _()` when unpickling, the class must define a special method `_ _getinitargs_ _()` that returns a tuple of arguments to be supplied to `_ _init_ _()`. If present, `pickle` will call this function and encode the constructor arguments in the byte stream for use when unpickling.

It’s also worth noting that when pickling class instances in which the corresponding class definition appears in `_ _main_ _`, that class definition must be manually reloaded prior to unpickling a saved object (because there’s no way for the interpreter to know how to automatically load the necessary class definitions back into `_ _main_ _` when unpickling).

A class can define customized methods for saving and restoring its state by implementing the special methods `_ _getstate_ _()` and `_ _setstate_ _()`. The `_ _getstate_ _()` method must return a pickleable object (such as a string) representing the state of the object. The `_ _setstate_ _()` method accepts the pickled object and restores its state. If no `_ _getstate_ _()` method is found, `pickle` simply pickles an object’s `_ _dict_ _` attribute.

When an attempt is made to pickle an unsupported object type, the `pickle.PicklingError` exception is raised. If an error occurs while unpickling, the `pickle.UnpicklingError` exception is raised.

##### Notes

- Recursive objects (objects containing references to themselves) and object sharing are handled correctly. However, if the same object is dumped to a `Pickler` object more than once, only the first instance is saved (even if the object has changed between dumps).

- When class instances are pickled, their class definitions and associated code for methods are not saved. This allows classes to be modified or upgraded while still being able to read data saved from older versions.

- `pickle` defines `Pickler` and `Unpickler` as classes that can be subclassed if necessary.

- The `cPickle` module is significantly faster than `pickle`, but doesn’t allow subclassing of the `Pickler` and `Unpickler` objects.

- The data format used by `pickle` is Python-specific and shouldn’t be assumed to be compatible with any external standards such as XDR.

- Any object that provides `write()`, `read()`, and `readline()` methods can be used in place of a file.

- The `copy_reg` module is used to register new types with the `pickle` module.

? See Also shelve (153), marshal (111), copy_reg (109).

#### `site`

The `site` module is automatically imported when the interpreter starts and is used to perform site-wide initialization of packages and to set the default Unicode encoding. The module works by first creating a list of up to four directory names created from the values of `sys.prefix` and `sys.exec_prefix`. On Windows or Macintosh platforms, the list of directories is as follows:

    [ sys.prefix,
       sys.exec_prefix ]

On UNIX, the directories are as follows:

    [ sys.prefix + '/lib/pythonvers/site-packages',
      sys.prefix + '/lib/site-python',
      sys.exec_prefix + '/lib/pythonvers/site-packages',
      sys.exec_prefix + '/lib/site-python' ]

For each directory in the list, a check is made to see whether the directory exists. If so, it’s added to the `sys.path` variable. Next, a check is made to see whether it contains any path configuration files (files with a `.pth` suffix). A path configuration file contains a list of directories relative to the location of the path file that should be added to `sys.path`. For example:

    # foo package configuration file 'foo.pth'
    foo
    bar

Each directory in the path configuration file must be listed on a separate line. Comments and blank lines are ignored. When the `site` module loads the file, it checks to see whether each directory exists. If so, the directory is added to `sys.path`. Duplicated items are added to the path only once.

After all paths have been added to `sys.path`, an attempt is made to import a module named `sitecustomize`. The purpose of this module is to perform any additional (and arbitrary) site customization. If the import of `sitecustomize` fails with an `ImportError`, the error is silently ignored.

The `site` module is also responsible for setting the default Unicode encoding. By default, the encoding is set to `'ascii'`. However, the encoding can be changed by placing code in `sitecustomize.py` that calls `sys.setdefaultencoding()` with a new encoding such as `'utf-8'`. If you’re willing to experiment, the source code of `site` can also be modified to automatically set the encoding based on the machine’s locale settings.

? See Also sys (116), Chapter 8, Chapter 10.

#### `sys`

The `sys` module contains variables and functions that pertain to the operation of the interpreter and its environment. The following variables are defined:

    argv

List of command-line options passed to a program. `argv[0]` is the name of the program.

    builtin_module_names

Tuple containing names of modules built into the Python executable.

    byteorder

Native byte-ordering of the machine— `'little'` for little-endian or `'big'` for big-endian.

    copyright

String containing copyright message.

    _ _displayhook_ _

Original value of the `displayhook()` function.

    _ _excepthook_ _

Original value of the `excepthook()` function.

    dllhandle

Integer handle for the Python DLL (Windows).

    exec_prefix

Directory where platform-dependent Python files are installed.

    executable

String containing the name of the interpreter executable.

    exitfunc

Function object that’s called when the interpreter exits. It can be set to a function taking no parameters. By default, `exitfunc` is not defined. Direct use of this variable is discouraged—use the `atexit` module instead.

? See Also atexit (108).

    hexversion

Integer whose hexadecimal representation encodes the version information contained in `sys.version_info`. The value of this integer is always guaranteed to increase with newer versions of the interpreter.

    last_type, last_value, last_traceback

These variables are set when an unhandled exception is encountered and the interpreter prints an error message. `last_type` is the last exception type, `last_value` is the last exception value, and `last_traceback` is a stack trace. Note: The use of these variables is not thread-safe. `sys.exc_info()` should be used instead.

    maxint

Largest integer supported by the integer type.

    modules

Dictionary mapping module names to module objects.

    path

List of strings specifying the search path for modules. See Chapter 8, “Modules and Packages.”

    platform

Platform identifier string, such as `'linux-i386'`.

    prefix

Directory where platform-independent Python files are installed.

    ps1, ps2

Strings containing the text for the primary and secondary prompts of the interpreter. Initially, `ps1` is set to `'>>> '` and `ps2` is set to `'... '`. The `str()` method of whatever object is assigned to these values is evaluated to generate the prompt text.

    stdin, stdout, stderr

File objects corresponding to standard input, standard output, and standard error. `stdin` is used for the `raw_input()` and `input()` functions. `stdout` is used for `print` and the prompts of `raw_input()` and `input()`. `stderr` is used for the interpreter’s prompts and error messages. These variables can be assigned to any object that supports a `write()` method operating on a single string argument.

    _ _stdin_ _, _ _stdout_ _, _ _stderr_ _

File objects containing the values of `stdin`, `stdout`, and `stderr` at the start of the interpreter.

    tracebacklimit

Maximum number of levels of traceback information printed when an unhandled exception occurs. The default value is `1000`. A value of `0` suppresses all traceback information and causes only the exception type and value to be printed.

    version

Version string.

    version_info

Version information represented as a tuple `(major, minor, micro, releaselevel, serial)`. All values are integers except `releaselevel`, which is a string `'alpha'`, `'beta'`, `'candidate'`, or `'final'`.

    warnoptions

List of warning options supplied to the interpreter with the `-W` command-line option.

    winver

The version number used to form registry keys on Windows.

The following functions are available:

    displayhook([value])

This function is called to print the result of an expression when the interpreter is running in interactive mode. By default, the value of `repr(``value` `)` is printed to standard output and `value` is saved in the variable _ _ `builtin_ _._`. `displayhook` can be redefined to provide different behavior if desired.

    excepthook(type, value, traceback)

This function is called when an uncaught exception occurs. `type` is the exception class, `value` is the value supplied by the `raise` statement, and `traceback` is a traceback object. The default behavior is to print the exception and traceback to standard error. However, this function can be redefined to provide alternative handling of uncaught exceptions (which may be useful in specialized applications such as debuggers or CGI scripts).

    exc_info()

Returns a tuple (`type` , `value` , `traceback` ) containing information about the exception that’s currently being handled. `type` is the exception type, `value` is the exception parameter passed to raise, and `traceback` is a traceback object containing the call stack at the point where the exception occurred. Returns `None` if no exception is currently being handled.

    exit([n])

Exits from Python by raising the `SystemExit` exception. `n` is an integer exit code indicating a status code. A value of `0` is considered normal (the default); nonzero values are considered abnormal. If a noninteger value is given to `n`, it’s printed to `sys.stderr` and an exit code of `1` is used.

    getdefaultencoding()

Gets the default string encoding in Unicode conversions. Returns a value such as `'ascii'` or `'utf-8'`. The default encoding is set by the `site` module.

    _getframe([depth])

Returns a frame object from the call stack. If `depth` is omitted or is zero, the topmost frame is returned. Otherwise, the frame for that many calls below the current frame is returned. For example, `_getframe(1)` returns the caller’s frame. Raises `ValueError` if `depth` is invalid.

    getrecursionlimit()

Returns the recursion limit for functions.

    getrefcount(object)

Returns the reference count of `object` .

    setcheckinterval(n)

Sets the number of Python virtual machine instructions that must be executed by the interpreter before it checks for periodic events such as signals and thread context switches. The default value is `10`.

    setdefaultencoding(enc)

Sets the default encoding. `enc` is a string such as `'ascii'` or `'utf-8'`. This function is only defined inside the `site` module. It can be called from user-definable `sitecustomize` modules.

? See Also site (115).

    setprofile(pfunc)

Sets the system profile function that can be used to implement a source code profiler. See the later section “The Python Profiler” for information about the Python profiler.

    setrecursionlimit(n)

Changes the recursion limit for functions. The default value is `1000`.

    settrace(tfunc)

Sets the system trace function, which can be used to implement a debugger. See the later section “The Python Debugger” for information about the Python debugger.

#### `traceback`

The `traceback` module is used to gather and print stack traces of a program after an exception has occurred. The functions in this module operate on traceback objects such as the third item returned by the `sys.exc_info()` function.

    print_tb(traceback [, limit [, file]])

Prints up to `limit` stack trace entries from `traceback` to the file `file` . If `limit` is omitted, all the entries are printed. If `file` is omitted, the output is sent to `sys.stderr`.

    print_exception(type, value, traceback [, limit [, file]])

Prints exception information and a stack trace to `file` . `type` is the exception type and `value` is the exception value. `limit` and `file` are the same as in `print_tb()`.

    print_exc([limit [, file]])

Same as `print_exception()` applied to the information returned by the `sys.exc_info()` function.

    print_last([limit [, file]])

Same as `print_exception(sys.last_type, sys.last_value, sys.last_traceback,` `limit` `,` `file` `)`.

    print_stack([frame [, limit [, file]]])

Prints a stack trace from the point at which it’s invoked. `frame` specifies an optional stack frame from which to start. `limit` and `file` have the same meaning as for `print_tb()`.

    extract_tb(traceback [, limit])

Extracts the stack trace information used by `print_tb()`.

    extract_stack([frame [, limit]])

Extracts the stack trace information used by `print_stack()`.

    format_list(list)

Formats stack trace information for printing.

    format_exception_only(type, value)

Formats exception information for printing.

    format_exception(type, value, traceback [, limit])

Formats an exception and stack trace for printing.

    format_tb(traceback [, limit])

Same as `format_list(extract_tb(``traceback` `,` `limit` `))`.

    format_stack([frame [, limit]])

Same as `format_list(extract_stack(``frame` `,` `limit` `))`.

    tb_lineno(traceback)

Returns the line number set in a traceback object.

Additional details are available in the online documentation.

? See Also sys (116),“The Python Debugger” (289), Chapter 3, and http://www.python.org/doc/lib/module-traceback.html.

#### `types`

The `types` module defines names for all the built-in object types. The contents of this module are often used in conjunction with the built-in `isinstance()` function and other type-related operations. The module defines the following variables:

Variable | Description
--- | ---
`BufferType` | Buffer object.
`BuiltinFunctionType` | Built-in functions.
`CodeType` | Code object.
`ComplexType` | Complex numbers.
`ClassType` | User-defined class.
`DictType` | Dictionaries.
`DictionaryType` | Alternative name for dictionaries.
`EllipsisType` | Type of Ellipsis.
`FileType` | File object.
`FloatType` | Floating-point numbers.
`FrameType` | Execution frame object.
`FunctionType` | User-defined functions and lambdas.
`InstanceType` | Instance of a user-defined class.
`IntType` | Integers.
`LambdaType` | Alternative name for `FunctionType`.
`ListType` | Lists.
`LongType` | Long integers.
`MethodType` | User-defined class method.
`ModuleType` | Modules.
`NoneType` | Type of `None`.
`SliceType` | Extended slice object. Returned by `slice()`.
`StringType` | Strings.
`TracebackType` | Traceback objects.
`TupleType` | Tuples.
`TypeType` | Type of type objects.
`UnboundMethodType` | Alternative name for `MethodType`.
`UnicodeType` | Unicode string.
`XRangeType` | Object created by using `xrange()`.

##### Example

    import types
    if isinstance(s, types.ListType):
         print 'Is a list'
    else:
         print 'Is not a list'

? See Also Chapter 3.

#### `warnings`

The `warnings` module provides functions to issue and filter warning messages. Unlike exceptions, warnings are intended to alert the user to potential problems, but without generating an exception or causing execution to stop. One of the primary uses of the `warnings` module is to inform users about deprecated language features that may not be supported in future versions of Python. For example:

    >>> import regex
    _ _main_ _:1: DeprecationWarning: the regex module is deprecated; please use the re
    module
    >>>

Like exceptions, warnings are organized into a class hierarchy that describe general categories of warnings. The following table lists the currently supported categories:

Category | Description
--- | ---
`Warning` | Base class of all warning types
`UserWarning` | User-defined warning
`DeprecationWarning` | Deprecated feature
`SyntaxWarning` | Potential syntax problem
`RuntimeWarning` | Potential runtime problem

Each of these classes is available in the `_ _builtin_ _` module as well as the `exceptions` module. In addition, they’re instances of `Exception`. This makes it possible to easily convert warnings into errors.

Warnings are issued using the `warn()` function. For example:

    warnings.warn("feature X is deprecated.")
    warnings.warn("feature Y might be broken.", RuntimeWarning)

If desired, warnings can be filtered. The filtering process can be used to alter the output behavior of warning messages, ignore warnings, or turn warnings into exceptions. The `filterwarnings()` function is used to add a filter for a specific type of warning. For example:

    warnings.filterwarnings(action="ignore",
                            message=".*regex.*",
                            category=DeprecationWarning)
    import regex       # Warning message disappears

Limited forms of filtering can also be specified using the `-W` option to the interpreter. For example:

    % python -Wignore:the\ regex::DeprecationWarning

The following functions are defined in the `warnings` module:

    warn(message[, category[, stacklevel]])

Issues a warning. `message` is a string containing the warning message. `category` is the warning class, such as `DeprecationWarning`. `stacklevel` is an integer that specifies the stack frame from which the warning message should originate. By default, `category` is `UserWarning` and `stacklevel` is `1`.

    warn_explicit(message, category, filename, lineno[, module[, registry]])

This is a low-level version of the `warn()` function. `message` and `category` have the same meaning as for `warn()`. `filename` , `lineno` , and `module` explicitly specify the location of the warning. `registry` is an object representing all the currently active filters. If `registry` is omitted, the warning message is not suppressed.

    showwarning(message, category, filename, lineno[, file])

Writes a warning to a file. If `file` is omitted, the warning is printed to `sys.stderr`.

    formatwarning(message, category, filename, lineno)

Creates the formatted string that’s printed when a warning is issued.

    filterwarnings(action[, message[, category[, module[, lineno[, append]]]]])

Adds an entry to the list of warning filters. `action` is one of `'error'`, `'``ignore` `'`, `'always'`, `'default'`, `'once'`, or `'module'`, as described in the following table. `message` is a regular expression string used to match against the warning message. `category` is a warning class such as `DeprecationError`. `module` is a regular expression string that’s matched against the module name. `lineno` is a specific line number or `0` to match against all lines. `append` specifies that the filter should be appended to the list of all filters (checked last). By default, new filters are added to the beginning of the filter list. If any argument is omitted, it defaults to a value that matches all warnings.

Action | Description
--- | ---
`'error'` | Convert the warning into an exception.
`'ignore'` | Ignore the warning.
`'always'` | Always print a warning message.
`'default'` | Print the warning once for each location where the warning occurs.
`'module'` | Print the warning once for each module in which the warning occurs.
`'once'` | Print the warning once regardless of where it occurs.

    resetwarnings()

Resets all the warning filters. This discards all previous calls to `filterwarnings()` as well as options specified with `-W`.

##### Notes

- The list of currently active filters is found in the `warnings.filters` variable.

- The `warnings` module was first added to Python 2.1.

- When warnings are converted to exceptions, the warning category becomes the exception type. For instance, an error on `DeprecationWarning` raises a `DeprecationWarning` exception.

- The `-W` option can be used to specify a warning filter on the command line. The general format of this option is as follows:

      -Waction:message:category:module:lineno

  Each part has the same meaning as in the `filterwarning()` function. However, in this case the `message` and `module` fields specify substrings (instead of regular expressions) for the first part of the warning message and module name to be filtered.

#### `weakref`

The `weakref` module provides support for weak references. Normally, a reference to an object causes its reference count to increase—effectively keeping the object alive until the reference goes away. A weak reference, on the other hand, provides a way of referring to an object without increasing its reference count. A weak reference is created using the `weakref.ref()` function as follows:

    >>> class A: pass
    >>> a = A()
    >>> ar = weakref.ref(a)        # Create a weak reference to a
    >>> print ar
    <weakref at 0x135a24; to 'instance' at 0x12ce0c>

Once created, the original object can be obtained from a weak reference by simply calling it as a function with no arguments. If the underlying object still exists, it will be returned. Otherwise, `None` is returned to indicate that the original object no longer exists. For example:

    >>> print ar()                    # Print original object
    <_ _main_ _.A instance at 12ce0c>
    >>> del a                         # Delete the original object
    >>> print ar()                    # a is gone, so this now returns None
    None
    >>>

The following functions are defined by the `weakref` module:

    ref(object[, callback])

Creates a weak reference to `object` . `callback` is an optional function that will be called when `object` is about to be destroyed. If supplied, this function should accept a single argument that’s the corresponding weak reference object. More than one weak reference may refer to the same object. In this case, the `callback` functions will be called in order from the most recently applied reference to the oldest reference. `object` can be obtained from a weak reference by calling the returned weak reference object as a function with no arguments. If the original object no longer exists, `None` will be returned.

    proxy(object[, callback])

Creates a proxy using a weak reference to `object` . The returned proxy object is really a wrapper around the original object that provides access to its attributes and methods. As long as the original object exists, manipulation of the proxy object will transparently mimic the behavior of the underlying object. On the other hand, if the original object has been destroyed, operations on the proxy will raise a `weakref.ReferenceError` to indicate that the object no longer exists. `callback` is a callback function with the same meaning as for the `ref()` function. The type of a proxy object is either `ProxyType` or `CallableProxyType`, depending on whether the original object is callable.

    getweakrefcount(object)

Returns the number of weak references and proxies that refer to `object` .

    getweakrefs(object)

Returns a list of all weak reference and proxy objects that refer to `object` .

    WeakKeyDictionary([dict])

Creates a dictionary in which the keys are referenced weakly. When there are no more strong references to a key, the corresponding entry in the dictionary is automatically removed. If supplied, the items in `dict` are initially added to the returned `WeakKeyDictionary` object. Because only certain types of objects can be weakly referenced, there are many restrictions on acceptable key values. In particular, built-in strings cannot be used as weak keys. However, instances of user-defined classes that define a `_ _hash_ _()` method can be used as keys.

    WeakValueDictionary([dict])

Creates a dictionary in which the values are referenced weakly. When there are no more strong references to a value, corresponding entries in the dictionary will be discarded. If supplied, the entries in `dict` are added to the returned `WeakValueDictionary`.

##### Example

One application of weak references is to create caches of recently computed results. For instance, if a function takes a long time to compute a result, it might make sense to cache these results and reuse them as long as they’re still in use someplace in the application. For example:

    _resultcache = { }
    def foocache(x):
         if _resultcache.has_key(x):
             r = _resultcache[x]()       # Get weak ref and dereference it
             if r is not None: return r
         r = foo(x)
         _resultcache[x] = weakref.ref(r)
         return r

##### Notes

- Only class instances, functions, and methods currently support weak references. Built-in functions and most built-in types such as lists, dictionaries, strings, and numbers cannot be used.

- The dictionaries returned by `WeakKeyDictionary` and `WeakValueDictionary` are subclasses of `UserDict` in the `UserDict` module. `WeakKeyDictionary` and `WeakValueDictionary` can also be subclassed.

- If an exception occurs during the execution of a callback registered with `ref()` or `proxy()`, the exception is printed to standard error and ignored.

- Weak references are hashable as long as the original object is hashable. Moreover, the weak reference will maintain its hash value after the original object has been deleted, provided that the original hash value is computed while the object still exists.

- Weak references can be tested for equality, but not for ordering. If the objects are still alive, references are equal if the underlying objects have the same value. Otherwise, references are equal if they are the same reference.

- Weak references were first added to Python 2.1.

#### `UserDict`, `UserList`, and `UserString`

The `UserDict`, `UserList`, and `UserString` modules provide class wrappers around the built-in dictionary, list, and string types. These wrappers can be used as a base class for classes that want to override or add new methods to these types. Each module defines a single class `UserDict`, `UserList`, and `UserString`, respectively:

    UserDict([initialdata])

Returns a class instance that simulates a dictionary.

    UserList([list])

Returns a class instance that simulates a list. `list` is an optional list that will be used to set the initial value. If omitted, the list will be set to `[ ]`.

    UserString([sequence])

Returns a class instance that simulates a string. The initial value of the string is

set to the value of `str(``sequence` `)`.

In all cases, the real dictionary, list, or string object can be accessed in the `data` attribute of the instance.

##### Example

    # A dictionary with case-insensitive keys
    from UserDict import UserDict
    import string

    class MyDict(UserDict):
          # Perform a case-insensitive lookup
          def _ _getitem_ _(self,key):
                return self.data[key.lower()]
          def _ _setitem_ _(self,key,value):
                self.data[key.lower()] = value
          def _ _delitem_ _(self,key):
                del self.data[key.lower()]
          def has_key(self,key):
                return self.data.has_key(key.lower())

    # Use new dictionary-like class
    d = MyDict()
    d['Content-Type'] = 'text/html'
    print d['content-type']        # Returns 'text/html'

The `UserString` module also defines a class `MutableString` that provides an implementation of mutable strings. For example:

    a = UserString.MutableString("Hello World!")
    a[1] = 'a'         # a = "Hallo World!"
    a[6:] = 'Welt!'    # a = "Hallo Welt!"

Although mutable strings are a frequently requested Python feature, the implementation provided by `MutableString` has a number of drawbacks. First, the standard string methods such as `s` `.replace()` and `s` `.upper()` return new strings as opposed to modifying the string in place. Second, mutable strings cannot be used as dictionary keys. Finally, the mutable string implementation doesn’t provide extra memory efficiency or runtime performance, as you might expect. For instance, all changes to a `MutableString` object involve a full memory copy of the underlying string, as opposed to simply modifying the contents in place.

##### Notes

- Use of the `MutableString` class should generally be discouraged, since it provides no significant benefit over the use of standard strings. In fact, it will probably make your application run more slowly.

- Subclasses of `UserList` should provide a constructor that takes one or no arguments.

| Last updated on 3/28/2002 Python Essential Reference, Second Edition, © 2002 New Riders Publishing

< BACK | Make Note | Bookmark | CONTINUE >

© 2002, O'Reilly & Associates, Inc.