Per-accessor identity

Author: p1c2u

README.rst

@@ -89,6 +89,37 @@ Usage
    ...     print(contents)
    {'type': 'string', 'default': '1.0'}
 
+Identity and equality
+#####################
+
+Two ``SchemaPath`` instances are equal if they have the same ``parts``
+*and* point to the same ``SchemaAccessor``. ``SchemaAccessor`` identity
+is per-resource-handle: same wrapped dict (by reference), same
+``base_uri``, and same internal resolver instance. In practice:
+
+* Paths derived from the *same* accessor compare equal as expected:
+
+  .. code-block:: python
+
+     >>> accessor = SchemaAccessor.from_schema(d)
+     >>> SchemaPath(accessor) / "properties" == SchemaPath(accessor) / "properties"
+     True
+
+* Paths from *separate* ``from_dict`` or ``from_schema`` calls do **not**
+  compare equal even with identical arguments, because each call builds
+  its own accessor:
+
+  .. code-block:: python
+
+     >>> SchemaPath.from_dict(d) == SchemaPath.from_dict(d)
+     False
+
+* ``SchemaAccessor`` is hashable, so accessors and paths can be used as
+  set members and dict keys.
+
+This is also why the "build one accessor, reuse it" pattern below
+matters: it is both a caching optimisation and the contract you need
+for path equality to behave the way you expect.
 
 Resolved cache
 ##############
@@ -117,8 +148,7 @@ it.
 
 .. code-block:: python
 
-   >>> from jsonschema_path import SchemaPath
-   >>> from jsonschema_path.accessors import SchemaAccessor
+   >>> from jsonschema_path import SchemaAccessor, SchemaPath
 
    >>> # Construct the accessor once, with caching enabled.
    >>> accessor = SchemaAccessor.from_schema(d, resolved_cache_maxsize=128)

jsonschema_path/accessors.py

@@ -46,6 +46,47 @@ def __init__(
             maxsize=resolved_cache_maxsize
         )
 
+    def __eq__(self, other: object) -> Any:
+        if not isinstance(other, SchemaAccessor):
+            return NotImplemented
+        # SchemaAccessor identity is the resource handle itself, not a
+        # value tuple. Two SchemaAccessors are equal only when they
+        # wrap the same dict (by reference), share the same base_uri,
+        # and share the same `_path_resolver` instance. The
+        # `_path_resolver` encodes the specification, handlers, and
+        # registry configuration: it is constructed once in `__init__`
+        # and never reassigned (only its inner `resolver` field is
+        # swapped when the registry evolves), so comparing it by `is`
+        # gives a stable identity token without depending on the
+        # mutating registry.
+        #
+        # Consequence: `SchemaAccessor.from_schema(doc, ...)` called
+        # twice produces non-equal accessors even with identical
+        # arguments, because each call builds its own `_path_resolver`.
+        # Build one accessor per schema and reuse it across all
+        # derived `SchemaPath`s — see "Recommended usage" in the
+        # README.
+        return (
+            type(self) is type(other)
+            and self._node is other._node
+            and self.base_uri == other.base_uri
+            and self._path_resolver is other._path_resolver
+        )
+
+    def __hash__(self) -> int:
+        # Stable for the accessor's lifetime: node identity, base_uri
+        # (set once at construction), and `_path_resolver` identity.
+        # Does not depend on the schema dict being hashable or on the
+        # mutating registry.
+        return hash(
+            (
+                type(self),
+                id(self._node),
+                self.base_uri,
+                id(self._path_resolver),
+            )
+        )
+
     @classmethod
     def from_schema(
         cls,

poetry.lock

@@ -42,7 +42,7 @@ classifiers = [
 
 [tool.poetry.dependencies]
 attrs = ">=22.2.0"
-pathable = "^0.5.0"
+pathable = "^0.6.0"
 python = ">=3.10,<4.0.0"
 PyYAML = ">=5.1"
 requests = {version = "^2.31.0", optional = true}

pyproject.toml

@@ -387,3 +387,106 @@ def test_prefix_cache_rebound_avoids_redundant_retrieval(self):
 
         calls = sorted(c.args[0] for c in retrieve.call_args_list)
         assert calls == ["x://later", "x://one", "x://primer"]
+
+
+class TestSchemaAccessorIdentity:
+    """Locks in the per-resource-handle identity model.
+
+    SchemaAccessor identity is the accessor instance itself (with
+    discrimination on node, base_uri, and `_path_resolver` instance),
+    not a value tuple of its inputs. This forces the recommended
+    lifecycle: construct one SchemaAccessor per schema document and
+    reuse it across all derived SchemaPaths.
+    """
+
+    def test_same_instance_compares_equal_and_hashes_equal(self):
+        accessor = SchemaAccessor.from_schema({"a": 1})
+
+        assert accessor == accessor
+        assert hash(accessor) == hash(accessor)
+
+    def test_accessor_is_hashable(self):
+        accessor = SchemaAccessor.from_schema({"a": 1})
+
+        # Would raise TypeError before this PR (defining __eq__
+        # without __hash__ silently makes instances unhashable).
+        assert hash(accessor) == hash(accessor)
+        {accessor}  # constructable as a set element
+
+    def test_distinct_from_schema_calls_not_equal(self):
+        # Each from_schema() call builds its own _path_resolver, so
+        # the resulting accessors are distinct resource handles even
+        # with identical arguments. This is the "reuse the accessor"
+        # assertion: callers must hold onto the accessor instance,
+        # not reconstruct it on demand.
+        doc = {"a": 1}
+
+        acc1 = SchemaAccessor.from_schema(doc)
+        acc2 = SchemaAccessor.from_schema(doc)
+
+        assert acc1 != acc2
+        # Hashes are allowed to collide but are very unlikely to here.
+
+    def test_distinct_dicts_not_equal(self):
+        # Inherited from LookupAccessor: value-equal but distinct dicts
+        # are distinct resources. Included for clarity.
+        acc1 = SchemaAccessor.from_schema({"a": 1})
+        acc2 = SchemaAccessor.from_schema({"a": 1})
+
+        assert acc1 != acc2
+
+    def test_different_base_uri_not_equal(self):
+        # Same schema dict by reference, different base_uri → different
+        # resources, because $ref resolution differs.
+        doc = {"a": 1}
+
+        acc1 = SchemaAccessor.from_schema(doc, base_uri="https://a/")
+        acc2 = SchemaAccessor.from_schema(doc, base_uri="https://b/")
+
+        assert acc1 != acc2
+
+    def test_path_equality_follows_accessor_equality(self):
+        from jsonschema_path import SchemaPath
+
+        accessor = SchemaAccessor.from_schema({"a": {"b": 1}})
+
+        p1 = SchemaPath(accessor) / "a"
+        p2 = SchemaPath(accessor) / "a"
+
+        # Same accessor instance + same parts → equal paths and
+        # equal hashes (delegated to pathable's AccessorPath identity).
+        assert p1 == p2
+        assert hash(p1) == hash(p2)
+
+    def test_path_inequality_across_distinct_accessors(self):
+        from jsonschema_path import SchemaPath
+
+        doc = {"a": {"b": 1}}
+        acc1 = SchemaAccessor.from_schema(doc)
+        acc2 = SchemaAccessor.from_schema(doc)
+
+        p1 = SchemaPath(acc1) / "a"
+        p2 = SchemaPath(acc2) / "a"
+
+        # Distinct accessor instances → distinct resources → unequal
+        # paths even though parts and underlying dict reference match.
+        assert p1 != p2
+
+    def test_resolved_cache_shared_when_accessor_reused(self):
+        # Two paths over the same accessor hit the same resolved cache.
+        # If a future refactor reintroduces per-path caching, this test
+        # fails because the second .get_resolved would return a fresh
+        # object instead of the cached one.
+        from jsonschema_path import SchemaPath
+
+        accessor = SchemaAccessor.from_schema(
+            {"a": {"b": 1}},
+            resolved_cache_maxsize=8,
+        )
+
+        p1 = SchemaPath(accessor) / "a" / "b"
+        p2 = SchemaPath(accessor) / "a" / "b"
+
+        with p1.resolve() as r1:
+            with p2.resolve() as r2:
+                assert r1 is r2