Package: asyncscope
This library implements scoped taskgroups / nurseries.RationaleComposabilityLarge programs often consist of building blocks which depend on each other.
Those dependencies may be non-trivial, aren’t always linear, and generally
form some sort of directed acyclic graph instead of a nice linear or
hierarchical set of relationships.Let’s invent an example.Your server contains some admin module, which requires a support library,
which connects to a database. Halfway through it encounters an error, thus
loads an error handler, which also uses the database.Next, a client of your server does some shady stuff so you want to log
that, and since loading the error handler and connecting to the database is
expensive you want to re-use the handler you already have.Later the admin code terminates. However, it shouldn’t unload the error
handler, because that other code still needs it.This is a problem because you like to use Structured Programming
principles, which state that if you started it you need to stop it.
Thus, you need to jump through some hoops getting all of this connected up,
keeping track of each module’s users, and shutting things down in the
correct order.Worse: let’s say that your code dies with a fatal exception. That exception
typically propagates through all of your code and thus tends to cancel the
database connection before the error handler has a chance to log the
problem. Worse, if the error from the logger occurs in afinally:block
it basically replaces the original exception, so you’ll have a lot of fun
trying to debug all of this.AsyncScope can help you.AsyncScope keeps track of your program’s building blocks. It remembers
which parts depend on which other parts, prevents cyclic dependencies,
and terminates a scope as soon as nobody uses it any more.Now your error handler stays around exactly as long as you need it, your
database connection won’t die while the error handler (or any other code)
requires it, your error gets logged correctly, and you find the problem.Multiple servicesSome programs need any number of async contexts, e.g. a client that talks
to any number of servers within the same method. Creating server contexts
is often awkward under these circumstances; you need a subtask or ancontextlib.AsyncExitStackto act as the contexts’ “keeper”. However,
setting up a subtask is a lot of boilerplate; an exit stack doesn’t help
when you need to dynamically remove servers.AsyncScopehelps by decoupling code structure from service usage, while
ensuring that external connections and other subtasks are not duplicatedandended cleanly when their last user terminates.UsageMain codeWrap your main code in anasync withasyncscope.main_scope('NAME'):...block. (The name defaults to_mainif omitted.)This call initializes the globalAsyncScope.scopeobject. It always
refers to the current service (i.e. initially, your main code).Wrapping servicesA “service” is defined as any nontrivial object that might be used from
multiple contexts within your program. That can be a HTTP session, or a
database connection, any object that’s non-trivial to create, …AsyncScoperequires wrapping your service in a function with common
calling conventions because it doesn’t know (indeed doesn’t want to know)
the details of how to set up and tear down your service objects.Here are some examples.If the service uses arunmethod, you’d do this:from asyncscope import scope

async def some_service(*p, **kw):
   srv = your_service(*p, **kw)
   async with anyio.create_task_group() as tg:
      await tg.start(srv.run)

      scope.register(srv)
      await scope.no_more_dependents()

      await srv.stop_running()
      tg.cancel_scope.cancel()Alternately, if the service runs as an async context manager:from asyncscope import scope

async def some_service(*p, **kw):
   async with your_service(*p, **kw) as srv:
      # NB: some services use "async with await …"
      scope.register(srv)
      await scope.no_more_dependents()Alternately², it might run as a context-free background service:from asyncscope import scope

async def some_service(*p, **kw):
   srv = your_service(*p, **kw)
   srv = await srv.start()

   scope.register(srv)
   await scope.no_more_dependents()

   await srv.aclose()Alternately³, if the service is an annoying-to-set-up object:from asyncscope import scope

async def some_service(*p, **kw):
   srv = SomeObject(*p, **kw)
   await SomeObject.costly_setup()

   scope.register(srv)
   try:
      await scope.no_more_dependents()
   finally:
      srv.teardown()
   # use this to e.g. clean up circular references within your objectNext, we’ll see how to use these objects.Using servicesUsingAsyncScope, a service is used in one of two ways.within a context:from asyncscope import scope

async with scope.using_scope():
    srv = await scope.service(name, some_service, *p, **kw)
    ...until the caller’s scope endsoryou explicitly release it:from asyncscope import scope

srv = await scope.service(name, some_service, *p, **kw)
...
del srv  # don't hog the memory!
scope.release(name)You can also check whether a named service exists:from asyncscope import scope

try:
    srv = scope.lookup(name)
except KeyError:
    pass  # no it does not
else:
    ...
    del srv
    scope.release(name)In all three casessrvis the object that yoursome_servicecode has
passed toAsyncScope.Scope.register.NoteScope.lookupraisesKeyErrorif the scope is currently being
set up. The other methods wait for the service’s call toScope.register.Service namingAsyncScope usesnameto discover whether the service is already up and
running. If so, it records that the current scope is also using this named
service and simply returns it.Names must be globally unique. To avoid collisions, add your object class,
an idenifier likeid(YourServiceClass), orid(container_object)to it, depending on usage.AsyncScopedoes not try to derive uniqueness from its parameters, because
arbitrary naming conventions are unlikely to work for everybody. One easy
way to disambiguate potential collisions is to includeid(some_service)in the name.ImplicationsCallingScope.serviceorScope.using_servicedoes not guarantee that
the service in question will start when you do: it might have been running
already. Likewise, leaving theasync withblock or exiting the caller’s
scope may not stop the service: there might be other users, or some caching
mechanism that delays closing it.Calling these functions twice / nestingScope.using_servicecalls is OK.
Usage cycles (service A starts service B which later requires A) are
forbidden and will be detected.Every scope contains a taskgroup which you can access using the usualstartandstart_soonmethods. You can also callscope.spawn().
This function returns aCancelScopethat wraps the new tasks, so you
can cancel it if you need to. All tasks started this way are also
auto-cancelled when the scope exits.Yoursome_servicecodemustcallscope.register()exactly once,
otherwise the scopes waiting for it to start will wait forever. (They’ll
get cancelled if your scope’s main task exits before doing so.)The current scope is available as thescopecontext variable.Theexamplesdirectory contains some sample code.Logggingscope.loggeris a standardlogging.Loggerobject, namedscope.NAME.MultithreadingAsyncScopeisnotcompatible with multithreading. Using a single main
scope from multiple threadswillcause inconsistent data, deadlocks,
and/or other hard-to-find bugs.If you start a separate async mainloop in a new thread, you must callscope.thread_reset()before entering the thread’s main scope. You also
should pass a thread-specific name tomain_scope.Do not share services between threads. They are typically not
multithreading-aware andAsyncScopemight terminate them at any time.Exception handlingThis section describes the effects of an exception that escapes from a
service’s main task, causing it to terminate.Errors that are subclasses ofBaseExceptionbut notExceptionare
never caught. If the service did not yet callScope.registerthey may
receive either aconcurrent.Futures.CancelledError, or a cancellation
exception from the async framework.Exceptions raised after the service calledScope.registerare not
handled. They will ultimately propagate out of theAsyncScope.main_scopeblock.Otherwise the error are propagated to the caller(s) that are waiting
for itsScope.registercall.Otherwise the exception is left unhandled; the effects are described in the
nest section.Cancellation semanticsWhen a scope exits (either cleanly or when it raises an error that escapes
its taskgroup), the scopes depending on it are cancelled immediately, in
parallel. Then, those it itself depends on are terminated cleanly and
in-order, assuming they’re not used by some other scope.This also happens when a scope’s main task ends.“Clean termination” means that the scope’s call tono_more_dependents()returns. If there is no such call open, the scope’s tasks are cancelled.TODO: write a service which your code can use to keep another service alive
for a bit.Code structureA scope’s main code typically looks like this:do whatever you need to start the service. This code may start other
scopes it depends on. Note that if the scope is already running,servicesimply returns its existing service object.callscope.register(service_object)callawait scope.no_more_dependents()(subordinate task) or wait for SIGTERM (daemon main task)
or terminate (main task’s job is done)cleanly stop your service.Ifno_more_dependentsis not used, your code will be cancelled instead.Scopes typically don’t need to access their own scope object. It’s stored in
a contextvar and can be retrieved viascope.get()if you need it.
For most uses, however,asyncscope’s globalscopeobject accesses
the current scope transparently.Temporary servicesSome services don’t need to be running all the time. To release a service
early, useasync withscope.using_scope():. This creates an embedded scope.
Services started within an embedded scope are auto-released when its
context exits, assuming (as usual) that no other code uses them.If a scope handler that’s used by an embedded scope exits, the code running
in the embedded scope is cancelled as usual. Leaving the embedded scope
then triggers aScopeDiedexception.