Metadata-Version: 2.4
Name: bcch-sdk
Version: 2.0.0
Summary: Python SDK for the Banco Central de Chile SieteRestWS API.
License-Expression: MIT
License-File: LICENSE.md
Keywords: banco-central-chile,bcch,central-bank,economic-data,siete
Author: Eli-ezer Reuven Ramirez Ruiz
Author-email: ramirez.ruiz.eliezer.reuven@gmail.com
Requires-Python: >=3.12
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Provides-Extra: dataframe
Provides-Extra: pandas
Provides-Extra: polars
Requires-Dist: httpx-retries (>=0.6.0,<0.7.0)
Requires-Dist: httpx[brotli,zstd] (>=0.28.1,<0.29.0)
Requires-Dist: pandas (>=3.0.3,<4.0.0) ; extra == "dataframe"
Requires-Dist: pandas (>=3.0.3,<4.0.0) ; extra == "pandas"
Requires-Dist: polars (>=1.42.1,<2.0.0) ; extra == "dataframe"
Requires-Dist: polars (>=1.42.1,<2.0.0) ; extra == "polars"
Requires-Dist: pydantic (>=2.13.4,<3.0.0)
Project-URL: Changelog, https://github.com/ezer-mackenzie/bcch-sdk/blob/main/CHANGELOG.md
Project-URL: Documentation, https://ezer-mackenzie.github.io/bcch-sdk/
Project-URL: Homepage, https://github.com/ezer-mackenzie/bcch-sdk
Project-URL: Issues, https://github.com/ezer-mackenzie/bcch-sdk/issues
Project-URL: Repository, https://github.com/ezer-mackenzie/bcch-sdk
Description-Content-Type: text/markdown

# Banco Central Chile SDK

[![CI](https://github.com/ezer-mackenzie/bcch-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/ezer-mackenzie/bcch-sdk/actions/workflows/ci.yml)
[![Codecov](https://codecov.io/gh/ezer-mackenzie/bcch-sdk/branch/main/graph/badge.svg)](https://codecov.io/gh/ezer-mackenzie/bcch-sdk)
[![Documentation](https://github.com/ezer-mackenzie/bcch-sdk/actions/workflows/mkdocs.yml/badge.svg)](https://ezer-mackenzie.github.io/bcch-sdk/)
[![PyPI](https://img.shields.io/pypi/v/bcch-sdk.svg)](https://pypi.org/project/bcch-sdk/)
[![Python](https://img.shields.io/pypi/pyversions/bcch-sdk.svg)](https://pypi.org/project/bcch-sdk/)
[![License](https://img.shields.io/pypi/l/bcch-sdk.svg)](https://github.com/ezer-mackenzie/bcch-sdk/blob/main/LICENSE)

A Python client library for the Banco Central de Chile SieteRestWS API.

This repository provides sync and async wrappers over the API, returning data as `pandas.DataFrame` or `polars.DataFrame` and managing retries, timeout configuration, and error handling.

## Features

- Synchronous and asynchronous SDK layers
- Built-in HTTP retries using `httpx-retries`
- Configurable `httpx.Timeout`
- Configurable sync/async concurrency limit
- `get_series(...)` and `search_series(...)`
- Output as `pandas.DataFrame` or `polars.DataFrame`
- Standard `logging` integration using `logging.getLogger(__name__)`
- Typed configuration and credentials

## Requirements

- Python 3.12+
- `httpx[brotli,zstd]`
- `pydantic`
- `httpx-retries`

Pandas and Polars are optional in v2. Install only the backend your application
uses.

## Installation

This project uses a `src/` layout and exposes the `bcch_sdk` package.

Use Poetry if available:

```bash
poetry install
```

For an installed package, choose an extra:

```bash
python -m pip install "bcch-sdk[polars]"
python -m pip install "bcch-sdk[pandas]"
python -m pip install "bcch-sdk[dataframe]"  # both backends
```

Or install the runtime dependencies manually:

```bash
python -m pip install httpx[brotli,zstd] pydantic httpx-retries
```

If you want to run code from the repository directly, make sure the `src/` folder is on `PYTHONPATH`:

```bash
export PYTHONPATH=$(pwd)/src
```

## Quickstart

Import the SDK classes and configure the client using `BCChConfig`.

### Sync example

```python
from httpx import Timeout
from bcch_sdk import BCChSyncSDK
from bcch_sdk.types import BCChConfig

config = BCChConfig(
    credentials={"username": "your_user", "password": "your_pass"},
    timeout=Timeout(10.0),
    max_concurrency=8,
)

sdk = BCChSyncSDK(configuration=config)

series_data = sdk.get_series(
    time_series="SF6041",
    first_date="2023-01-01",
    last_date="2023-12-31",
    polars_response=False,
)

print(series_data)
```

### Async example

```python
import asyncio
from httpx import Timeout
from bcch_sdk import BCChAsyncSDK
from bcch_sdk.types import BCChConfig

async def main() -> None:
    config = BCChConfig(
        credentials={"username": "your_user", "password": "your_pass"},
        timeout=Timeout(10.0),
    )

    sdk = BCChAsyncSDK(configuration=config)

    series_data = await sdk.get_series(
        time_series=["SF6041", "SF6060"],
        first_date="2023-01-01",
        last_date="2023-12-31",
        polars_response=True,
    )

    print(series_data)

asyncio.run(main())
```

### Search series example

```python
from bcch_sdk.types import Frequency

result = sdk.search_series(Frequency.MONTHLY, polars_response=False)
print(result)
```

## Configuration

The main configuration object is `BCChConfig` from `bcch_sdk.types.config`.

`max_concurrency` controls both the maximum thread workers used by the sync SDK
and in-flight tasks used by the async SDK. It defaults to 8 and must be greater
than zero.

The Banco Central API requires credentials in its query string. The SDK does
not log query parameters, but HTTPX logs complete request URLs at `INFO`; keep
the `httpx` logger at `WARNING` or higher in production.

Requesting a DataFrame backend that is not installed raises
`MissingDataFrameDependencyException` with the corresponding installation
command. The low-level sync/async clients and Pydantic models work with the base
installation and do not require either DataFrame library.

- `credentials`: a typed dict with `username` and `password`
- `timeout`: an `httpx.Timeout` object

The SDK clients use `httpx` under the hood and will apply retries and timeout settings automatically.

## Logging

This library uses `logging.getLogger(__name__)` in each module. Consumers should configure handlers and levels in their own applications.

Example:

```python
import logging

logging.basicConfig(level=logging.INFO)
```

## Contributing

See `CONTRIBUTING.md` for contribution guidelines.

## Security

See `SECURITY.md` for security reporting and vulnerability handling.

## Code of Conduct

See `CODE_OF_CONDUCT.md` for community expectations.

