txaio
=====

.. py:module:: txaio


Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/txaio/_common/index
   /autoapi/txaio/_iotype/index
   /autoapi/txaio/_unframework/index
   /autoapi/txaio/_util/index
   /autoapi/txaio/aio/index
   /autoapi/txaio/interfaces/index
   /autoapi/txaio/testutil/index
   /autoapi/txaio/tx/index
   /autoapi/txaio/with_asyncio/index
   /autoapi/txaio/with_twisted/index


Classes
-------

.. autoapisummary::

   txaio.IFailedFuture
   txaio.ILogger


Functions
---------

.. autoapisummary::

   txaio.use_asyncio
   txaio.use_twisted


Package Contents
----------------

.. 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:function:: use_asyncio()

.. py:function:: use_twisted()

