txaio.interfaces
================

.. py:module:: txaio.interfaces


Attributes
----------

.. autoapisummary::

   txaio.interfaces.log_levels


Classes
-------

.. autoapisummary::

   txaio.interfaces.IBatchedTimer
   txaio.interfaces.IFailedFuture
   txaio.interfaces.ILogger


Module Contents
---------------

.. py:class:: IBatchedTimer

   Bases: :py:obj:`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


   .. py:method:: call_later(delay, func, *args, **kw)

      This speaks the same API as :meth:`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.



.. py:class:: IFailedFuture

   Bases: :py:obj:`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 :meth:`txaio.add_callbacks`

   In your errback you can extract information from an IFailedFuture
   with :meth:`txaio.failure_message` and
   :meth:`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.


   .. py:method:: value()
      :abstractmethod:


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



.. py:class:: ILogger

   Bases: :py:obj:`abc.ABC`


   This defines the methods you can call on the object returned from
   :meth:`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
   <https://www.python.org/dev/peps/pep-3101/>`_-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
   <http://twistedmatrix.com/documents/current/core/howto/logger.html>`_
   for details.


   .. py:method:: critical(message, **kwargs)

      log a critical-level message



   .. py:method:: debug(message, **kwargs)

      log an debug-level message



   .. py:method:: error(message, **kwargs)

      log a error-level message



   .. py:method:: info(message, **kwargs)

      log an info-level message



   .. py:method:: trace(message, **kwargs)

      log a trace-level message



   .. py:method:: warn(message, **kwargs)

      log a error-level message



.. py:data:: log_levels
   :value: ['none', 'critical', 'error', 'warn', 'info', 'debug', 'trace']


