txaio.interfaces

Attributes

log_levels

Classes

IBatchedTimer	Objects created by :met:`txaio.make_batched_timer` implement this
IFailedFuture	This defines the interface for a common object encapsulating a
ILogger	This defines the methods you can call on the object returned from

Module Contents

class IBatchedTimer

Bases: abc.ABC

Objects created by :met:`txaio.make_batched_timer` implement this interface.

These APIs allow you to put call_later()’s into “buckets”, reducing the number of actual underlying delayed calls that the event-loop (asyncio or Twisted) needs to deal with. Obviously, you lose some amount of precision in when the timers fire in exchange for less memory use, and fewer objects on the queues for the underlying event-loop/reactor.

As a concrete example, in Autobahn we’re using this to batch together timers for the “auto ping” feature. In this case, it is not vital when precisely the timers fire, but as the connection-count increases the number of outstanding timers becomes quite large.

It is intended to be used like so:

class Something(object):

timers = txaio.make_batched_timer()

def a_method(self):

self.timers.call_later() # drop-in API from txaio.call_later

call_later(delay, func, *args, **kw)

This speaks the same API as txaio.call_later() and also returns an object that has a .cancel method.

You cannot rely on any other methods/attributes of the returned object. The timeout will actually fire at an aribtrary time “close” to the delay specified, depening upon the arguments this IBatchedTimer was created with.

class IFailedFuture

Bases: abc.ABC

This defines the interface for a common object encapsulating a failure from either an asyncio task/coroutine or a Twisted Deferred.

An instance implementing this interface is given to any errback callables you provide via txaio.add_callbacks()

In your errback you can extract information from an IFailedFuture with txaio.failure_message() and txaio.failure_traceback() or use .value to get the Exception instance.

Depending on other details or methods will probably cause incompatibilities between asyncio and Twisted.

abstractmethod value()

An actual Exception instance. Same as the second item returned from sys.exc_info()

class ILogger

Bases: abc.ABC

This defines the methods you can call on the object returned from txaio.make_logger() – although the actual object may have additional methods, you should only call the methods listed here.

All the log methods have the same signature, they just differ in what “log level” they represent to the handlers/emitters. The message argument is a format string using PEP3101-style references to things from the kwargs. Note that there are also the following keys added to the kwargs: log_time and log_level.

For example:

class MyThing(object):
    log = txaio.make_logger()

    def something_interesting(self, things=dict(one=1, two=2)):
        try:
            self.log.debug("Called with {things[one]}", things=things)
            result = self._method_call()
            self.log.info("Got '{result}'.", result=result)
        except Exception:
            fail = txaio.create_failure()
            self.log.critical(txaio.failure_format_traceback(fail))

The philsophy behind txaio’s interface is fairly similar to Twisted’s logging APIs after version 15. See Twisted’s documentation for details.

critical(message, **kwargs)

log a critical-level message

debug(message, **kwargs)

log an debug-level message

error(message, **kwargs)

log a error-level message

info(message, **kwargs)

log an info-level message

trace(message, **kwargs)

log a trace-level message

warn(message, **kwargs)

log a error-level message

log_levels = ['none', 'critical', 'error', 'warn', 'info', 'debug', 'trace']