|
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177 |
- ###############################################################################
- #
- # The MIT License (MIT)
- #
- # Copyright (c) typedef int GmbH
- #
- # Permission is hereby granted, free of charge, to any person obtaining a copy
- # of this software and associated documentation files (the "Software"), to deal
- # in the Software without restriction, including without limitation the rights
- # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- # copies of the Software, and to permit persons to whom the Software is
- # furnished to do so, subject to the following conditions:
- #
- # The above copyright notice and this permission notice shall be included in
- # all copies or substantial portions of the Software.
- #
- # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
- # THE SOFTWARE.
- #
- ###############################################################################
-
- import abc
-
- #: all the log-levels that txaio recognizes
- log_levels = [
- 'none',
- 'critical',
- 'error',
- 'warn',
- 'info',
- 'debug',
- 'trace',
- ]
-
-
- class IBatchedTimer(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
- """
-
- def call_later(self, 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.
- """
-
-
- class ILogger(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.
- """
-
- # stdlib notes:
- # levels:
- # CRITICAL 50
- # ERROR 40
- # WARNING 30
- # INFO 20
- # DEBUG 10
- # NOTSET 0
-
-
- # NOTES
- # things in Twisted's event:
- # - log_level
- # - log_failure (sometimes?)
- # - log_format (can be None)
- # - log_source (sometimes? no, always, but sometimes None)
- # - log_namespace
- #
- # .warn not warning!
-
- def critical(self, message, **kwargs):
- "log a critical-level message"
-
- def error(self, message, **kwargs):
- "log a error-level message"
-
- def warn(self, message, **kwargs):
- "log a error-level message"
-
- def info(self, message, **kwargs):
- "log an info-level message"
-
- def debug(self, message, **kwargs):
- "log an debug-level message"
-
- def trace(self, message, **kwargs):
- "log a trace-level message"
-
-
- class IFailedFuture(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.
- """
-
- @abc.abstractproperty
- def value(self):
- """
- An actual Exception instance. Same as the second item returned from
- ``sys.exc_info()``
- """
|