gitsheets (Python)

The Python binding for gitsheets — a git-backed document store for low-volume, high-touch, human-scale data. Records are canonical TOML files in a git tree; every write is a real git commit you can diff, review, revert, and sync like any other.

The guarantee that defines this package: a record written from Python and the same record written from the Node.js gitsheets package produce byte-identical trees, blobs, and commits. The binding is a thin pyo3 layer over the shared Rust gitsheets-core engine; everything that determines on-disk bytes (canonical TOML, path-template rendering, JSON-Schema validation, the embedded JS engine, the Sheet/Transaction/Store state machine) lives in the core, and a cross-binding parity suite proves the byte equivalence in CI on every change.

Install

pip install gitsheets

Prebuilt abi3 wheels (any CPython >= 3.9) ship for Linux x86_64 + aarch64 (glibc), Linux x86_64 (musl), macOS x86_64 + arm64, and Windows x86_64. Other platforms install from the sdist, which needs a Rust toolchain.

Quick start

A sheet is declared by a TOML config committed in the repo — here, one record file per person, keyed by slug, under people/:

mkdir crm && cd crm && git init -b main
mkdir .gitsheets
cat > .gitsheets/people.toml <<'EOF'
[gitsheet]
path = '${{ slug }}'
root = 'people'
EOF
git add .gitsheets && git commit -m "declare the people sheet"

Write records inside a transaction — commit on success, discard on error:

import time
import gitsheets

with gitsheets.transact(
    ".git",                       # the repo's GIT_DIR
    "people: add jane",           # commit message
    int(time.time()),
    author=("Jane Doe", "jane@example.org"),
    branch="refs/heads/main",
) as tx:
    tx.open_sheet("people", ".gitsheets/people.toml")
    tx.upsert("people", {"slug": "jane", "email": "jane@example.org"})

print(tx.result["commit_hash"])

The round-trip is plain git — and the bytes are canonical, identical to what the Node binding would have written:

$ git show main:people/jane.toml
email = "jane@example.org"
slug = "jane"

Type fidelity

The binding marshals Python natives ↔ the core's TOML-faithful value type:

Python core Value TOML
int Integer (i64) integer (distinct from float)
float Float (f64) float (1 ≠ 1.0)
str String string
bool Boolean boolean
datetime.datetime Datetime datetime (aware UTC instant)
dict Table table
list / tuple Array array

Python's int is arbitrary-precision, so small ids stay ergonomic and large values never lose precision (an int outside the i64 range TOML permits raises OverflowError).

Consumer validators

The runtime consumer-validator hook runs Python-side on the normalized record before the core writes any bytes — pass any callable (a Pydantic Model.model_validate, a Zod-style check, a plain assertion):

import gitsheets
from pydantic import BaseModel

class Person(BaseModel):
    slug: str
    email: str

with gitsheets.transact(git_dir, "add jane", time_seconds, author=("Jane", "jane@x.org"), branch="refs/heads/main") as tx:
    tx.open_sheet("people", ".gitsheets/people.toml")
    tx.upsert("people", {"slug": "jane", "email": "jane@x.org"}, validate=Person.model_validate)

JSON-Schema validation declared in the sheet config runs in-core, identically to the Node binding.

What 0.x is (and isn't)

The 0.x releases are honestly scoped as a transactional writer with parity-proven reads: transact/Transaction (open_sheet, upsert, delete, clear, will_change), attachments (set_attachment(s)/get_attachment(s)/delete_attachment(s)), reads through opened sheets, and validation.

Known gaps, tracked in #240 and stated plainly rather than papered over:

  • No freshness model — no refresh/auto-refresh after commit; reads see the tree a transaction opened, not later commits.
  • No streaming blob reads — attachments surface as blob hashes; there is no streaming read API yet.
  • No push daemon — syncing the repo to remotes is yours to arrange.

These reach parity with the Node binding as #240 lands.

Versioning and releases

Releases ship from the py-v* tag track: the released version is committed in rust/gitsheets-py/Cargo.toml, the tag must match it, and every release is built from a commit whose cross-binding byte-parity suite is green. Pre-1.0 semver: breaking surface changes bump the minor version.

Development

Build a local wheel and run the smoke + cross-binding parity suite:

uv venv && uv pip install maturin pytest pydantic
uv run maturin develop
uv run pytest tests/

Project links

Data verified by PyPI on Aug 21, 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:
Latest release

1 maintainer

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

Credits

Author: Jarvus Innovations

GitHub Statistics

Data verified by PyPI on Aug 21, 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 Software License (Apache-2.0)

Requires

Python >=3.9

Provides Extra

test

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 Distribution

gitsheets-0.2.0.tar.gz (178.5 kB view details)

Uploaded Source

Built Distributions

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

gitsheets-0.2.0-cp39-abi3-win_amd64.whl (8.6 MB view details)

Uploaded CPython 3.9+Windows x86-64

gitsheets-0.2.0-cp39-abi3-musllinux_1_2_x86_64.whl (9.8 MB view details)

Uploaded CPython 3.9+musllinux: musl 1.2+ x86-64

gitsheets-0.2.0-cp39-abi3-manylinux_2_28_x86_64.whl (9.2 MB view details)

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

gitsheets-0.2.0-cp39-abi3-manylinux_2_28_aarch64.whl (9.3 MB view details)

Uploaded CPython 3.9+manylinux: glibc 2.28+ ARM64

gitsheets-0.2.0-cp39-abi3-macosx_11_0_arm64.whl (8.4 MB view details)

Uploaded CPython 3.9+macOS 11.0+ ARM64

gitsheets-0.2.0-cp39-abi3-macosx_10_12_x86_64.whl (8.7 MB view details)

Uploaded CPython 3.9+macOS 10.12+ x86-64

File details

Details for the file gitsheets-0.2.0.tar.gz.

File metadata

  • Download URL: gitsheets-0.2.0.tar.gz
  • Upload date:
  • Size: 178.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for gitsheets-0.2.0.tar.gz
Algorithm Hash digest
SHA256 be591c34a530819fb4989a3f21d1438ff3e888a57e19b9cd4423e82cf2b682fc
MD5 b114d875c9c1bfe4f664374375b65236
BLAKE2b-256 bb8ef9d3fcf57030afcb1e6002b49e59d87dfdc867bd37f6ab4d22a15e6e5246

See more details on using hashes here.

Provenance

The following attestation bundles were made for gitsheets-0.2.0.tar.gz:

Publisher: python-publish.yml on JarvusInnovations/gitsheets

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

File details

Details for the file gitsheets-0.2.0-cp39-abi3-win_amd64.whl.

File metadata

  • Download URL: gitsheets-0.2.0-cp39-abi3-win_amd64.whl
  • Upload date:
  • Size: 8.6 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 gitsheets-0.2.0-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 e2b5d5b27429538fed81fbb7450b428f0ea8c62f0187e14615f78a4d712ebaa6
MD5 2d215a6cefc040732cd9fc5c18d7b675
BLAKE2b-256 33673d4630bf5d6ae64c3e48df43cbd46b1db9fac92e4dc709da0ac9301f2ca8

See more details on using hashes here.

Provenance

The following attestation bundles were made for gitsheets-0.2.0-cp39-abi3-win_amd64.whl:

Publisher: python-publish.yml on JarvusInnovations/gitsheets

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

File details

Details for the file gitsheets-0.2.0-cp39-abi3-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for gitsheets-0.2.0-cp39-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 52c4c85d108e2ef2111270ae8dcaba763e879de9b87c81689cbc2225b89bf1cf
MD5 088e08a8f88734b4fb49710285fb6bc0
BLAKE2b-256 f18d9afe636eba99b519118aea36e81f3b6d41b6344594b170248d7755e64839

See more details on using hashes here.

Provenance

The following attestation bundles were made for gitsheets-0.2.0-cp39-abi3-musllinux_1_2_x86_64.whl:

Publisher: python-publish.yml on JarvusInnovations/gitsheets

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

File details

Details for the file gitsheets-0.2.0-cp39-abi3-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for gitsheets-0.2.0-cp39-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 f996acb5edd60c51a3ae794d89615f59e908c502d0db96ac3db2a4a62a8ad785
MD5 903bfd38f9003e0d927ff415dde7e26f
BLAKE2b-256 2c41c2ea6a6c103542ef6d561095a127264647f1f54b79937c33774210d0856f

See more details on using hashes here.

Provenance

The following attestation bundles were made for gitsheets-0.2.0-cp39-abi3-manylinux_2_28_x86_64.whl:

Publisher: python-publish.yml on JarvusInnovations/gitsheets

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

File details

Details for the file gitsheets-0.2.0-cp39-abi3-manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for gitsheets-0.2.0-cp39-abi3-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 09dd519b66b1358093e8d0ec9ba2683fc645d06efddc83d1b1994749e559eeac
MD5 a678f4312898e87d456e177b65aa872e
BLAKE2b-256 bc525b6650225fa5d7b429acf75bc5a397019383532f36b5c0ac8924b2543ae1

See more details on using hashes here.

Provenance

The following attestation bundles were made for gitsheets-0.2.0-cp39-abi3-manylinux_2_28_aarch64.whl:

Publisher: python-publish.yml on JarvusInnovations/gitsheets

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

File details

Details for the file gitsheets-0.2.0-cp39-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for gitsheets-0.2.0-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 686ad5e118f9294b31be97b337d8d17e9ee57ed0c7ff14c421add85229d4f2d7
MD5 36479d40e8808abc9d6d05de5d224b3c
BLAKE2b-256 f335853c0d0f4b02ee5b4b2c6c1bd8821e88205e5b34014547200d1c1c10156e

See more details on using hashes here.

Provenance

The following attestation bundles were made for gitsheets-0.2.0-cp39-abi3-macosx_11_0_arm64.whl:

Publisher: python-publish.yml on JarvusInnovations/gitsheets

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

File details

Details for the file gitsheets-0.2.0-cp39-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for gitsheets-0.2.0-cp39-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 cf218b00b8df44aa1f5707372aa3a19c3c16344914198adec4e6bcd5e8f6ac47
MD5 35a1400c35ebf63947f4bf50f55bfbff
BLAKE2b-256 9e1febbb03c495deb66ecb76596db9ab8486866e8018f690f9fc2c2950de27ac

See more details on using hashes here.

Provenance

The following attestation bundles were made for gitsheets-0.2.0-cp39-abi3-macosx_10_12_x86_64.whl:

Publisher: python-publish.yml on JarvusInnovations/gitsheets

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

Release history Release notifications | RSS feed

This release

0.2.0 This release

7 files

0.1.0

7 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page