Minor fixes

• Protect task against bubbling when adding a done callback to it (same as awaiting it)
• when cancelling a scope, await all tasks in parallel (instead of one by one)
• add documentation and tests around run_in_executor

Add `awaited` option to `spawn`

A task by default is awaited, which means the scope will wait for it to finish during finalisation stage, before exiting.

It is now possible (thanks @ll1ks!) to mark some tasks as not awaited if you want a task running, but not so essential that it should prevent cancellation. Typically, a background job which has no meaning alone.

This is backward compatible as by default, like before, tasks are awaited.

Ensure scope cleans its mess before being done

In this new release, we modified slightly how Scope teardown is performed, and it is now easier and simpler to use:

• As a context manager

async with Scope(timeout=10) as scope:
    scope << do_something()
# At this point you are guaranteed that task created on the scope are finished, or cancelled and awaited.

• As a long living scope which will be cancelled by API

async def main():
    scope = Scope()
    scope.spawn(server_coro(), master=True)
    await scope

• Or you can also mark a scope as finalized, in which case it will automatically be terminated when the last task is done

async def main():
    scope = Scope()
    scope << will_last_some_time()

    # Mark scope a finalized and wait for its task to terminate
    scope.finalize()
    await scope

Note that join function as been removed in favor if this new mechanism. The same way, Scope.set_current is now internal Scope._set_current and should not be used externally unless you really know what you are doing.

Context gets cancelled

Before this release, doing something like this:

async with Scope(timeout=1):
    await asyncio.sleep(10)

Would have blocked for 10 second, the timeout not being enforced. Same problem if the Scope was cancelled.
Now timeout and cancellation while the context code is blocked is handled properly!

Scope!

I didn't like much the Nursery name in itself. In the end it's all about managing a scope, and although Trio just makes the distinction between Nursery and Cancel scope, here it seemed a bit too much.

So now you call:

async with Scope() as s:
    s.spawn(coro())

Other things are identical, with the addition of a new class method Scope.get_current() which will return the current scope in (hopefully) most of the cases, especially if running in a task spawned by a scope!

Getting there...

Changes:

• Nursery now inherits from Future; we don't need the _done internal future anymore!
• There is no more start function, which was overkill and annoying when used without context manager
• No more internal state. Use Future state to know how it went
• Most of the logs are now debugs
• We can now fork a Nursery! just use the child Nursery as usual, but:
  • child nursery can be launched with the same parameters as a task
  • child nursery will be cancelled with parent (yeah!)
  • but an error in child will not cancel the parent directly
• Nursery.set_debug allows to enable internal logging
• Implementation of the << operator as en equivalent of start_soon
• add join(forever=True) capability to get a never auto-cancelling Nursery
• add a provisional Nursery.get_tasks method to retrieve all tasks of a scope
• improved documentation

If you are working with this package already since 0.2, this will not change much.

Just be careful, next release will rename Nursery into Scope and start_soon into spawn!

Lighter, better

Among the various added tests, fixes and code cleanup:

• tasks can be retrieved and awaited (they are now futures)
• removed the AsyncTask.join method in favor of awaiting the task itself
• No more TaskException: you get directly the exception which popped up
• You can continue adding tasks and awaiting them on a nursery as long as you don't join the nursery

Several internal improvements

• Adds checks preventing to use as a synchronous context manager
• Better handles Cancellation in various scenarios
• Tests cleanup and split
• Added Travis and Coveralls integration

Initial version - very alpha!

Supports:

• Creating nurseries
• adding awaitables to a nursery (coroutines or futures)
• setting a timeout on a nursery
• by default, an error in a task will bubble at top level. There is an option to ignore exceptions on particular tasks with the bubble parameter of start_soon
• by default, a nursery will wait for all its tasks to terminate, except if a task is marked as master. A master task termination will cause the the nursery to cancel (with all pending tasks)

This is tested supposed to work on python >= 3.5 (tested up to 3.7).