Metadata-Version: 2.3
Name: sdmxlib
Version: 0.50.0
Summary: SDMX structural metadata library for Python
Keywords: sdmx,statistics,metadata,datastructure
Author: gabrielgellner
Author-email: gabrielgellner <gabrielgellner@gmail.com>
License: Apache-2.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Dist: attrs>=26.1.0
Requires-Dist: duckdb>=1.5.3
Requires-Dist: httpx>=0.28.1
Requires-Dist: lxml>=6.0.2
Requires-Dist: msgspec>=0.19
Requires-Dist: polars>=1.39.3
Requires-Dist: pyarrow>=18.0.0
Requires-Python: >=3.13
Project-URL: Homepage, https://gitlab.com/pinax-suite/sdmxlib
Project-URL: Repository, https://gitlab.com/pinax-suite/sdmxlib
Project-URL: Documentation, https://pinax-suite.gitlab.io/sdmxlib
Project-URL: Changelog, https://gitlab.com/pinax-suite/sdmxlib/-/blob/main/CHANGELOG.md
Description-Content-Type: text/markdown

# sdmxlib

> **Note:** This library has been written extensively with AI assistance
> (Claude Code). Users who are not comfortable with AI-generated code should
> take that into account before adopting it.

SDMX structural metadata library for Python. Fetch and navigate Data Structure
Definitions, Codelists, Dataflows, and related artefacts from any SDMX REST
endpoint — with plain attribute access, no XML or URN chasing required.

## Quick start

```python
import sdmxlib as sl

with sl.RestRegistry(sl.Provider.BIS) as reg:
    urn = sl.DataStructure.urn_for(agency="BIS", id="WS_CBPOL")
    dsd = reg.get(urn, resolve=True)

    for dim in dsd.dimensions:
        if dim.is_enumerated:
            cl = dim.representation()
            print(f"{dim.id}: {cl.id} ({len(cl.codes)} codes)")
```

```
FREQ: CL_FREQ (7 codes)
REF_AREA: CL_BIS_IF_REF_AREA (44 codes)
INSTR_ASSET: CL_INSTR_ASSET (12 codes)
BORROWER_CTY: CL_BIS_IF_REF_AREA (44 codes)
```

## Installation

```bash
uv add sdmxlib
# or: pip install sdmxlib
```

## What it does

- Connects to any SDMX 2.1 or 3.0 REST endpoint; built-in shortcuts for ECB,
  BIS, ESTAT, IMF, OECD, and the SDMX Global Registry via `sl.Provider`
- One read, with resolution depth as a parameter: `get(urn)` for a skeleton,
  `get(urn, resolve=True)` for the full reference graph, `resolve=[sl.Codelist]`
  for named types only, and `partial=False` for untrimmed schemes
- Returns fully resolved domain objects with plain attribute access — no XML,
  no URN chasing
- Filter collections with lambdas or the `item()` expression API
- Build SDMX artefacts locally and serialise to SDMX-ML or SDMX-JSON
- `LocalRegistry` — a DuckDB-backed persistent store for offline access, and
  a position in a `RestRegistry`'s source chain via `store=`
- A path query language over both planes: `reg.query(sl.q.dataflow)` for
  structures, `reg.observations(flow)` for rows
  with lazy codelist + hierarchy loading, automatic Ref resolution, and
  direct SQL code maps; supports shared connections and any-language queries
- Uniform SKOS-aligned tree API (`roots`/`leaves`/`narrower`/`broader`/
  `*_transitive`/`depth_of` plus bulk projections `depths`/`broader_map`/
  `ancestors_map`/`inherit_along_broader`) on `Codelist`, `Hierarchy`,
  `CategoryScheme`, `MetadataStructure` — and their lazy SQL variants
  `LazyCodelist`/`LazyHierarchy`
- Reference metadata via `MetadataStructure` (MSD), `Metadataflow`, and
  `MetadataSet` — attach typed footnotes, methodology notes, or quality
  reports to any identifiable artefact. Definitions ride in
  `StructureMessage`; populated payloads ride in `MetadataMessage`
  (`<mes:GenericMetadata>` in SDMX-ML 3.0; metadata-schema envelope in
  SDMX-JSON 2.0). Both message kinds round-trip through
  `Registry`, JSON, and XML.
- Integrates with [Polars](https://pola.rs) for schema generation and data
  validation
- Fully typed — IDE completion and static analysis work throughout

## For AI assistants

Two condensed reference files at the repo root are written for LLM tools
(Claude Code, Cursor, Copilot, etc.):

- [`llms.txt`](llms.txt) — full library overview: install, registries,
  data fetching, reference metadata, and the domain-type cheat sheet
- [`llms-dsl.txt`](llms-dsl.txt) — focused query-DSL reference:
  `sl.item` / `sl.q` / `sl.dim` predicates, the `Query` / `Frame` /
  `DataQuery` chains, and the uniform SKOS tree API

Point your assistant at these to keep generated code aligned with the
library's actual surface.

## Upgrading

sdmxlib is pre-stability and breaks cleanly rather than carrying two spellings
of the same idea. If you are coming from **0.48**, read
[Upgrading](https://pinax-suite.gitlab.io/sdmxlib/upgrading/) — `sl.Registry`
is now `sl.LocalRegistry`, `get()` takes a URN and a resolution depth, and the
four query DSLs are one path language.

## Documentation

See the [docs](https://pinax-suite.gitlab.io/sdmxlib/) for the full cookbook,
including:

- Connecting to registries and choosing a resolution depth
- Persisting artefacts in a local DuckDB store with `LocalRegistry`
- Querying structures and observations with the `sl.q` path language
- Fetching observation data and pivoting to wide format
- Inspecting DSDs and building code maps for ETL pipelines
- Generating Polars schemas from SDMX Data Structure Definitions
- Browsing data catalogs and filtering dataflows
- Working with constraints, hierarchies, and serialisation

## Development

```bash
just check           # lint + typecheck
just test            # unit tests
just test-integration  # live endpoint tests (requires network)
just ci              # full pre-commit gate
```
