Package: aionursery
This library implements a Nursery object, similar to trio’sNurseryforasyncio.asyncdefchild():...asyncdefparent():asyncwithaionursery.Nursery()asnursery:# Make two concurrent calls to childnursery.start_soon(child())nursery.start_soon(child())Tasks form a tree: when you run your main coroutine (viaasyncio.get_event_loop().run_until_completeorasyncio.run), this creates an initial task, and all your other tasks will be children, grandchildren, etc. of the main task.The body of theasync withblock acts like an initial task that’s running inside the nursery, and then each call tonursery.start_soonadds another task that runs in parallel.Keep in mind that:If any task inside the nursery raises an unhandled exception, then the nursery immediately cancels all the tasks inside the nursery.Since all of the tasks are running concurrently inside the async with block, the block does not exit until all tasks have completed. If you’ve used other concurrency frameworks, then you can think of it as, the de-indentation at the end of the async with automatically “joins” (waits for) all of the tasks in the nursery.Once all the tasks have finished, then:
* The nursery is marked as “closed”, meaning that no new tasks can be started inside it.
* Any unhandled exceptions are re-raised inside the parent task. If there are multiple exceptions, then they’re collected up into a single MultiError exception.Since all tasks are descendents of the initial task, one consequence of this is that the parent can’t finish until all tasks have finished.Please note that you can’t reuse an already exited nursery. Trying to re-open it again, or tostart_soonmore tasks in it will raiseNurseryClosed.Shielding some tasks from being cancelledSometimes, however, you need to have an opposite behavior: a child must execute no matter what exceptions are raised in other tasks.
Imagine a payment transaction running in one task, and an sms sending in another.
You certainly don’t want an sms sending error to cancel a payment transaction.For that, you canasyncio.shieldyour tasks before starting them in the nursery:asyncdefperform_payment():...asyncdefsend_sms():...asyncdefparent():asyncwithNursery()asnursery:nursery.start_soon(asyncio.shield(perform_payment()))nursery.start_soon(send_sms())Getting results from childrenIf your background tasks are not quite long-lived and return some useful values that you want to process, you can gather all tasks into a list and useasyncio.wait(or similar functions) as usual:asyncdefparent():asyncwithNursery()asnursery:task_foo=nursery.start_soon(foo())task_bar=nursery.start_soon(bar())results=awaitasyncio.wait([task_foo,task_bar])If your background tasks are long-lived, you should useasyncio.Queueto pass objects between children and parent tasks:asyncdefchild(queue):whileTrue:data=awaitfrom_external_system()awaitqueue.put(data)asyncdefparent():queue=asyncio.Queue()asyncwithNursery()asnursery:nursery.start_soon(child(queue))whilesome_condition():data=awaitqueue.get()awaitdo_stuff_with(data)Integration withasync_timeoutYou can wrap a nursery in aasync_timeout.timeoutcontext manager.
When timeout happens, the whole nursery cancels:fromasync_timeoutimporttimeoutasyncdefchild():awaitasyncio.sleep(1000*1000)asyncdefparent():asyncwithtimeout(10):asyncwithNursery()asnursery:nursery.start_soon(child())awaitasyncio.sleep(1000*1000)