statcatlib 0.10.0__tar.gz → 0.11.0__tar.gz

{statcatlib-0.10.0 → statcatlib-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: statcatlib
-Version: 0.10.0
+Version: 0.11.0
 Summary: Queryable open data catalog engine for DCAT-AP, StatDCAT-AP, CKAN, and SDMX
 Keywords: sdmx,dcat,open-data,catalog,duckdb,statistical-data,ckan
 Author: gabrielgellner
@@ -39,7 +39,7 @@ Description-Content-Type: text/markdown
 > take that into account before adopting it.
 
 **statcatlib** is a Python library for building, managing, and querying
-statistical metadata catalogs. Formerly published as `pinaxlib`.
+statistical metadata catalogs.
 
 **Documentation:** <https://statcat-suite.github.io/statcatlib/>
 
@@ -61,9 +61,9 @@ statcatlib materializes remote catalog and structural metadata into a local
 DuckDB database and exposes a fluent Python API for discovery queries —
 filtering by publisher, theme, dimension, code, free text, or provenance lineage.
 
-**The catalog is a materialized graph.** Rather than federated queries across
-separate REST endpoints, ingest pulls the full structural model into one database.
-SQL JOINs are the graph traversal. No network round-trips at query time.
+**The catalog is a materialized graph.** Ingest pulls the full structural model
+into one database, SQL JOINs are the graph traversal, and a query makes no
+network calls.
 
 ## Installation
 
@@ -85,7 +85,7 @@ import statcatlib as sc
 import statcatlib.query as q
 import sdmxlib as sl
 
-# Creates my_catalog/bundle.duckdb and my_catalog/parquet/
+# Creates my_catalog/ with meta.duckdb, lake.ducklake and parquet/
 with sc.Catalog("my_catalog").open() as store:
     with sl.RestRegistry(sl.Provider.ESTAT) as reg:
         reg.get(sl.Dataflow.urn_for(agency="ESTAT", id="NAMA_10_GDP"), resolve=True)
@@ -142,8 +142,13 @@ with sc.Catalog("my_catalog").open() as store:
             reg.get(sl.Dataflow.urn_for(agency="ESTAT", id=df_id), resolve=True)
         sc.ingest_sdmx(store, reg.registry)
 
-        # Stream observation data to Parquet, attach as Distribution
+        # Write observations to the bundle's DuckLake and bind them to the dataflow
         sc.ingest_data(store, reg, "ESTAT:NAMA_10_GDP(latest)", measure_dim="na_item")
+
+    # Read them back through the co-located sdmxlib registry
+    ds = store.get(sc.AggregateDataset, "ESTAT:NAMA_10_GDP(1.0)")
+    obs = store.registry.obs(sl.Dataflow.parse_urn(ds.sdmx_dataflow_urn))
+    wide = obs.pivot(on=ds.measure_dim)   # a polars.DataFrame
 ```
 
 ### CKAN (open.canada.ca, data.gov, ...)
@@ -285,7 +290,7 @@ Use `.include()` to declare exactly which relationships to batch-load — the re
 are set to an `UNLOADED` sentinel:
 
 ```python
-# Only load publisher and themes — 3 queries instead of ~17
+# Load publisher, themes and keywords only: 3 queries instead of ~17
 results = (
     store.query(sc.BaseDataset)
     .filter(status="published")
@@ -295,7 +300,7 @@ results = (
     .all()
 )
 
-# Explicit full hydration — useful to make the cost visible at the call site
+# Explicit full hydration shows the cost at the call site
 results = store.query(sc.BaseDataset).filter(...).full().all()
 
 # get() always loads everything — no include() needed
@@ -398,12 +403,13 @@ Three layers share one DuckDB database:
 ```
 Discovery layer  — Catalog            (dataset, agent, concept_scheme, concept, distribution, lineage)
 Structural layer — sdmxlib tables     (dataflows, dsd_components, codes, codelists)
-Observation layer — Polars / Parquet  (actual time-series data)
+Observation layer — DuckLake tables  (actual time-series data, under parquet/)
 ```
 
 statcatlib owns the discovery layer. sdmxlib owns the structural layer. Both write
-to the same DuckDB connection — queries JOIN freely across both. Parquet files live
-alongside the database and are referenced via DCAT `Distribution` records.
+to the same DuckDB connection, and queries JOIN freely across both. `ingest_data()`
+writes each dataflow's observations to a DuckLake table and registers an sdmxlib
+`DataflowBinding`, through which `store.registry.obs(flow)` reads them.
 
 ## Development
 
@@ -415,12 +421,12 @@ just hooks-install
 ```
 
 ```bash
-just ci                # full gate: index guard + lint + format + docstrings + Any ratchet + both type checkers + unit tests + strict docs build
+just ci                # full gate: index guard + lint + format + docstrings + prose + Any ratchet + pyrefly + unit and integration tests + strict docs build
 just test              # unit tests
 just test-integration  # integration tests (no network)
 just test-live         # live tests against real SDMX endpoints
 just lint              # ruff check
-just typecheck         # basedpyright
+just typecheck         # pyrefly
 just check-indexes     # only public PyPI is named anywhere in the repo
 just docs              # local docs server
 ```

{statcatlib-0.10.0 → statcatlib-0.11.0}/README.md

@@ -5,7 +5,7 @@
 > take that into account before adopting it.
 
 **statcatlib** is a Python library for building, managing, and querying
-statistical metadata catalogs. Formerly published as `pinaxlib`.
+statistical metadata catalogs.
 
 **Documentation:** <https://statcat-suite.github.io/statcatlib/>
 
@@ -27,9 +27,9 @@ statcatlib materializes remote catalog and structural metadata into a local
 DuckDB database and exposes a fluent Python API for discovery queries —
 filtering by publisher, theme, dimension, code, free text, or provenance lineage.
 
-**The catalog is a materialized graph.** Rather than federated queries across
-separate REST endpoints, ingest pulls the full structural model into one database.
-SQL JOINs are the graph traversal. No network round-trips at query time.
+**The catalog is a materialized graph.** Ingest pulls the full structural model
+into one database, SQL JOINs are the graph traversal, and a query makes no
+network calls.
 
 ## Installation
 
@@ -51,7 +51,7 @@ import statcatlib as sc
 import statcatlib.query as q
 import sdmxlib as sl
 
-# Creates my_catalog/bundle.duckdb and my_catalog/parquet/
+# Creates my_catalog/ with meta.duckdb, lake.ducklake and parquet/
 with sc.Catalog("my_catalog").open() as store:
     with sl.RestRegistry(sl.Provider.ESTAT) as reg:
         reg.get(sl.Dataflow.urn_for(agency="ESTAT", id="NAMA_10_GDP"), resolve=True)
@@ -108,8 +108,13 @@ with sc.Catalog("my_catalog").open() as store:
             reg.get(sl.Dataflow.urn_for(agency="ESTAT", id=df_id), resolve=True)
         sc.ingest_sdmx(store, reg.registry)
 
-        # Stream observation data to Parquet, attach as Distribution
+        # Write observations to the bundle's DuckLake and bind them to the dataflow
         sc.ingest_data(store, reg, "ESTAT:NAMA_10_GDP(latest)", measure_dim="na_item")
+
+    # Read them back through the co-located sdmxlib registry
+    ds = store.get(sc.AggregateDataset, "ESTAT:NAMA_10_GDP(1.0)")
+    obs = store.registry.obs(sl.Dataflow.parse_urn(ds.sdmx_dataflow_urn))
+    wide = obs.pivot(on=ds.measure_dim)   # a polars.DataFrame
 ```
 
 ### CKAN (open.canada.ca, data.gov, ...)
@@ -251,7 +256,7 @@ Use `.include()` to declare exactly which relationships to batch-load — the re
 are set to an `UNLOADED` sentinel:
 
 ```python
-# Only load publisher and themes — 3 queries instead of ~17
+# Load publisher, themes and keywords only: 3 queries instead of ~17
 results = (
     store.query(sc.BaseDataset)
     .filter(status="published")
@@ -261,7 +266,7 @@ results = (
     .all()
 )
 
-# Explicit full hydration — useful to make the cost visible at the call site
+# Explicit full hydration shows the cost at the call site
 results = store.query(sc.BaseDataset).filter(...).full().all()
 
 # get() always loads everything — no include() needed
@@ -364,12 +369,13 @@ Three layers share one DuckDB database:
 ```
 Discovery layer  — Catalog            (dataset, agent, concept_scheme, concept, distribution, lineage)
 Structural layer — sdmxlib tables     (dataflows, dsd_components, codes, codelists)
-Observation layer — Polars / Parquet  (actual time-series data)
+Observation layer — DuckLake tables  (actual time-series data, under parquet/)
 ```
 
 statcatlib owns the discovery layer. sdmxlib owns the structural layer. Both write
-to the same DuckDB connection — queries JOIN freely across both. Parquet files live
-alongside the database and are referenced via DCAT `Distribution` records.
+to the same DuckDB connection, and queries JOIN freely across both. `ingest_data()`
+writes each dataflow's observations to a DuckLake table and registers an sdmxlib
+`DataflowBinding`, through which `store.registry.obs(flow)` reads them.
 
 ## Development
 
@@ -381,12 +387,12 @@ just hooks-install
 ```
 
 ```bash
-just ci                # full gate: index guard + lint + format + docstrings + Any ratchet + both type checkers + unit tests + strict docs build
+just ci                # full gate: index guard + lint + format + docstrings + prose + Any ratchet + pyrefly + unit and integration tests + strict docs build
 just test              # unit tests
 just test-integration  # integration tests (no network)
 just test-live         # live tests against real SDMX endpoints
 just lint              # ruff check
-just typecheck         # basedpyright
+just typecheck         # pyrefly
 just check-indexes     # only public PyPI is named anywhere in the repo
 just docs              # local docs server
 ```

{statcatlib-0.10.0 → statcatlib-0.11.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "statcatlib"
-version = "0.10.0"
+version = "0.11.0"
 description = "Queryable open data catalog engine for DCAT-AP, StatDCAT-AP, CKAN, and SDMX"
 license = "Apache-2.0"
 license-files = ["LICENSE"]
@@ -71,59 +71,40 @@ allow-init-docstring = true
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+strict = true
+filterwarnings = ["error"]
 markers = [
     "unit: fast, in-process tests with no network I/O",
-    "docs: doctests and example-script tests",
     "integration: tests that use real DuckDB and sdmxlib but no network",
     "live: tests that make real HTTP calls to external SDMX endpoints",
 ]
 
-[tool.basedpyright]
-pythonVersion = "3.14"
-typeCheckingMode = "standard"
-venvPath = "."
-venv = ".venv"
-exclude = [
-    "scripts",
-    ".venv",
-]
-reportMissingTypeArgument = "error"
-reportMissingParameterType = "error"
-reportUnnecessaryCast = "error"
-reportInvalidCast = "error"
-reportPropertyTypeMismatch = "error"
-reportInconsistentConstructor = "error"
-reportUnnecessaryContains = "error"
-reportDeprecated = "error"
-reportUnsafeMultipleInheritance = "error"
-reportTypeCommentUsage = "error"
-reportSelfClsParameterName = "error"
-reportUnnecessaryTypeIgnoreComment = "error"
-reportAny = "none"
-reportExplicitAny = "none"
-reportUnknownVariableType = "none"
-
-[[tool.basedpyright.executionEnvironments]]
-root = "tests"
-extraPaths = ["."]
-reportMissingParameterType = "none"
-reportTypedDictNotRequiredAccess = "none"
+[tool.coverage.run]
+source = ["src/statcatlib"]
 
-[[tool.basedpyright.executionEnvironments]]
-root = "src"
+[tool.coverage.report]
+show_missing = true
+skip_covered = false
+fail_under = 85
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+    "@overload",
+]
 
 [dependency-groups]
 dev = [
-    "basedpyright>=1.38.4",
     "lancedb>=0.39",
     "mkdocs-material>=9.7.6",
     "polars>=1.39.3",
-    "pydoclint>=0.9.1",
-    "pyrefly>=1.2.0",
+    "pydoclint>=0.11.1,<0.12",
+    "pyrefly>=1.4.0,<1.5",
     "pytest>=9.0.3",
+    "pytest-cov>=7.1.0",
     "pytest-httpx>=0.35",
     "rich>=15.0",
-    "ruff>=0.15.8",
+    "ruff>=0.17.1,<0.18",
     "sentence-transformers>=3.0",
     "typer>=0.15",
     "watchfiles>=1.1.1",

{statcatlib-0.10.0 → statcatlib-0.11.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "statcatlib"
-version = "0.10.0"
+version = "0.11.0"
 description = "Queryable open data catalog engine for DCAT-AP, StatDCAT-AP, CKAN, and SDMX"
 license = "Apache-2.0"
 license-files = ["LICENSE"]
@@ -74,91 +74,53 @@ allow-init-docstring = true
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+# `strict` makes an unregistered marker a collection error: a typo such as
+# `pytest.mark.uint` would otherwise drop a whole file out of `just ci`, which
+# selects by marker (GH-8). It also rejects duplicate parametrize ids.
+strict = true
+# A warning that cannot fail is a warning nobody reads. The suite raised seven
+# when this went on, all statcatlib's own: each test now asserts the warning
+# its setup provokes, or avoids it as a real caller would. No ignore list.
+filterwarnings = ["error"]
 markers = [
     "unit: fast, in-process tests with no network I/O",
-    "docs: doctests and example-script tests",
     "integration: tests that use real DuckDB and sdmxlib but no network",
     "live: tests that make real HTTP calls to external SDMX endpoints",
 ]
 
+[tool.coverage.run]
+source = ["src/statcatlib"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false
+# 88% when this was set (2026-10-23, `just coverage`). A floor, a little under
+# that, so a change that drops a module's tests fails here. `sources/sdmx.py`
+# is the lowest at 54%: `ingest_data` is reached only by the `live` tier.
+fail_under = 85
+exclude_lines = [
+  "pragma: no cover",
+  "if TYPE_CHECKING:",
+  "raise NotImplementedError",
+  "@overload",
+]
+
 [dependency-groups]
 dev = [
-    "basedpyright>=1.38.4",
     "lancedb>=0.39",
     "mkdocs-material>=9.7.6",
     "polars>=1.39.3",
-    "pydoclint>=0.9.1",
-    "pyrefly>=1.2.0",
+    # The checkers are capped, as sdmxlib's are: uv.lock is gitignored, so an
+    # uncapped checker's next release would change what `just ci` reports
+    # without a commit. A bump goes in its own PR, with its findings fixed.
+    "pydoclint>=0.11.1,<0.12",
+    "pyrefly>=1.4.0,<1.5",
     "pytest>=9.0.3",
+    "pytest-cov>=7.1.0",
     "pytest-httpx>=0.35",
     "rich>=15.0",
-    "ruff>=0.15.8",
+    "ruff>=0.17.1,<0.18",
     "sentence-transformers>=3.0",
     "typer>=0.15",
     "watchfiles>=1.1.1",
 ]
-
-[tool.basedpyright]
-pythonVersion = "3.14"
-typeCheckingMode = "standard"
-venvPath = "."
-venv = ".venv"
-exclude = ["scripts", ".venv"]
-# Strict-mode rules that are clean on this codebase (0 findings each, measured
-# on the commit that turned them on), enabled as regression guards rather than
-# as a cleanup. Borrowed from sdmxlib, which runs the same set — see #106.
-#
-# The first two are basedpyright's Any-degradation catchers: a bare generic
-# (`list` rather than `list[str]`) and an untyped parameter both silently
-# become Any.
-reportMissingTypeArgument = "error"
-reportMissingParameterType = "error"
-# Dead casts, getter/setter drift, __init__/__new__ disagreement, and
-# always-true/false `in` checks. Pure hardening.
-reportUnnecessaryCast = "error"
-reportInvalidCast = "error"
-reportPropertyTypeMismatch = "error"
-reportInconsistentConstructor = "error"
-reportUnnecessaryContains = "error"
-reportDeprecated = "error"
-reportUnsafeMultipleInheritance = "error"
-reportTypeCommentUsage = "error"
-reportSelfClsParameterName = "error"
-# Suppression hygiene, and the rule that keeps the .claude suppression guard
-# honest in the other direction: an ignore that outlived its defect is a lie
-# the next reader believes. Found 6 the day it went on, none of which were
-# hiding anything.
-reportUnnecessaryTypeIgnoreComment = "error"
-#
-# NOT enabled: reportCallInDefaultInitializer (23 findings). `ruff.toml`
-# already ignores B008, which is the same concern — turning this on would
-# contradict a decision the project has already made. Recorded here so the
-# next person diffing against sdmxlib's config does not re-litigate it.
-reportAny = "none"
-reportExplicitAny = "none"
-reportUnknownVariableType = "none"
-
-# `tests/` is type-checked too (#116) — the gap let a wrong `tmp_path`
-# annotation stand behind 25 suppressions, and hid three dead ignores from
-# `reportUnnecessaryTypeIgnoreComment`, which exists to catch exactly those.
-#
-# Annotation-completeness rules stay off there. `ruff.toml` already exempts
-# tests from `ANN`; demanding parameter types here would contradict that
-# decision rather than extend it. Measured: 285 of basedpyright's 416
-# findings over `tests/` were this one rule, and neither bug the gap hid was
-# an annotation-coverage finding.
-[[tool.basedpyright.executionEnvironments]]
-root = "tests"
-# `from tests.conftest import …` is how the suite shares fixtures; without the
-# repo root on the path the package does not resolve from inside `tests`.
-extraPaths = ["."]
-reportMissingParameterType = "none"
-# 48 — a test collects rows of one kind and reads that kind's keys, which
-# `SearchRow` cannot express: every extension key is `NotRequired` because it
-# belongs to one row kind, deliberately and per its docstring. The rule is
-# right in `src`, where the kind is not known locally, and cannot see the
-# narrowing a test performs by construction.
-reportTypedDictNotRequiredAccess = "none"
-
-[[tool.basedpyright.executionEnvironments]]
-root = "src"

{statcatlib-0.10.0 → statcatlib-0.11.0}/src/statcatlib/expr.py

@@ -5,7 +5,7 @@ any SQL.  They are context-free objects — like ``pl.col()`` in Polars — and
 can be reused across ``.enrich()``, ``.filter()``, and ``.sort_by()`` on any
 collection scope.
 
-Usage::
+Usage:
 
     import statcatlib as sc
 

{statcatlib-0.10.0 → statcatlib-0.11.0}/src/statcatlib/model/dataset.py

@@ -119,7 +119,7 @@ class AggregateDataset(BaseDataset):
     num_series: int | None = None
     # SDMX link: FK into sdmxlib's dataflows.urn in the shared DuckDB
     sdmx_dataflow_urn: str | None = None
-    # Pivot axis dimension for ingest_data(). None = auto-detect from DSD.
+    # Default pivot axis for readers, recorded by ingest_data(). None = the DSD's MeasureDimension.
     measure_dim: str | None = None
 
 

{statcatlib-0.10.0 → statcatlib-0.11.0}/src/statcatlib/model/skos.py

@@ -134,8 +134,14 @@ def is_concept_in_scheme(scheme: ConceptScheme, notation: str) -> bool:
     Pure-Python — no DuckDB or any other storage involved.
     Useful for validation pipelines that operate on in-memory domain objects.
 
-    Example::
+    Args:
+        scheme: The concept scheme.
+        notation: The concept's notation.
 
+    Returns:
+        Whether *scheme* lists *notation* among its concepts.
+
+    Example:
         valid = is_concept_in_scheme(product_type_scheme, dataset.dataset_type.notation)
     """
     return notation in scheme.concepts

{statcatlib-0.10.0 → statcatlib-0.11.0}/src/statcatlib/query.py

@@ -1,6 +1,6 @@
 """Composable filter objects for Catalog queries.
 
-Usage::
+Usage:
 
     import statcatlib.query as q
 
@@ -630,8 +630,7 @@ def within(
             ``q.hcode.ancestors``, which excludes the node itself.
         codelist_urn: Optional codelist URN to disambiguate same-named dimensions across DSDs.
 
-    Example::
-
+    Example:
         store.query(sc.AggregateDataset).filter(
             q.within("REF_AREA", "ON", hierarchy=h_geo_statistical_urn)
         )
@@ -653,8 +652,13 @@ def has_dimensions(dims: list[str]) -> SdmxDimensionFilter | _NoOpFilter:
     JOINs through ``sdmx.dataflow → sdmx.dsd_component``.
     An empty list matches all datasets.
 
-    Example::
+    Args:
+        dims: The dimension ids every matching DSD must have.
+
+    Returns:
+        The filter, or one that matches everything when *dims* is empty.
 
+    Example:
         store.query(sc.AggregateDataset).filter(q.has_dimensions(["GEO", "SEX"])).execute()
     """
     if not dims:
@@ -676,8 +680,14 @@ def distribution(**kwargs: object) -> ExistsFilter:
         .filter(q.distribution(format="CSV"))
         .filter(q.distribution(format="JSON"))
 
-    Example::
+    Args:
+        **kwargs: Column values one distribution must all match: ``format``,
+            ``media_type``, ``service_type`` or ``endpoint_url``.
+
+    Returns:
+        An EXISTS filter over the dataset's distributions.
 
+    Example:
         store.query(sc.BaseDataset).filter(q.distribution(media_type="text/csv")).execute()
     """
     service_keys = {"service_type", "endpoint_url"}
@@ -709,8 +719,13 @@ def has_service(**kwargs: object) -> ExistsFilter:
 
     Supported keys: ``service_type``, ``endpoint_url``.
 
-    Example::
+    Args:
+        **kwargs: Column values the data service must all match.
+
+    Returns:
+        An EXISTS filter over the dataset's distributions and their services.
 
+    Example:
         store.query(sc.BaseDataset).filter(
             q.has_service(endpoint_url="https://example.com/sdmx")
         ).execute()
@@ -849,8 +864,14 @@ def publishes(*inner_filters: PositionalFilter, **kwargs: object) -> ExistsFilte
     positional arguments, and/or dataset-level conditions as keyword arguments
     (``kind``, ``status``).
 
-    Example::
+    Args:
+        *inner_filters: Filters a published dataset must match.
+        **kwargs: Dataset columns a published dataset must match.
 
+    Returns:
+        An EXISTS filter over the agent's datasets.
+
+    Example:
         # Agents that publish aggregate datasets about Ontario
         store.query(sc.Agent).filter(
             q.publishes(q.has_code("GEO", "ON"), kind="aggregate")
@@ -865,8 +886,14 @@ def serves(*inner_filters: PositionalFilter, **kwargs: object) -> ExistsFilter:
     Pass ``ExistsFilter`` objects as positional arguments and/or dataset-level
     conditions as keyword arguments (``kind``, ``status``).
 
-    Example::
+    Args:
+        *inner_filters: Filters a served dataset must match.
+        **kwargs: Dataset columns a served dataset must match.
+
+    Returns:
+        An EXISTS filter over the service's datasets.
 
+    Example:
         # DataServices that serve datasets with a GEO dimension
         store.query(sc.DataService).filter(q.serves(q.has_dimensions(["GEO"]))).all()
     """
@@ -881,8 +908,14 @@ def serves(*inner_filters: PositionalFilter, **kwargs: object) -> ExistsFilter:
 def has_spatial(label: str, *, lang: str = "en") -> ExistsFilter:
     """Filter datasets that have a spatial coverage matching *label*.
 
-    Example::
+    Args:
+        label: The spatial coverage label, matched exactly.
+        lang: The language of *label*.
 
+    Returns:
+        An EXISTS filter over the dataset's spatial coverage.
+
+    Example:
         store.query(sc.BaseDataset).filter(q.has_spatial("Canada")).execute()
     """
     return ExistsFilter(
@@ -894,8 +927,14 @@ def has_spatial(label: str, *, lang: str = "en") -> ExistsFilter:
 def has_keyword(keyword: str, *, lang: str = "en") -> ExistsFilter:
     """Filter datasets that have a keyword matching *keyword*.
 
-    Example::
+    Args:
+        keyword: The keyword, matched exactly.
+        lang: The language of *keyword*.
+
+    Returns:
+        An EXISTS filter over the dataset's keywords.
 
+    Example:
         store.query(sc.BaseDataset).filter(q.has_keyword("employment")).execute()
     """
     return ExistsFilter(
@@ -907,8 +946,14 @@ def has_keyword(keyword: str, *, lang: str = "en") -> ExistsFilter:
 def title_contains(text: str, *, lang: str = "en") -> MapFilter:
     """Filter datasets whose title contains *text* (case-insensitive).
 
-    Example::
+    Args:
+        text: The text to find, anywhere in the title.
+        lang: Which language's title to search.
+
+    Returns:
+        A filter on the dataset's title in *lang*.
 
+    Example:
         store.query(sc.BaseDataset).filter(q.title_contains("GDP")).execute()
     """
     return MapFilter(column="title", key=lang, value=text, op="ilike")
@@ -917,8 +962,14 @@ def title_contains(text: str, *, lang: str = "en") -> MapFilter:
 def description_contains(text: str, *, lang: str = "en") -> MapFilter:
     """Filter datasets whose description contains *text* (case-insensitive).
 
-    Example::
+    Args:
+        text: The text to find, anywhere in the description.
+        lang: Which language's description to search.
+
+    Returns:
+        A filter on the dataset's description in *lang*.
 
+    Example:
         store.query(sc.BaseDataset).filter(q.description_contains("exchange")).execute()
     """
     return MapFilter(column="description", key=lang, value=text, op="ilike")

{statcatlib-0.10.0 → statcatlib-0.11.0}/src/statcatlib/sources/sdmx.py

@@ -6,7 +6,7 @@ This is the only statcatlib module that imports sdmxlib beyond InternationalStri
 from __future__ import annotations
 
 import re
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Protocol
 
 from sdmxlib import InternationalString
 from sdmxlib.model.dataflow import Dataflow
@@ -16,14 +16,16 @@ from statcatlib.model.agents import Agent
 from statcatlib.model.dataset import AggregateDataset
 
 if TYPE_CHECKING:
-    from sdmxlib.api.registry import RestRegistry
+    from sdmxlib import ObsQuery
     from sdmxlib.local.registry import LocalRegistry
     from sdmxlib.model.in_memory_registry import InMemoryRegistry
+    from sdmxlib.model.urn import SdmxUrn
 
     from statcatlib.model.skos import ConceptRef
     from statcatlib.store.store import Catalog
 
 __all__ = [
+    "ObservationSource",
     "dataset_from_dataflow",
     "ingest_data",
     "ingest_sdmx",
@@ -34,6 +36,17 @@ __all__ = [
 _IDENTIFIER_RE = re.compile(r"^([^:]+):([^(]+)\(([^)]+)\)$")
 
 
+class ObservationSource(Protocol):
+    """Where `ingest_data` reads observations from.
+
+    `sdmxlib.RestRegistry` is the usual one; `sdmxlib.LocalRegistry` fits too.
+    """
+
+    def obs(self, flow: SdmxUrn[Dataflow], /) -> ObsQuery:
+        """A lazy query over *flow*'s observations."""
+        ...
+
+
 def _resolve_latest(store: Catalog, identifier: str) -> str:
     """Resolve ``(latest)`` to the highest stored version for that agency:id."""
     if not identifier.endswith("(latest)"):
@@ -237,31 +250,40 @@ def _query_dimension_names(conn: object, dataflow_urn: str) -> list[Internationa
 
 def ingest_data(
     store: Catalog,
-    reg: RestRegistry,
+    reg: ObservationSource,
     identifier: str,
     *,
     measure_dim: str | None = None,
 ) -> str:
     """Materialise observation data for one dataflow into the bundle's lake.
 
-    Fetches the observations wide via ``reg.obs(...).pivot()``, writes them
-    into ``lake.<agency>.df_<id>_<version>`` through the bundle's
-    DuckLake-backed data store, and registers a
-    `sdmxlib.DataflowBinding` so the dataflow is queryable through
-    ``cat.observations(...)``.
+    Fetches the observations from *reg* in the long layout, one row per
+    observation with a column per dimension and measure, and writes them into
+    ``lake.<agency>.df_<id>_<version>`` through the bundle's DuckLake-backed
+    data store. A re-run replaces the table. It then registers a
+    `sdmxlib.DataflowBinding` for that table, so the dataflow reads back
+    through the co-located registry::
+
+        obs = cat.registry.obs(flow_urn)
+        obs.filter(obs.col("GEO") == "CA").frame()
+        obs.pivot(on=ds.measure_dim)
 
     Requires that ``ingest_sdmx`` has already been called for this
-    identifier so the catalog record exists, and that ``store`` is a
-    folder-mode `Catalog` (a DuckLake is ATTACHed on ``open()``).
+    identifier, so the catalog record and the DSD are stored, and that
+    ``store`` is a folder-mode `Catalog` (a DuckLake is ATTACHed on
+    ``open()``).
 
     Args:
         store: The catalog holding the `AggregateDataset` for *identifier*.
             Must be folder-mode — a DuckLake is ATTACHed on ``open()``.
-        reg: REST registry to fetch observations from.
+        reg: Where to fetch observations from, usually a
+            `sdmxlib.RestRegistry`.
         identifier: Catalog identifier in ``AGENCY:ID(VERSION)`` form.
             ``(latest)`` resolves to the highest stored version.
-        measure_dim: Dimension to pivot into measure columns. ``None``
-            (default) pivots on the DSD's ``MeasureDimension``.
+        measure_dim: The dimension readers pivot on, recorded as
+            `AggregateDataset.measure_dim`. It does not change what is
+            stored. ``None`` (default) records none, and ``pivot()`` then
+            uses the DSD's ``MeasureDimension``.
 
     Returns:
         The fully-qualified table location (``<schema>.<table>``).
@@ -271,9 +293,12 @@ def ingest_data(
             ``ingest_sdmx`` first.
         ValueError: The dataset carries no ``sdmx_dataflow_urn``, so there is
             nothing to fetch observations for; *identifier* is not in
-            ``AGENCY:ID(VERSION)`` form; or *measure_dim* is ``None`` and the
-            DSD declares no ``MeasureDimension`` to pivot on.
+            ``AGENCY:ID(VERSION)`` form; the dataflow's DSD is not stored, so
+            no binding can describe the table; or *measure_dim* is not one of
+            the DSD's dimensions.
     """
+    import sdmxlib as sl  # noqa: PLC0415
+
     identifier = _resolve_latest(store, identifier)
 
     ds = store.get(AggregateDataset, identifier)
@@ -290,31 +315,31 @@ def ingest_data(
         raise ValueError(msg)
     agency, flow_id, version = m.group(1), m.group(2), m.group(3)
 
-    schema = agency.lower()
-    table = f"df_{flow_id}_{version.replace('.', '_')}".lower()
-
-    # Pull the wide dataframe and write through the bundle's lake. ``pivot()``
-    # returns an eager DataFrame; with ``on=None`` it pivots on the DSD's
-    # MeasureDimension, as ``reg.data(...).pivot()`` did.
     flow_urn = Dataflow.parse_urn(ds.sdmx_dataflow_urn)
-    wide = reg.obs(flow_urn).pivot(on=measure_dim)
-    store.data.write_observations(schema=schema, table=table, source=wide)
+    dsd = store.registry.dsd(flow_urn)
+    if dsd is None:
+        msg = f"The DSD of {ds.sdmx_dataflow_urn} is not stored — run ingest_sdmx with resolve=True first"
+        raise ValueError(msg)
+    dimensions = [d.id for d in dsd.dimensions]
+    if measure_dim is not None and measure_dim not in dimensions:
+        msg = f"measure_dim {measure_dim!r} is not a dimension of {dsd.id}: {', '.join(dimensions)}"
+        raise ValueError(msg)
 
-    # Register a DataflowBinding so ``cat.observations(flow_urn)`` can find
-    # the table. Derive identity column maps from the DSD when resolvable.
-    import sdmxlib as sl  # noqa: PLC0415
+    schema = agency.lower()
+    table = f"df_{flow_id}_{version.replace('.', '_')}".lower()
 
-    flow = store.registry.get(flow_urn)
-    if isinstance(flow, Dataflow) and isinstance(flow.structure, sl.Ref):
-        dsd = store.registry.get(flow.structure.urn)
-        if isinstance(dsd, DataStructure):
-            binding = sl.DataflowBinding.from_dsd(
-                dsd,
-                dataflow=sl.Ref[Dataflow].unresolved(flow_urn),
-                schema=schema,
-                table=table,
-            )
-            store.registry.add(binding)
+    # Store the long layout. The binding below maps each DSD component to a
+    # column of the same name, which is the long layout; a pivoted table has a
+    # column per code instead and cannot be read through it (GH-29).
+    store.data.write_observations(schema=schema, table=table, source=reg.obs(flow_urn).frame())
+    store.registry.add(
+        sl.DataflowBinding.from_dsd(
+            dsd,
+            dataflow=sl.Ref[Dataflow].unresolved(flow_urn),
+            schema=schema,
+            table=table,
+        )
+    )
 
     ds.measure_dim = measure_dim
     store.put(ds)

{statcatlib-0.10.0 → statcatlib-0.11.0}/src/statcatlib/store/lance.py

@@ -933,18 +933,18 @@ class _LanguageIndex:
     ) -> list[Bm25HitRow]:
         """Run a BM25 query, returning raw result rows.
 
-        The `# pyright: ignore[reportReturnType]` below is this module's only
-        suppression, and is the shape sdmxlib's CLAUDE.md prescribes for a
-        gradual-typing boundary: the one unsafe step, kept to the accessor
-        that performs it. `to_list()` is declared `List[dict[Unknown, Unknown]]`
+        The `# pyrefly: ignore[bad-return]` below (and its twin in `vector`)
+        is this module's only suppression, and is the shape sdmxlib's
+        CLAUDE.md prescribes for a gradual-typing boundary: the one unsafe
+        step, kept to the accessor that performs it. `to_list()` is declared `List[dict[Unknown, Unknown]]`
         — LanceDB hands back rows of the schema *this module declared* and
         says nothing about their shape. Validating 19 keys per row on every
         search to recover what `make_schema` already guarantees would cost
         more than it proves.
 
-        Not `# type: ignore`: that form is unattributable, so neither checker
-        can tell a dead comment from one carrying the other's error, and
-        `reportUnnecessaryTypeIgnoreComment` stops being trustworthy.
+        Not `# type: ignore`: that form names no checker and no error kind,
+        so a dead one cannot be told from a live one, and pyrefly's
+        `unused-ignore` stops being trustworthy.
         """
         if self._tbl is None:
             return []
@@ -957,7 +957,7 @@ class _LanguageIndex:
             where = self._where(*filters)
             if where:
                 search = search.where(where, prefilter=True)
-            return search.limit(limit).select(select_cols).to_list()  # pyright: ignore[reportReturnType] # pyrefly: ignore[bad-return]
+            return search.limit(limit).select(select_cols).to_list()  # pyrefly: ignore[bad-return]
         except Exception:  # noqa: BLE001
             return []
 
@@ -978,7 +978,7 @@ class _LanguageIndex:
             where = self._where(*filters)
             if where:
                 search = search.where(where, prefilter=True)
-            return search.limit(limit).select(select_cols).to_list()  # pyright: ignore[reportReturnType] # pyrefly: ignore[bad-return]
+            return search.limit(limit).select(select_cols).to_list()  # pyrefly: ignore[bad-return]
         except Exception:  # noqa: BLE001
             return []
 

{statcatlib-0.10.0 → statcatlib-0.11.0}/src/statcatlib/store/scopes.py

@@ -4,7 +4,7 @@ Scopes represent positions in the catalog graph.  Navigation builds new
 scopes without executing SQL; only terminal methods (``.collect()``,
 ``.count()``) hit the database.
 
-Usage::
+Usage:
 
     store.themes["https://example.com/themes"].collect()  # ItemList[ConceptRef]
     store.themes["https://example.com/themes"]["13"].collect()  # Concept
@@ -143,9 +143,10 @@ class _SdmxEdge(TypedDict):
 #:
 #: Discriminated on an explicit ``kind`` rather than on key presence. Testing
 #: ``"custom_count_sql" in edge`` to conclude ``custom_exists_sql`` also exists
-#: is sound given the TypedDicts, but only basedpyright narrows it; pyrefly
-#: reported reading the second key as an error. Two checkers disagreeing about
-#: whether a branch is safe is reason enough to say which branch it is.
+#: is sound given the TypedDicts, but pyrefly reports reading the second key as
+#: an error, where basedpyright (run beside it until GH-7) narrowed it. Two
+#: checkers disagreeing about whether a branch is safe is reason enough to say
+#: which branch it is.
 type _Edge = _BridgeEdge | _SdmxEdge
 
 
@@ -1131,8 +1132,16 @@ class DatasetScope:
 
         Supported edges: ``"codelist"``.
 
-        Example::
+        Args:
+            edge: The kind of entity the datasets share.
+
+        Returns:
+            A query over the datasets linked to this one through *edge*.
 
+        Raises:
+            ValueError: *edge* is not a supported edge type.
+
+        Example:
             store.dataset("id").related("codelist").include("publisher").limit(10).collect()
         """
         from statcatlib.model.dataset import BaseDataset  # noqa: PLC0415
@@ -1163,8 +1172,14 @@ class DatasetScope:
 
         Gremlin equivalent: ``g.V(id).repeat(in('derivedFrom')).times(depth)``
 
-        Example::
+        Args:
+            relationship: Follow only lineage edges of this relationship; all of them when ``None``.
+            depth: How many lineage hops to follow.
+
+        Returns:
+            A query over this dataset's ancestors, to *depth* hops.
 
+        Example:
             store.dataset("id").upstream(depth=3).include("publisher").collect()
         """
         from statcatlib.model.dataset import BaseDataset  # noqa: PLC0415
@@ -1207,8 +1222,14 @@ class DatasetScope:
 
         Gremlin equivalent: ``g.V(id).repeat(out('derivedFrom')).times(depth)``
 
-        Example::
+        Args:
+            relationship: Follow only lineage edges of this relationship; all of them when ``None``.
+            depth: How many lineage hops to follow.
+
+        Returns:
+            A query over this dataset's descendants, to *depth* hops.
 
+        Example:
             store.dataset("id").downstream().include("publisher").collect()
         """
         from statcatlib.model.dataset import BaseDataset  # noqa: PLC0415

{statcatlib-0.10.0 → statcatlib-0.11.0}/src/statcatlib/store/sentinel.py

@@ -18,8 +18,10 @@ _cache: dict[str, _UnloadedType] = {}
 class NotLoadedError(AttributeError):
     """Raised when accessing a relationship that was not loaded in this query.
 
-    Example::
+    Args:
+        field: The relationship that was not loaded, as `include` names it.
 
+    Example:
         ds = store.query(BaseDataset).include("publisher").first()
         ds.themes  # NotLoadedError: 'themes' was not loaded.
         #   Add 'themes' to .include() or call .full().
@@ -86,7 +88,7 @@ def make_unloaded(field: str) -> Any:
 
     (No `# noqa: ANN401` yet — ANN401 is still ignored project-wide until
     #109 step 3, and a suppression that suppresses nothing is the thing
-    `reportUnnecessaryTypeIgnoreComment` exists to catch. Add it with the
+    pyrefly's `unused-ignore` exists to catch. Add it with the
     rule.)
     """
     if field not in _cache:

{statcatlib-0.10.0 → statcatlib-0.11.0}/src/statcatlib/store/store.py

@@ -36,7 +36,7 @@ from sdmxlib import InternationalString
 from sdmxlib.model.registry import artefact_urn
 from sdmxlib.storage.schema import SCHEMA_VERSION as _SDMX_SCHEMA_VERSION
 
-from statcatlib.bundle import Embedded
+from statcatlib.bundle import Embedded, normalize_lake_data_path, read_current_data_path
 from statcatlib.model.agents import Agent, ContactPoint
 from statcatlib.model.classification import Standard
 from statcatlib.model.dataset import (
@@ -543,9 +543,10 @@ class _EntitySpec[R: NamedTuple, E]:
 
     Bounding ``R`` by `NamedTuple` is what makes `columns` derivable —
     it is the one spelling of "a row type" that basedpyright *and* pyrefly
-    both accept. A `Protocol` carrying ``_fields`` does not: declared
-    `ClassVar` (which it truly is) basedpyright rejects ``type[R]``;
-    declared as an instance attribute pyrefly rejects the specialization.
+    both accepted while both ran (until GH-7). A `Protocol` carrying
+    ``_fields`` did not: declared `ClassVar` (which it truly is) basedpyright
+    rejected ``type[R]``; declared as an instance attribute pyrefly rejects
+    the specialization.
 
     Attributes:
         table: The DuckDB table name, unqualified.
@@ -590,8 +591,8 @@ class EmbeddingModel(Protocol):
     ``inputs`` (older versions: ``sentences``), and declares a return union
     wide enough to include ``dict[str, Tensor]``. Promising
     ``-> Iterable[float]`` here was the first attempt and no real encoder
-    satisfied it; worse, narrowing to it with `isinstance` is unsound, and
-    basedpyright says so — a runtime_checkable Protocol checks method
+    satisfied it; worse, narrowing to it with `isinstance` is unsound, as
+    basedpyright reported — a runtime_checkable Protocol checks method
     *presence*, never signatures.
 
     So: two overloads, one per shape statcatlib passes, `object` out, and
@@ -1157,7 +1158,7 @@ class _SortSpec:
 #:
 #: A union rather than `Hit[object]` because attrs generics are invariant:
 #: `Hit` is frozen and `SearchResult.items` could be a `Sequence`, and
-#: basedpyright still reports the parameter invariant, since the synthesised
+#: basedpyright reported the parameter invariant, since the synthesised
 #: `__init__` puts `T` in a parameter position. `Hit[CodeHit]` is therefore not
 #: a `Hit[object]`, and no amount of freezing changes that.
 type AnyHit = Hit[BaseDataset] | Hit[CodeHit] | Hit[ConceptHit] | Hit[ReferenceMetadataHit]
@@ -2847,8 +2848,8 @@ class Catalog:
         # abfss:// URI) via ``data_path``.
         if self._bundle_dir is not None:
             attach_url = f"'ducklake:{self._bundle_dir / 'lake.ducklake'}'"
-            data_path_literal = self._resolve_data_path(self._bundle_dir)
-            attach_options = self._attach_options(data_path_literal)
+            data_path_literal, override = self._resolve_data_path(self._bundle_dir)
+            attach_options = self._attach_options(data_path_literal, override=override)
 
             self._data = sdmxlib.DuckDBDataStore.from_registry(
                 self._registry,
@@ -2914,7 +2915,11 @@ class Catalog:
                 msg = "data_path is not supported with an in-memory catalog (':memory:')"
                 raise ValueError(msg)
             return duckdb.connect(":memory:"), None
-        path = Path(self._uri)
+        # Absolute, so the stamp DuckLake records on first open is too: a
+        # relative one is resolved against whatever the working directory is
+        # when the lake is read (GH-23). `absolute()`, not `resolve()`, which
+        # follows symlinks and would respell a catalog created by absolute path.
+        path = Path(self._uri).absolute()
         if self._read_only:
             meta_path = path / "meta.duckdb"
             if not meta_path.exists():
@@ -2929,7 +2934,7 @@ class Catalog:
         path.mkdir(parents=True, exist_ok=True)
         return duckdb.connect(str(path / "meta.duckdb")), path
 
-    def _attach_options(self, data_path_literal: str | None) -> str:
+    def _attach_options(self, data_path_literal: str | None, *, override: bool = False) -> str:
         """Render the DuckLake ATTACH option list.
 
         A ``None`` literal means honour the lake's own stamp: DuckLake only
@@ -2944,31 +2949,73 @@ class Catalog:
         allowed under ``READ_ONLY``. The default (``data_path=None``) stays
         a checked ``<bundle>/parquet/``, so a plain ``Catalog(path)`` on a
         split bundle still fails at ATTACH rather than reading an empty
-        local directory.
+        local directory. *override* is the one exception, for a read-only
+        open of a catalog stamped with a relative path (`_resolve_data_path`).
         """
         opts = [] if data_path_literal is None else [f"DATA_PATH '{data_path_literal}'"]
-        if data_path_literal is not None and self._data_path is not None:
+        if data_path_literal is not None and (self._data_path is not None or override):
             opts.append("OVERRIDE_DATA_PATH true")
         if self._read_only:
             opts.append("READ_ONLY")
         return f"({', '.join(opts)})" if opts else ""
 
-    def _resolve_data_path(self, bundle_dir: Path) -> str | None:
-        """Return the DuckLake DATA_PATH literal, with trailing slash.
+    def _resolve_data_path(self, bundle_dir: Path) -> tuple[str | None, bool]:
+        """Return the DuckLake DATA_PATH literal, with trailing slash, and whether to override.
 
         Remote URIs (``abfss://``, ``s3://``, ``gs://``, etc.) are passed
         through verbatim; local paths are rendered as ``<bundle>/parquet/``
-        when no override is set.
+        when no override is set, reconciled with the lake's stamp by
+        `_colocated_data_path`.
 
         Returns `None` for `statcatlib.bundle.Embedded` — meaning "omit the
         option entirely and let the lake's own stamp stand".
         """
         if isinstance(self._data_path, Embedded):
-            return None
+            return None, False
         if self._data_path is None:
-            return f"{bundle_dir / 'parquet'}/"
+            return self._colocated_data_path(bundle_dir)
         raw = str(self._data_path)
-        return raw if raw.endswith("/") else f"{raw}/"
+        return (raw if raw.endswith("/") else f"{raw}/"), False
+
+    def _colocated_data_path(self, bundle_dir: Path) -> tuple[str, bool]:
+        """The DATA_PATH for a default open: ``<bundle>/parquet/``, as the lake spells it.
+
+        DuckLake compares DATA_PATH with its stamp as strings, so the same
+        directory spelled differently was refused (GH-23). The stamp is read
+        first:
+
+        - the same directory, spelled any way (a relative open, a symlink):
+          passed back verbatim, which DuckLake accepts unchanged;
+        - relative and ending in ``<bundle name>/parquet``, as
+          ``Catalog("relative")`` stamped it before GH-23: DuckLake resolves
+          it against the working directory, so it is replaced by the absolute
+          path. A read-write open rewrites the stamp, which repairs the
+          catalog; a read-only one overrides it for this attach only;
+        - anything else, a remote URI or another directory: the absolute
+          path, unchanged, so a split bundle still fails at ATTACH rather than
+          reading an empty local directory.
+        """
+        parquet = bundle_dir / "parquet"
+        target = f"{parquet}/"
+        lake = bundle_dir / "lake.ducklake"
+        if not lake.exists():
+            return target, False
+        try:
+            stamp = read_current_data_path(lake)
+        except duckdb.Error, FileNotFoundError:
+            return target, False
+        stamped = Path(stamp)
+        if "://" in stamp or stamp == target:
+            return target, False
+        if stamped.is_absolute():
+            return (stamp, False) if stamped.resolve() == parquet.resolve() else (target, False)
+        colocated = stamped.name == "parquet" and stamped.parent.name in {"", bundle_dir.name}
+        if not colocated:
+            return target, False
+        if self._read_only:
+            return target, True
+        normalize_lake_data_path(lake, target)
+        return target, False
 
     @classmethod
     def from_connection(
@@ -3228,8 +3275,10 @@ class Catalog:
         the caller's responsibility — the encoder name is opaque to
         statcatlib.
 
-        Example::
+        Args:
+            model: The encoder, the one `embedding_model_name` names.
 
+        Example:
             store = Catalog("data/catalog").open()
             if store.embedding_model_name:
                 from sentence_transformers import SentenceTransformer
@@ -6391,7 +6440,7 @@ class Catalog:
         # arg 2 must be a type`. Found by trying it; five tests failed.
         # Entity queries never see the alias, which is why the same fix holds
         # there.
-        items: list[T] = [  # pyright: ignore[reportAssignmentType] # pyrefly: ignore[bad-assignment]
+        items: list[T] = [  # pyrefly: ignore[bad-assignment]
             ds_by_id[ident] for ident in qr.rows if ident in ds_by_id
         ]
 
@@ -6447,7 +6496,7 @@ class Catalog:
         # returns `Any` here, and the `isinstance` is what soundly recovers `T`
         # — the bridge back from runtime dispatch to the declared return type,
         # not a redundant assertion. It is also why this path needs no
-        # `pyright: ignore` while the dataset path above does.
+        # suppression while the dataset path above does.
         items: list[T] = []
         for raw in rows:
             item = spec.build(raw)

{statcatlib-0.10.0 → statcatlib-0.11.0}/src/statcatlib/urn.py

@@ -48,8 +48,15 @@ def _build(package: str, artefact_class: str, agency: str, artefact_id: str, ver
 def codelist(agency: str, id: str, version: str = "1.0") -> str:  # noqa: A002
     """Build a codelist URN string.
 
-    Example::
+    Args:
+        agency: The maintenance agency's id.
+        id: The codelist's id.
+        version: Its version.
 
+    Returns:
+        The URN, as SDMX spells it.
+
+    Example:
         sc.urn.codelist("SDMX", "CL_GEO", "1.0")
         # → "urn:sdmx:org.sdmx.infomodel.codelist.Codelist=SDMX:CL_GEO(1.0)"
     """
@@ -59,8 +66,15 @@ def codelist(agency: str, id: str, version: str = "1.0") -> str:  # noqa: A002
 def dataflow(agency: str, id: str, version: str = "1.0") -> str:  # noqa: A002
     """Build a dataflow URN string.
 
-    Example::
+    Args:
+        agency: The maintenance agency's id.
+        id: The dataflow's id.
+        version: Its version.
+
+    Returns:
+        The URN, as SDMX spells it.
 
+    Example:
         sc.urn.dataflow("ESTAT", "NAMA_10_GDP", "1.0")
         # → "urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=ESTAT:NAMA_10_GDP(1.0)"
     """
@@ -70,8 +84,15 @@ def dataflow(agency: str, id: str, version: str = "1.0") -> str:  # noqa: A002
 def data_structure(agency: str, id: str, version: str = "1.0") -> str:  # noqa: A002
     """Build a data structure definition URN string.
 
-    Example::
+    Args:
+        agency: The maintenance agency's id.
+        id: The data structure definition's id.
+        version: Its version.
+
+    Returns:
+        The URN, as SDMX spells it.
 
+    Example:
         sc.urn.data_structure("ESTAT", "DSD_NAMA_10_GDP", "1.0")
         # → "urn:sdmx:org.sdmx.infomodel.datastructure.DataStructure=ESTAT:DSD_NAMA_10_GDP(1.0)"
     """
@@ -81,8 +102,15 @@ def data_structure(agency: str, id: str, version: str = "1.0") -> str:  # noqa:
 def concept_scheme(agency: str, id: str, version: str = "1.0") -> str:  # noqa: A002
     """Build a concept scheme URN string.
 
-    Example::
+    Args:
+        agency: The maintenance agency's id.
+        id: The concept scheme's id.
+        version: Its version.
 
+    Returns:
+        The URN, as SDMX spells it.
+
+    Example:
         sc.urn.concept_scheme("SDMX", "CS_FREQ", "1.0")
         # → "urn:sdmx:org.sdmx.infomodel.conceptscheme.ConceptScheme=SDMX:CS_FREQ(1.0)"
     """
@@ -92,17 +120,18 @@ def concept_scheme(agency: str, id: str, version: str = "1.0") -> str:  # noqa:
 def parse(urn: str) -> SdmxUrn[object]:
     """Parse a URN string into its components.
 
-    Returns an ``SdmxUrn`` object with ``.agency``, ``.id``, ``.version``,
-    ``.package``, and ``.artefact_class`` attributes.
+    Args:
+        urn: An SDMX URN string. One that is not valid raises `ValueError`.
 
-    Example::
+    Returns:
+        The parsed URN, with ``.agency``, ``.id``, ``.version``, ``.package``
+        and ``.artefact_class``.
 
+    Example:
         parsed = sc.urn.parse("urn:sdmx:org.sdmx.infomodel.codelist.Codelist=SDMX:CL_GEO(1.0)")
         parsed.agency  # "SDMX"
         parsed.id  # "CL_GEO"
         parsed.version  # "1.0"
         str(parsed)  # round-trips to original URN string
-
-    Raises ``ValueError`` if the string is not a valid SDMX URN.
     """
     return SdmxUrn.parse(urn)