Metadata-Version: 2.4
Name: pysiebanxico
Version: 0.1.0
Summary: Independent Python client for Banco de México's SIE API
Project-URL: Homepage, https://github.com/guadaloop-07/pysiebanxico
Project-URL: Documentation, https://github.com/guadaloop-07/pysiebanxico#readme
Project-URL: Repository, https://github.com/guadaloop-07/pysiebanxico
Project-URL: Issues, https://github.com/guadaloop-07/pysiebanxico/issues
Project-URL: Changelog, https://github.com/guadaloop-07/pysiebanxico/blob/main/CHANGELOG.md
Author-email: Guadalupe Castillo <guadalupe.csln@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: banxico,economics,mexico,sie,time-series
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: requests>=2.31
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: pre-commit>=4.0; extra == 'dev'
Requires-Dist: pytest-cov>=6.0; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Requires-Dist: twine>=6.0; extra == 'dev'
Provides-Extra: pandas
Requires-Dist: pandas>=2.0; extra == 'pandas'
Description-Content-Type: text/markdown

# pysiebanxico

[![CI](https://github.com/guadaloop-07/pysiebanxico/actions/workflows/ci.yml/badge.svg)](https://github.com/guadaloop-07/pysiebanxico/actions/workflows/ci.yml)

An independent Python client for querying time series, historical data, and
metadata from Banco de México's Economic Information System (SIE).

> Status: version 0.1.0 is the initial public release. The public API will
> continue to evolve through documented, versioned releases.

## Goal

`pysiebanxico` aims to provide a clear, typed, and tested interface for the SIE
REST API. The initial public release covers historical data, current values,
metadata, and optional pandas conversions. It does not include frequency
conversion or a graphical interface.

## Installation

Install the package from PyPI:

```bash
python3 -m pip install pysiebanxico
```

## Planned usage

```python
from pysiebanxico import BanxicoClient

client = BanxicoClient()  # Reads BANXICO_TOKEN from the environment.
series = client.get_series_data(["SF43718"], start_date="2024-01-01", end_date="2024-12-31")

for observation in series[0].observations:
    print(observation.date, observation.value)
```

The client also exposes `get_current_value()` for the latest published
observation and `get_series_metadata()` for series titles in Spanish or English.
It automatically splits requests containing more than 20 series, the maximum
accepted by the SIE API. For transient network failures, server errors, or rate
limits, opt into limited retries with `BanxicoClient(max_retries=2)`.

Values such as `N/E`, `N.D.`, `ND`, `NA`, and `N/A` are exposed as `None` while
the original text remains available through `Observation.raw_value`.

## Data utilities

Use dependency-free helpers to index results or export plain records:

```python
from pysiebanxico import index_by_id, to_records

fix = index_by_id(series)["SF43718"]
records = to_records(series)
```

For pandas integration, install the optional extra:

```bash
python3 -m pip install "pysiebanxico[pandas]"
```

```python
from pysiebanxico.pandas import metadata_to_dataframe, to_dataframe

long = to_dataframe(series)
wide = to_dataframe(series, layout="wide")
metadata_frame = metadata_to_dataframe(metadata)
```

The long layout contains `series_id`, `title`, `date`, `value`, and `raw_value`.
The wide layout uses dates as its index and series identifiers as columns.

## Development

```bash
python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install -e ".[dev,pandas]"
pre-commit install
pre-commit run --all-files
pytest
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for the complete workflow.

## Security

Each user must use their own SIE token. Do not commit tokens, `.env` files,
`tokens.yaml`, PyPI credentials, or API responses that contain them. Report
security issues according to [SECURITY.md](SECURITY.md).

## Independence notice

This project is an independent library. It is not affiliated with, sponsored by,
or endorsed by Banco de México. It uses Banco de México's public SIE API and
requires each user to provide their own token.

## License

Distributed under the [MIT License](LICENSE).
