json-atom 0.1.0__tar.gz

json_atom-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --python ${{ matrix.python-version }}
+
+      - name: Lint
+        run: uv run ruff check src/
+
+      - name: Type check
+        run: uv run mypy src/
+
+      - name: Test
+        run: uv run pytest tests/ -q --tb=short
+
+      - name: Test with coverage
+        run: uv run pytest tests/ --cov=json_atom --cov-report=term-missing --cov-fail-under=90

json_atom-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,71 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Run tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        run: uv sync --python 3.12
+
+      - name: Lint
+        run: uv run ruff check src/
+
+      - name: Type check
+        run: uv run mypy src/
+
+      - name: Test
+        run: uv run pytest tests/ -q --tb=short
+
+  build:
+    name: Build distribution
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Build wheel and sdist
+        run: uv build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/json-atom
+    permissions:
+      id-token: write  # required for Trusted Publishing (OIDC)
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

json_atom-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+*.egg
+.vscode/
+.playwright-mcp/
+uv.lock
+.DS_Store
+*.DS_Store

json_atom-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,25 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.14.1
+    hooks:
+      - id: mypy
+        additional_dependencies: []
+        args: [--strict]
+        pass_filenames: false
+        entry: mypy src/
+
+  - repo: local
+    hooks:
+      - id: pytest
+        name: pytest
+        entry: uv run pytest tests/ -q
+        language: system
+        pass_filenames: false
+        always_run: true

json_atom-0.1.0/CLAUDE.md

@@ -0,0 +1,78 @@
+# CLAUDE.md — Developer Guide for json-atom-py
+
+## Build & Test Commands
+
+```bash
+uv sync                          # Install dependencies
+uv run pytest tests/             # Run all tests
+uv run pytest tests/ -v          # Verbose output
+uv run pytest tests/ --cov=json_atom  # With coverage
+uv run ruff check src/           # Lint
+uv run mypy src/                 # Type check
+uv run python examples/keyed_arrays.py  # Run an example
+uv build                         # Build wheel + sdist
+```
+
+## Project Structure
+
+```
+src/json_atom/
+    __init__.py       # Public API re-exports and __all__
+    errors.py         # Exception hierarchy (JsonDeltaError → PathError, ApplyError, etc.)
+    models.py         # PathSegment dataclasses, ValidationResult, ChangeType, ComparisonNode, Delta/Operation
+    _utils.py         # Internal helpers: json_equal, json_type_of
+    _identity.py      # Shared identity resolution (IdentityResolver, resolve_identity, extract_identity)
+    path.py           # Path parser/builder + describe_path, resolve_path
+    validate.py       # Structural validation (validate_delta)
+    apply.py          # Delta application (apply_delta)
+    invert.py         # Delta inversion (invert_delta, revert_delta)
+    diff.py           # Delta computation (diff_delta) — callable keys, regex routing, exclude_paths
+    compare.py        # Enriched comparison tree (compare) — visual diff rendering
+    json_patch.py     # JSON Patch (RFC 6902) interop: to_json_patch, from_json_patch
+    py.typed          # PEP 561 marker
+
+tests/
+    conftest.py       # Shared helpers: load_fixture, deep_clone
+    fixtures/         # Conformance fixtures from json-atom-format repo
+    test_models.py    # PathSegment, ValidationResult, Delta/Operation types
+    test_utils.py     # json_equal edge cases (bool vs int, int vs float)
+    test_path.py      # Path parser/builder, describe_path, resolve_path
+    test_validate.py  # Delta validation
+    test_apply.py     # Delta application + Level 1 conformance
+    test_invert.py    # Inversion + revert round-trips
+    test_extensions.py  # Extension property preservation
+    test_conformance.py # Level 1 + Level 2 conformance fixtures
+    test_diff.py      # Diff computation + all identity models + callable/regex/exclude_paths
+    test_compare.py   # Enriched comparison tree tests
+    test_cross_validation.py # Cross-validation with json-diff-ts
+    test_edge_cases.py  # Cross-module edge cases
+    test_json_patch.py  # JSON Patch (RFC 6902) interop
+    test_pydantic.py    # Pydantic v2 integration (conditional on pydantic)
+```
+
+## Architecture
+
+- **Zero runtime dependencies** — uses only stdlib (re, copy, math, dataclasses)
+- **Delta/Operation are dict subclasses** — typed property access (`delta.operations`, `op.path`) + full dict compat (`json.dumps`, `[]` access, extensions)
+- **Extension properties** accessible as attributes (`op.x_editor`) or dict syntax (`op["x_editor"]`), via `__getattr__` fallback. `op.extensions` returns all non-spec keys
+- **Pydantic v2 native** — `__get_pydantic_core_schema__` on both classes, zero runtime dependency on pydantic. Use as `BaseModel` fields without `arbitrary_types_allowed`
+- **Cached properties** — `op.segments` and `op.filter_values` are `cached_property` (parsed once per instance)
+- **Path segments are frozen dataclasses** — immutable, hashable, printable
+- **apply_delta mutates in place** — always use the return value (root ops return new objects)
+- **json_equal handles Python's bool⊂int** — `True != 1` in JSON semantics
+
+## Spec Compliance
+
+- **Specification**: [JSON Atom v0](https://github.com/ltwlf/json-atom-format/blob/main/spec/v0.md)
+- **Conformance**: Level 2 (Apply + Reversible) — passes all fixtures
+- **Spec is source of truth** — when spec and TypeScript reference diverge, follow the spec
+- **Spec-faithful divergence from TS**: digit-after-dot (`$.items.0`) is a PathError per spec grammar
+- **remove without oldValue**: valid per spec (OPTIONAL), unlike TS which requires it
+
+## Coding Conventions
+
+- Python 3.12+ — uses `type` statement, `X | Y` union syntax, `@dataclass(slots=True)`
+- Strict mypy on library source (`uv run mypy src/`; tests are not strict-checked)
+- Ruff for linting (line-length=120)
+- All public functions have docstrings
+- Tests organized by module with descriptive class names

json_atom-0.1.0/LICENSE

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