corvid-python 0.3.3__tar.gz

corvid_python-0.3.3/.cargo/config.toml

@@ -0,0 +1,6 @@
+# Fetch git dependencies through the git CLI: this machine (and some
+# CI images) rewrite https://github.com/* to ssh://git@github.com/* and
+# cargo's built-in libgit2 fetcher cannot use the ssh-agent/keychain
+# the CLI uses. Harmless elsewhere.
+[net]
+git-fetch-with-cli = true

corvid_python-0.3.3/.github/workflows/ci.yml

@@ -0,0 +1,103 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+defaults:
+  run:
+    # bash everywhere: wheel globs and paths behave the same on windows.
+    shell: bash
+
+jobs:
+  surface-gate:
+    # docs/SURFACE.tsv vs the engine's surface list at the PINNED tag:
+    # every engine construct mapped (binding api + proving test) or N/A
+    # with a reason; N/A count pinned to the committed baseline.
+    name: surface gate (SURFACE.tsv vs pinned engine)
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v7
+      - name: Resolve docs/SURFACE.tsv against the pinned engine surface
+        run: ./scripts/surface-gate.sh
+
+  lint:
+    name: fmt + clippy
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo fmt --all -- --check
+      - run: cargo clippy --all-targets -- -D warnings
+
+  test:
+    name: golden suite — ${{ matrix.target }} / py${{ matrix.python }}
+    needs: lint
+    strategy:
+      fail-fast: false
+      matrix:
+        # The wheel platform matrix: linux-x64/arm64, macos-arm64,
+        # windows-x64 (macos-x64 retired with GitHub's macos-13 runners —
+        # no x86_64-darwin runner exists, same as corvid-node's matrix)
+        # × every supported minor line, latest first (toolchain policy:
+        # floor 3.11, CI covers latest + every previous line).
+        target: [linux-x64, linux-arm64, macos-arm64, windows-x64]
+        python: ["3.14", "3.13", "3.12", "3.11"]
+        include:
+          - { target: linux-x64, runs-on: ubuntu-latest }
+          - { target: linux-arm64, runs-on: ubuntu-24.04-arm }
+          - { target: macos-arm64, runs-on: macos-latest }
+          - { target: windows-x64, runs-on: windows-latest }
+    runs-on: ${{ matrix.runs-on }}
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install --upgrade "maturin>=1.5,<2.0" pytest
+      - name: Build the extension (debug wheel — speed; release is the package job)
+        run: maturin build --out wheels
+      - run: python -m pip install wheels/corvid_python-*.whl
+      - name: Golden suite (267 fixture lines through the OOP surface)
+        run: python -m pytest tests -q
+      - name: Examples tour (six runnable programs, deterministic output)
+        env:
+          # CJK output against the Windows console encoding
+          PYTHONIOENCODING: utf-8
+        run: |
+          for ex in quickstart hybrid vector_index text_search graph geo; do
+            echo "== examples/${ex}.py =="
+            python "examples/${ex}.py"
+          done
+
+  package:
+    name: maturin build smoke
+    needs: lint
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.14"
+      - run: python -m pip install --upgrade "maturin>=1.5,<2.0" pytest
+      - name: Release wheel build (the publish artifact shape)
+        run: maturin build --release --out dist
+      - run: python -m pip install dist/corvid_python-*.whl
+      - run: python -c "import corvid; assert corvid.ffi_version() == 1"
+      - run: python -m pytest tests -q

corvid_python-0.3.3/.github/workflows/release.yml

@@ -0,0 +1,158 @@
+name: Release PyPI
+
+# The corvid-python publish flow: a tag push (vX.Y.Z — must equal
+# pyproject.toml's [project] version) builds the SAME wheel matrix ci.yml
+# covers (linux x64/arm64, macos arm64, windows x64 — abi3 cp311, so one
+# wheel per platform covers every Python >= 3.11) plus the sdist on the
+# linux-x64 leg; ONE publish job then collects the artifacts and uploads
+# them with `maturin upload --skip-existing`.
+#
+# Authentication is PyPI TRUSTED PUBLISHING (OIDC): the publish job grants
+# only `id-token: write`; maturin detects the GitHub OIDC environment and
+# exchanges the short-lived token for an upload credential — NO token
+# secret is stored in the repo. One-time registration on pypi.org
+# (account -> Publishing -> "Add a new pending publisher", see
+# scripts/bindings/README.md in the engine repo):
+#   PyPI project name: corvid-python
+#   Owner:             corvid-db
+#   Repository:        corvid-python
+#   Workflow name:     release.yml
+#   Environment name:  (leave blank — omitted here on purpose; the workflow
+#                      runs without a GitHub environment, and one can be
+#                      added later by registering it on both sides)
+# (NB: maturin's upload/publish commands print a deprecation warning that
+# points at uv publish — harmless; the upload path, OIDC included, is
+# unchanged.)
+#
+# API-TOKEN FALLBACK instead of trusted publishing (only if preferred):
+# create a token at https://pypi.org/manage/account/token/ and:
+#   gh secret set PYPI_API_TOKEN -R corvid-db/corvid-python
+# then give the upload step below:
+#   env:
+#     MATURIN_PYPI_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+# (and drop id-token: write from the job).
+#
+# Dry-run (no publishing, e.g. after touching this file): dispatch the
+# workflow manually with `dry_run` checked — the whole wheel matrix, the
+# sdist, the artifact merge, and the version verification all run; the
+# upload step is skipped.
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: Build wheels + sdist + verify, but skip the PyPI upload
+        type: boolean
+        default: false
+
+permissions: {}
+
+# Never cancel mid-run: a re-pushed tag queues behind the in-flight publish.
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: build ${{ matrix.target }}${{ matrix.sdist && ' + sdist' || '' }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # The wheel platform matrix mirrors ci.yml's test matrix exactly.
+        # macos-x64 retired with GitHub's macos-13 runners — no x86_64
+        # darwin runner exists (same as corvid-node's matrix).
+        include:
+          - { target: linux-x64, runs-on: ubuntu-latest, sdist: true }
+          - { target: linux-arm64, runs-on: ubuntu-24.04-arm, sdist: false }
+          - { target: macos-arm64, runs-on: macos-latest, sdist: false }
+          - { target: windows-x64, runs-on: windows-latest, sdist: false }
+    runs-on: ${{ matrix.runs-on }}
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v7
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+        with:
+          key: ${{ matrix.target }}
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.14"
+      - run: python -m pip install --upgrade "maturin>=1.5,<2.0"
+      - name: Build the release wheel (the publish artifact shape)
+        run: maturin build --release --out dist
+      - name: Build the sdist (one leg only — PyPI wants a single source tarball)
+        if: matrix.sdist == true
+        run: maturin sdist --out dist
+      - name: Upload distributions as workflow artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist-${{ matrix.target }}
+          path: dist/*
+          if-no-files-found: error
+
+  publish:
+    name: collect + upload to PyPI (trusted publishing)
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    # Must match the pending publisher's environment field on pypi.org
+    # (the standard PyPI guide registers the environment as "pypi").
+    environment: pypi
+    permissions:
+      contents: read
+      # PyPI trusted publishing (OIDC): the ONLY credential this job needs.
+      id-token: write
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.14"
+      - run: python -m pip install --upgrade "maturin>=1.5,<2.0"
+      - name: Tag must match the pyproject.toml version
+        run: |
+          VERSION=$(awk '/^\[project\]/{f=1;next} /^\[/{f=0} f && /^version = /{gsub(/[";]/,"",$3); print $3; exit}' pyproject.toml)
+          if [ -z "$VERSION" ]; then
+            echo "::error::version not found in pyproject.toml [project]"
+            exit 1
+          fi
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            # no tag context on dispatch; the equality is enforced on tag pushes
+            echo "dispatch (dry_run=${{ inputs.dry_run }}): pyproject version ${VERSION}"
+          else
+            TAG="${GITHUB_REF_NAME#v}"
+            echo "tag: ${GITHUB_REF_NAME} (version part: ${TAG}), pyproject version: ${VERSION}"
+            if [ "$TAG" != "$VERSION" ]; then
+              echo "::error::tag ${GITHUB_REF_NAME} does not match pyproject version ${VERSION}"
+              exit 1
+            fi
+          fi
+      - name: Download every matrix distribution
+        uses: actions/download-artifact@v4
+        with:
+          pattern: dist-*
+          path: dist
+          merge-multiple: true
+      - name: Inventory (the exact upload set)
+        run: |
+          ls -l dist/
+          echo "wheels: $(find dist -name '*.whl' | wc -l | tr -d ' '), sdists: $(find dist -name '*.tar.gz' | wc -l | tr -d ' ')"
+      - name: "dry-run: upload skipped"
+        if: inputs.dry_run == true
+        run: >
+          echo "dry-run: upload skipped — wheel matrix, sdist, artifact
+          merge, and version verification all ran; nothing uploaded."
+      # maturin upload with no MATURIN_PYPI_TOKEN/username configured and the
+      # OIDC env vars present (id-token: write) authenticates via trusted
+      # publishing. --skip-existing keeps re-runs of an already-uploaded file
+      # from failing the job (per-file idempotence).
+      - name: Upload to PyPI
+        if: inputs.dry_run != true
+        run: maturin upload --skip-existing dist/*
+      - name: Verify the publish (pypi.org JSON API)
+        if: inputs.dry_run != true
+        run: |
+          VERSION=$(awk '/^\[project\]/{f=1;next} /^\[/{f=0} f && /^version = /{gsub(/[";]/,"",$3); print $3; exit}' pyproject.toml)
+          curl -sSf "https://pypi.org/pypi/corvid-python/$VERSION/json" \
+            | jq -r '"corvid-python " + .info.version + " live: " + .info.release_url'

corvid_python-0.3.3/.gitignore

@@ -0,0 +1,24 @@
+# Rust
+/target
+Cargo.lock.orig
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.venv3*/
+venv/
+build/
+dist/
+
+# Packaging (wheels are built per platform by the CI matrix, not git)
+*.so
+*.dylib
+*.dll
+python/corvid/_native.*
+
+# test scratch
+tests/work/
+.pytest_cache/
+wheels/

corvid_python-0.3.3/Cargo.lock

@@ -0,0 +1,183 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "corvid-db"
+version = "0.3.2"
+source = "git+https://github.com/corvid-db/corvid.git?tag=v0.3.3#b726ac5a1ebace9f94dc12007a4e06927241cf4c"
+dependencies = [
+ "redb",
+ "thiserror",
+]
+
+[[package]]
+name = "corvid-python"
+version = "0.1.0"
+dependencies = [
+ "corvid-db",
+ "pyo3",
+ "redb",
+]
+
+[[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.189"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
+
+[[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.29.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4688ddedf473e32662b9b067670129a8afb8c18e351482c70d62ba4a88171e8b"
+dependencies = [
+ "libc",
+ "once_cell",
+ "portable-atomic",
+ "pyo3-build-config",
+ "pyo3-ffi",
+ "pyo3-macros",
+]
+
+[[package]]
+name = "pyo3-build-config"
+version = "0.29.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f41027e41b4bd03f6e60f9f417fe24a6341a6bb744edd62b6f709f2a52ea30e9"
+dependencies = [
+ "target-lexicon",
+]
+
+[[package]]
+name = "pyo3-ffi"
+version = "0.29.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e591a95526fead067432c3b3a33fc74770b87b1e04e73671090d9c2055a2b327"
+dependencies = [
+ "libc",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "pyo3-macros"
+version = "0.29.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "73225868fc1cd84eef2c3c230ddb91273bf1de46aeb8a4248da76d32a0924a1c"
+dependencies = [
+ "proc-macro2",
+ "pyo3-macros-backend",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "pyo3-macros-backend"
+version = "0.29.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "571575aa3749fa6216757dd47d2a3e7ef360f329a40f0666a9fbd14889024952"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "redb"
+version = "4.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "de6c3b63e007e90ce536ec2ae4690826136a20ec8dbbbb400daef1bb999d2e36"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "syn"
+version = "3.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6275cddf4610d1775e6d1fe9469b2e77d0f39fd98fb7450901b821e0c53649f"
+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 = "thiserror"
+version = "2.0.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ec86235f5fcc2a73650310756d2ac5b138a5780bbbdfae3eeccec992c435ba4f"
+dependencies = [
+ "thiserror-impl",
+]
+
+[[package]]
+name = "thiserror-impl"
+version = "2.0.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bc04cd3e1236dd4a98afca4569f2deb3f120e5422a4023be2cb683f8486292af"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.4",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"

corvid_python-0.3.3/Cargo.toml

@@ -0,0 +1,46 @@
+[package]
+name = "corvid-python"
+version = "0.1.0"
+edition = "2021"
+rust-version = "1.88"
+license = "MIT"
+description = "Python binding for the corvid embedded database — the engine compiled in via pyo3, exposed as idiomatic OOP"
+repository = "https://github.com/corvid-db/corvid-python"
+keywords = ["database", "embedded", "vector", "search", "python"]
+categories = ["database-implementations"]
+readme = "README.md"
+
+# The extension module Python imports as `corvid._native` (see
+# [tool.maturin] in pyproject.toml; the #[pymodule] fn and the lib name
+# must match the last component of the module name).
+[lib]
+name = "_native"
+crate-type = ["cdylib"]
+
+[dependencies]
+pyo3 = { version = "0.29", features = ["abi3-py311"] }
+
+# The engine, pinned to the exact release tag (docs/PLAN.md §2: the
+# binding pins exact engine tags; the engine PACKAGE is corvid-db —
+# bare `corvid` is an unrelated crates.io crate — its LIB ident is
+# corvid, so `use corvid::…` is unchanged).
+corvid-db = { git = "https://github.com/corvid-db/corvid.git", tag = "v0.3.3" }
+
+[dev-dependencies]
+# Test-only: the variant-inventory snapshot test (src/error.rs)
+# constructs one instance of every engine error to pin the code
+# mapping; six of the eighteen variants wrap redb's passthrough error
+# types, and redb's public error enums are their only constructors.
+# Same requirement line the engine's workspace uses — one resolution
+# with the git dep (Cargo.lock unifies both to a single redb).
+redb = "4.1"
+
+# `extension-module` is enabled only when building the wheel (pyproject
+# [tool.maturin] features), so `cargo clippy`/`cargo check` still link
+# libpython and see the full API surface.
+[features]
+extension-module = ["pyo3/extension-module"]
+
+[profile.release]
+lto = true
+strip = "symbols"

corvid_python-0.3.3/LICENSE

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