[jasperblues]

Fixes #228

What was wrong

0.2.0's README said to shut down with await assembly.drivine.close(). #195 moved DrivineAssembly onto pi-pilgrim's lifecycle and removed its async close(). So in 0.3.0 that call reaches pi-pilgrim's sync close(). Once the registry is made, that raises PilgrimError ... Close it with await aclose() and leaves the drivers and pools open.

The fix

pi-pilgrim 0.4.0 (liberation-data/pi-pilgrim#10) adds AsyncPilgrimAssembly, for an assembly whose teardown is async. Its close() is a native async def that awaits aclose(), and its with refuses. It closes held and owned child assemblies through their own lifecycle. It also adds AsyncTeardownRequired, a PilgrimError.

• pi-pilgrim is now >=0.4.0,<0.5, and the lock is updated.
• The async DrivineAssembly subclasses AsyncPilgrimAssembly. So await close(), asyncio.run(close()), await aclose() and async with all close it, whether or not the registry was made. An application assembly closes it whether it holds it with AssemblyHolder.shared(DrivineAssembly) or as a component, self.shared(DrivineAssembly). A sync close of either assembly closes Drivine while it has no registry. Once Drivine has a registry, that sync close refuses with AsyncTeardownRequired before closing anything. A subclass of DrivineAssembly that overrides aclose() refuses a sync close from the start, since its own teardown is async.
• with DrivineAssembly() (async) raises AsyncTeardownRequired. DrivineAssembly overrides only __enter__, so that the refusal also points to drivine.sync.DrivineAssembly. __exit__ is pi-pilgrim's.
• The sync assembly is unchanged. It's still a plain PilgrimAssembly, and drivine/sync/drivine_assembly.py is byte for byte the same as on main. scripts/unasync.py maps AsyncPilgrimAssembly to PilgrimAssembly. Its ASYNC_ONLY table leaves DrivineAssembly.__enter__ out of the sync code, and that's the only entry it has.
• Docs. docs/09-with-pi-pilgrim.md says that the async assembly is an AsyncPilgrimAssembly and lists what closes it. Its "Upgrading from 0.2.0" section is updated to match. docs/design.md says the same.

One behaviour to know about: close() called without await closes nothing, even with no registry made, and Python warns that a coroutine was never awaited. That's how a native coroutine behaves, and the docs say to await it.

Tests

In tests/unit/test_assembly_lifecycle.py, which passes under -W error:

• DrivineAssembly is an AsyncPilgrimAssembly, and the sync one isn't.
• await close() ends the providers, and the assembly makes no more components. Calling it twice, or after aclose(), ends them only once. With no registry made, it closes the assembly.
• asyncio.run(close()) closes it, with or without a registry.
• close() left unawaited closes nothing and warns, with or without a registry.
• Holding Drivine as a component (self.shared): a sync close closes a Drivine with no registry. Once Drivine has a registry, the sync close refuses with AsyncTeardownRequired, leaves everything open, and aclose() then closes it. await aclose() on the holder closes Drivine.
• The 0.2.0 README pattern works: AssemblyHolder.shared(DrivineAssembly), then await app.drivine.close(). The application assembly's sync close() closes a Drivine with no registry, and refuses once Drivine has one. await AssemblyHolder.aclose() closes it.
• with on the async assembly raises AsyncTeardownRequired, and the message names the sync API.
• The sync assembly's close() still closes and returns None.

drivine4j and Drivine for TypeScript have no DrivineAssembly, so there's nothing to port.

• A subclass that overrides aclose(): await close() runs the override, and a sync close refuses even with no registry.
• A provider that fails while closing doesn't stop the others closing (test_await_close_ends_every_provider_when_one_fails).
• tests/unit/test_unasync.py: ASYNC_ONLY leaves out exactly the definitions it names, and refuses a name the module doesn't define.