Metadata-Version: 2.4
Name: statwrapper
Version: 0.1.1
Summary: A completely dependency-free unified wrapper around common statistical api types
Author-email: Nordic Intel <info@nordicintel.com>
License-Expression: Apache-2.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=8.3.5; extra == "dev"
Requires-Dist: pytest-asyncio>=0.26.0; extra == "dev"
Requires-Dist: build>=1.2.2; extra == "dev"
Requires-Dist: ruff>=0.11.0; extra == "dev"

# statwrapper

`statwrapper` is a dependency-free Python library that provides a unified interface for common statistical API families. It currently ships wrapper support for:

- `pxweb`
- `pxweb2`
- `dst`
- `eurostat`

The package standardizes three operations across providers:

- health checks
- dataset discovery
- dataset metadata resolution

## Installation

```bash
pip install statwrapper
```

## Quick Start

```python
import asyncio

from statwrapper import StatWrapper


async def main() -> None:
    wrapper = StatWrapper()

    discovered = await wrapper.discover_datasets("scb", "en")
    first = discovered[0]

    metadata = await wrapper.resolve_dataset_metadata(first)
    print(metadata.label)
    print(metadata.dimension_ids)


asyncio.run(main())
```

## Public API

### `StatWrapper`

```python
from statwrapper import StatWrapper

wrapper = StatWrapper()
```

Methods:

- `await wrapper.discover_datasets(provider_code, language, task_id=None)`
- `await wrapper.resolve_dataset_metadata(discovered, task_id=None)`
- `wrapper.get_provider(provider_code)`
- `wrapper.get_wrapper(provider_code, language)`

### Convenience Functions

```python
from statwrapper import discover_provider_datasets, get_datasets
```

- `await discover_provider_datasets(provider_code, language)`
- `get_datasets(provider_code, language)`

## Request Layer

The default request layer is a stdlib-backed async helper:

```python
from statwrapper import RateLimitedSession
```

`StatWrapper` uses `RateLimitedSession` automatically, but you can inject your own session object if it exposes:

- `async def get_json(url, **kwargs)`
- `async def get_text(url, **kwargs)`
- `async def get_bytes(url, **kwargs)`

## Provider Registry

Provider metadata is loaded from `PROVIDERS.json`. During development, the package reads the repository file. In built distributions, the same data is bundled inside the package.

## Development

Run tests:

```bash
python -m pytest tests/unit tests/integration -q
```

Build locally:

```bash
python -m build
```

## Publishing

PyPI publishing is handled by GitHub Actions through `.github/workflows/pypi_publish.yml` and the repository secret `PYPI_API_TOKEN`.
