glyff

Guaranteed Lightweight Yieldable Function Foundation.

A primitive for pausing async functions across process and request boundaries, and resuming them later from the same point.

Install

pip install glyff

glyff has no dependencies beyond the Python standard library.

Behavior

• Marked function calls are recorded in a session-scoped execution repository, keyed by function identity, arguments, and an ordinal among identical calls.
• Re-invoking the same completed call within the same session returns the recorded result instead of re-executing.
• An exception persists nothing: the interrupted call stays STARTED (retried on resume), completed descendant work remains committed, and the original exception propagates.
• To pause a session intentionally, raise an application-owned exception and catch it outside the Session block.

Public API

glyff.migration carries the offline half: MigratableBackend and SessionMigration for a store that can replace a session atomically, SessionMigrator for what a session should become, and DomainMigration — declared as the ExecutionShape pairs that changed shape — as the one glyff ships. See migration.

Every engraved function belongs to a domain, which owns and versions its records:

engrave = glyff.Domain("com.example.payments", version="3").engrave

The first call into a domain records that version for the session, and a later call under a different one raises DomainVersionMismatchError rather than migrating. See migration.

Persistent boundaries should declare an identity such as @engrave(name="chat.reply"), so Python function renames do not change recorded keys. Without name, glyff derives it from the function's module and __qualname__.

Extending

• For persistent storage, see glyff-sqlite (production) and glyff-file-store (debug).
• For Pydantic-typed serialization, see glyff-pydantic.
• Custom backends provide an ExecutionRepository, a TransactionProvider and claim_domain, usually through a small backend bundle. See the backends doc.
• glyff.testing carries a conformance suite for each extension point, listed in the backends doc (planned: #36).

Status

Pre-1.0 — the API is unstable and will change. See the documentation for the guarantees and what is planned.

License

MIT