greenback

With this release, greenback now requires at least Python 3.8.

Features

• greenback's internals have been reorganized to improve the performance of executing ordinary checkpoints (await statements, approximately) in a task that has a greenback portal active. On the author's laptop with CPython 3.12, the overhead is only about one microsecond compared to the performance without greenback involved, versus four microseconds before this change. For comparison, the non-greenback cost of executing a checkpoint is 12-13 microseconds. (#26)

Bugfixes

• greenback now properly handles cases where a task spawns another greenlet (not managed by greenback) that in turn calls greenback.await_. This improves interoperability with other greenback-like systems that do not use the greenback library, such as SQLAlchemy's async ORM support. (#22)

• greenback.has_portal now returns False if run in a task that has called greenback.bestow_portal on itself but has not yet made the portal usable by executing a checkpoint. This reflects the fact that greenback.await_ in such a task will fail. The exception message for such an ~greenback.await_ failure has also been updated to more precisely describe the problem, rather than the previous generic "you must create a portal first". (#26)

Bugfixes

• Public exports now use from ._submod import X as X syntax so that type checkers will know they're public exports. (#23)

Bugfixes

• greenback.has_portal now returns False, instead of raising an error, if it is called within an asyncio program in a context where no task is running (such as a file descriptor readability callback). (#16)

• Fixed a bug that could result in inadvertent sharing of context variables. Specifically, when one task that already had a greenback portal set up called greenback.bestow_portal on a different task, the second task could wind up sharing the first task's contextvars context. (#17)

Features

• Added @greenback.decorate_as_sync() <greenback.decorate_as_sync>, which wraps a synchronous function decorator such as functools.lru_cache so that it can be used to decorate an async function. (#14)

Bugfixes

• greenback.has_portal now returns False instead of raising an error if called outside async context. (#12)

• greenback.has_portal now properly respects its task argument; previously it erroneously would always inspect the current task. (#13)

Features

• New function greenback.with_portal_run_tree is like greenback.with_portal_run for an entire Trio task subtree: it will enable greenback.await_ not only in the given async function but also in any child tasks spawned inside that function. This feature relies on the Trio instrumentation API and is thus unavailable on asyncio. (#9)

• New function greenback.has_portal determines whether the current task, or another specified task, has a greenback portal set up already. (#9)

Bugfixes

• Add support for newer (1.0+) versions of greenlet, which expose a gr_context attribute directly, allowing us to remove the hacks that were added to support 0.4.17. greenlet 0.4.17 is no longer supported, but earlier (contextvar-naive) versions should still work. (#8)

• We no longer assume that greenback.bestow_portal is invoked from the "main" greenlet of the event loop. This was not a safe assumption: any task running with access to a greenback portal runs in a separate greenlet, and it is quite plausible that such a task might want to ~greenback.bestow_portal on another task. (#9)

Features

• Add greenback.with_portal_run and greenback.with_portal_run_sync, which let you scope the greenback portal (and its performance impact) to a single function call rather than an entire task. greenback.with_portal_run_sync provides somewhat reduced portal setup/teardown overhead in cases where the entire function you want to provide the portal to is syntactically synchronous. (#6)

Bugfixes

• Work around a regression introduced by greenlet 0.4.17's attempt at adding contextvars support. (#5)

Documentation improvements

• Add a more detailed discussion of the performance impacts of using greenback.

Features

• Added greenback.bestow_portal, which enables greenback for a task from outside of that task. (#1)

• Added support for newer versions of Trio with a trio.lowlevel module rather than trio.hazmat. Older versions of Trio remain supported.