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 base corium artifact. Install at most one of corium-turso, corium-postgres, or corium-s3 alongside it to add exactly one driver. Each artifact uses a distinct extension-module name and depends on the common package, so it neither overwrites the base extension nor pulls other drivers into a remote-only installation. The package selects the installed artifact automatically and rejects ambiguous multi-artifact installations. A wheel without the advertised backend rejects it with an actionable StorageError, and available_storage_backends() reports the current artifact. See artifacts/ for local builds.

Release automation builds and smoke-tests CPython 3.10+ ABI3 wheels for Linux x86-64 and ARM64, macOS ARM64 and x86-64, and Windows x86-64. A tagged release publishes the base package and each optional artifact using PyPI trusted publishing. Unsupported platforms fail installation without falling back to an unverified source build.

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 3, 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 3, 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.71-cp310-abi3-win_amd64.whl (2.6 MB view details)

Uploaded CPython 3.10+Windows x86-64

corium-0.1.71-cp310-abi3-manylinux_2_28_x86_64.whl (3.1 MB view details)

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

corium-0.1.71-cp310-abi3-manylinux_2_28_aarch64.whl (3.1 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.28+ ARM64

corium-0.1.71-cp310-abi3-macosx_11_0_arm64.whl (2.7 MB view details)

Uploaded CPython 3.10+macOS 11.0+ ARM64

corium-0.1.71-cp310-abi3-macosx_10_12_x86_64.whl (2.8 MB view details)

Uploaded CPython 3.10+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: corium-0.1.71-cp310-abi3-win_amd64.whl
  • Upload date:
  • Size: 2.6 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.71-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 167a4b3e6e9cc277482cc00d17640faa36e77f12d41190ba32aa04261cc5a91b
MD5 1f8f02fd09b7728c4ed5ed0d6fb23d49
BLAKE2b-256 b0ecd0b21b0776b0b5b23f8a3cdd5fdc4e0d17d4039fc96f5f8ccc2f0081429d

See more details on using hashes here.

Provenance

The following attestation bundles were made for corium-0.1.71-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.71-cp310-abi3-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for corium-0.1.71-cp310-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 2c5639c69bcf9c93e30438878769e467841dc21b33130e7aea8ebf97a61f73eb
MD5 28af66ac117409f5fdad2786ac10c5e2
BLAKE2b-256 4d5c1152db09bbf0fa57fde557897eb87eeeb4b8bdbd5d7fef5be9b8488b00b8

See more details on using hashes here.

Provenance

The following attestation bundles were made for corium-0.1.71-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.71-cp310-abi3-manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for corium-0.1.71-cp310-abi3-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 d4c29e339fb566febe3912e115d728a0c4dd8cc0699cdeacd363f8e3756f3e35
MD5 34ab2d9b3d7b2fdf31c4a3faa35d7d44
BLAKE2b-256 1cbab3b9c8d05a45371b9e1c0ef87059243285dd783f69d9f2090bfd575dc487

See more details on using hashes here.

Provenance

The following attestation bundles were made for corium-0.1.71-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.71-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for corium-0.1.71-cp310-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 6e5a0d30d1f01e8e13d8fba24e59eb6508eab1c5793c68babc74361360bda45c
MD5 15be182894947efecf9af9f3b8719403
BLAKE2b-256 36d834feab9e687d16c8d50ce12eed940887f5d06a5e917ae6272f3993082afd

See more details on using hashes here.

Provenance

The following attestation bundles were made for corium-0.1.71-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.71-cp310-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for corium-0.1.71-cp310-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 893f90589016edd0467733a647ed821b518bbc8d74b95eb7a5cb771979b8bdb1
MD5 91e9e21aa43c26f4f1179b711e17ff8a
BLAKE2b-256 2f6379e667bcde53980e8632d8b0a794e94e10a769b42f47cf95bd73586ee5a4

See more details on using hashes here.

Provenance

The following attestation bundles were made for corium-0.1.71-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