Corium Python client

corium is the asynchronous Python API for both Corium deployment modes:

  • LocalPeer runs a full peer in-process.
  • RemotePeer connects to corium peer-server.

Both satisfy the same runtime-checkable Peer protocol and return immutable Db values. The native extension connects LocalPeer directly to Corium's peer library and RemotePeer to corium peer-server.

from corium import LocalPeer, Query

async with await LocalPeer.connect(
    "http://127.0.0.1:4334",
    database="people",
) as peer:
    db = await peer.db()
    rows = await db.query(Query.find("?name").where("?entity", ":person/name", "?name"))

Explicit close() (or async with) is required for deterministic shutdown. Wall-clock database views accept timezone-aware, millisecond-precision datetime values only. Custom Tagged values may use any tag except bytes, eid, inst, and uuid, which are reserved for dedicated boundary types. https:// endpoints automatically enable platform TLS roots, and bearer tokens are rejected for plaintext http:// endpoints by default. Local development may opt in explicitly with allow_insecure_token=True. Every endpoint must include an http:// or https:// scheme. Datom scans use limit=None for an explicitly unbounded scan.

Query, Pull, and transaction builders

All builders are immutable: every fluent method returns a new value, and Db.query, Db.pull, and Peer.transact accept either builders or the existing raw data-form escape hatches.

from corium import (
    EntityMap,
    Pull,
    Query,
    TxBuilder,
    data,
    gte,
    lookup,
    tempid,
)

tx = (
    TxBuilder()
    .entity(
        EntityMap.with_id(tempid("ada")).set("person/name", "Ada").set("person/age", 36)
    )
    .build()
)
report = await peer.transact(tx)

adults = (
    Query.find_collection("?name")
    .in_scalar("?minimum")
    .where(data("?entity", ":person/name", "?name"))
    .where("?entity", ":person/age", "?age")
    .where(gte("?age", "?minimum"))
)
names = await report.db_after.query(adults, 18)

person = await report.db_after.pull(
    Pull().db_id().attr("person/name").attr("person/age"),
    lookup("person/name", "Ada"),
)

Query builders cover relation, collection, tuple, and scalar results; scalar, tuple, collection, relation, database, and rule inputs; data patterns; predicates and functions; not, not-join, or, and or-join; rules; Pull find expressions; and aggregates. Strings beginning with ? are variables, strings beginning with : are keywords, and _ is the blank term. Use lit(...) when one of those spellings must remain a string literal.

Pull builders cover wildcard and entity-id selections, reverse references, nested patterns, bounded and unbounded recursion, aliases, defaults, and limits. Transaction builders cover entity maps, temporary IDs, lookup references, explicit EntityId values, add/retract/CAS/retract-entity operations, and arbitrary raw forms.

See examples/people.py for a complete topology-neutral example. The package includes py.typed, so these APIs are visible to static type checkers without a separate stub distribution.

Private PKI deployments can add a PEM certificate authority and override the certificate DNS name without replacing the platform trust store:

from pathlib import Path

peer = await RemotePeer.connect(
    "https://127.0.0.1:4336",
    database="people",
    token="secret",
    tls_ca=Path("ca.pem").read_bytes(),
    tls_domain="corium.internal",
)

Direct storage

LocalPeer normally reconstructs its in-process database from the transactor's gapless transaction stream. For faster cold starts, DirectStorage asks the transactor for a separately usable, read-only storage connection and loads the latest published snapshot before subscribing to the remaining transaction tail:

from corium import DirectStorage, LocalPeer, SegmentCache

peer = await LocalPeer.connect(
    "https://transactor.example.com",
    database="people",
    token=token,
    storage=DirectStorage(
        cache=SegmentCache(
            "/var/cache/corium/people",
            capacity_bytes=256 * 1024**3,
        )
    ),
)

Filesystem storage is present in the corium package. Install the package for the storage backend that the transactor uses:

python -m pip install corium corium-turso
# Or install corium-postgres or corium-s3.

Install all packages before the Python process starts. Corium loads each installed plugin through the corium.store_plugins entry-point group.

Make sure that the required backend is available:

from corium import available_storage_backends

assert "turso" in available_storage_backends()

Then pass DirectStorage to LocalPeer.connect, as shown in the first example. The transactor supplies the separate read-only configuration for the backend. You do not import the plugin package or give Corium a library path.

available_storage_backends() reports all loaded backends. A missing backend causes a StorageError when LocalPeer connects.

WARNING: Install plugins only from trusted publishers. A plugin runs native code in the Python process and can receive storage credentials.

Filesystem and Turso advertise local paths, so their direct-storage peers must run on a host that can reach the same path as the transactor. Corium rejects a missing store with StorageError; it does not create an empty store or silently fall back to replaying the full transaction stream.

PostgreSQL and S3 discovery never reuses the transactor's write credentials. The transactor must advertise its separately configured read-only PostgreSQL URL or S3 credentials. Temporary S3 credentials are refreshed through GetStorageInfo, and a refresh is rejected if the bucket, prefix, region, or endpoint changes.

The native integration suite uses the same workload for local and remote peers: query result conversion, Pull, datom scans, immutable views, stable caller-error mapping, transactions, and deterministic close. Set CORIUM_TEST_LOCAL_ENDPOINT and/or CORIUM_TEST_REMOTE_ENDPOINT to run it against live services. The dedicated private-CA and bearer-auth test uses CORIUM_TEST_REMOTE_TLS_ENDPOINT, CORIUM_TEST_REMOTE_TLS_TOKEN, CORIUM_TEST_REMOTE_TLS_CA, and optionally CORIUM_TEST_REMOTE_TLS_DOMAIN/CORIUM_TEST_REMOTE_BAD_TOKEN.

Project links

Data verified by PyPI on Aug 5, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.1.84)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for csm831 from gravatar.com csm831

GitHub Statistics

Data verified by PyPI on Aug 5, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

Apache-2.0 OR MIT

Requires

Python >=3.10

Provides Extra

dev

Tags

database datalog asyncio

Classifiers

Report project as malware

Download files

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

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

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

corium-0.1.82-cp310-abi3-win_amd64.whl (3.0 MB view details)

Uploaded CPython 3.10+Windows x86-64

corium-0.1.82-cp310-abi3-manylinux_2_28_x86_64.whl (3.5 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.28+ x86-64

corium-0.1.82-cp310-abi3-manylinux_2_28_aarch64.whl (3.6 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.28+ ARM64

corium-0.1.82-cp310-abi3-macosx_11_0_arm64.whl (3.1 MB view details)

Uploaded CPython 3.10+macOS 11.0+ ARM64

corium-0.1.82-cp310-abi3-macosx_10_12_x86_64.whl (3.2 MB view details)

Uploaded CPython 3.10+macOS 10.12+ x86-64

File details

Details for the file corium-0.1.82-cp310-abi3-win_amd64.whl.

File metadata

  • Download URL: corium-0.1.82-cp310-abi3-win_amd64.whl
  • Upload date:
  • Size: 3.0 MB
  • Tags: CPython 3.10+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for corium-0.1.82-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 f4983d97e73d3fffa96175f5ac4b1866703443ca37d83fcbbb93ed17cda22102
MD5 97b976939c21de1aa678075b74cae17c
BLAKE2b-256 bae45130ffb1f74e2e40009dc1e121d23a1ae108c53f3e308ea9671f24ca0a1e

See more details on using hashes here.

Provenance

The following attestation bundles were made for corium-0.1.82-cp310-abi3-win_amd64.whl:

Publisher: publish.yml on csm/corium

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

File details

Details for the file corium-0.1.82-cp310-abi3-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for corium-0.1.82-cp310-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 4805b16794818a20a2f4ec4dcb9b4b11e3a1a9a4ed2bc0a35ad4f6cceccbe2f2
MD5 391264f5690a132be55e2fbc1f49e8e0
BLAKE2b-256 4738c6c965b3dfe2c8db3ec00754146697db48f6927646bcf914b05ce43e576c

See more details on using hashes here.

Provenance

The following attestation bundles were made for corium-0.1.82-cp310-abi3-manylinux_2_28_x86_64.whl:

Publisher: publish.yml on csm/corium

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

File details

Details for the file corium-0.1.82-cp310-abi3-manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for corium-0.1.82-cp310-abi3-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 bb6dfafcf409489d273ac19a70ee7c902b555664ee59cf38b1a5037e2441f16c
MD5 0f62e7fcbb2735a4d835e270289bff23
BLAKE2b-256 1deabb28ea1dda2f94716f16771694cadd0ba3a1fbdfa38cae1f3efd3b0086e0

See more details on using hashes here.

Provenance

The following attestation bundles were made for corium-0.1.82-cp310-abi3-manylinux_2_28_aarch64.whl:

Publisher: publish.yml on csm/corium

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

File details

Details for the file corium-0.1.82-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for corium-0.1.82-cp310-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 c5d89caf2332633b2a04d24e0b0bce59227fb0de5f80c127358e23853bfb1af6
MD5 d6bb628ac754854d56b9b8e52ff9c7ef
BLAKE2b-256 045bd4344a68503e844a055b020f24f6a7411c0478657c764e1a5e1bd1d7ff98

See more details on using hashes here.

Provenance

The following attestation bundles were made for corium-0.1.82-cp310-abi3-macosx_11_0_arm64.whl:

Publisher: publish.yml on csm/corium

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

File details

Details for the file corium-0.1.82-cp310-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for corium-0.1.82-cp310-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 3b4f9c657cde86ce3a717d8cb2b98df1bf9f3e41e5cb088f8fc16231b606e879
MD5 8a5b8d2a2402c18ed33803502eeb2463
BLAKE2b-256 cb06e5d462e11b32bd3a1fad2debdfd5fd27de1bd8fcd2d0ac9a1e4afd70d544

See more details on using hashes here.

Provenance

The following attestation bundles were made for corium-0.1.82-cp310-abi3-macosx_10_12_x86_64.whl:

Publisher: publish.yml on csm/corium

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

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page