Version 0.2.5.dev0

Local State

class aiolocals.Context(ident=None, locals=None, parent=None)

Tracks a context, or set of locals for a given task. Should only be used as a context manager or via wrap_async

class aiolocals.Local

An object that stores different state for different task contexts. Meant to be used with Context.

To use within a Context, simply set arbitrary attributes on this object and they will be tracked automatically.

aiolocals.wrap_async(coro, **kwargs)

Wraps a coroutine with a Task that runs in the background. It ensures any context information is transferred to the new task

Parameters:coro – The coroutine to wrap as an asynchronous task
aiolocals.wrap_gather(*tasks, loop=None, return_exceptions=False)

Return a task aggregating results from the given tasks. Any context information for each task if transferred to the new task

Parameters:tasks – Coroutines or tasks to perform


aiolocals.configure_logging(service_name, debug=True, logconf=None)

Configure logging with service name. Should be called one time when the service starts.

  • service_name – The service name to prefix the logs with
  • debug – Whether to configure debug logging or not
  • logconf (aiolocals.log.LogConfiguration) – The LogConfiguration inheritor which is capable of providing interface for initialization of common logging configuration bits.
class aiolocals.LogConfiguration

Inherit from this class and then pass the instance of inheritor to adjust logging configuration for your asyncio application

format = '{}: [%(request_path)s#%(request_id)s] %(levelname)s - %(message)s'

The expression which should be used as format of the sole logging formatter.


This should return iterable of logging.Filter subclasses, which will be used


Override this method to get your specific formatter to be in use for the app. For example, for logging the time of time format in UTC:

class MyFormatter(logging.Formatter):

    converter = time.gmtime

class MyLogConf(LogConfiguration):

    def get_formatter(self):
        return MyFormatter(fmt=self.format.format(self.name))

This should return logging handler instance.


Override me to use your specific log level, depending on application debug mode.

name = None

The name of the service. Defaults to the first paraemter of :func:configure_logging(), or process title if None passed

class aiolocals.RequestIdLoggingFilter(name='')

A filter that adds the request_id and request_path attributes to the record, if available.


Wraps the execution of a job by setting the request id to something meaningful, allowing tracking of all logging statements throughout the job execution. The request id will start with “JOB”

Parameters:name (str) – The name of the job for the logs

aiohttp Integration

aiolocals.context_middleware_factory(app, handler)

A aiohttp middleware factory for wrapping each request with id/path information in task-local variable

  • app (aiohttp.web.Application) – The aiohttp app
  • handler (function) – The next middleware handler

Tracking local context in threads

aiolocals.local.preserve_context_in_threads The context manager which preserves task identity in threads spawned by task[source]

Usage example:

some_local = Local()

def some_calculations():
    print("BTW, spam is %s" % some_local.spam)

def main_multithreaded():
    with Context(locals=(some_local,)):
        some_local.spam = 'ham'
        with preserve_context_in_threads():
            yield from asyncio.get_event_loop().run_in_executor(ThreadPoolExecutor(1), some_calculations)