zodish 0.3.0__tar.gz

zodish-0.3.0/.github/workflows/publish.yml

@@ -0,0 +1,142 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  verify-version:
+    name: Verify version metadata
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.14'
+      - name: Check manifest and release tag versions
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          REF_NAME: ${{ github.ref_name }}
+        run: |
+          python - <<'PY'
+          import os
+          import tomllib
+          from pathlib import Path
+
+          pyproject = tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))
+          cargo = tomllib.loads(Path("Cargo.toml").read_text(encoding="utf-8"))
+          project_version = pyproject["project"]["version"]
+          cargo_version = cargo["package"]["version"]
+          if project_version != cargo_version:
+              raise SystemExit(
+                  f"version mismatch: pyproject.toml {project_version}, "
+                  f"Cargo.toml {cargo_version}"
+              )
+          if os.environ["EVENT_NAME"] == "release":
+              tag_version = os.environ["REF_NAME"].removeprefix("v")
+              if tag_version != project_version:
+                  raise SystemExit(
+                      f"release tag {os.environ['REF_NAME']} does not match "
+                      f"package version {project_version}"
+                  )
+          print(f"version ok: {project_version}")
+          PY
+
+  build-sdist:
+    name: Build sdist
+    needs: verify-version
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.14'
+      - run: python -m pip install 'maturin>=1.15,<2'
+      - run: maturin sdist --out dist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist-sdist
+          path: dist/*.tar.gz
+
+  build-wheels:
+    name: Build wheels (${{ matrix.os }} / ${{ matrix.target }} / ${{ matrix.manylinux }})
+    needs: verify-version
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # manylinux (glibc)
+          - os: ubuntu-latest
+            target: x86_64
+            manylinux: auto
+            interpreter: python3.14
+          - os: ubuntu-latest
+            target: aarch64
+            manylinux: auto
+            interpreter: python3.14
+          # musllinux (Alpine / musl libc)
+          - os: ubuntu-latest
+            target: x86_64
+            manylinux: musllinux_1_2
+            interpreter: python3.14
+          - os: ubuntu-latest
+            target: aarch64
+            manylinux: musllinux_1_2
+            interpreter: python3.14
+          # macOS
+          - os: macos-latest
+            target: x86_64
+            manylinux: auto
+            interpreter: python3.14
+          - os: macos-latest
+            target: aarch64
+            manylinux: auto
+            interpreter: python3.14
+          # Windows
+          - os: windows-latest
+            target: x64
+            manylinux: auto
+            interpreter: python
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.14'
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          # abi3-py314: one stable-ABI wheel per platform covers Python 3.14+.
+          args: --release --locked --interpreter ${{ matrix.interpreter }} --out dist
+          manylinux: ${{ matrix.manylinux }}
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist-${{ matrix.os }}-${{ matrix.target }}-${{ matrix.manylinux }}
+          path: dist/*.whl
+
+  publish:
+    name: Publish to PyPI
+    needs: [build-sdist, build-wheels]
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: dist-*
+          merge-multiple: true
+          path: dist
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.14'
+      - name: Verify distribution artifacts
+        run: python scripts/verify_dist.py dist
+      - uses: pypa/gh-action-pypi-publish@release/v1

zodish-0.3.0/.github/workflows/tests.yml

@@ -0,0 +1,83 @@
+name: tests
+on: [push, pull_request]
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.14'
+      - run: python -m pip install --group dev --group benchmark
+      - run: ruff check .
+      - run: mypy
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ['3.14', '3.15']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+      - run: cargo fmt --check
+      - run: cargo clippy --locked -- -D warnings
+      - run: python -m pip install .
+      - run: python -m unittest discover -s tests -v
+      - run: python examples/quickstart.py
+      - run: python benchmarks/bench_parse.py --smoke
+      - run: python -m pip install --group benchmark
+      - run: python benchmarks/bench_compare.py --check-only
+      - name: Exercise benchmark worker argument forwarding
+        run: >-
+          python benchmarks/bench_compare.py --library pydantic
+          --scenario object_success --processes 1 --values 1
+          --warmups 1 --min-time 0.001
+  package:
+    name: package (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.14'
+      - uses: dtolnay/rust-toolchain@stable
+      - run: python -m pip install 'maturin>=1.15,<2'
+      - run: maturin build --release --locked --interpreter python --out dist
+      - run: maturin sdist --out dist
+      - run: python scripts/verify_dist.py dist
+      - name: Smoke-test the wheel
+        run: |
+          python -m pip install --no-index --no-deps --force-reinstall dist/*.whl
+          python examples/verify_native.py
+          python -m unittest discover -s tests -v
+          python examples/quickstart.py
+      - name: Smoke-test the sdist
+        run: |
+          python -m pip uninstall -y zodish
+          python -m pip install --no-index --no-deps --no-cache-dir --no-build-isolation --force-reinstall dist/*.tar.gz
+          python examples/verify_native.py
+          python -m unittest discover -s tests -v
+          python examples/quickstart.py
+      - uses: actions/setup-python@v5
+        if: runner.os == 'Linux'
+        with:
+          python-version: '3.15'
+      - name: Smoke-test the abi3 wheel on Python 3.15
+        if: runner.os == 'Linux'
+        run: |
+          python -m pip install --no-index --no-deps --force-reinstall dist/*.whl
+          python examples/verify_native.py
+          python -m unittest discover -s tests -v
+          python examples/quickstart.py

zodish-0.3.0/.gitignore

@@ -0,0 +1,21 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.mypy_cache/
+.ruff_cache/
+build/
+dist/
+target/
+*.so
+*.pyd
+*.dylib
+
+/.idea/
+/.agents/
+/.claude/
+/.codex/
+ai-agents-standards-v*
+.mcp.json
+AGENTS.md
+CLAUDE.md

zodish-0.3.0/CHANGELOG.md

@@ -0,0 +1,125 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-10-21
+
+### Changed
+
+- Arrays whose item schema is a primitive validator (string, integer, number,
+  boolean, none, or unknown) use a native fast path, and exact lists snapshot
+  through direct list iteration. A 1,000-integer parse improved from roughly
+  31 µs to 5.8 µs in the local release benchmark.
+- Lazy schema factories resolve once per lazy node per parse instead of once
+  per visit, using a compact per-parse cache. Factories are still invoked again
+  on subsequent parses.
+- Object traversal pre-reads declared field values without copying exact-shape
+  inputs, caches the unknown-key policy, and validates primitive fields without
+  constructing a path. Recursive trees improved from 18.8 µs to 9.0 µs in the
+  local release benchmark.
+- Failure construction is cheaper: `ValidationError` formats its combined
+  message lazily, and native failures retain a GC-aware native issue bundle
+  until `.issues` is read. The first access materializes and caches the public
+  `Issue` objects without copying params or running dataclass initialization.
+  Checks that only need success or failure, including `validate()`, avoid both
+  raw and Python issue conversion. Object failure improved from 2.77 µs to
+  1.05 µs in the local release benchmark; inspecting the materialized issues
+  takes 2.29 µs.
+- Constraint, literal, enum, and primitive type failures reuse native error
+  templates instead of rebuilding parameter dictionaries and messages. The
+  last-union branch improved from 1.17 µs to 0.69 µs locally.
+- Callback async guards fast-path common exact synchronous result types before
+  falling back to `inspect.isawaitable` and `inspect.isasyncgen`. Refinement
+  callbacks improved from 0.32 µs to 0.14 µs in the local benchmark.
+- Small array and tuple snapshots use inline storage for up to four items, and
+  lazy nodes check a last-resolved entry before scanning the per-parse cache.
+  Recursive trees improved from 9.2 µs to 9.0 µs locally.
+- Object parsing skips the unknown-key scan and temporary known-key map when
+  the input contains no keys outside the shape, including when optional fields
+  are absent. Object success improved from 0.53 µs to 0.38 µs in the local
+  release benchmark.
+
+### Added
+
+- `Schema.parse_json()`, `.safe_parse_json()`, and `.validate_json()` accept
+  `str`, `bytes`, or `bytearray` JSON input. A native fast path validates
+  JSON-compatible objects and arrays with primitive leaves, numeric bounds and
+  multiples, literals and enums, nullable/optional wrappers, optional object
+  fields, and string/array length constraints. Other schemas fall back to
+  standard JSON decoding and normal validation. Invalid JSON reports
+  `invalid_format` with a `position`.
+- CPython 3.15 support: the `abi3-py314` wheel runs on 3.15, CI covers 3.14 and
+  3.15, and the package metadata declares both versions.
+- Bidirectional codecs through `z.codec(input_schema, output_schema, *,
+  decode=..., encode=...)`, with `.decode()`/`.encode()`,
+  `.safe_decode()`/`.safe_encode()`, reverse validation through containers, and
+  JSON Schema input/output selection. One-way operations such as transforms,
+  refinements, coercions, defaults, catches, pipes, preprocessors, and lazy
+  schemas make encoding unavailable.
+- Built-in codecs: `z.codecs.iso_date()`, `iso_time()`, `iso_datetime()`,
+  `decimal()`, `json_text()`, `path()`, and `bytes_base64()` with standard or
+  URL-safe base64.
+- Dataclass codecs through `z.codecs.dataclass(Cls, fields=None)`, mapping
+  encoded dictionaries to dataclass instances. Field schemas are inferred from
+  common type annotations, including nested dataclasses, lists, records, fixed
+  tuples, optional fields, and unions, and may be overridden per field.
+  Recursive dataclass cycles are rejected. Dataclass defaults may be omitted
+  from input, and input/output-mode JSON Schema describe the encoded and decoded
+  object shapes respectively.
+- Public codec combinators: `z.codecs.array()`, `z.codecs.union()`,
+  `z.codecs.tuple()`, and codec `.record()`, `.optional()`, `.nullable()`,
+  `.nonoptional()`, `.nullish()` methods. Compound codecs now retain
+  output-side JSON Schema across nested dataclasses and containers.
+- Exclusive numeric comparisons (`.gt()`, `.gte()`, `.lt()`, `.lte()`), exact
+  integer and tolerant float `.multiple_of()` checks, string
+  `.starts_with()`/`.ends_with()`/`.includes()` predicates, and `.ipv6()`.
+- JSON Schema export for exclusive bounds, `multipleOf`, string predicate
+  patterns, and IPv6 formats, with multiple checks emitted through `allOf`.
+- Fixed-length tuple typing: `z.tuple()` infers precise output tuples for up to
+  four items; larger tuples and tuples with a rest schema return
+  `tuple[Any, ...]`.
+- Parse benchmarks covering successful and failing parses, a 1,000-element
+  array, union branch position, recursive schemas, and a refinement callback.
+- Packaging CI that builds the wheel and sdist on Ubuntu, macOS, and Windows,
+  verifies artifact contents and version agreement, and installs and smoke-tests
+  each artifact.
+
+## [0.2.0] - 2026-10-20
+
+### Added
+
+- Immutable, composable schemas for CPython 3.14+, with a Rust validation core
+  and a typed Python API.
+- Primitive schemas: `z.string()`, `z.number()`, `z.integer()`, `z.boolean()`,
+  `z.none()`, `z.unknown()`, and `z.instance_of()`.
+- String constraints and transforms (`.min()`, `.max()`, `.regex()`, `.email()`,
+  `.trim()`, `.lower()`, `.upper()`) and numeric constraints (`.min()`, `.max()`,
+  `.positive()`, `.nonnegative()`, `.int()`).
+- Object schemas with `.strict()`, `.strip()`, `.passthrough()`, `.extend()`,
+  `.pick()`, `.omit()`, and `.partial()`, plus array, tuple, and record schemas.
+- Choice schemas: `z.literal()`, `z.enum()`, `z.union()`, and `schema.or_()`.
+- Composition through `.optional()`, `.nullable()`, `.nullish()`, `.default()`,
+  `.default_factory()`, `.refine()`, `.transform()`, `.pipe()`,
+  `z.preprocess()`, and `z.lazy()` for recursive schemas.
+- `parse()` and `safe_parse()` with native-only evaluation, aggregated issues,
+  nested error paths, union branch details, and JSON-serializable
+  `ValidationError.to_dict()` output.
+- Arbitrary-precision integer comparisons for bounds and literals, with
+  type-exact literals and no implicit coercion.
+- `Schema[Out, In]` typing, a `py.typed` marker, and strict mypy coverage.
+- Maturin wheel and sdist builds for the CPython 3.14+ stable ABI, with no
+  third-party runtime dependencies.
+
+### Fixed
+
+- Async callbacks, and callbacks returning awaitables, now raise `TypeError`
+  instead of being accepted as valid refinement results.
+- Defaults are typed and validated as input values, matching runtime behavior
+  after a transform.
+- A callback raising `ValidationError([])` now produces a `custom` issue
+  instead of being treated as success.

zodish-0.3.0/Cargo.lock

@@ -0,0 +1,193 @@
+# 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 = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "libc"
+version = "0.2.191"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a"
+
+[[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",
+]
+
+[[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 = "zmij"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"
+
+[[package]]
+name = "zodish-core"
+version = "0.3.0"
+dependencies = [
+ "pyo3",
+ "serde_json",
+]

zodish-0.3.0/Cargo.toml

@@ -0,0 +1,23 @@
+[package]
+name = "zodish-core"
+version = "0.3.0"
+edition = "2024"
+rust-version = "1.85"
+license = "MIT"
+description = "Rust validation engine for the Zodish Python package"
+authors = ["Aleksandr Pavlov <ckidoz@gmail.com>"]
+repository = "https://github.com/kidoz/zodish"
+readme = "README.md"
+
+[lib]
+name = "_native"
+crate-type = ["cdylib"]
+path = "rust/lib.rs"
+
+[dependencies]
+pyo3 = { version = "=0.30.1", features = ["abi3-py314"] }
+serde_json = "1.0"
+
+[profile.release]
+lto = "thin"
+codegen-units = 1

zodish-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aleksandr Pavlov <ckidoz@gmail.com>
+
+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.