oold 2.3.0__tar.gz → 2.3.1__tar.gz

{oold-2.3.0 → oold-2.3.1}/CHANGELOG.md

@@ -7,6 +7,25 @@ not edit released sections by hand.
 
 <!-- version list -->
 
+## v2.3.1 (2026-11-15)
+
+### Bug Fixes
+
+- **frame**: Anchor the frame on a type pinned as a default
+  ([`fa22022`](https://github.com/OO-LD/oold-python/commit/fa220221e48feb83c26879748c317457d2484012))
+
+- **frame**: Keep a $ref-valued embed out of the reference list
+  ([`a7ac1d1`](https://github.com/OO-LD/oold-python/commit/a7ac1d1d153719258fb299c3f706a58238bbe9c4))
+
+- **frame**: One reverse subframe per IRI, not per term
+  ([`74a3adf`](https://github.com/OO-LD/oold-python/commit/74a3adf44fb647aa544c7432c0e5fd78f44949c1))
+
+### Documentation
+
+- **controller**: Name controller members for what they do
+  ([`648018f`](https://github.com/OO-LD/oold-python/commit/648018fc480934b5b5185c6d0702860392e90c25))
+
+
 ## v2.3.0 (2026-10-15)
 
 ### Bug Fixes

{oold-2.3.0 → oold-2.3.1}/CITATION.cff

@@ -3,7 +3,7 @@ message: "If you use this software, please cite it as below."
 type: software
 title: "oold-python: Object-Oriented Linked Data for Python"
 # Managed by python-semantic-release (version_variables). Do not edit by hand.
-version: 2.3.0
+version: 2.3.1
 abstract: "A Python package for abstract and object-oriented access to knowledge graphs, bridging semantic web technologies (RDF, JSON-LD, SPARQL) with Pydantic type safety."
 repository-code: "https://github.com/oo-ld/oold-python"
 url: "https://OO-LD.github.io/oold-python/"

{oold-2.3.0 → oold-2.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: oold
-Version: 2.3.0
+Version: 2.3.1
 Summary: Linked data class python package
 Project-URL: Homepage, https://OO-LD.github.io/oold-python/
 Project-URL: Documentation, https://OO-LD.github.io/oold-python/

{oold-2.3.0 → oold-2.3.1}/docs/how-to/controller.md

@@ -147,6 +147,8 @@ This is useful for checkpointing state (e.g. saving `joint_count` after a calibr
 
 ## Guidelines
 
+- Name controller members for what they *do*: `connect()`, `download()`, `store()`, not `connection`, `url`, `storage`. A controller extends a model whose field names come from a schema, and a noun-named method or property competes with a field that the schema may gain at any regeneration - it shadows the field, or the field shadows it, and the two are hard to tell apart because both answer to attribute access. A verb is almost never a field name.
+- The risk is worst for a property: it reads like data, so callers reach for it with `getattr()`, and anything it does on the way - opening a session, touching the filesystem - surfaces where a plain attribute read was expected. If a controller has to expose derived data, give it a method.
 - Prefix controller-only attributes with `_` to make the distinction explicit
 - Keep `__init__` arguments limited to data model fields - controllers should be constructed from data, not from runtime handles
 - If a controller needs runtime resources (sockets, threads), initialize them in a dedicated `connect()` / `start()` method, not in `__init__`

{oold-2.3.0 → oold-2.3.1}/pyproject.toml

@@ -9,7 +9,7 @@ keywords = ['python', 'linked-data', 'json-ld', 'pydantic', 'oo-ld']
 requires-python = ">=3.10,<4.0"
 # Version is managed by python-semantic-release (see [tool.semantic_release]).
 # Do not edit by hand; it is bumped automatically on merge to main.
-version = "2.3.0"
+version = "2.3.1"
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",

{oold-2.3.0 → oold-2.3.1}/src/oold/validation/frame.py

@@ -41,14 +41,17 @@ IRI_FORMATS = frozenset({"iri", "iri-reference", "uri", "uri-reference"})
 def is_embed(node: Any) -> bool:
     """True when a property's schema describes an embedded *object* value.
 
-    A ``$ref`` alone is not enough: it may point at a scalar DataType leaf, which is a literal
-    rather than an embed. After dereferencing, a real embed is inlined as an object with its own
-    properties anyway, so the object shape is the reliable signal.
+    After dereferencing an embed is inlined as an object with its own properties, so the object
+    shape is the primary signal. On an undereferenced schema it is a ``$ref``, which therefore
+    counts too. A ``$ref`` pointing at a scalar DataType leaf is a literal rather than an embed,
+    but it costs only an empty subframe, and framing leaves a literal value alone.
     """
     if not isinstance(node, dict):
         return False
     if node.get("type") == "object" and node.get("properties"):
         return True
+    if isinstance(node.get("$ref"), str):
+        return True
     if node.get("items") is not None:
         return is_embed(node["items"])
     for keyword in ("anyOf", "oneOf", "allOf"):
@@ -97,6 +100,25 @@ def embedded_properties(schema: dict[str, Any]) -> list[str]:
     return list(dict.fromkeys([*structural, *scoped]))
 
 
+def pinned_type_default(schema: Any) -> list[str] | None:
+    """The instance type a schema pins through ``properties.type.default``.
+
+    ``OOLD-INS-4b5c`` only fires where ``x-oold-instance-rdf-type`` is declared, so pinning the
+    type as a default on the ``@type``-aliased property is a permitted spelling, and the frame
+    needs that anchor as much as it needs the keyword's.
+    """
+    if not isinstance(schema, dict):
+        return None
+    properties = schema.get("properties")
+    declaration = properties.get("type") if isinstance(properties, dict) else None
+    default = declaration.get("default") if isinstance(declaration, dict) else None
+    if isinstance(default, str):
+        return [default]
+    if isinstance(default, list) and default and all(isinstance(entry, str) for entry in default):
+        return list(default)
+    return None
+
+
 def instance_rdf_types(schema: Any) -> list[str] | None:
     """The instance ``rdf:type``(s) a schema declares, most-derived-wins.
 
@@ -105,12 +127,18 @@ def instance_rdf_types(schema: Any) -> list[str] | None:
     inference rather than being materialised. A subclass that wants supertypes in the data lists
     them explicitly. After dereferencing the most-derived value sits at the top level; the
     ``allOf`` walk is the fallback for a subclass that omits its own declaration.
+
+    ``properties.type.default`` is read where the keyword is absent, and it is read before the
+    ``allOf`` walk, because a schema's own spelling of its type is nearer than an inherited one.
     """
     if not isinstance(schema, dict):
         return None
     own = schema.get("x-oold-instance-rdf-type")
     if isinstance(own, list) and own:
         return own
+    pinned = pinned_type_default(schema)
+    if pinned:
+        return pinned
     if isinstance(schema.get("allOf"), list):
         for sub in schema["allOf"]:
             types = instance_rdf_types(sub)
@@ -162,6 +190,22 @@ def _is_reference_term(definition: Any) -> bool:
     return definition.get("@type") == "@id" or "@reverse" in definition
 
 
+def reverse_predicates(schema: dict[str, Any]) -> dict[str, list[str]]:
+    """The reverse IRI each reverse-mapped property compacts to, keyed by that IRI.
+
+    Several terms may share one reverse IRI, since nothing stops a schema from naming the same
+    relation twice. The IRI is taken as the term writes it, compact or absolute: the frame
+    resolves it against the same context the term was read from.
+    """
+    properties = collect_composed_properties(schema)
+    grouped: dict[str, list[str]] = {}
+    for name, definition in context_terms(schema.get("@context")).items():
+        predicate = definition.get("@reverse")
+        if name in properties and isinstance(predicate, str):
+            grouped.setdefault(predicate, []).append(name)
+    return grouped
+
+
 def reference_properties(schema: dict[str, Any]) -> list[str]:
     """Properties whose value is a reference, so framing must leave it an IRI.
 
@@ -173,8 +217,9 @@ def reference_properties(schema: dict[str, Any]) -> list[str]:
     (JSON-LD 1.1 4.1.10), so ``"@type": "@id"`` beside it is redundant and authors omit it;
     keying only on ``@type`` misses the idiomatic spelling and embeds the targets.
 
-    Embedding takes precedence where a property carries both: a property shaped like an object
-    is an embed whatever its term says.
+    Embedding takes precedence where a property carries both, and the test is membership in
+    :func:`embedded_properties` rather than the shape alone, so the two lists cannot both claim a
+    property that embeds through a scoped ``@context``.
     """
 
     def is_reference(node: Any) -> bool:
@@ -195,11 +240,12 @@ def reference_properties(schema: dict[str, Any]) -> list[str]:
     properties = collect_composed_properties(schema)
     terms = context_terms(schema.get("@context"))
     aliases = keyword_alias_keys(schema)
+    embedded = set(embedded_properties(schema))
     return [
         name
         for name, prop in properties.items()
         if name not in aliases
-        and not is_embed(prop)
+        and name not in embedded
         and (is_reference(prop) or _is_reference_term(terms.get(name, {})))
     ]
 
@@ -210,14 +256,34 @@ def schema_to_frame(schema: dict[str, Any], context_ref: Any = _UNSET) -> dict[s
     ``context_ref``, when given, is used as the frame's ``@context`` in place of the schema's
     inline one. Pass the schema's URL so the document loader resolves inherited and scoped
     contexts rather than losing them.
+
+    The reference subframes are written before the embedded ones, so a property both lists claim
+    keeps the ``{}`` that preserves its nested keys.
+
+    A reverse-mapped property is written under ``@reverse``, by its reverse IRI rather than by its
+    term name. Term names expand, so two terms sharing one reverse IRI would otherwise produce two
+    subframes under that IRI; a frame must be a single object, and a processor rejects the pair.
     """
     frame: dict[str, Any] = {"@embed": "@once"}
     frame["@context"] = schema.get("@context") if context_ref is _UNSET else context_ref
     types = instance_rdf_types(schema)
     if types:
         frame["@type"] = types[0] if len(types) == 1 else types
-    for name in embedded_properties(schema):
-        frame[name] = {}
+
+    predicate_of = {name: predicate for predicate, names in reverse_predicates(schema).items() for name in names}
+    grouped: dict[str, dict[str, Any]] = {}
+
+    def place(name: str, subframe: dict[str, Any]) -> None:
+        predicate = predicate_of.get(name)
+        if predicate is None:
+            frame[name] = subframe
+        else:
+            grouped[predicate] = subframe
+
     for name in reference_properties(schema):
-        frame[name] = {"@embed": "@never"}
+        place(name, {"@embed": "@never"})
+    for name in embedded_properties(schema):
+        place(name, {})
+    if grouped:
+        frame["@reverse"] = grouped
     return frame

{oold-2.3.0 → oold-2.3.1}/tests/test_validation/test_jsonld.py

@@ -14,6 +14,7 @@ from oold.validation.frame import (
     is_embed,
     keyword_alias_keys,
     reference_properties,
+    reverse_predicates,
     schema_to_frame,
 )
 from oold.validation.loader import DocumentLoader, describe_jsonld_error
@@ -98,6 +99,61 @@ def test_instance_rdf_types_is_most_derived_wins():
     assert instance_rdf_types({"type": "object"}) is None
 
 
+def test_a_type_pinned_as_a_default_anchors_the_frame():
+    """OO-LD/oold-python#177.
+
+    Without an anchor the root is only the frame root while every edge runs forward; the first
+    backwards edge leaves nothing matched and framing returns a bare ``@graph``.
+    """
+    context = {
+        "ex": "https://example.org/",
+        "obo": "http://purl.obolibrary.org/obo/",
+        "id": "@id",
+        "type": {"@id": "@type", "@container": "@set"},
+        "Material": "ex:Material",
+        "components": "ex:components",
+        "chemical_composition": {"@reverse": "obo:RO_0000080"},
+    }
+    schema = {
+        "type": "object",
+        "@context": context,
+        "properties": {
+            "type": {"type": "array", "items": {"type": "string"}, "default": ["Material"]},
+            "chemical_composition": {"type": "object", "properties": {"components": {}}},
+        },
+    }
+    assert instance_rdf_types(schema) == ["Material"]
+    frame = schema_to_frame(schema)
+    assert frame["@type"] == "Material"
+
+    rdf_type = "<http://www.w3.org/1999/02/22-rdf-syntax-ns#type>"
+    nq = "\n".join([
+        f"<https://example.org/m1> {rdf_type} <https://example.org/Material> .",
+        f"_:c {rdf_type} <https://example.org/ChemicalComposition> .",
+        "_:c <http://purl.obolibrary.org/obo/RO_0000080> <https://example.org/m1> .",
+        '_:c <https://example.org/components> "Fe" .',
+        "",
+    ])
+    graph = jsonld.from_rdf(nq, {"format": "application/n-quads", "useNativeTypes": True})
+    framed = jsonld.frame(graph, frame, {"omitDefault": True})
+
+    assert "@graph" not in framed
+    assert framed["chemical_composition"]["components"] == "Fe"
+
+
+def test_the_keyword_wins_over_a_type_pinned_as_a_default():
+    schema = {
+        "x-oold-instance-rdf-type": ["ex:B"],
+        "properties": {"type": {"default": ["ex:A"]}},
+    }
+    assert instance_rdf_types(schema) == ["ex:B"]
+    # A schema's own default is nearer than a type inherited through allOf.
+    assert instance_rdf_types({
+        "allOf": [{"x-oold-instance-rdf-type": ["ex:A"]}],
+        "properties": {"type": {"default": ["ex:B"]}},
+    }) == ["ex:B"]
+
+
 def test_schema_to_frame_carries_type_context_and_subframes():
     schema = {
         "x-oold-instance-rdf-type": ["schema:Person"],
@@ -175,6 +231,35 @@ def test_embedding_wins_where_a_property_carries_both_signals():
     assert reference_properties(schema) == []
 
 
+def test_a_ref_valued_embed_keeps_its_subframe_before_dereferencing():
+    """OO-LD/oold-python#175.
+
+    ``$ref`` is the only trace of the embed while the schema is undereferenced, and the
+    ``"@type": "@id"`` that OO-LD requires on such a term makes it look reference-valued at the
+    same time. With both lists claiming it, ``{}`` was overwritten by ``@embed: @never`` and the
+    framed node came back empty.
+    """
+    schema = {
+        "type": "object",
+        "@context": {
+            "type": {"@id": "@type", "@container": "@set"},
+            "chemical_composition": {
+                "@id": "https://example.org/chemical_composition",
+                "@type": "@id",
+                "@context": "ChemicalComposition.schema.json",
+            },
+        },
+        "properties": {
+            "type": {"type": "array", "items": {"type": "string"}, "default": ["Material"]},
+            "chemical_composition": {"$ref": "ChemicalComposition.schema.json"},
+        },
+    }
+    assert is_embed({"$ref": "ChemicalComposition.schema.json"})
+    assert embedded_properties(schema) == ["chemical_composition"]
+    assert reference_properties(schema) == []
+    assert schema_to_frame(schema, "Material.schema.json")["chemical_composition"] == {}
+
+
 def test_a_bare_reverse_term_is_reference_valued():
     """A reverse term's values are node references by definition (JSON-LD 1.1 4.1.10).
 
@@ -187,7 +272,55 @@ def test_a_bare_reverse_term_is_reference_valued():
         "properties": {"employees": {"type": "array", "items": {"type": "string"}}},
     }
     assert reference_properties(schema) == ["employees"]
-    assert schema_to_frame(schema)["employees"] == {"@embed": "@never"}
+    assert schema_to_frame(schema)["@reverse"] == {"schema:worksFor": {"@embed": "@never"}}
+
+
+def test_two_terms_on_one_reverse_iri_share_a_single_subframe():
+    """OO-LD/oold-python#176.
+
+    Term names expand, so a subframe per term became two subframes under one IRI. A frame must be
+    a single object, and pyld raised ``invalid frame`` with ``{'frame': [{}, {}]}``.
+    """
+    context = {
+        "ex": "https://example.org/",
+        "obo": "http://purl.obolibrary.org/obo/",
+        "id": "@id",
+        "type": {"@id": "@type", "@container": "@set"},
+        "Material": "ex:Material",
+        "components": "ex:components",
+        "chemical_composition": {"@reverse": "obo:RO_0000080"},
+        "material_composition": {"@reverse": "obo:RO_0000080"},
+    }
+    schema = {
+        "x-oold-instance-rdf-type": ["ex:Material"],
+        "type": "object",
+        "@context": context,
+        "properties": {
+            "chemical_composition": {"type": "object", "properties": {"components": {}}},
+            "material_composition": {"type": "object", "properties": {"components": {}}},
+        },
+    }
+    assert reverse_predicates(schema) == {"obo:RO_0000080": ["chemical_composition", "material_composition"]}
+    frame = schema_to_frame(schema)
+    assert frame["@reverse"] == {"obo:RO_0000080": {}}
+    assert "chemical_composition" not in frame
+
+    rdf_type = "<http://www.w3.org/1999/02/22-rdf-syntax-ns#type>"
+    nq = "\n".join([
+        f"<https://example.org/m1> {rdf_type} <https://example.org/Material> .",
+        f"_:c {rdf_type} <https://example.org/ChemicalComposition> .",
+        "_:c <http://purl.obolibrary.org/obo/RO_0000080> <https://example.org/m1> .",
+        '_:c <https://example.org/components> "Fe" .',
+        f"_:m {rdf_type} <https://example.org/MaterialComposition> .",
+        "_:m <http://purl.obolibrary.org/obo/RO_0000080> <https://example.org/m1> .",
+        '_:m <https://example.org/components> "steel" .',
+        "",
+    ])
+    graph = jsonld.from_rdf(nq, {"format": "application/n-quads", "useNativeTypes": True})
+    framed = jsonld.frame(graph, frame, {"omitDefault": True})
+
+    compositions = framed["chemical_composition"]
+    assert sorted(entry["components"] for entry in compositions) == ["Fe", "steel"]
 
 
 def test_a_keyword_alias_never_gets_a_subframe():
@@ -234,7 +367,7 @@ def test_schema_to_frame_keeps_reference_valued_properties_as_iris():
     }
     frame = schema_to_frame(schema, "Organization.schema.json")
     assert frame["address"] == {}
-    assert frame["employees"] == {"@embed": "@never"}
+    assert frame["@reverse"] == {"schema:worksFor": {"@embed": "@never"}}
 
 
 def test_framing_leaves_a_reference_whose_target_has_triples_as_an_iri():

{oold-2.3.0 → oold-2.3.1}/uv.lock

@@ -2730,7 +2730,7 @@ wheels = [
 
 [[package]]
 name = "oold"
-version = "2.3.0"
+version = "2.3.1"
 source = { editable = "." }
 dependencies = [
     { name = "datamodel-code-generator" },
@@ -5613,13 +5613,8 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/ad/fd/6b84115e3bbe6b76ebb1265e8ff2161c0bc88dcd6499eaf29c61a66421e9/zensical-0.0.45-cp310-abi3-macosx_10_12_x86_64.whl", hash = "sha256:c4cb2e11132f02ae824e246e016e073458e12e9de1eaf86fd39f01890d41204c", size = 12698844, upload-time = "2026-06-09T11:22:56.537Z" },
     { url = "https://files.pythonhosted.org/packages/e2/dc/4ddf05d77c1455c32cb26da71f2a19d355927a45a3db5b26fb258a07ce8f/zensical-0.0.45-cp310-abi3-macosx_11_0_arm64.whl", hash = "sha256:799a01de2102b5f731744ad31bdbc464d0c07d484e67ba148f6923679afa6ce6", size = 12571590, upload-time = "2026-06-09T11:23:00.192Z" },
     { url = "https://files.pythonhosted.org/packages/4c/53/60c6cc7b2ce8b1a83eb87bff3f7289447995552fd9a30ca76ffba22ca9d5/zensical-0.0.45-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:6201e79ea8a64bd3ced3f05ef4b1529da0e675d67b1395987c0ba942e4e10dc4", size = 12939590, upload-time = "2026-06-09T11:23:02.721Z" },
-    { url = "https://files.pythonhosted.org/packages/9f/1e/e9217ed75dba323a6f9a4eee28eb40416eff99932cd0ee6c394bf07b9ead/zensical-0.0.45-cp310-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:854aaf500e4a3ce64adea1faa7a1820c7cf9a4f66be1043e4e9ba727fe9cf2b5", size = 12911669, upload-time = "2026-06-09T11:23:05.407Z" },
-    { url = "https://files.pythonhosted.org/packages/71/3c/6fc9fe2334bb4460a8a8d732e23a30d2ddc2ecf63c2eb3487d9e7405e70d/zensical-0.0.45-cp310-abi3-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:a80c57fd50fc60415914388286ac10a7d8b6f70b8ca7235597d09fb12c3171b0", size = 13267643, upload-time = "2026-06-09T11:23:07.915Z" },
     { url = "https://files.pythonhosted.org/packages/be/f9/5696114af4ede5f1bd01e641a4ff24ee8ca49810bfaa28e5be12d930c0ef/zensical-0.0.45-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:58c3510f69e08b6ed8bb9596fc9393e4687f90394aa0ef2d6118b1375ad97be5", size = 12972147, upload-time = "2026-06-09T11:23:12.069Z" },
     { url = "https://files.pythonhosted.org/packages/a3/9e/5c6acde480c43f8c993b13260925df8db31d51ab8a9977618e9efdd98d45/zensical-0.0.45-cp310-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:01c484bb2ee85e98e21e24b397ff52ffc31101f7485935eee5d3afa6cca6cc08", size = 13117360, upload-time = "2026-06-09T11:23:15.155Z" },
-    { url = "https://files.pythonhosted.org/packages/3d/31/ea21f102049b35a8fe5218c5331857a15eeb60deb1bb21823a4c0701e274/zensical-0.0.45-cp310-abi3-musllinux_1_2_armv7l.whl", hash = "sha256:3654b708830303759e866a58a60c483cd2a1c56a44acdaae5bbb341a3f40ebce", size = 13185593, upload-time = "2026-06-09T11:23:18.166Z" },
-    { url = "https://files.pythonhosted.org/packages/b4/97/6ded39fe27fa8a292d17d9af713b018e4919315233b60fa4b4b0aca737a6/zensical-0.0.45-cp310-abi3-musllinux_1_2_i686.whl", hash = "sha256:c4da1c37eca1474b487def0ef40d7ac2aff31a9d7a029cb7479ef7c354437361", size = 13326882, upload-time = "2026-06-09T11:23:21.027Z" },
     { url = "https://files.pythonhosted.org/packages/79/80/075975032a9e20f319c0134f8ca659d295ee4908f15ab212702a2728247f/zensical-0.0.45-cp310-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:f8a1966c186feebd3b795f9d420000bfd582e16eefdd9bc7a286d878faabae52", size = 13253961, upload-time = "2026-06-09T11:23:23.99Z" },
-    { url = "https://files.pythonhosted.org/packages/3f/6a/0eab0eb311af6a07cde15ca58d5d720cbfa02cd509e4c7fb5fa20cda0b46/zensical-0.0.45-cp310-abi3-win32.whl", hash = "sha256:a1dd63a5efb8d0e5f2fadf862f02771a279dc5cbe9a982700194650065758f01", size = 12257083, upload-time = "2026-06-09T11:23:26.769Z" },
     { url = "https://files.pythonhosted.org/packages/1f/cd/b117e749c60b1d1e16b8450db1355f69f38376f783b8c6c8815202988933/zensical-0.0.45-cp310-abi3-win_amd64.whl", hash = "sha256:1f2c0e69839ce4274bde34d18139d3b0d96bbf02b245ada46243590c9eedebc1", size = 12498335, upload-time = "2026-06-09T11:23:29.702Z" },
 ]