forgelib

Python bindings for Forge via pyo3. A natively async ForgeClient over the async Rust core: every method returns an awaitable driven on a shared Tokio runtime, so an asyncio app awaits the binding directly: no thread-pool wrapper, the event loop is never blocked. The full primitive surface is exposed (kv, queue, config, ratelimit, blob, auth, schedule, pubsub), plus capability inspection, readiness probes, per-instance metrics, and W3C queue trace propagation.

Scheduler methods expose UTC schedule inspection, pause/resume, due lag/count, last successful tick, enqueue failures, and explicit bounded misfire policies. The scheduler enqueues ordinary deterministic queue jobs and does not own workflow state.

The top-level encode_cloud_event/decode_cloud_event and import_env_config/export_env_config helpers are state-free. They add no transport, framework, or environment mutation to the native client; see the repository's integration recipes for HTTP frameworks, deployment, and MCP patterns.

Forge errors surface as a typed exception hierarchy (forgelib.NotFoundError, forgelib.InvalidError, forgelib.LimitError, … all subclasses of forgelib.ForgeError), and every raised instance carries a retryable attribute.

Built against the stable ABI (abi3-py39), so one wheel runs on CPython ≥ 3.9. The 1.x release publishes wheels for Linux x64, Linux arm64, macOS arm64, and Windows x64, plus a source distribution. Intel macOS installs from source.

Build

docker compose up -d db          # a Postgres for local use

cd bindings/python
python -m venv .venv && . .venv/bin/activate
pip install maturin
maturin develop                  # compiles + installs `forgelib` into the venv

(On a CPython newer than this pyo3 release knows about, prefix the build with PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1.)

Use

Configuration lives in a forge.toml at the project root; init() reads it and instantiates the runtime. A minimal one:

[postgres]
url = "${DATABASE_URL:-postgres://postgres:forge@localhost:5432/forge_dev}"

[blob]
signing_secret = "${BLOB_SIGNING_SECRET:-dev-secret}"  # enables presigned blob URLs

import forgelib

forge = await forgelib.ForgeClient.init()  # reads ./forge.toml

greeting = forge.kv("greeting")
await greeting.set("hi")
print(await greeting.get())

# Realtime: topic handles decode JSON events for you.
async for event in forge.topic("chat:1").subscribe():
    handle(event)

Native typed handles

The main forgelib package binds names to JSON value types directly on the client, so most app code does not need raw queue strings plus json.dumps:

import forgelib

emails = forge.queue("emails")
await emails.enqueue({"to": "a@b.c", "template": "welcome"}, max_attempts=3)
job = await emails.dequeue(wait_seconds=1.0)
if job:
    handle(job.payload)            # already decoded
    await emails.ack(job.receipt)

profile = forge.kv("user:1:profile")
await profile.set({"name": "Ada"})

The raw methods (kv_set, queue_enqueue, ...) remain available for exact cross-language parity and string/byte contracts. The packaged stubs include both the raw client and the typed handles.

Deterministic tests

await ForgeClient.init_memory_for_testing(toml, start_ms, seed) creates the normal memory profile with manual time and repeatable test-only entropy. Call forge.advance_test_clock(seconds) to drive expiry, delayed work, scheduling, and rate-limit refill without sleeping. The seeded tokens are predictable and must never leave tests.

Application-owned names can use the v1 helper: forgelib.scope_kv_key("billing", tenant_id, user_id, invoice_id). parse_scoped_name reverses the length-prefixed encoding. This is a naming aid only; authorize every component before calling Forge.

OpenFeature, bulk reads, and snapshots

Install forgelib[openfeature] and use forgelib.openfeature.ForgeProvider with the official OpenFeature async client. The provider preserves stable variants and reasons, installs no global hooks, and exposes the official OpenTelemetry tracing hook for application-scoped registration. Startup code can use config_get_many and flag_details_many for ordered 256-item reads. config_snapshot captures only requested keys and pre-evaluated flags for 1–86,400 seconds; access it through config_snapshot_get and config_snapshot_flag_details, and protect application_protected snapshots before they leave the trusted server boundary.

Download files

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

Source Distribution

forgelib-1.1.0.tar.gz (347.9 kB view details)

Uploaded Aug 26, 2026 Source

Built Distributions

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.

forgelib-1.1.0-cp39-abi3-win_amd64.whl (10.5 MB view details)

Uploaded Aug 26, 2026 CPython 3.9+Windows x86-64

forgelib-1.1.0-cp39-abi3-manylinux_2_28_aarch64.whl (9.3 MB view details)

Uploaded Aug 26, 2026 CPython 3.9+manylinux: glibc 2.28+ ARM64

forgelib-1.1.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (9.7 MB view details)

Uploaded Aug 26, 2026 CPython 3.9+manylinux: glibc 2.17+ x86-64

forgelib-1.1.0-cp39-abi3-macosx_11_0_arm64.whl (8.4 MB view details)

Uploaded Aug 26, 2026 CPython 3.9+macOS 11.0+ ARM64

File details

Details for the file forgelib-1.1.0.tar.gz.

File metadata

Download URL: forgelib-1.1.0.tar.gz
Upload date: Aug 26, 2026
Size: 347.9 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for forgelib-1.1.0.tar.gz
Algorithm	Hash digest
SHA256	`50fc49ac5fb0cda503bb1d41648dcd98bea2e35a22838c1487a53f8f567497dc`
MD5	`c8784054df0c6e16fbbe3392c424b41b`
BLAKE2b-256	`bde12868dabdf3bfedaa20df8f05677409bd69b5017d80294bc07bcec6683233`

See more details on using hashes here.

Provenance

The following attestation bundles were made for forgelib-1.1.0.tar.gz:

Publisher: release.yml on isala404/forge

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: forgelib-1.1.0.tar.gz
- Subject digest: 50fc49ac5fb0cda503bb1d41648dcd98bea2e35a22838c1487a53f8f567497dc
- Sigstore transparency entry: 2604267765
- Sigstore integration time: Aug 26, 2026
Source repository:
- Permalink: isala404/forge@339b6bb86390e3bb2044d885cb0ed97a3da8454d
- Branch / Tag: refs/heads/main
- Owner: https://github.com/isala404
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@339b6bb86390e3bb2044d885cb0ed97a3da8454d
- Trigger Event: workflow_dispatch

File details

Details for the file forgelib-1.1.0-cp39-abi3-win_amd64.whl.

File metadata

Download URL: forgelib-1.1.0-cp39-abi3-win_amd64.whl
Upload date: Aug 26, 2026
Size: 10.5 MB
Tags: CPython 3.9+, Windows x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for forgelib-1.1.0-cp39-abi3-win_amd64.whl
Algorithm	Hash digest
SHA256	`c69a660995871b8003bd574696bcdcda440750fc34396b247a82cccc8770ec1d`
MD5	`0c91b8160973e4ad7f2f8014c2eac861`
BLAKE2b-256	`cd8975a4fb28c56026368dad63a14ef1dcd00af118b0b689f8222d84629dc8f1`

See more details on using hashes here.

Provenance

The following attestation bundles were made for forgelib-1.1.0-cp39-abi3-win_amd64.whl:

Publisher: release.yml on isala404/forge

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: forgelib-1.1.0-cp39-abi3-win_amd64.whl
- Subject digest: c69a660995871b8003bd574696bcdcda440750fc34396b247a82cccc8770ec1d
- Sigstore transparency entry: 2604267791
- Sigstore integration time: Aug 26, 2026
Source repository:
- Permalink: isala404/forge@339b6bb86390e3bb2044d885cb0ed97a3da8454d
- Branch / Tag: refs/heads/main
- Owner: https://github.com/isala404
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@339b6bb86390e3bb2044d885cb0ed97a3da8454d
- Trigger Event: workflow_dispatch

File details

Details for the file forgelib-1.1.0-cp39-abi3-manylinux_2_28_aarch64.whl.

File metadata

Download URL: forgelib-1.1.0-cp39-abi3-manylinux_2_28_aarch64.whl
Upload date: Aug 26, 2026
Size: 9.3 MB
Tags: CPython 3.9+, manylinux: glibc 2.28+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for forgelib-1.1.0-cp39-abi3-manylinux_2_28_aarch64.whl
Algorithm	Hash digest
SHA256	`c1681705094e542d850e07651d8a8ad8eeeebe66bca80155165c752bdca7e67d`
MD5	`a80026cd6b6ef3227264ed55af2b1b72`
BLAKE2b-256	`e8538724ca4a39473e9e04fee659cedad739ce7033d6de0aeee64b015d79b10b`

See more details on using hashes here.

Provenance

The following attestation bundles were made for forgelib-1.1.0-cp39-abi3-manylinux_2_28_aarch64.whl:

Publisher: release.yml on isala404/forge

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: forgelib-1.1.0-cp39-abi3-manylinux_2_28_aarch64.whl
- Subject digest: c1681705094e542d850e07651d8a8ad8eeeebe66bca80155165c752bdca7e67d
- Sigstore transparency entry: 2604267772
- Sigstore integration time: Aug 26, 2026
Source repository:
- Permalink: isala404/forge@339b6bb86390e3bb2044d885cb0ed97a3da8454d
- Branch / Tag: refs/heads/main
- Owner: https://github.com/isala404
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@339b6bb86390e3bb2044d885cb0ed97a3da8454d
- Trigger Event: workflow_dispatch

File details

Details for the file forgelib-1.1.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

Download URL: forgelib-1.1.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Upload date: Aug 26, 2026
Size: 9.7 MB
Tags: CPython 3.9+, manylinux: glibc 2.17+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for forgelib-1.1.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm	Hash digest
SHA256	`839ead60feb70445a6f60db5f2b024fcd0c6f749e0e98c54608d52f4561a7901`
MD5	`15aa0946c7b67a99bbd266ce1eab4eb4`
BLAKE2b-256	`7fb5e925d4979d73fdeec9685cafba80ac866d07e776d10fa3939681b7ecc68b`

See more details on using hashes here.

Provenance

The following attestation bundles were made for forgelib-1.1.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on isala404/forge

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: forgelib-1.1.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Subject digest: 839ead60feb70445a6f60db5f2b024fcd0c6f749e0e98c54608d52f4561a7901
- Sigstore transparency entry: 2604267780
- Sigstore integration time: Aug 26, 2026
Source repository:
- Permalink: isala404/forge@339b6bb86390e3bb2044d885cb0ed97a3da8454d
- Branch / Tag: refs/heads/main
- Owner: https://github.com/isala404
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@339b6bb86390e3bb2044d885cb0ed97a3da8454d
- Trigger Event: workflow_dispatch

File details

Details for the file forgelib-1.1.0-cp39-abi3-macosx_11_0_arm64.whl.

File metadata

Download URL: forgelib-1.1.0-cp39-abi3-macosx_11_0_arm64.whl
Upload date: Aug 26, 2026
Size: 8.4 MB
Tags: CPython 3.9+, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for forgelib-1.1.0-cp39-abi3-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`0483c7312a91ea7853f113ceb50ab9253412ff5eae80d586628bd19631b8a495`
MD5	`2e983a4f09d33ab38b6e995f048df112`
BLAKE2b-256	`7ae4e0db2990f97c8c78c378452e62d8bc889ea6a2bfb2c8cd108ef7ccf74017`

See more details on using hashes here.

Provenance

The following attestation bundles were made for forgelib-1.1.0-cp39-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on isala404/forge

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: forgelib-1.1.0-cp39-abi3-macosx_11_0_arm64.whl
- Subject digest: 0483c7312a91ea7853f113ceb50ab9253412ff5eae80d586628bd19631b8a495
- Sigstore transparency entry: 2604267784
- Sigstore integration time: Aug 26, 2026
Source repository:
- Permalink: isala404/forge@339b6bb86390e3bb2044d885cb0ed97a3da8454d
- Branch / Tag: refs/heads/main
- Owner: https://github.com/isala404
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@339b6bb86390e3bb2044d885cb0ed97a3da8454d
- Trigger Event: workflow_dispatch

Release history Release notifications | RSS feed

This release

1.1.0 This release

Aug 26, 2026 5 files

1.0.1

Jul 14, 2026 5 files

1.0.0

Jul 10, 2026 5 files

0.0.1

Jul 5, 2026 5 files

forgelib 1.1.0

forgelib

Build

Use

Native typed handles

Deterministic tests

OpenFeature, bulk reads, and snapshots

Project links

Key dates

1 maintainer

GitHub Statistics

License expression

Requires

Provides Extra

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

Release history Release notifications | RSS feed