tornado.util — General-purpose utilities

Miscellaneous utility functions and classes.

This module is used internally by Tornado. It is not necessarily expected that the functions and classes defined here will be useful to other applications, but they are documented here in case they are.

The one public-facing part of this module is the Configurable class and its configure method, which becomes a part of the interface of its subclasses, including AsyncHTTPClient, IOLoop, and Resolver.

class tornado.util.ObjectDict

Makes a dictionary behave like an object, with attribute-style access.

class tornado.util.GzipDecompressor

Streaming gzip decompressor.

The interface is like that of zlib.decompressobj (without the optional arguments, but it understands gzip headers and checksums.

decompress(value)

Decompress a chunk, returning newly-available data.

Some data may be buffered for later processing; flush must be called when there is no more input data to ensure that all data was processed.

flush()

Return any remaining buffered data not yet returned by decompress.

Also checks for errors such as truncated input. No other methods may be called on this object after flush.

tornado.util.import_object(name)

Imports an object by name.

import_object(‘x’) is equivalent to ‘import x’. import_object(‘x.y.z’) is equivalent to ‘from x.y import z’.

>>> import tornado.escape
>>> import_object('tornado.escape') is tornado.escape
True
>>> import_object('tornado.escape.utf8') is tornado.escape.utf8
True
>>> import_object('tornado') is tornado
True
>>> import_object('tornado.missing_module')
Traceback (most recent call last):
    ...
ImportError: No module named missing_module

class tornado.util.Configurable

Base class for configurable interfaces.

A configurable interface is an (abstract) class whose constructor acts as a factory function for one of its implementation subclasses. The implementation subclass as well as optional keyword arguments to its initializer can be set globally at runtime with configure.

By using the constructor as the factory method, the interface looks like a normal class, isinstance works as usual, etc. This pattern is most useful when the choice of implementation is likely to be a global decision (e.g. when epoll is available, always use it instead of select), or when a previously-monolithic class has been split into specialized subclasses.

Configurable subclasses must define the class methods configurable_base and configurable_default, and use the instance method initialize instead of __init__.

classmethod configurable_base()

Returns the base class of a configurable hierarchy.

This will normally return the class in which it is defined. (which is not necessarily the same as the cls classmethod parameter).

classmethod configurable_default()

Returns the implementation class to be used if none is configured.

initialize()

Initialize a Configurable subclass instance.

Configurable classes should use initialize instead of __init__.

classmethod configure(impl, **kwargs)

Sets the class to use when the base class is instantiated.

Keyword arguments will be saved and added to the arguments passed to the constructor. This can be used to set global defaults for some parameters.

classmethod configured_class()

Returns the currently configured class.

class tornado.util.ArgReplacer(func, name)

Replaces one value in an args, kwargs pair.

Inspects the function signature to find an argument by name whether it is passed by position or keyword. For use in decorators and similar wrappers.

replace(new_value, args, kwargs)

Replace the named argument in args, kwargs with new_value.

Returns (old_value, args, kwargs). The returned args and kwargs objects may not be the same as the input objects, or the input objects may be mutated.

If the named argument was not found, new_value will be added to kwargs and None will be returned as old_value.