Metadata-Version: 2.3
Name: sdmxlib
Version: 0.18.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.0.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: lxml>=6.0.2
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:
    dsd = reg.get(sl.DataStructure, agency="BIS", id="WS_CBPOL").resolve()

    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 @ git+https://gitlab.com/gabrielgellner/sdmxlib.git"
```

## 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`
- Three resolution modes: `browse()` for catalogue scanning, `fetch()` for
  unresolved artefacts, `resolve()` for the full reference graph (with optional
  constraint-trimming via `partial=True/False`)
- 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
  with lazy codelist loading, automatic Ref resolution, and direct SQL
  code maps; supports shared connections and any-language queries
- 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
  `LocalRegistry`, JSON, and XML.
- Integrates with [Polars](https://pola.rs) for schema generation and data
  validation
- Fully typed — IDE completion and static analysis work throughout

## Documentation

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

- Connecting to registries and choosing a resolution mode
- Persisting artefacts in a local DuckDB store with `LocalRegistry`
- Fetching observation data with `sl.dim()` filters 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
```
