Release history

greenback 1.3.0 (2025-12-22)

Added portals_for_children(), portals_for_tree(), and AutoPortalInstrument, offering better support for portalizing portions of the Trio task tree. These generalize the facility that was previously available through with_portal_run_tree().

greenback now uses deferred evaluation for its type hints. This resolves an incompatibility with less-than-bleeding-edge versions of outcome that was inadvertently introduced in the 1.2.0 release. (#30)

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

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)

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 await_() failure has also been updated to more precisely describe the problem, rather than the previous generic “you must create a portal first”. (#26)

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

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)

Added @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)

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)

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)

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 bestow_portal() on another task. (#9)

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)

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

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.

Initial release.