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

Name	Description
`Domain`	Versioned ownership boundary; its `engrave` marks a function.
`Session`	Async context manager that scopes a sequence of engraved calls.
`ExecutionId`	Identifier for a recorded function execution.
`DomainId`	A domain's persistent machine identifier.
`ExecutionName`	The recorded name of an engraved function.
`ArgumentsDigest`	Digest of a call's canonical arguments.
`Execution`	Aggregate Root for a recorded function execution.
`ExecutionStatus`	Enum: `STARTED`, `COMPLETED`.
`SerializedValue`	Serializer-neutral persisted value (results, metadata).
`CanonicalArguments`	A call's encoded canonical arguments, the preimage of its key.
`CanonicalArgumentValue`	A logical canonical value, including a fallback.
`CanonicalFallback`	A fallback representation in a canonical argument.
`Metadata`	Metadata entry owned by an `Execution`.
`ExecutionRepository`	Repository for execution aggregates.
`Transaction`	Active transaction boundary.
`TransactionProvider`	Provider used by `TransactionScope`.
`Serializer`	Protocol for value serialization.
`ArgumentCanonicalizer`	Contract for normalizing bound call arguments into a canonical form.
`CanonicalValue`	A value in the JSON data model.
`SessionId`	The name a session's records are stored under.

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.

Planned: an explicit identity — @engrave(name="chat.reply", version=2) — so recorded histories survive renames (#40); released versions derive the name from the function's __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

Development Status
- 3 - Alpha
Framework
- AsyncIO
License
- OSI Approved :: MIT License
Operating System
- OS Independent
Programming Language
Typing
- Typed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

glyff-0.14.0.tar.gz (72.6 kB view details)

Uploaded Aug 13, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

glyff-0.14.0-py3-none-any.whl (64.1 kB view details)

Uploaded Aug 13, 2026 Python 3

File details

Details for the file glyff-0.14.0.tar.gz.

File metadata

Download URL: glyff-0.14.0.tar.gz
Upload date: Aug 13, 2026
Size: 72.6 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for glyff-0.14.0.tar.gz
Algorithm	Hash digest
SHA256	`dba4529fa7478d8732ca62dcc3951ae5ed8d06faecddb1e25bb54485ebf010ad`
MD5	`fc9cf0e2d0c57c709675185b72bc4534`
BLAKE2b-256	`0c0037746f949612c4d9df20c7d83e384926f9d7353722801579a3caebdb8252`

See more details on using hashes here.

Provenance

The following attestation bundles were made for glyff-0.14.0.tar.gz:

Publisher: publish-glyff.yml on nueruyu/glyff

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: glyff-0.14.0.tar.gz
- Subject digest: dba4529fa7478d8732ca62dcc3951ae5ed8d06faecddb1e25bb54485ebf010ad
- Sigstore transparency entry: 2450038302
- Sigstore integration time: Aug 13, 2026
Source repository:
- Permalink: nueruyu/glyff@3e083fd79982abe3de8d09f0e36d8e82e005b45e
- Branch / Tag: refs/tags/v0.14.0
- Owner: https://github.com/nueruyu
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish-glyff.yml@3e083fd79982abe3de8d09f0e36d8e82e005b45e
- Trigger Event: push