# `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`

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.

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

    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 in `unconsumed_tail`; you must retrieve this value and pass it back to a future call to `decompress` if it is not empty.

  property unconsumed_tail: bytes

    Returns the unconsumed portion left over

  flush() → bytes

    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: 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).

  New 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).