zova 0.17.0__tar.gz

zova-0.17.0/Cargo.lock

@@ -0,0 +1,148 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "libc"
+version = "0.2.186"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
+
+[[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.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c33a9471896f1c69cecef8d20cbe2f7accd12527ce60845ff44c153bb2a21b49"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pyo3"
+version = "0.29.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cd274650b21d4bfc26a0a47587962c1edb425f69287324355cd040c3ea66071c"
+dependencies = [
+ "libc",
+ "once_cell",
+ "portable-atomic",
+ "pyo3-build-config",
+ "pyo3-ffi",
+ "pyo3-macros",
+]
+
+[[package]]
+name = "pyo3-build-config"
+version = "0.29.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c5e2a7d2f0d013342f295c048ad19237add5154a55b1c5a254c0ec93d4109078"
+dependencies = [
+ "target-lexicon",
+]
+
+[[package]]
+name = "pyo3-ffi"
+version = "0.29.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ca85c467da1bbc8d866eea5deff9cf29ea5f7785054a17da36e65bda9c05845b"
+dependencies = [
+ "libc",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "pyo3-macros"
+version = "0.29.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ac53762fd065daa3194dd09337a38bd793a188100fd1a9304c4ab312d901771"
+dependencies = [
+ "proc-macro2",
+ "pyo3-macros-backend",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "pyo3-macros-backend"
+version = "0.29.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4ca3a1557399783172dc5bf39cfca835157732532cba56b71d2292161e53b362"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.46"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dfbc457d0c7a0759a614551b11a6409e5951f6c7537be1f1b7682b9ae9230368"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.118"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1b9ae57f904213ebb649ce6895b8a66c66f0203b9319718f69a5612a065b1422"
+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.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "zova"
+version = "0.17.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4a8fb0a3a7ca0fef420a4c4e1bd31bb519e7bc697553f541e249163cf866ef56"
+dependencies = [
+ "zova-sys",
+]
+
+[[package]]
+name = "zova-python"
+version = "0.17.0"
+dependencies = [
+ "pyo3",
+ "zova",
+]
+
+[[package]]
+name = "zova-sys"
+version = "0.17.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4c11b4d0622a9a16ef3f75518face4a6425c70bd5c4e872612c8c231a0f915bf"

zova-0.17.0/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "zova-python"
+version = "0.17.0"
+edition = "2021"
+license = "MIT"
+description = "PyO3 extension for the Zova Python package."
+repository = "https://github.com/atasesli/zova"
+homepage = "https://github.com/atasesli/zova"
+readme = "README.md"
+
+[lib]
+name = "zova_python"
+crate-type = ["cdylib"]
+
+[dependencies]
+pyo3 = { version = "0.29.0", features = ["extension-module"] }
+zova_rust = { package = "zova", version = "0.17.0" }

zova-0.17.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ata Sesli
+
+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.

zova-0.17.0/PKG-INFO

@@ -0,0 +1,319 @@
+Metadata-Version: 2.4
+Name: zova
+Version: 0.17.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Database
+License-File: LICENSE
+Summary: SQLite-backed embedded database for records, objects, and vectors in one local file.
+Keywords: zova,sqlite,database,objects,vectors
+Home-Page: https://github.com/atasesli/zova
+Author: Ata Sesli
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/atasesli/zova
+Project-URL: Issues, https://github.com/atasesli/zova/issues
+Project-URL: Repository, https://github.com/atasesli/zova
+
+# Zova Python Bindings
+
+This package contains the source-first Python bindings for Zova.
+
+It is a PyO3/maturin extension backed by the safe Rust `zova` binding. It does
+not wrap the C ABI directly with `ctypes` or cffi. The native build still uses
+Zova's C ABI underneath through the Rust `zova-sys` crate, so Python gets the
+same records/objects/vectors foundation without reimplementing the ABI ownership
+rules.
+
+## Contents
+
+1. [How It Fits](#how-it-fits)
+2. [Install](#install)
+3. [Local Development](#local-development)
+4. [What It Covers](#what-it-covers)
+5. [Savepoints](#savepoints)
+6. [Operational Safety](#operational-safety)
+7. [Objects](#objects)
+8. [Vectors](#vectors)
+9. [SQL-Native Vector Search](#sql-native-vector-search)
+
+## How It Fits
+
+Python users import `zova`. The extension is built with PyO3 and reuses the
+safe Rust binding, which in turn links Zova's C ABI.
+
+```mermaid
+flowchart LR
+    App["Python app"]
+    PyPkg["zova Python package"]
+    PyO3["PyO3 extension"]
+    Rust["Rust zova crate"]
+    CABI["libzova_c.a"]
+    File["local .zova file"]
+
+    App --> PyPkg
+    PyPkg --> PyO3
+    PyO3 --> Rust
+    Rust --> CABI
+    CABI --> File
+```
+
+## Install
+
+After the Python package is published to PyPI:
+
+```sh
+python -m pip install zova
+```
+
+The v0.17 Python package is source-first. It builds the PyO3 extension locally
+through maturin and Cargo, and the Rust crates `zova` and `zova-sys` must be
+available on crates.io first. Users need Python 3.10 or newer, Rust/Cargo, Zig
+0.16.0 or newer, and a working C compiler/linker.
+
+No official platform wheel matrix is promised in v0.17.
+
+## Local Development
+
+From `bindings/python`:
+
+```sh
+uv run --isolated --with maturin --with pytest maturin develop
+uv run --isolated --with pytest python -m pytest
+```
+
+The native build uses maturin, Cargo, Zig, and the Rust `zova` crate. Users do
+not need to locate a shared C library manually.
+
+The Python API is pre-1.0 and may still change alongside the Rust binding.
+
+## What It Covers
+
+The Python package exposes database lifecycle, conversion, prepared SQL
+statements, transactions, explicit vacuum, backup/compact/restore, objects,
+streaming object writes, vectors, SQL-native vector search, context managers,
+and Zova status exceptions.
+
+One Python `Database` object owns one native handle. The native C ABI serializes
+calls on that handle, so one handle is safe but not parallel. Open additional
+database handles when an application needs independent concurrent connections;
+SQLite locking rules still apply across handles. PyO3 classes remain unsendable
+in this release even though the native C ABI serializes its own calls.
+
+Use `Database.open(path, read_only=True)` for read-only handles, and
+`Database.set_busy_timeout(milliseconds)` when an application wants SQLite to
+wait briefly on cross-handle contention. No nonzero timeout is installed by
+default.
+
+Use `Database.last_insert_rowid()`, `Database.changes()`,
+`Database.total_changes()`, and `Statement.column_name(index)` for normal
+application SQL record helpers. They do not expose or stabilize Zova's private
+`_zova_*` tables.
+
+## Savepoints
+
+Use explicit savepoints for partial rollback inside one database connection:
+
+```python
+with zova.Database.open("app.zova") as db:
+    db.begin_immediate()
+    db.savepoint("attach_file")
+    db.exec("insert into attachments(filename) values ('draft.txt')")
+    db.rollback_to_savepoint("attach_file")
+    db.release_savepoint("attach_file")
+    db.commit()
+```
+
+Savepoint names are strict ASCII identifiers: 1-64 bytes, first byte
+`[A-Za-z_]`, remaining bytes `[A-Za-z0-9_]`, and no case-insensitive `_zova_`
+prefix. `rollback_to_savepoint()` keeps the savepoint active;
+`release_savepoint()` removes it.
+An inner released savepoint can still be undone by rolling back an outer
+transaction or savepoint.
+
+Use `savepoint_context()` when you want rollback cleanup tied to a `with` block:
+
+```python
+with db.savepoint_context("attach_file") as scoped_db:
+    scoped_db.exec("insert into attachments(filename) values ('draft.txt')")
+```
+
+On normal exit the context releases the savepoint. On exception it rolls back,
+releases, and then re-raises the original exception when cleanup succeeds.
+
+## Operational Safety
+
+Use `backup_to()` for a faithful snapshot, `compact_to()` for a
+space-reclaiming copy, and `restore_backup()` to copy a backup into a new
+destination file. Destinations must be `.zova` paths and are never overwritten.
+
+```python
+with zova.Database.open("app.zova") as db:
+    db.backup_to("app.backup.zova")
+    db.compact_to("app.compact.zova")
+
+zova.restore_backup("app.backup.zova", "app.restored.zova")
+```
+
+By default, each operation verifies the destination after copying. Pass
+`verify=False` only when you will verify separately, for example with
+`zova check --deep`.
+
+Diagnostic recovery commands such as `zova doctor`, `zova salvage --dry-run`,
+and `zova salvage <source> <destination>` are CLI-first in the v0.16 line. The
+Python package does not expose typed doctor/salvage report APIs yet, and library
+code should not parse the human text output as a stable binding contract.
+
+## Objects
+
+The Python binding exposes Zova objects as content-addressed byte values while
+keeping application metadata in normal SQL tables.
+
+```python
+import zova
+
+with zova.Database.create("app.zova") as db:
+    db.exec(
+        "create table attachments("
+        "id integer primary key, "
+        "filename text not null, "
+        "object_id blob not null)"
+    )
+
+    object_id = db.put_object(b"hello from Zova")
+
+    with db.prepare("insert into attachments(filename, object_id) values (?1, ?2)") as stmt:
+        stmt.bind_text(1, "hello.txt")
+        stmt.bind_blob(2, bytes(object_id))
+        stmt.step()
+
+    assert db.read_object_range(object_id, 0, 5) == b"hello"
+```
+
+For large inputs, use `ObjectWriter` so the full object does not have to be held
+in memory by the caller:
+
+```python
+with db.object_writer() as writer:
+    writer.write(b"chunk one")
+    writer.write(b"chunk two")
+    object_id = writer.finish()
+```
+
+If a writer leaves the context without `finish()`, it is cancelled and any
+unreferenced chunks written by that writer are cleaned up. Writer operations
+follow Zova's object transaction policy and reject active user transactions.
+
+Loose chunks and assembly are also exposed for receive-side workflows:
+applications track transfer state in their own SQL tables, call
+`put_object_chunk()` for verified chunks, then call
+`assemble_object_from_chunks()` when the manifest is complete.
+
+## Vectors
+
+The Python binding exposes Zova vectors with the same model as the Rust binding:
+Zova stores numeric vectors in named collections, while application metadata
+stays in normal SQL tables.
+
+```python
+import zova
+
+with zova.Database.create("vectors.zova") as db:
+    db.exec(
+        "create table chunks("
+        "id text primary key, "
+        "document_id text not null, "
+        "text text not null, "
+        "vector_id text not null)"
+    )
+
+    db.create_vector_collection(
+        "chunks",
+        zova.VectorCollectionOptions(2, zova.VectorMetric.L2),
+    )
+    db.put_vectors(
+        "chunks",
+        [
+            zova.VectorInput("chunk:1", [0.0, 0.0]),
+            zova.VectorInput("chunk:2", [1.0, 0.0]),
+        ],
+    )
+
+    db.exec(
+        "insert into chunks(id, document_id, text, vector_id) values "
+        "('c1', 'doc-a', 'first chunk', 'chunk:1'), "
+        "('c2', 'doc-a', 'near chunk', 'chunk:2')"
+    )
+
+    results = db.search_vectors_in(
+        "chunks",
+        [0.0, 0.0],
+        ["chunk:1", "chunk:2"],
+        2,
+    )
+    for result in results:
+        with db.prepare("select text from chunks where vector_id = ?1") as stmt:
+            stmt.bind_text(1, result.id)
+            stmt.step()
+            print(result.id, result.distance, stmt.column_text(0))
+```
+
+Search is exact and lower distance is better. Candidate-filtered searches skip
+missing ids and deduplicate duplicate candidates. Search-by-id excludes the
+source vector. Threshold variants are inclusive, and dot-product thresholds may
+be negative because dot distance is `-dot_product`.
+
+Deleting a vector collection removes Zova's private vector rows only. User SQL
+metadata rows that reference vector ids are application-owned and remain in
+place.
+
+## SQL-Native Vector Search
+
+Zova registers SQL vector functions and the `zova_vector_search` virtual table
+on Zova database connections. Bind query vectors as little-endian `f32` blobs
+with `encode_f32_le()`:
+
+```python
+query = zova.encode_f32_le([0.0, 0.0])
+
+with db.prepare(
+    "select c.id, zova_vector_distance('chunks', c.vector_id, ?1) as distance "
+    "from chunks as c "
+    "where c.document_id = 'doc-a' "
+    "order by distance "
+    "limit 10"
+) as stmt:
+    stmt.bind_blob(1, query)
+```
+
+Row-to-row distances use `zova_vector_distance_by_id(collection, vector_id,
+source_vector_id)`. Collection-wide SQL search uses `zova_vector_search`:
+
+```python
+with db.prepare(
+    "select c.text, s.distance "
+    "from zova_vector_search as s "
+    "join chunks as c on c.vector_id = s.vector_id "
+    "where s.collection = 'chunks' "
+    "and s.query_vector = ?1 "
+    "and s.top_k = 10 "
+    "order by s.rank"
+) as stmt:
+    stmt.bind_blob(1, query)
+```
+
+Python's built-in `sqlite3` module opens an ordinary SQLite connection and does
+not automatically register Zova's SQL functions or virtual table. Use
+`zova.Database` for SQL-native vector search in this binding. A future SQLite
+loadable extension may make the SQL surface available to external SQLite
+connections.
+