cedrodb 0.3.0__tar.gz

cedrodb-0.3.0/Cargo.lock

@@ -0,0 +1,253 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 3
+
+[[package]]
+name = "cedrodb"
+version = "0.3.0"
+dependencies = [
+ "crc32fast",
+ "fs2",
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "cedrodb-python"
+version = "0.3.0"
+dependencies = [
+ "cedrodb",
+ "pyo3",
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "cfg-if"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"
+
+[[package]]
+name = "crc32fast"
+version = "1.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "01a7799fd6b852db0e61728dde9a204c423b44d689dbd432522543614b490e78"
+dependencies = [
+ "cfg-if",
+]
+
+[[package]]
+name = "fs2"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9564fc758e15025b46aa6643b1b77d047d1a56a1aea6e01002ac0c7026876213"
+dependencies = [
+ "libc",
+ "winapi",
+]
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "libc"
+version = "0.2.190"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ce5d3ddc6d3fa000eb1536d85e147bfe31aacaba692ed6a876f95cb7c855be78"
+
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "portable-atomic"
+version = "1.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05c8b63e8d9609db387f0324918f81d68fe27748f084ef092fb35954d0539a85"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pyo3"
+version = "0.30.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "229ca13b8a15bb0d1487b81ab975bfcd97513416499a8312011b6036e42e0de4"
+dependencies = [
+ "libc",
+ "once_cell",
+ "portable-atomic",
+ "pyo3-build-config",
+ "pyo3-ffi",
+ "pyo3-macros",
+]
+
+[[package]]
+name = "pyo3-build-config"
+version = "0.30.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "70130e2b6dd1ee589a8788026a429561ca5c40fa7a2fa7914c2282eddae24700"
+dependencies = [
+ "target-lexicon",
+]
+
+[[package]]
+name = "pyo3-ffi"
+version = "0.30.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5e7ff73c555c286d212d4ce7e5fbda845a973c4f61bd5f160f5f2c3c2a04d1c4"
+dependencies = [
+ "libc",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "pyo3-macros"
+version = "0.30.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c46d2e5862c7bb8207e3b639f713dda3c499933444784154c11d013c5a691b60"
+dependencies = [
+ "proc-macro2",
+ "pyo3-macros-backend",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "pyo3-macros-backend"
+version = "0.30.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "38b89f066f2ae72a2aef52d1537ca2fcd104440ebfadee06e97aa90738a25b9b"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "serde"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.154"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "syn"
+version = "3.0.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d78c8dee4c7bf0e14673097256fed6142ce9d3b85a408189d07482442145823b"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "target-lexicon"
+version = "0.13.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"
+
+[[package]]
+name = "winapi"
+version = "0.3.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5c839a674fcd7a98952e593242ea400abe93992746761e38641405d28b00f419"
+dependencies = [
+ "winapi-i686-pc-windows-gnu",
+ "winapi-x86_64-pc-windows-gnu",
+]
+
+[[package]]
+name = "winapi-i686-pc-windows-gnu"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6"
+
+[[package]]
+name = "winapi-x86_64-pc-windows-gnu"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
+
+[[package]]
+name = "zmij"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"

cedrodb-0.3.0/Cargo.toml

@@ -0,0 +1,28 @@
+[package]
+name = "cedrodb-python"
+version = "0.3.0"
+edition = "2021"
+rust-version = "1.85"
+description = "Native Python bindings for the CedroDB embedded database"
+license = "MIT"
+repository = "https://github.com/uppy19d0/cedrodb"
+homepage = "https://www.ltavarez.me/labs/cedrodb"
+publish = false
+include = ["src/**/*.rs", "Cargo.toml", "Cargo.lock", "LICENSE"]
+readme = "README.md"
+
+[lib]
+name = "_native"
+crate-type = ["cdylib"]
+
+[dependencies]
+cedrodb = { path = "core", version = "=0.3.0" }
+pyo3 = { version = "0.30.1", features = ["abi3-py39"] }
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+
+[profile.release]
+lto = "thin"
+strip = "symbols"
+
+[workspace]

cedrodb-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luis Tavarez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cedrodb-0.3.0/PKG-INFO

@@ -0,0 +1,300 @@
+Metadata-Version: 2.4
+Name: cedrodb
+Version: 0.3.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Database :: Database Engines/Servers
+License-File: LICENSE
+Summary: Embedded Rust document database with atomic batches, indexes and a durable changefeed
+Keywords: database,embedded,document,outbox,changefeed,rust
+Home-Page: https://www.ltavarez.me/labs/cedrodb
+Author: Luis Tavarez
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Documentation, https://www.ltavarez.me/labs/cedrodb
+Project-URL: Homepage, https://www.ltavarez.me/labs/cedrodb
+Project-URL: Repository, https://github.com/uppy19d0/cedrodb
+
+# CedroDB for Python
+
+**Keep application documents, events and recovery history in one local database.**
+CedroDB is an embedded document engine written in Rust, with a native Python API.
+A form submission and its outbox event can commit together, indexed queries find
+pending work, and a durable changefeed lets your application resume processing
+after restarting. Version 0.3 adds integrity verification and portable backups.
+
+Use it for offline forms and inspections, desktop application state, local
+automation, or small services that need JSON documents without running a database
+server. The Python package calls the Rust engine directly; it does not spawn a
+process or maintain a second Python storage implementation.
+
+**Experimental software.** Active documents and indexes live in RAM, a directory
+has one owning handle/process, and the log currently has no compaction. See the
+limits below before choosing it for important data. There are no performance
+claims or production-readiness guarantees.
+
+## Installation
+
+For the 0.3.0 release on PyPI:
+
+```sh
+python -m pip install cedrodb==0.3.0
+```
+
+PyPI publication requires the project's publisher configuration. If that version
+is not available there yet, obtain its wheel or self-contained source archive
+from [GitHub Releases](https://github.com/uppy19d0/cedrodb/releases), then install
+the downloaded file:
+
+```sh
+python -m pip install ./cedrodb-0.3.0.tar.gz
+```
+
+A compatible wheel needs no Rust toolchain at runtime. Source installation
+requires Python 3.9+, Rust 1.85+ and a working C linker. The source archive bundles
+the Rust core; it builds independently of the repository.
+
+The release wheel build matrix covers four platform/architecture combinations:
+
+| Platform | Architecture | Python ABI |
+| --- | --- | --- |
+| Linux | x86_64 | CPython 3.9+ (`cp39-abi3`) |
+| macOS | Apple Silicon / ARM64 | CPython 3.9+ (`cp39-abi3`) |
+| macOS | Intel / x86_64 | CPython 3.9+ (`cp39-abi3`) |
+| Windows | x86_64 | CPython 3.9+ (`cp39-abi3`) |
+
+Check a release's assets for its available builds and platform tags. Other
+architectures may require a source build; a Linux wheel does not imply support
+for every Linux distribution or musl-based system.
+
+## Quickstart: save and query documents
+
+```python
+from cedrodb import Database
+
+with Database("./app.cedro") as db:
+    orders = db.collection("orders")
+    orders.put_many({
+        "order:1": {"status": "paid", "total": 120},
+        "order:2": {"status": "pending", "total": 35},
+    })
+    orders.create_index("status")
+    page = orders.find_page(
+        [{"field": "status", "op": "eq", "value": "paid"}], limit=20
+    )
+    print(page["records"])       # [{"key": "order:1", "value": {...}}]
+    print(page["used_index"])    # status
+    print(orders.get("order:1"))
+    print(db.stats())
+```
+
+Collections store any supported JSON value, including arrays and null. `put`
+replaces the complete value for a key; `delete` removes it. `put_many` accepts a
+mapping or an iterable of `(key, value)` pairs and commits them atomically.
+
+`find()` returns one list of `{key, value}` records. `find_page()` also returns
+`next_after`, `scanned` and `used_index`. To continue, pass `next_after` as `after`;
+`None` means there is no continuation. `iter_records(page_size=100)` iterates
+bounded result pages. Results are ordered by key; pages do not share a snapshot.
+Writes between requests can change subsequent results. Limits are 1..1000 records.
+
+Filters are combined with AND. Operations are `eq`, `ne`, `gt`, `gte`, `lt`,
+`lte`, and `exists` (with a boolean value). A field is a top-level name or an
+RFC 6901 JSON Pointer, such as `/customer/city`. Missing fields differ from JSON
+null; use `exists` to test absence. Equality indexes stay consistent with writes
+and must be recreated after reopening or restoring a database.
+
+## Offline writes and the atomic outbox
+
+Commit the document and the event in the same transaction. Your uploader can
+then find the event after a restart without losing the corresponding form.
+
+```python
+from cedrodb import Database
+
+with Database("./field-app.cedro") as db:
+    with db.transaction() as tx:
+        tx.put("forms", "inspection:1", {
+            "site": "Santo Domingo", "status": "pending_upload"
+        })
+        tx.put("outbox", "inspection:1:submitted", {
+            "event_id": "inspection:1:submitted",
+            "type": "inspection.submitted", "form_id": "inspection:1"
+        })
+
+    page = db.changes(since=0, limit=100)
+    for transaction in page["transactions"]:
+        for operation in transaction["operations"]:
+            if operation["collection"] == "outbox" and operation["kind"] == "put":
+                print(operation["value"])
+    # Save page["next_cursor"] only after processing succeeds.
+```
+
+The feed survives close/reopen and contains complete put/delete operations in
+transaction order. `since` is an exclusive transaction cursor, starting at zero,
+and belongs to this database history. `limit` counts transactions (1..1000), not
+operations. `has_more` tells you whether another page is available. Pages also
+cap encoded frame bytes at `max_frame_bytes + 12` without splitting a transaction;
+decoded Python objects require additional memory.
+
+Your application owns the uploader, checkpoint storage and event deduplication.
+A crash after an external effect but before its checkpoint can repeat delivery;
+CedroDB does not promise exactly-once delivery or provide a background worker.
+
+`db.transaction()` buffers writes and copies staged values. A successful context
+exit commits one batch; an exception rolls it back. Reads continue to observe
+committed data, without read-your-writes, snapshot isolation or automatic conflict
+detection. Alternatively, pass operations directly to `db.batch([...])`:
+
+```python
+with Database("./app.cedro") as db:
+    db.batch([
+        {"kind": "put", "collection": "orders", "key": "order:3", "value": {"total": 10}},
+        {"kind": "delete", "collection": "drafts", "key": "order:3"},
+    ])
+```
+
+## Verify, back up and restore
+
+A backup contains the committed log inside a versioned container with a length
+and CRC checksum. It preserves transaction history and changefeed cursors.
+
+```python
+from pathlib import Path
+from cedrodb import Database
+
+backup = Path("./field-app.backup")      # Must not already exist.
+restored = Path("./recovered.cedro")      # Must not already exist, even empty.
+
+with Database("./field-app.cedro") as db:
+    print(db.verify())
+    print(db.backup(backup))
+
+report = Database.restore_backup(backup, restored)
+print(report)  # log_bytes, transactions, records, content_bytes
+
+with Database(restored) as db:
+    db.collection("forms").create_index("status")
+    print(db.changes(since=0))
+```
+
+`verify()` reads and validates the committed log; it does not repair data.
+`backup(path)` creates a new file and never overwrites an existing file or
+folder. `restore_backup(backup_path, destination_path)` validates the complete
+container and log before creating a new destination directory. Parent directories
+must already exist. Static restore returns an `IntegrityReport` dictionary,
+without retaining an open handle or file lock. Index definitions are handle-local
+and must be recreated; the committed documents and history are retained.
+
+For custom content limits, pass the same configuration to restore and open:
+
+```python
+limits = {"max_document_bytes": 2_097_152, "max_state_bytes": 134_217_728}
+Database.restore_backup("./large.backup", "./large-restored.cedro", **limits)
+with Database("./large-restored.cedro", **limits) as db:
+    print(db.verify())
+```
+
+All three methods are synchronous and perform disk I/O; the native operation
+releases Python's GIL. Verification replays state in memory and can require
+another copy of the live state plus a frame buffer. CRC detects accidental
+corruption; it does not authenticate or encrypt a backup. Interrupted I/O can
+require inspecting and removing an incomplete output before retrying. See
+[backup format and recovery details](https://github.com/uppy19d0/cedrodb/blob/main/docs/backups.md).
+
+Run the complete offline-form example with `python examples/offline_forms.py`.
+
+## Conditional updates and null
+
+```python
+from cedrodb import Database, DELETE, MISSING
+
+with Database("./app.cedro") as db:
+    claims = db.collection("claims")
+    created = claims.compare_exchange(
+        "job:1", expected=MISSING, replacement={"owner": "worker-1"}
+    )
+    removed = claims.compare_exchange(
+        "job:1", expected={"owner": "worker-1"}, replacement=DELETE
+    )
+    missing = claims.get("unknown", MISSING) is MISSING
+```
+
+`replacement` is required. `None` stores JSON null; `DELETE` removes the record.
+`MISSING` as expected means the key must not exist, while `expected=None` requires
+a stored null. A mismatch returns `False` without appending a transaction. The
+comparison covers the complete JSON value. Exact integers and integral floats
+compare equally only within the safe range ±2**53; booleans remain distinct.
+
+## API reference
+
+| Object | Methods |
+| --- | --- |
+| `Database` | `collection`, `batch`, `transaction`, `changes`, `stats`, `verify`, `backup`, `close` |
+| `Database.restore_backup` | Static restore with optional content-limit keywords |
+| `Collection` | `put`, `get`, `delete`, `put_many`, `find`, `find_page`, `iter_records`, `create_index`, `compare_exchange`, `aggregate` |
+| `Transaction` | `put(collection, key, value)`, `delete(collection, key)`, `commit`, `rollback`, context manager |
+
+`Database(path, *, max_document_bytes=1_048_576, max_frame_bytes=16_777_216,
+max_state_bytes=67_108_864)` opens or creates a directory. Paths accept strings
+and `os.PathLike` objects returning strings. Use a context manager or `close()`;
+closing is idempotent and releases the native lock immediately. `db.closed`
+reports its state. Existing collection handles fail with `DatabaseClosedError`
+after close.
+
+Engine failures raise `CedroError`. Unsupported JSON raises `TypeError` or
+`ValueError`; integers outside `[-2**63, 2**64 - 1]` raise `OverflowError`. NaN,
+infinity, cycles, non-string object keys and unsupported objects are rejected
+before mutation. Supported integers round-trip exactly. JSON depth is limited
+to 64 levels, and the transport always uses `allow_nan=False`. Type annotations
+and a `py.typed` marker are included.
+
+## Current limits
+
+- One open owning handle/process per directory; its native calls are serialized.
+- Documents, equality indexes and transaction offsets are held in RAM. Encoded
+  content limits exclude allocator overhead, indexes and temporary buffers.
+- Append-only log with no compaction, retention or bounded total disk use.
+- Handle-local indexes and key-based query pagination, without snapshot isolation.
+- `aggregate(field)` uses floating-point arithmetic on a top-level numeric field
+  and can lose integer precision above 2**53; stored documents remain exact.
+- No SQL, MVCC, replication, encryption or automatic synchronization.
+
+## Upgrade from 0.2 to 0.3
+
+Existing document, batch, query, CAS and changefeed APIs keep their signatures.
+The database log format is unchanged; 0.2 stores can be opened directly. Version
+0.3 adds `db.verify()`, `db.backup(path)` and `Database.restore_backup(...)`.
+Backup containers are distinct from raw `cedro.log` files: use `backup()` to
+create them. Restore requires a new destination and preserves the original
+history/cursor sequence. Recreate equality indexes after opening the restored
+store, and configure matching limits when your store exceeds the defaults.
+
+## Build and test
+
+```sh
+python -m venv .venv
+# Activate the environment with your platform's activation command.
+python -m pip install 'maturin>=1.15,<2'
+python scripts/prepare_core.py
+maturin build --release --out dist
+maturin sdist --out dist
+python -m pip install ./dist/<your-platform-wheel>.whl
+python -m unittest discover -s tests -v
+python scripts/verify_sdist.py dist/cedrodb-0.3.0.tar.gz
+python examples/offline_forms.py
+```
+
+`prepare_core.py` copies only the core manifest, license and Rust source into
+ignored `core/`. Regenerate that copy after engine changes. The sdist includes
+those files and has no dependency on `../..` at installation. `verify_sdist.py`
+rebuilds an extracted archive, installs the resulting wheel in an isolated target
+and runs its tests. Keep `Cargo.lock` for reproducible dependency versions.
+
+[Source](https://github.com/uppy19d0/cedrodb) ·
+[Demo](https://www.ltavarez.me/labs/cedrodb) ·
+[Issues](https://github.com/uppy19d0/cedrodb/issues)
+