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.TimeoutError

Exception raised by gen.with_timeout and IOLoop.run_sync.

Changed in version 5.0: Unified tornado.gen.TimeoutError and tornado.ioloop.TimeoutError as tornado.util.TimeoutError. Both former names remain as aliases.

Changed in version 6.2: tornado.util.TimeoutError is an alias to asyncio.TimeoutError

Deprecated since version 6.6: tornado.util.TimeoutError, tornado.gen.TimeoutError, and tornado.ioloop.TimeoutError are aliases for the builtin TimeoutError, which should be used instead.

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 some of the optional arguments, but it understands gzip headers and checksums.

Changed in version 6.6: Streams containing multiple gzip members (as defined in RFC 1952 section 2.2) are now decompressed in full; previously everything after the first member was ignored. Any data after the last member that is not the start of another member is now an error, as is a stream that ends partway through a member.

decompress(value: bytes, max_length: int = 0) → bytes

Decompress a chunk, returning newly-available data.

When there is no more input, call flush to check that the stream was complete.

If max_length is given, some input data may be left over in unconsumed_tail; you must retrieve this value and pass it back to a future call to decompress if it is not empty. A call may return less than max_length, or nothing at all, even though unconsumed_tail is not empty (for example, at the end of one gzip member and the start of the next), so keep calling decompress until unconsumed_tail is empty.

Raises zlib.error if the input is not valid gzip data.

Deprecated since version 6.6: Calling this method without max_length (or with max_length=0) is deprecated, because a small input can decompress to an arbitrarily large output. In Tornado 7.0, max_length will be required.

property unconsumed_tail: bytes

Returns the unconsumed portion left over

flush() → bytes

Signals the end of the input.

Call this once, after the last call to decompress, to check that the stream was complete. Raises zlib.error if the input ended partway through a gzip member. Raises ValueError if unconsumed_tail is not empty; it must be passed back to decompress first.

Always returns an empty byte string, because decompress returns all of the output. The return value is kept for compatibility with zlib.Decompress.flush, whose interface this follows.

No other methods may be called on this object after flush.

Changed in version 6.6: Previously, this decompressed any remaining unconsumed_tail with no limit on the size of the output, and it did not detect truncated input.

tornado.util.import_object(name: str) → Any

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

tornado.util.errno_from_exception(e: BaseException) → int | None

Provides the errno from an Exception object.

There are cases that the errno attribute was not set so we pull the errno out of the args but if someone instantiates an Exception without any args you will get a tuple error. So this function abstracts all that behavior to give you a safe way to get the errno.

tornado.util.re_unescape(s: str) → str

Unescape a string escaped by re.escape.

May raise ValueError for regular expressions which could not have been produced by re.escape (for example, strings containing \d cannot be unescaped).

Added in version 4.4.

class tornado.util.Configurable(*args: Any, **kwargs: Any)

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__.

Changed in version 5.0: It is now possible for configuration to be specified at multiple levels of a class hierarchy.

classmethod configurable_base() → type[Configurable]

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() → type[Configurable]

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

initialize() → None

Initialize a Configurable subclass instance.

Configurable classes should use initialize instead of __init__.

Changed in version 4.2: Now accepts positional arguments in addition to keyword arguments.

classmethod configure(impl: None | str | type[Configurable], **kwargs: Any) → None

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() → type[Configurable]

Returns the currently configured class.

class tornado.util.ArgReplacer(func: Callable, name: str)

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.

get_old_value(args: Sequence[Any], kwargs: dict[str, Any], default: Any = None) → Any

Returns the old value of the named argument without replacing it.

Returns default if the argument is not present.

replace(new_value: Any, args: Sequence[Any], kwargs: dict[str, Any]) → tuple[Any, Sequence[Any], dict[str, Any]]

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.

tornado.util.timedelta_to_seconds(td: datetime.timedelta) → float

Equivalent to td.total_seconds() (introduced in Python 2.7).