Metadata-Version: 2.4
Name: bcch-sdk
Version: 0.8.1
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 :: 4 - Beta
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
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)
Requires-Dist: polars (>=1.42.1,<2.0.0)
Requires-Dist: pydantic (>=2.13.4,<3.0.0)
Project-URL: Changelog, https://github.com/ezer-mackenzie/bank-central-chile-sdk/blob/main/CHANGELOG.md
Project-URL: Documentation, https://ezer-mackenzie.github.io/bank-central-chile-sdk/
Project-URL: Homepage, https://github.com/ezer-mackenzie/bank-central-chile-sdk
Project-URL: Issues, https://github.com/ezer-mackenzie/bank-central-chile-sdk/issues
Project-URL: Repository, https://github.com/ezer-mackenzie/bank-central-chile-sdk
Description-Content-Type: text/markdown

# Banco Central Chile SDK

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`
- `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`
- `polars`
- `pandas`
- `httpx-retries`

`pandas` and `polars` are runtime dependencies by design for the `0.x` and `1.0`
release line because DataFrame responses are part of the core SDK contract. They
may be split into optional extras in a future release after the stable API is
established.

## Installation

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

Use Poetry if available:

```bash
poetry install
```

Or install the runtime dependencies manually:

```bash
python -m pip install httpx[brotli,zstd] pydantic polars pandas 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),
)

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`.

- `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.

