json-source-edit 0.1.0__tar.gz → 0.2.0__tar.gz

{json_source_edit-0.1.0/src/json_source_edit.egg-info → json_source_edit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: json-source-edit
-Version: 0.1.0
+Version: 0.2.0
 Summary: Surgical, byte-preserving JSON editing — change only what you intend to change.
 Author: Jérémie Lumbroso
 License: MIT
@@ -62,14 +62,12 @@ everything else on the reel undisturbed.
 
 ## Install
 
-Not yet on PyPI (see [Status](#status) below). Until then:
-
 ```bash
-git clone https://github.com/jlumbroso/json-source-edit
-cd json-source-edit
-pip install -e .
+pip install json-source-edit
 ```
 
+(Or clone the repo and `pip install -e .` for local development.)
+
 ## Usage
 
 ```python
@@ -121,12 +119,13 @@ it: `get_value`, `get_modifications`, and `preview_diff`.
 |---|---|
 | `replace` | Supported — any path, any depth |
 | `remove` | Supported — array elements and object properties, any depth, except the document root itself (structurally undefined: the root has no parent container to apply a comma/whitespace rule against) |
-| `add`, `move`, `copy`, `test` | Not implemented — raise `NotImplementedError` |
+| `test` | Supported — not a text edit, an assertion. Evaluated against the document as it stood before this batch's own operations (not a naive sequential reading of RFC 6902 — see the docstring on `operations.Test`), with type-strict comparison (`1` does not test-equal `1.0` or `true`) |
+| `add`, `move`, `copy` | Not implemented — raise `NotImplementedError`. Planned next (see `CHANGELOG.md`) |
 
-Multiple `replace`/`remove` calls batch correctly against the same original
-document — every path resolves in original-document coordinates regardless
-of what else is in the batch, so edit order doesn't matter and one deletion
-can't corrupt another edit's position.
+Multiple `replace`/`remove`/`test` calls batch correctly against the same
+original document — every path resolves in original-document coordinates
+regardless of what else is in the batch, so edit order doesn't matter and
+one deletion can't corrupt another edit's position.
 
 ## Benchmark (v0)
 
@@ -174,10 +173,10 @@ make a package like this one feasible to write at all.
 
 ## Status
 
-Pre-release. 187 tests, 100% line coverage. Not yet on PyPI — CI is scaffolded
-(GitHub Actions test matrix, Python 3.8–3.13) but the publish workflow is
-deliberately inert pending the repo owner's two-step activation (see
-`.github/workflows/publish.yml`).
+Published: [pypi.org/project/json-source-edit](https://pypi.org/project/json-source-edit/).
+`pip install json-source-edit`. 203 tests, 100% line coverage. See
+`CHANGELOG.md` for release history and the Scope table above for what's
+implemented.
 
 ## License
 

{json_source_edit-0.1.0 → json_source_edit-0.2.0}/README.md

@@ -33,14 +33,12 @@ everything else on the reel undisturbed.
 
 ## Install
 
-Not yet on PyPI (see [Status](#status) below). Until then:
-
 ```bash
-git clone https://github.com/jlumbroso/json-source-edit
-cd json-source-edit
-pip install -e .
+pip install json-source-edit
 ```
 
+(Or clone the repo and `pip install -e .` for local development.)
+
 ## Usage
 
 ```python
@@ -92,12 +90,13 @@ it: `get_value`, `get_modifications`, and `preview_diff`.
 |---|---|
 | `replace` | Supported — any path, any depth |
 | `remove` | Supported — array elements and object properties, any depth, except the document root itself (structurally undefined: the root has no parent container to apply a comma/whitespace rule against) |
-| `add`, `move`, `copy`, `test` | Not implemented — raise `NotImplementedError` |
+| `test` | Supported — not a text edit, an assertion. Evaluated against the document as it stood before this batch's own operations (not a naive sequential reading of RFC 6902 — see the docstring on `operations.Test`), with type-strict comparison (`1` does not test-equal `1.0` or `true`) |
+| `add`, `move`, `copy` | Not implemented — raise `NotImplementedError`. Planned next (see `CHANGELOG.md`) |
 
-Multiple `replace`/`remove` calls batch correctly against the same original
-document — every path resolves in original-document coordinates regardless
-of what else is in the batch, so edit order doesn't matter and one deletion
-can't corrupt another edit's position.
+Multiple `replace`/`remove`/`test` calls batch correctly against the same
+original document — every path resolves in original-document coordinates
+regardless of what else is in the batch, so edit order doesn't matter and
+one deletion can't corrupt another edit's position.
 
 ## Benchmark (v0)
 
@@ -145,10 +144,10 @@ make a package like this one feasible to write at all.
 
 ## Status
 
-Pre-release. 187 tests, 100% line coverage. Not yet on PyPI — CI is scaffolded
-(GitHub Actions test matrix, Python 3.8–3.13) but the publish workflow is
-deliberately inert pending the repo owner's two-step activation (see
-`.github/workflows/publish.yml`).
+Published: [pypi.org/project/json-source-edit](https://pypi.org/project/json-source-edit/).
+`pip install json-source-edit`. 203 tests, 100% line coverage. See
+`CHANGELOG.md` for release history and the Scope table above for what's
+implemented.
 
 ## License
 

{json_source_edit-0.1.0 → json_source_edit-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "json-source-edit"
-version = "0.1.0"
+version = "0.2.0"
 description = "Surgical, byte-preserving JSON editing — change only what you intend to change."
 authors = [{name = "Jérémie Lumbroso"}]
 readme = "README.md"

{json_source_edit-0.1.0 → json_source_edit-0.2.0}/src/json_source_edit/__init__.py

@@ -5,12 +5,13 @@ byte-for-byte." See ADR-0013 in the parent codetour-cli project
 (``docs/adr/0013-format-preserving-json-editing.md``) for the design.
 """
 from .editor import JSONEditor, Modification
-from .operations import UnsupportedRemovePath
+from .operations import TestOperationFailed, UnsupportedRemovePath
 from .validator import SemanticValidationError
 
 __all__ = [
     "JSONEditor",
     "Modification",
     "UnsupportedRemovePath",
+    "TestOperationFailed",
     "SemanticValidationError",
 ]

{json_source_edit-0.1.0 → json_source_edit-0.2.0}/src/json_source_edit/editor.py

@@ -16,7 +16,7 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional, Union
 
 from .algorithm import apply_edits, coalesce_deletions, strip_orphaned_trailing_commas
-from .operations import Operation, Remove, Replace, resolve_path
+from .operations import Operation, Remove, Replace, Test, resolve_path
 from .source_map import SourceMap
 from .validator import SemanticValidationError, validate_semantic_postconditions
 from .source_map import generate as generate_source_map
@@ -90,6 +90,17 @@ class JSONEditor:
         self.operations.append(Remove(path))
         self.modifications.append(Modification("remove", path, old_value, None))
 
+    def test(self, path: str, value: Any) -> None:
+        """Record an assertion that ``path`` currently equals ``value``
+        (does not apply yet). Evaluated at compile time against the
+        pristine, pre-batch parse — see ``operations.Test`` for the full
+        semantics and the type-strict comparison rule. Raises no
+        ``Modification``: a passing test doesn't change the document, and
+        ``get_modifications()``'s audit trail is specifically about what
+        changed.
+        """
+        self.operations.append(Test(path, value))
+
     # Backwards-compatible aliases matching the ADR's original API.
     def set_value(self, path: str, value: Any) -> None:
         """Alias for :meth:`replace`."""
@@ -147,6 +158,9 @@ class JSONEditor:
                 surgical edit.
             operations.UnsupportedRemovePath: if any recorded ``remove()``
                 targets an object-property path (Round 4 §2d).
+            operations.TestOperationFailed: if any recorded ``test()``'s
+                expected value doesn't match — raised before any edit in
+                the batch is applied, so nothing partial ever lands.
             ValueError: if two edits overlap after coalescing.
         """
         edits = self._compile_edits()

{json_source_edit-0.1.0 → json_source_edit-0.2.0}/src/json_source_edit/operations.py

@@ -37,6 +37,21 @@ class UnsupportedRemovePath(NotImplementedError):
     """
 
 
+class TestOperationFailed(Exception):
+    """Raised when a ``Test`` operation's expected value doesn't match the
+    document — JSON Patch ``test`` semantics: a failing test aborts the
+    whole batch. Raised during ``compile()``, which runs entirely before
+    ``apply_edits()`` ever splices text, so a failing test guarantees
+    nothing in the batch — not even edits queued before it — gets applied.
+
+    ``__test__ = False``: same reason as ``Test`` itself — the name starts
+    with "Test", and pytest's collector would otherwise try (and fail) to
+    treat this exception class as a test class.
+    """
+
+    __test__ = False
+
+
 def calculate_deletion_range(path: str, entry, parsed: Any, original_text: str) -> "tuple[int, int]":
     """Compute the deletion range for a Remove, for either an array element
     or an object property.
@@ -191,14 +206,49 @@ class Copy(Operation):
 
 @dataclass
 class Test(Operation):
-    """Test operation (JSON Patch ``test``) — not yet implemented.
+    """Test operation (JSON Patch ``test``): assert the value at ``path``
+    equals ``value``. Not a text edit — contributes no ``Edit`` objects on
+    success; raises ``TestOperationFailed`` on mismatch.
 
     Named ``Test`` to match JSON Patch's own vocabulary, not a pytest test
     class; ``__test__ = False`` tells pytest's collector to leave it alone.
+
+    **Evaluated against the pristine, pre-batch parse** (Round 4 §1's
+    coordinate-frame contract — the same rule ``Replace``/``Remove`` follow),
+    not against the effect of any earlier operation in the same batch. This
+    is a real, deliberate deviation from a naive reading of RFC 6902's
+    sequential-application model, where a `test` following a `replace` on
+    the same path would see the replace's effect. Batching several
+    operations in this package works *because* every operation resolves
+    independently against fixed original-document coordinates — extending
+    that same guarantee to ``Test`` keeps the whole batch model coherent,
+    at the cost of not supporting "test the value my own batch just set."
+    Call ``apply()``/``save()`` once per patch if you need that.
+
+    **Comparison is type-strict**, not Python's own loose ``==``: ``1`` does
+    not test-equal ``1.0``, and ``true`` does not test-equal ``1`` — Python's
+    ``bool`` being an ``int`` subclass would otherwise make
+    ``test(path, True)`` silently pass against a stored ``1``. A package
+    whose whole purpose is preserving a document's exact original
+    representation should not blur exactly this distinction in the one
+    operation whose entire job is comparison.
     """
 
     __test__ = False
     value: Any
 
     def compile(self, source_map: SourceMap, parsed: Any, original_text: str) -> List[Edit]:
-        raise NotImplementedError("Test operation not yet supported")
+        try:
+            actual = resolve_path(parsed, self.path)
+        except (KeyError, IndexError, ValueError):
+            raise TestOperationFailed(
+                f"Test on {self.path!r} failed: path does not exist in the document."
+            ) from None
+        if type(actual) is not type(self.value) or actual != self.value:
+            raise TestOperationFailed(
+                f"Test on {self.path!r} failed: expected {self.value!r} "
+                f"({type(self.value).__name__}), found {actual!r} "
+                f"({type(actual).__name__}) in the document as it stood "
+                "before this batch's own operations."
+            )
+        return []

{json_source_edit-0.1.0 → json_source_edit-0.2.0/src/json_source_edit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: json-source-edit
-Version: 0.1.0
+Version: 0.2.0
 Summary: Surgical, byte-preserving JSON editing — change only what you intend to change.
 Author: Jérémie Lumbroso
 License: MIT
@@ -62,14 +62,12 @@ everything else on the reel undisturbed.
 
 ## Install
 
-Not yet on PyPI (see [Status](#status) below). Until then:
-
 ```bash
-git clone https://github.com/jlumbroso/json-source-edit
-cd json-source-edit
-pip install -e .
+pip install json-source-edit
 ```
 
+(Or clone the repo and `pip install -e .` for local development.)
+
 ## Usage
 
 ```python
@@ -121,12 +119,13 @@ it: `get_value`, `get_modifications`, and `preview_diff`.
 |---|---|
 | `replace` | Supported — any path, any depth |
 | `remove` | Supported — array elements and object properties, any depth, except the document root itself (structurally undefined: the root has no parent container to apply a comma/whitespace rule against) |
-| `add`, `move`, `copy`, `test` | Not implemented — raise `NotImplementedError` |
+| `test` | Supported — not a text edit, an assertion. Evaluated against the document as it stood before this batch's own operations (not a naive sequential reading of RFC 6902 — see the docstring on `operations.Test`), with type-strict comparison (`1` does not test-equal `1.0` or `true`) |
+| `add`, `move`, `copy` | Not implemented — raise `NotImplementedError`. Planned next (see `CHANGELOG.md`) |
 
-Multiple `replace`/`remove` calls batch correctly against the same original
-document — every path resolves in original-document coordinates regardless
-of what else is in the batch, so edit order doesn't matter and one deletion
-can't corrupt another edit's position.
+Multiple `replace`/`remove`/`test` calls batch correctly against the same
+original document — every path resolves in original-document coordinates
+regardless of what else is in the batch, so edit order doesn't matter and
+one deletion can't corrupt another edit's position.
 
 ## Benchmark (v0)
 
@@ -174,10 +173,10 @@ make a package like this one feasible to write at all.
 
 ## Status
 
-Pre-release. 187 tests, 100% line coverage. Not yet on PyPI — CI is scaffolded
-(GitHub Actions test matrix, Python 3.8–3.13) but the publish workflow is
-deliberately inert pending the repo owner's two-step activation (see
-`.github/workflows/publish.yml`).
+Published: [pypi.org/project/json-source-edit](https://pypi.org/project/json-source-edit/).
+`pip install json-source-edit`. 203 tests, 100% line coverage. See
+`CHANGELOG.md` for release history and the Scope table above for what's
+implemented.
 
 ## License
 

{json_source_edit-0.1.0 → json_source_edit-0.2.0}/tests/test_operations.py

@@ -197,14 +197,107 @@ def test_ops_2_6_5_remove_from_a_scalar_parent_still_unsupported():
     assert "/scalar" in message
 
 
-# --- Future operations remain stubbed ---
+# --- Future operations remain stubbed (Mission 5: Test is implemented below; Add/Move/Copy are not) ---
 
 @pytest.mark.parametrize("op", [
     Add("/x", 1),
     Move("/ignored", "/a", "/b"),
     Copy("/ignored", "/a", "/b"),
-    Test("/x", 1),
 ])
 def test_future_operations_not_implemented(op):
     with pytest.raises(NotImplementedError):
         op.compile(sm.generate('{"a": 1}'), {"a": 1}, '{"a": 1}')
+
+
+# --- Mission 5: Test operation (TEST-2.* — not a text edit, a value assertion) ---
+
+from json_source_edit.operations import TestOperationFailed  # noqa: E402
+
+
+def test_test_2_1_passing_test_contributes_no_edits():
+    text = '{"a": 1, "steps": [1, 2, 3]}'
+    assert _compile(Test("/a", 1), text) == []
+    assert _apply(Test("/a", 1), text) == text
+
+
+@pytest.mark.parametrize("path,expected,json_text", [
+    ("/a", 1, '{"a": 1}'),
+    ("/name", "hello", '{"name": "hello"}'),
+    ("/flag", True, '{"flag": true}'),
+    ("/nothing", None, '{"nothing": null}'),
+    ("/items/1", 20, '{"items": [10, 20, 30]}'),
+    ("/nested/deep", "x", '{"nested": {"deep": "x"}}'),
+    ("", {"a": 1}, '{"a": 1}'),  # root path
+])
+def test_test_2_2_passes_for_matching_values_various_types_and_positions(path, expected, json_text):
+    assert _compile(Test(path, expected), json_text) == []
+
+
+def test_test_2_3_failing_test_raises_with_actionable_message():
+    with pytest.raises(TestOperationFailed) as exc_info:
+        _compile(Test("/a", 2), '{"a": 1}')
+    message = str(exc_info.value)
+    assert "/a" in message and "2" in message and "1" in message
+
+
+def test_test_2_4_missing_path_fails_cleanly_not_a_raw_lookup_error():
+    """RFC 6902: testing a path that doesn't exist is a *failed* test, not
+    a malformed-patch error -- resolve_path's KeyError/IndexError/ValueError
+    must not leak past Test.compile()."""
+    with pytest.raises(TestOperationFailed):
+        _compile(Test("/nonexistent", 1), '{"a": 1}')
+    with pytest.raises(TestOperationFailed):
+        _compile(Test("/items/99", 1), '{"items": [1, 2]}')
+
+
+@pytest.mark.parametrize("path,expected,json_text", [
+    ("/flag", 1, '{"flag": true}'),       # bool stored, int expected
+    ("/count", True, '{"count": 1}'),      # int stored, bool expected
+    ("/n", 1.0, '{"n": 1}'),               # int stored, float expected
+    ("/n", 1, '{"n": 1.0}'),               # float stored, int expected
+])
+def test_test_2_5_type_strict_comparison_rejects_bool_int_float_crossover(path, expected, json_text):
+    """Plain Python `==` would pass all four of these (bool is an int
+    subclass; 1 == 1.0) -- a package whose whole point is preserving exact
+    original representation shouldn't blur that in its comparison op."""
+    with pytest.raises(TestOperationFailed):
+        _compile(Test(path, expected), json_text)
+
+
+def test_test_2_6_failing_test_aborts_the_whole_batch_nothing_partial_applies():
+    """A replace queued *before* a failing test must not land -- compile()
+    raises before apply_edits() ever runs, for every op in the batch."""
+    from json_source_edit.editor import JSONEditor
+
+    editor = JSONEditor.from_string('{"a": 1}')
+    editor.replace("/a", 999)
+    editor.test("/a", 2)  # fails against the pristine value, 1
+    with pytest.raises(TestOperationFailed):
+        editor.apply()
+
+
+def test_test_2_7_evaluates_against_pristine_batch_start_not_sequential_effect():
+    """Deliberate deviation from a naive sequential JSON Patch reading: a
+    `test` following a `replace` on the same path in the SAME batch sees
+    the pristine pre-batch value, not the queued replace's effect -- the
+    same coordinate-frame contract every other operation in this package
+    follows (Round 4 §1). A test against the value the batch is ABOUT to
+    set (999) would fail; against the ORIGINAL value (1) it passes."""
+    from json_source_edit.editor import JSONEditor
+
+    editor = JSONEditor.from_string('{"a": 1}')
+    editor.replace("/a", 999)
+    editor.test("/a", 1)  # pristine value, not editor.replace's queued 999
+    result = editor.apply()
+    assert json.loads(result)["a"] == 999  # the replace still lands: test passed
+
+
+def test_test_2_8_editor_test_records_no_modification():
+    """A passing test doesn't change the document -- get_modifications()'s
+    audit trail is specifically about what changed, so Test shouldn't
+    appear there."""
+    from json_source_edit.editor import JSONEditor
+
+    editor = JSONEditor.from_string('{"a": 1}')
+    editor.test("/a", 1)
+    assert editor.get_modifications() == []