Package: asgiref
ASGI is a standard for Python asynchronous web apps and servers to communicate
with each other, and positioned as an asynchronous successor to WSGI. You can
read more athttps://asgi.readthedocs.io/en/latest/This package includes ASGI base libraries, such as:Sync-to-async and async-to-sync function wrappers,asgiref.syncServer base classes,asgiref.serverA WSGI-to-ASGI adapter, inasgiref.wsgiFunction wrappersThese allow you to wrap or decorate async or sync functions to call them from
the other style (so you can call async functions from a synchronous thread,
or vice-versa).In particular:AsyncToSync lets a synchronous subthread stop and wait while the async
function is called on the main thread’s event loop, and then control is
returned to the thread when the async function is finished.SyncToAsync lets async code call a synchronous function, which is run in
a threadpool and control returned to the async coroutine when the synchronous
function completes.The idea is to make it easier to call synchronous APIs from async code and
asynchronous APIs from synchronous code so it’s easier to transition code from
one style to the other. In the case of Channels, we wrap the (synchronous)
Django view system with SyncToAsync to allow it to run inside the (asynchronous)
ASGI server.Note that exactly what threads things run in is very specific, and aimed to
keep maximum compatibility with old synchronous code. See
“Synchronous code & Threads” below for a full explanation. By default,sync_to_asyncwill run all synchronous code in the program in the same
thread for safety reasons; you can disable this for more performance with@sync_to_async(thread_sensitive=False), but make sure that your code does
not rely on anything bound to threads (like database connections) when you do.Threadlocal replacementThis is a drop-in replacement forthreading.localthat works with both
threads and asyncio Tasks. Even better, it will proxy values through from a
task-local context to a thread-local context when you usesync_to_asyncto run things in a threadpool, and vice-versa forasync_to_sync.If you instead want true thread- and task-safety, you can setthread_criticalon the Local object to ensure this instead.Server base classesIncludes aStatelessServerclass which provides all the hard work of
writing a stateless server (as in, does not handle direct incoming sockets
but instead consumes external streams or sockets to work out what is happening).An example of such a server would be a chatbot server that connects out to
a central chat server and provides a “connection scope” per user chatting to
it. There’s only one actual connection, but the server has to separate things
into several scopes for easier writing of the code.You can see an example of this being used infrequensgi.WSGI-to-ASGI adapterAllows you to wrap a WSGI application so it appears as a valid ASGI application.Simply wrap it around your WSGI application like so:asgi_application = WsgiToAsgi(wsgi_application)The WSGI application will be run in a synchronous threadpool, and the wrapped
ASGI application will be one that acceptshttpclass messages.Please note that not all extended features of WSGI may be supported (such as
file handles for incoming POST bodies).Dependenciesasgirefrequires Python 3.7 or higher.ContributingPlease refer to themain Channels contributing docs.TestingTo run tests, make sure you have installed thetestsextra with the package:cd asgiref/
pip install -e .[tests]
pytestBuilding the documentationThe documentation usesSphinx:cd asgiref/docs/
pip install sphinxTo build the docs, you can use the default tools:sphinx-build -b html . _build/html  # or `make html`, if you've got make set up
cd _build/html
python -m http.server…or you can usesphinx-autobuildto run a server and rebuild/reload
your documentation changes automatically:pip install sphinx-autobuild
sphinx-autobuild . _build/htmlReleasingTo release, first add details to CHANGELOG.txt and update the version number inasgiref/__init__.py.Then, build and push the packages:python -m build
twine upload dist/*
rm -r build/ dist/Implementation DetailsSynchronous code & threadsTheasgiref.syncmodule provides two wrappers that let you go between
asynchronous and synchronous code at will, while taking care of the rough edges
for you.Unfortunately, the rough edges are numerous, and the code has to work especially
hard to keep things in the same thread as much as possible. Notably, the
restrictions we are working with are:All synchronous code called throughSyncToAsyncand marked withthread_sensitiveshould run in the same thread as each other (and if the
outer layer of the program is synchronous, the main thread)If a thread already has a running async loop,AsyncToSynccan’t run things
on that loop if it’s blocked on synchronous code that is above you in the
call stack.The first compromise you get to might be thatthread_sensitivecode should
just run in the same thread and not spawn in a sub-thread, fulfilling the first
restriction, but that immediately runs you into the second restriction.The only real solution is to essentially have a variant of ThreadPoolExecutor
that executes anythread_sensitivecode on the outermost synchronous
thread - either the main thread, or a single spawned subthread.This means you now have two basic states:If the outermost layer of your program is synchronous, then all async code
run throughAsyncToSyncwill run in a per-call event loop in arbitrary
sub-threads, while allthread_sensitivecode will run in the main thread.If the outermost layer of your program is asynchronous, then all async code
runs on the main thread’s event loop, and allthread_sensitivesynchronous
code will run in a single shared sub-thread.Crucially, this means that in both cases there is a thread which is a shared
resource that allthread_sensitivecode must run on, and there is a chance
that this thread is currently blocked on its ownAsyncToSynccall. Thus,AsyncToSyncneeds to act as an executor for thread code while it’s blocking.TheCurrentThreadExecutorclass provides this functionality; rather than
simply waiting on a Future, you can call itsrun_until_futuremethod and
it will run submitted code until that Future is done. This means that code
inside the call can then run code on your thread.Maintenance and SecurityTo report security issues, please contactsecurity@djangoproject.com. For GPG
signatures and more security process information, seehttps://docs.djangoproject.com/en/dev/internals/security/.To report bugs or request new features, please open a new GitHub issue.This repository is part of the Channels project. For the shepherd and maintenance team, please see themain Channels readme.