sdmxlib 0.65.0__tar.gz → 0.67.0__tar.gz

{sdmxlib-0.65.0 → sdmxlib-0.67.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: sdmxlib
-Version: 0.65.0
+Version: 0.67.0
 Summary: SDMX structural metadata library for Python
 Keywords: sdmx,statistics,metadata,datastructure
 Author: gabrielgellner

{sdmxlib-0.65.0 → sdmxlib-0.67.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sdmxlib"
-version = "0.65.0"
+version = "0.67.0"
 description = "SDMX structural metadata library for Python"
 readme = "README.md"
 requires-python = ">=3.13"
@@ -72,51 +72,6 @@ exclude_lines = [
     "@overload",
 ]
 
-[tool.basedpyright]
-pythonVersion = "3.13"
-pythonPlatform = "Linux"
-venvPath = "."
-venv = ".venv"
-typeCheckingMode = "standard"
-reportUnusedCallResult = false
-reportMissingTypeArgument = "error"
-reportMissingParameterType = "error"
-reportUnnecessaryCast = "error"
-reportPropertyTypeMismatch = "error"
-reportInconsistentConstructor = "error"
-reportCallInDefaultInitializer = "error"
-reportUnnecessaryContains = "error"
-reportUnnecessaryTypeIgnoreComment = "error"
-
-[[tool.basedpyright.executionEnvironments]]
-root = "tests/integration"
-extraPaths = ["."]
-reportMissingParameterType = false
-reportOptionalMemberAccess = false
-
-[[tool.basedpyright.executionEnvironments]]
-root = "tests/docs"
-extraPaths = ["."]
-reportMissingParameterType = false
-reportOptionalMemberAccess = false
-
-[[tool.basedpyright.executionEnvironments]]
-root = "tests/unit"
-extraPaths = ["."]
-reportMissingParameterType = false
-reportOptionalMemberAccess = false
-
-[[tool.basedpyright.executionEnvironments]]
-root = "tests/bench"
-extraPaths = ["."]
-reportMissingParameterType = false
-reportOptionalMemberAccess = false
-reportInvalidCast = "error"
-reportDeprecated = "error"
-reportUnsafeMultipleInheritance = "error"
-reportTypeCommentUsage = "error"
-reportSelfClsParameterName = "error"
-
 [tool.mutmut]
 source_paths = ["src"]
 only_mutate = [
@@ -140,9 +95,10 @@ mutate_only_covered_lines = false
 
 [dependency-groups]
 dev = [
-    "basedpyright==1.39.9",
     "catppuccin[pygments]>=2.5.0",
     "types-lxml>=2025.3.30",
+    "types-jsonschema>=4.21.0",
+    "types-PyYAML>=6.0.12",
     "mkdocs-material>=9.7.6",
     "mkdocstrings[python]>=1.0.3",
     "polars>=1.39.3",
@@ -150,6 +106,7 @@ dev = [
     "jsonschema>=4.21.0",
     "pytest-benchmark>=4.0.0",
     "pytest-cov>=7.1.0",
+    "pytest-xdist>=3.8.0",
     "pytest-memray>=1.7.0",
     "pytest-recording>=0.13.4",
     "pydoclint>=0.9.1,<0.10",

{sdmxlib-0.65.0 → sdmxlib-0.67.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "sdmxlib"
-version = "0.65.0"
+version = "0.67.0"
 description = "SDMX structural metadata library for Python"
 readme = "README.md"
 license = { text = "Apache-2.0" }
@@ -92,126 +92,6 @@ exclude_lines = [
   "@overload",
 ]
 
-[tool.basedpyright]
-pythonVersion = "3.13"
-pythonPlatform = "Linux"
-venvPath = "."
-venv = ".venv"
-# "standard" rather than "strict" because the strict-only rules
-# (reportUnknownMemberType, reportUnknownArgumentType,
-# reportUnknownVariableType) fire on every duckdb / lxml / pyarrow
-# touch — third-party stubs we don't control. Standard mode still
-# catches the bugs we care about (assignments, attribute access,
-# return types, missing arguments). Strict-mode rules that *are*
-# enforceable on this codebase are turned on manually via
-# `# pyright: ignore[...]` opt-outs at the call sites that need them.
-typeCheckingMode = "standard"
-# `pytest.raises(...)` doesn't bind a name — without this every
-# `with pytest.raises(...):` block would need `# pyright: ignore`.
-# Off project-wide since the only places that consume return values
-# we *don't* care about are tests.
-reportUnusedCallResult = false
-
-# Strict-mode rules that ARE clean on this codebase (0 findings), turned on
-# to catch regressions the flood-prone `reportUnknown*` rules would bury.
-# The first two are basedpyright's Any-degradation catchers — the closest it
-# gets to pyrefly's `implicit-any` family without the duckdb/pyarrow noise:
-#   * reportMissingTypeArgument — a bare generic (`list` not `list[str]`) → Any.
-#   * reportMissingParameterType — an untyped parameter → Any.
-# The rest are pure hardening: dead casts (aligns with "narrow, don't cast"),
-# getter/setter type drift, __init__/__new__ disagreement, mutable-default
-# gotchas, and always-true/false `in` checks.
-reportMissingTypeArgument = "error"
-reportMissingParameterType = "error"
-reportUnnecessaryCast = "error"
-reportPropertyTypeMismatch = "error"
-reportInconsistentConstructor = "error"
-reportCallInDefaultInitializer = "error"
-reportUnnecessaryContains = "error"
-
-# Suppression hygiene. This is the rule that keeps the "suppressions require
-# approval" policy honest in the other direction: an ignore that outlived its
-# defect is a lie the next reader believes. It found 10 dead ones the day it
-# went in. Note that neither checker can adjudicate a shared `# type: ignore`
-# alone — pyrefly honours the same comment — which is why checker-specific
-# suppressions are written as `# pyright: ignore[rule]` and
-# `# pyrefly: ignore[kind]`, and why pyrefly's `unused-type-ignore` is off.
-reportUnnecessaryTypeIgnoreComment = "error"
-
-# ── Test directories: two rules subtracted, with reasons (#347) ────────────
-#
-# `tests/` was outside both checkers, which is what let 59 dead suppressions
-# accumulate there — a suppression written against a checker that never runs
-# can be neither validated nor invalidated. It is all in now: !433 brought
-# `tests/support`, !469 `tests/integration` / `tests/docs` / `tests/bench`,
-# and this pass `tests/unit`, which was the last holdout at 1,050 findings.
-#
-# Two rules are off for these paths, and only these paths. Both are measured
-# across the whole of `tests/` and both are *style*, not safety:
-#
-#   * reportMissingParameterType (919) — pytest injects fixtures by name, so
-#     `def test_x(bundle_conn)` is how every test in the suite is written.
-#     Annotating them all would be mechanical, would bind each test to its
-#     fixture's concrete type, and would buy nothing: the fixture's own return
-#     type is checked where it is defined. Where a fixture's type *does* carry
-#     through to many call sites it is annotated anyway — `tests/bench` proved
-#     the cost of not doing so, hiding four `str` URNs from `just check` until
-#     the bundle tier caught them.
-#   * reportOptionalMemberAccess (227) — `reg.get(urn).id` in a test that added
-#     `urn` three lines earlier. The Optional is real and the test is the proof
-#     it is not None; asserting that first in 227 places is noise. It covers
-#     attribute access only, so `len(x)`, `x in y` and passing the value on
-#     still need the assert spelled out, and do have it.
-#
-# `extraPaths = ["."]` appears in all four because `root` re-bases import
-# resolution: without it, `from tests.support …` stops resolving.
-#
-# Everything else is on, which is the point.
-
-[[tool.basedpyright.executionEnvironments]]
-root = "tests/integration"
-extraPaths = ["."]
-reportMissingParameterType = false
-reportOptionalMemberAccess = false
-
-[[tool.basedpyright.executionEnvironments]]
-root = "tests/docs"
-extraPaths = ["."]
-reportMissingParameterType = false
-reportOptionalMemberAccess = false
-
-[[tool.basedpyright.executionEnvironments]]
-root = "tests/unit"
-extraPaths = ["."]
-reportMissingParameterType = false
-reportOptionalMemberAccess = false
-
-[[tool.basedpyright.executionEnvironments]]
-root = "tests/bench"
-extraPaths = ["."]
-reportMissingParameterType = false
-reportOptionalMemberAccess = false
-
-# Zero findings when enabled; on as regression guards. reportInvalidCast in
-# particular backs the "narrow, don't cast" rule — it fires when a cast asserts
-# something the checker knows to be false.
-reportInvalidCast = "error"
-reportDeprecated = "error"
-reportUnsafeMultipleInheritance = "error"
-reportTypeCommentUsage = "error"
-reportSelfClsParameterName = "error"
-
-# NOT enabled, measured rather than assumed:
-#   * reportImplicitOverride (26) — after pyrefly's `missing-override-decorator`
-#     took the 29 real base-class overrides, every one left is a `__repr__` /
-#     `__eq__` / `__hash__` / `__str__` overriding `object`. Decorating those
-#     adds ceremony, not safety. One owner per check; pyrefly owns this one.
-#   * reportPrivateUsage (340) — same population as the SLF001 noqas.
-#   * reportUnnecessaryIsInstance (14) — half are pyright generic artifacts
-#     ("Ref[Code] is always an instance of Ref[Unknown]").
-#   * reportUnnecessaryComparison (7) — all `str`/`None` guards in `model/`
-#     that validate untyped caller input at runtime. Deliberate.
-
 [dependency-groups]
 dev = [
   # Checker versions carry UPPER bounds. uv.lock is gitignored (published
@@ -220,18 +100,13 @@ dev = [
   # ruff on `select = ["ALL"]` that is not hypothetical: ruff 0.16.0
   # stabilised 12 preview rules and would have turned CI red with no commit
   # of ours in between. Bump these deliberately, in their own MR.
-  #
-  # basedpyright is pinned *exactly*, because the bound above was not enough:
-  # 1.39.10 is a patch release built on pyright 1.1.412, which stopped solving
-  # a generic class passed as a `Callable[[], R]` factory from the declared
-  # type — `x: Box[int] = make(Box)` is an error there and fine on 1.1.411.
-  # Every `field(factory=ItemList, ...)` in the model is that shape, so a fresh
-  # environment failed `just check` with 44 errors and no commit of ours in
-  # between. Still broken on pyright 1.1.414 / basedpyright 1.40.2. The pin
-  # goes with basedpyright itself in the pyrefly-only migration.
-  "basedpyright==1.39.9",
   "catppuccin[pygments]>=2.5.0",
   "types-lxml>=2025.3.30",
+  # Stubs for the two untyped test-only imports, so pyrefly checks tests/ without
+  # `untyped-import` findings (#425): jsonschema (tests/support/json_schema.py)
+  # and PyYAML (test_query_closure). Dev group only — nothing published needs them.
+  "types-jsonschema>=4.21.0",
+  "types-PyYAML>=6.0.12",
   "mkdocs-material>=9.7.6",
   "mkdocstrings[python]>=1.0.3",
   "polars>=1.39.3",
@@ -239,6 +114,7 @@ dev = [
   "jsonschema>=4.21.0",
   "pytest-benchmark>=4.0.0",
   "pytest-cov>=7.1.0",
+  "pytest-xdist>=3.8.0",
   "pytest-memray>=1.7.0",
   "pytest-recording>=0.13.4",
   "pydoclint>=0.9.1,<0.10",

{sdmxlib-0.65.0 → sdmxlib-0.67.0}/src/sdmxlib/api/filters.py

@@ -26,7 +26,7 @@ class _DimExpr:
     def __init__(self, id: str) -> None:
         self._id = id
 
-    def __eq__(self, other: object) -> DimFilter:  # pyright: ignore[reportIncompatibleMethodOverride]  # pyrefly: ignore[bad-override]
+    def __eq__(self, other: object) -> DimFilter:  # pyrefly: ignore[bad-override]
         if not isinstance(other, str):
             msg = f"Expected a code string, got {type(other).__name__!r}"
             raise TypeError(msg)

{sdmxlib-0.65.0 → sdmxlib-0.67.0}/src/sdmxlib/api/registry.py

@@ -140,7 +140,7 @@ def _flow_urn(flow: "Dataflow | Ref[Dataflow] | SdmxUrn[Dataflow]") -> "SdmxUrn[
     if isinstance(flow, Ref):
         return flow.urn
     if isinstance(flow, Dataflow):
-        return artefact_urn(flow)
+        return flow.urn
     return flow
 
 

{sdmxlib-0.65.0 → sdmxlib-0.67.0}/src/sdmxlib/api/session.py

@@ -137,7 +137,7 @@ class Session:
         """
         hit = self._map.get(str(urn))
         if hit is not None:
-            return hit  # pyright: ignore[reportReturnType]  # pyrefly: ignore[bad-return]
+            return hit  # pyrefly: ignore[bad-return]
         return None
 
     def get_at_least[T](self, urn: SdmxUrn[T], completeness: Completeness) -> T | None:
@@ -154,7 +154,7 @@ class Session:
             return None
         hit = self._map.get(key)
         if hit is not None:
-            return hit  # pyright: ignore[reportReturnType]  # pyrefly: ignore[bad-return]
+            return hit  # pyrefly: ignore[bad-return]
         return None
 
     def completeness_for(self, urn: SdmxUrn[object]) -> Completeness:

sdmxlib-0.67.0/src/sdmxlib/formats/_arrow.py

@@ -0,0 +1,28 @@
+"""Arrow record batch → polars frame, on the fast path (#427).
+
+The data writers convert every batch they encode, so the conversion is on the
+hot path of every bulk download. `pl.from_arrow(batch)` is the zero-copy
+conversion; the `pl.DataFrame(batch)` constructor takes a slower general path —
+2.4x slower to build the frame on polars 1.39, and 1.33x slower for SDMX-CSV's
+whole per-batch encode. 4f65fd7 switched to the constructor for its return type
+and cost a consumer ~17% on large CSV downloads.
+
+`from_arrow` is typed `DataFrame | Series`, and since polars 2.0 really returns
+a `Series` for stream-only inputs. A `cast` would pass that through unchecked,
+so the result is narrowed at runtime instead: a record batch takes the fast
+branch, and anything that ever comes back as a `Series` falls back to the
+constructor rather than being mislabelled.
+
+Shared by the SDMX-CSV and SDMX-JSON data writers, hence `sdmxlib.formats`.
+"""
+
+import polars as pl
+import pyarrow as pa
+
+
+def frame_of(batch: pa.RecordBatch) -> pl.DataFrame:
+    """The batch as a polars frame, zero-copy where polars allows it."""
+    df = pl.from_arrow(batch)
+    if isinstance(df, pl.DataFrame):
+        return df
+    return pl.DataFrame(batch)

{sdmxlib-0.65.0 → sdmxlib-0.67.0}/src/sdmxlib/formats/sdmx_csv/writer.py

@@ -23,7 +23,7 @@ column maps in their dict-insertion order, which matches the order in
 which they were declared on the structure.
 
 Performance: rows are serialised via Polars' Rust CSV writer
-(``pl.DataFrame(batch).write_csv``) rather than Python's `csv`,
+(``pl.from_arrow(batch).write_csv``) rather than Python's `csv`,
 which makes the writer fast enough that bulk SDMX-CSV downloads are
 network-bound rather than writer-bound (#61).
 
@@ -47,6 +47,7 @@ from typing import TYPE_CHECKING
 
 import polars as pl
 
+from sdmxlib.formats._arrow import frame_of
 from sdmxlib.formats.sdmx_csv.reader import STRUCTURE_KINDS
 from sdmxlib.model.dataflow import Dataflow
 from sdmxlib.model.datastructure import DataStructure
@@ -143,11 +144,9 @@ def write_sdmx_csv(
             )
             raise KeyError(msg)
 
-        # The constructor rather than `pl.from_arrow`, which is typed
-        # `DataFrame | Series` and since polars 2.0 really does return a Series
-        # for stream-only inputs — a `cast` here would have hidden that.
+        # `frame_of`, not the `pl.DataFrame` constructor: 1.33x per batch (#427).
         df = (
-            pl.DataFrame(batch)
+            frame_of(batch)
             .select(data_cols)
             .with_columns(
                 pl.lit(structure).alias("STRUCTURE"),

{sdmxlib-0.65.0 → sdmxlib-0.67.0}/src/sdmxlib/formats/sdmx_json/_data_common.py

@@ -28,6 +28,7 @@ if TYPE_CHECKING:
     from sdmxlib.model.datastructure import Component, DataStructure, Dimension
     from sdmxlib.model.istring import InternationalString
 
+from sdmxlib.formats._arrow import frame_of
 from sdmxlib.formats._coerce import to_int
 from sdmxlib.model.errors import SdmxParseError
 from sdmxlib.model.ref import Ref
@@ -640,11 +641,8 @@ def encode_batch(
         )
         raise KeyError(msg)
 
-    # The constructor, not `pl.from_arrow`: the same frame for a RecordBatch, but
-    # typed `DataFrame` rather than `DataFrame | Series` — and polars 2.0 made
-    # `from_arrow` return a Series for stream-only inputs, which a `cast` would
-    # have passed through unchecked.
-    df = pl.DataFrame(batch)
+    # `frame_of`, not the `pl.DataFrame` constructor: 2.4x on the conversion (#427).
+    df = frame_of(batch)
     n = df.height
     if n == 0:
         return b""

{sdmxlib-0.65.0 → sdmxlib-0.67.0}/src/sdmxlib/formats/sdmx_json/_resolve.py

@@ -12,10 +12,30 @@ from __future__ import annotations
 
 from sdmxlib.formats._index import lookup
 from sdmxlib.model.ref import Ref
-from sdmxlib.model.urn import SdmxUrn
+from sdmxlib.model.urn import ParsesUrn, SdmxUrn
 
 
-def resolve_urn[T](urn_val: object, index: dict[str, object], cls: type[T]) -> Ref[T] | None:
+def resolve_any_urn(urn_val: object, index: dict[str, object]) -> Ref[object] | None:
+    """`resolve_urn` for a reference that may name any artefact.
+
+    A categorisation's source and target, or a constraint's attachment, can be
+    any maintainable, so there is no class to parse the URN as or to guard the
+    resolved object with. Split from `resolve_urn` when `SdmxUrn.parse` became
+    `SdmxUrn[object]` (#399): the typed path parses on the class
+    (`cls.parse_urn`), which `object` has not got, and saying "any" by name
+    here is clearer than an `object` witness there.
+    """
+    if not isinstance(urn_val, str) or not urn_val.startswith("urn:"):
+        return None
+    try:
+        urn = SdmxUrn.parse(urn_val)
+    except (ValueError, TypeError):
+        return None
+    obj = lookup(index, urn)
+    return Ref.of(urn, obj) if obj is not None else Ref.unresolved(urn)
+
+
+def resolve_urn[T: ParsesUrn](urn_val: object, index: dict[str, object], cls: type[T]) -> Ref[T] | None:
     """Parse a URN string and resolve it against the artefact index.
 
     *cls* is both a type witness and a runtime guard: the indexed object is
@@ -27,7 +47,7 @@ def resolve_urn[T](urn_val: object, index: dict[str, object], cls: type[T]) -> R
     if not isinstance(urn_val, str) or not urn_val.startswith("urn:"):
         return None
     try:
-        urn = SdmxUrn.parse(urn_val)
+        urn = cls.parse_urn(urn_val)
     except (ValueError, TypeError):
         return None
     obj = lookup(index, urn)

{sdmxlib-0.65.0 → sdmxlib-0.67.0}/src/sdmxlib/formats/sdmx_json/_structure_ingest.py

@@ -19,7 +19,7 @@ from datetime import date, datetime
 
 from sdmxlib.formats._coerce import to_date, to_datetime, to_int
 from sdmxlib.formats.sdmx_json._dto import ingest_annotations, ingest_istr
-from sdmxlib.formats.sdmx_json._resolve import resolve_urn
+from sdmxlib.formats.sdmx_json._resolve import resolve_any_urn, resolve_urn
 from sdmxlib.formats.sdmx_json._structure_dto import (
     AgencySchemeJson,
     AttributeJson,
@@ -552,8 +552,8 @@ def from_categorisation(cat: CategorisationJson, maintainer: Agency, index: dict
         description=ingest_istr(cat.description, cat.descriptions),
         annotations=ingest_annotations(cat.annotations),
         uri=read_uri(cat.links),
-        source=resolve_urn(cat.source, index, object),
-        target=resolve_urn(cat.target, index, object),
+        source=resolve_any_urn(cat.source, index),
+        target=resolve_any_urn(cat.target, index),
         valid_from=parse_dt(cat.valid_from),
         valid_to=parse_dt(cat.valid_to),
     )
@@ -571,7 +571,7 @@ def from_provision_agreement(
         annotations=ingest_annotations(pa.annotations),
         uri=read_uri(pa.links),
         dataflow=resolve_urn(pa.dataflow, index, Dataflow),
-        data_provider=resolve_urn(pa.data_provider, index, object),
+        data_provider=resolve_any_urn(pa.data_provider, index),
         valid_from=parse_dt(pa.valid_from),
         valid_to=parse_dt(pa.valid_to),
     )
@@ -585,13 +585,13 @@ def from_constraint_attachment(ca: ConstraintAttachmentJson | None, index: dict[
     if ca is None:
         return ConstraintAttachment()
     if ca.dataflows:
-        return ConstraintAttachment(dataflow=resolve_urn(ca.dataflows[0], index, object))
+        return ConstraintAttachment(dataflow=resolve_any_urn(ca.dataflows[0], index))
     if ca.data_structures:
-        return ConstraintAttachment(data_structure=resolve_urn(ca.data_structures[0], index, object))
+        return ConstraintAttachment(data_structure=resolve_any_urn(ca.data_structures[0], index))
     if ca.provision_agreements:
-        return ConstraintAttachment(provision_agreement=resolve_urn(ca.provision_agreements[0], index, object))
+        return ConstraintAttachment(provision_agreement=resolve_any_urn(ca.provision_agreements[0], index))
     if ca.data_provider is not None:
-        return ConstraintAttachment(data_provider=resolve_urn(ca.data_provider, index, object))
+        return ConstraintAttachment(data_provider=resolve_any_urn(ca.data_provider, index))
     return ConstraintAttachment()
 
 
@@ -637,7 +637,7 @@ def _hcode_ref(urn_val: str | None) -> Ref[Code] | None:
     if not isinstance(urn_val, str) or not urn_val.startswith("urn:"):
         return None
     try:
-        return Ref[Code].unresolved(SdmxUrn.parse(urn_val))
+        return Ref[Code].unresolved(Code.parse_urn(urn_val))
     except (ValueError, TypeError) as exc:
         warnings.warn(
             f"Skipping unparseable code URN in hierarchical code: {urn_val!r} ({exc})",
@@ -719,8 +719,8 @@ def from_hierarchy_association(
         valid_from=parse_dt(ha.valid_from),
         valid_to=parse_dt(ha.valid_to),
         linked_hierarchy=resolve_urn(ha.linked_hierarchy, index, Hierarchy),
-        linked_object=resolve_urn(ha.linked_object, index, object),
-        context_object=resolve_urn(ha.context_object, index, object),
+        linked_object=resolve_any_urn(ha.linked_object, index),
+        context_object=resolve_any_urn(ha.context_object, index),
     )
 
 
@@ -888,8 +888,8 @@ def from_concept_scheme_map(
         version=csm.version,
         name=ingest_istr(csm.name, csm.names),
         description=ingest_istr(csm.description, csm.descriptions),
-        source=resolve_urn(csm.source, index, object),
-        target=resolve_urn(csm.target, index, object),
+        source=resolve_any_urn(csm.source, index),
+        target=resolve_any_urn(csm.target, index),
         maps=tuple(maps),
         annotations=ingest_annotations(csm.annotations),
         uri=read_uri(csm.links),
@@ -908,8 +908,8 @@ def from_category_scheme_map(
         version=catm.version,
         name=ingest_istr(catm.name, catm.names),
         description=ingest_istr(catm.description, catm.descriptions),
-        source=resolve_urn(catm.source, index, object),
-        target=resolve_urn(catm.target, index, object),
+        source=resolve_any_urn(catm.source, index),
+        target=resolve_any_urn(catm.target, index),
         maps=tuple(maps),
         annotations=ingest_annotations(catm.annotations),
         uri=read_uri(catm.links),
@@ -926,8 +926,8 @@ def from_structure_map(sm: StructureMapJson, maintainer: Agency, index: dict[str
         version=sm.version,
         name=ingest_istr(sm.name, sm.names),
         description=ingest_istr(sm.description, sm.descriptions),
-        source=resolve_urn(sm.source, index, object),
-        target=resolve_urn(sm.target, index, object),
+        source=resolve_any_urn(sm.source, index),
+        target=resolve_any_urn(sm.target, index),
         maps=tuple(maps),
         annotations=ingest_annotations(sm.annotations),
         uri=read_uri(sm.links),

{sdmxlib-0.65.0 → sdmxlib-0.67.0}/src/sdmxlib/formats/sdmx_json/writer.py

@@ -15,10 +15,12 @@ from typing import Any, NamedTuple
 
 import msgspec
 
+from sdmxlib.model.base import MaintainableArtefact
 from sdmxlib.model.constraint import DataConstraint
 from sdmxlib.model.message import StructureMessage
 from sdmxlib.model.ref import artefact_urn
 from sdmxlib.model.urn import SdmxUrn
+from sdmxlib.model.version import check_writable
 
 from ._dto import ENCODER, Link, Meta, Sender, WireStruct
 from ._structure_dto import (
@@ -187,6 +189,8 @@ def write(
 
     Raises:
         ValueError: If ``metadata_links`` is given without ``base_url``.
+        VersionFormatError: If an artefact's version is one the structure
+            schema's `VersionType` (SDMX-ML 3.0's grammar) does not accept.
     """
     link_base: str | None = None
     if metadata_links:
@@ -195,6 +199,15 @@ def write(
             raise ValueError(msg_err)
         link_base = base_url
 
+    # The structure schema's `VersionType` is SDMX-ML 3.0's, so a version 3.0
+    # refuses would be written here schema-invalid (#417). Checked over every
+    # maintainable before anything is encoded, as the SDMX-ML writers do.
+    for artefact in msg.all_artefacts():
+        if isinstance(artefact, MaintainableArtefact):
+            check_writable(
+                artefact.version, "json", artefact=f"{type(artefact).__name__} {artefact.agency_id}:{artefact.id}"
+            )
+
     data: dict[str, object] = {}
 
     for sec in _SECTIONS:

{sdmxlib-0.65.0 → sdmxlib-0.67.0}/src/sdmxlib/formats/sdmx_ml/_common.py

@@ -51,7 +51,7 @@ from sdmxlib.model.organisation import Agency
 from sdmxlib.model.provision import ProvisionAgreement
 from sdmxlib.model.ref import Ref, SupportsUrn
 from sdmxlib.model.representation import Facet
-from sdmxlib.model.urn import SdmxUrn
+from sdmxlib.model.urn import ParsesUrn, SdmxUrn
 from sdmxlib.model.validation import SdmxConformanceError
 from sdmxlib.model.version import check_writable
 
@@ -506,7 +506,7 @@ class ReaderHelpers:
         el = local_rep_el.find("str:EnumerationFormat", namespaces=self._ns)
         return self.read_text_format(el) if el is not None else None
 
-    def read_representation[T](
+    def read_representation[T: ParsesUrn](
         self,
         local_rep_el: etree._Element,
         index: dict[str, object] | None = None,
@@ -542,7 +542,7 @@ class ReaderHelpers:
                     return Ref[T].unresolved(urn)
             text = (enum_el.text or "").strip()
             if text.startswith("urn:"):
-                urn = SdmxUrn.parse(text)
+                urn = enum_cls.parse_urn(text)
                 _require_urn_class(urn, enum_cls, tag)
                 return Ref[T].unresolved(urn)
         tf_el = local_rep_el.find("str:TextFormat", namespaces=self._ns)
@@ -998,7 +998,7 @@ def _read_codelist_extensions(cl_el: etree._Element, ns: dict[str, str]) -> tupl
         urn_text = cl_ref_el.text.strip()
         if not urn_text.startswith("urn:"):
             continue
-        codelist_ref = Ref[Codelist].unresolved(SdmxUrn.parse(urn_text))
+        codelist_ref = Ref[Codelist].unresolved(Codelist.parse_urn(urn_text))
 
         selection: CodeSelection | None = None
         sel_el = ext_el.find("str:InclusiveCodeSelection", namespaces=ns)

{sdmxlib-0.65.0 → sdmxlib-0.67.0}/src/sdmxlib/local/registry.py

@@ -945,33 +945,18 @@ class LocalRegistry(SessionFactory):
         For Codelists, returns a ``LazyCodelist`` by default (codes not
         materialized). Pass ``eager=True`` to get a real ``Codelist``.
 
-        **A `SdmxUrn[Any]` reads as `LazyCodelist | None` under basedpyright,
-        whatever the URN names — and that is the checker, not this ordering
-        (#399).** Typing-spec step 5 makes the call *ambiguous*: more than one
-        overload still matches and their return types are not equivalent, so a
-        checker must infer a gradual type assignable to each. pyrefly answers
-        `Any`. basedpyright applies the rule for an argument that *is* `Any`
-        and not for one nested inside a generic, which is what `SdmxUrn[Any]`
-        is — the case the spec illustrates with its own `list[Any]` example.
-
-        Two things not to do about it. **Reordering does not help:** put the
-        generic overload first and `get(Codelist.urn_for(...))` goes back to
-        claiming `Codelist` for a `LazyCodelist`, the silent lie #397 removed,
-        and the explicit spelling is the common one. **Narrowing
-        `SdmxUrn.parse` to `SdmxUrn[object]`** — #399's option 2 — measures at
-        52 basedpyright + 27 pyrefly findings, every one the same fact: a
-        `Ref[object]` does not go where a `Ref[Codelist]` is wanted. `Ref` is
-        *covariant* (see `Ref`'s own class comment and #289), so the assignment
-        that works is the other direction; narrowing `parse` asks for this one,
-        which covariance does not give. They are sites of correct code, not
-        defects.
-
-        Pass a typed URN where you have one; narrow with `isinstance` where you
-        do not. `tests/typing/probe_urn_any.py` pins the declared types and
-        `tests/unit/test_overload_any_ambiguity.py` the disagreement, so this
-        caveat comes due for deletion on its own when basedpyright conforms.
-
-        **`expect=` is the way out that does not wait on any of that (#406).**
+        **An untyped URN answers `object | None`.** `SdmxUrn.parse(text)` and
+        `artefact_urn(x)` are `SdmxUrn[object]` (#399): a URN string can name
+        anything, so this cannot say which class comes back, and the caller
+        narrows. A typed URN — `Codelist.urn_for(...)`, `Codelist.parse_urn(text)`,
+        `artefact.urn` — picks the matching overload and its class.
+
+        Until #399 those were `SdmxUrn[Any]`, which made the call ambiguous
+        across these overloads; basedpyright then answered a confident, wrong
+        `LazyCodelist | None` and pyrefly an unchecked `Any | None`.
+        `tests/typing/probe_urn_any.py` pins what is declared now.
+
+        **`expect=` names the class when the URN does not carry it (#406).**
         It names the class, so `T` comes from the argument rather than from the
         URN's phantom, and the ambiguity above never arises:
 
@@ -1336,7 +1321,7 @@ class LocalRegistry(SessionFactory):
         `tests/unit/test_query_applicability.py` compares them.
         """
         rows = self._applicability(dataflow, dim_id)
-        return [Ref[Hierarchy].unresolved(SdmxUrn.parse(urn)) for urn, _ha, _scoped in rows]
+        return [Ref[Hierarchy].unresolved(Hierarchy.parse_urn(urn)) for urn, _ha, _scoped in rows]
 
     def unique_hierarchy(
         self,
@@ -1378,7 +1363,7 @@ class LocalRegistry(SessionFactory):
                 dataflow_urn=str(artefact_urn(dataflow)),
                 ha_urns=sorted(association for _h, association, _s in chosen),
             )
-        return Ref[Hierarchy].unresolved(SdmxUrn.parse(rows[0][0]))
+        return Ref[Hierarchy].unresolved(Hierarchy.parse_urn(rows[0][0]))
 
     # ── The data plane ────────────────────────────────────────────────────