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[source]¶
Exception raised by
gen.with_timeout
andIOLoop.run_sync
.Changed in version 5.0: Unified
tornado.gen.TimeoutError
andtornado.ioloop.TimeoutError
astornado.util.TimeoutError
. Both former names remain as aliases.Changed in version 6.2:
tornado.util.TimeoutError
is an alias toasyncio.TimeoutError
- class tornado.util.ObjectDict[source]¶
Makes a dictionary behave like an object, with attribute-style access.
- class tornado.util.GzipDecompressor[source]¶
Streaming gzip decompressor.
The interface is like that of
zlib.decompressobj
(without some of the optional arguments, but it understands gzip headers and checksums.- decompress(value: bytes, max_length: int = 0) bytes [source]¶
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.If
max_length
is given, some input data may be left over inunconsumed_tail
; you must retrieve this value and pass it back to a future call todecompress
if it is not empty.
- tornado.util.import_object(name: str) Any [source]¶
Imports an object by name.
import_object('x')
is equivalent toimport x
.import_object('x.y.z')
is equivalent tofrom 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) Optional[int] [source]¶
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 [source]¶
Unescape a string escaped by
re.escape
.May raise
ValueError
for regular expressions which could not have been produced byre.escape
(for example, strings containing\d
cannot be unescaped).New in version 4.4.
- class tornado.util.Configurable(*args: Any, **kwargs: Any)[source]¶
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. whenepoll
is available, always use it instead ofselect
), or when a previously-monolithic class has been split into specialized subclasses.Configurable subclasses must define the class methods
configurable_base
andconfigurable_default
, and use the instance methodinitialize
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()[source]¶
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()[source]¶
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.
- class tornado.util.ArgReplacer(func: Callable, name: str)[source]¶
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: Optional[Any] = None) Any [source]¶
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]] [source]¶
Replace the named argument in
args, kwargs
withnew_value
.Returns
(old_value, args, kwargs)
. The returnedargs
andkwargs
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 tokwargs
and None will be returned asold_value
.