txaio.aio
=========

.. py:module:: txaio.aio


Attributes
----------

.. autoapisummary::

   txaio.aio._categories
   txaio.aio._default_api
   txaio.aio._log_level
   txaio.aio._loggers
   txaio.aio._started_logging
   txaio.aio._unspecified
   txaio.aio.add_callbacks
   txaio.aio.as_future
   txaio.aio.call_later
   txaio.aio.cancel
   txaio.aio.config
   txaio.aio.create_failure
   txaio.aio.create_future
   txaio.aio.create_future_error
   txaio.aio.create_future_success
   txaio.aio.failure_format_traceback
   txaio.aio.failure_message
   txaio.aio.failure_traceback
   txaio.aio.gather
   txaio.aio.is_called
   txaio.aio.is_future
   txaio.aio.make_batched_timer
   txaio.aio.perf_counter_ns
   txaio.aio.reject
   txaio.aio.resolve
   txaio.aio.sleep
   txaio.aio.sleep
   txaio.aio.time_ns
   txaio.aio.using_asyncio
   txaio.aio.using_twisted


Classes
-------

.. autoapisummary::

   txaio.aio.AsyncGeneratorType
   txaio.aio.FailedFuture
   txaio.aio._AsyncioApi
   txaio.aio._TxaioFileHandler
   txaio.aio._TxaioLogWrapper


Functions
---------

.. autoapisummary::

   txaio.aio._log
   txaio.aio._no_op
   txaio.aio.add_log_categories
   txaio.aio.get_global_log_level
   txaio.aio.make_logger
   txaio.aio.set_global_log_level
   txaio.aio.start_logging
   txaio.aio.with_config


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

.. py:class:: AsyncGeneratorType

.. py:class:: FailedFuture(type_, value, traceback)

   Bases: :py:obj:`txaio.interfaces.IFailedFuture`


   This provides an object with any features from Twisted's Failure
   that we might need in Autobahn classes that use FutureMixin.

   We need to encapsulate information from exceptions so that
   errbacks still have access to the traceback (in case they want to
   print it out) outside of "except" blocks.


   .. py:method:: __str__()


   .. py:attribute:: _traceback


   .. py:attribute:: _type


   .. py:attribute:: _value


   .. py:property:: value

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


.. py:class:: _AsyncioApi(config)

   Bases: :py:obj:`object`


   .. py:attribute:: _config


   .. py:property:: _loop


   .. py:method:: add_callbacks(future, callback, errback)

      callback or errback may be None, but at least one must be
      non-None.



   .. py:method:: as_future(fun, *args, **kwargs)


   .. py:method:: call_later(delay, fun, *args, **kwargs)


   .. py:method:: cancel(future, msg=None)


   .. py:method:: create_failure(exception=None)

      This returns an object implementing IFailedFuture.

      If exception is None (the default) we MUST be called within an
      "except" block (such that sys.exc_info() returns useful
      information).



   .. py:method:: create_future(result=_unspecified, error=_unspecified, canceller=_unspecified)


   .. py:method:: create_future_error(error=None)


   .. py:method:: create_future_success(result)


   .. py:method:: failure_format_traceback(fail)

      :param fail: must be an IFailedFuture
      returns a string



   .. py:method:: failure_message(fail)

      :param fail: must be an IFailedFuture
      returns a unicode error-message



   .. py:method:: failure_traceback(fail)

      :param fail: must be an IFailedFuture
      returns a traceback instance



   .. py:method:: gather(futures, consume_exceptions=True)

      This returns a Future that waits for all the Futures in the list
      ``futures``

      :param futures: a list of Futures (or coroutines?)

      :param consume_exceptions: if True, any errors are eaten and
      returned in the result list.



   .. py:method:: is_called(future)


   .. py:method:: is_future(obj)


   .. py:method:: make_batched_timer(bucket_seconds, chunk_size=100)

      Creates and returns an object implementing
      :class:`txaio.IBatchedTimer`.

      :param bucket_seconds: the number of seconds in each bucket. That
          is, a value of 5 means that any timeout within a 5 second
          window will be in the same bucket, and get notified at the
          same time. This is only accurate to "milliseconds".

      :param chunk_size: when "doing" the callbacks in a particular
          bucket, this controls how many we do at once before yielding to
          the reactor.



   .. py:method:: reject(future, error=None)


   .. py:method:: resolve(future, result=None)


   .. py:method:: sleep(delay)

      Inline sleep for use in co-routines.

      :param delay: Time to sleep in seconds.
      :type delay: float



   .. py:attribute:: using_asyncio
      :value: True



   .. py:attribute:: using_twisted
      :value: False



.. py:class:: _TxaioFileHandler(fileobj, **kw)

   Bases: :py:obj:`logging.Handler`, :py:obj:`object`


   Handler instances dispatch logging events to specific destinations.

   The base handler class. Acts as a placeholder which defines the Handler
   interface. Handlers can optionally use Formatter instances to format
   records as desired. By default, no formatter is specified; in this case,
   the 'raw' message as determined by record.message is logged.


   .. py:attribute:: _encode
      :value: True



   .. py:attribute:: _file


   .. py:method:: emit(record)

      Do whatever it takes to actually log the specified logging record.

      This version is intended to be implemented by subclasses and so
      raises a NotImplementedError.



.. py:class:: _TxaioLogWrapper(logger)

   Bases: :py:obj:`txaio.interfaces.ILogger`


   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:attribute:: _logger


   .. py:method:: _set_log_level(level)


   .. py:method:: emit(level, *args, **kwargs)


.. py:data:: _categories

.. py:data:: _default_api

.. py:function:: _log(logger, level, format='', **kwargs)

.. py:data:: _log_level
   :value: 'info'


.. py:data:: _loggers

.. py:function:: _no_op(*args, **kw)

.. py:data:: _started_logging
   :value: False


.. py:data:: _unspecified

.. py:data:: add_callbacks

.. py:function:: add_log_categories(categories)

.. py:data:: as_future

.. py:data:: call_later

.. py:data:: cancel

.. py:data:: config

.. py:data:: create_failure

.. py:data:: create_future

.. py:data:: create_future_error

.. py:data:: create_future_success

.. py:data:: failure_format_traceback

.. py:data:: failure_message

.. py:data:: failure_traceback

.. py:data:: gather

.. py:function:: get_global_log_level()

.. py:data:: is_called

.. py:data:: is_future

.. py:data:: make_batched_timer

.. py:function:: make_logger()

.. py:data:: perf_counter_ns

.. py:data:: reject

.. py:data:: resolve

.. py:function:: set_global_log_level(level)

   Set the global log level on all loggers instantiated by txaio.


.. py:data:: sleep

.. py:data:: sleep

.. py:function:: start_logging(out=_stdout, level='info')

   Begin logging.

   :param out: if provided, a file-like object to log to. By default, this is
               stdout.
   :param level: the maximum log-level to emit (a string)


.. py:data:: time_ns

.. py:data:: using_asyncio
   :value: True


.. py:data:: using_twisted
   :value: False


.. py:function:: with_config(loop=None)

   :return: an instance of the txaio API with the given
       configuration. This won't affect anything using the 'gloabl'
       config nor other instances created using this function.

   If you need to customize txaio configuration separately (e.g. to
   use multiple event-loops in asyncio), you can take code like this:

       import txaio


       class FunTimes(object):

           def something_async(self):
               return txaio.call_later(1, lambda: 'some result')

   and instead do this:

       import txaio


       class FunTimes(object):
           txaio = txaio

           def something_async(self):
               # this will run in the local/new event loop created in the constructor
               return self.txaio.call_later(1, lambda: 'some result')

       fun0 = FunTimes()
       fun1 = FunTimes()
       fun1.txaio = txaio.with_config(loop=asyncio.new_event_loop())

   So `fun1` will run its futures on the newly-created event loop,
   while `fun0` will work just as it did before this `with_config`
   method was introduced (after 2.6.2).


