Metadata-Version: 2.4
Name: cl-forge
Version: 2.0.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python
Classifier: Programming Language :: Rust
Classifier: Typing :: Typed
Classifier: Topic :: Utilities
Classifier: Topic :: Software Development :: Libraries
Requires-Dist: httpx2[http2]>=2.12.0
Requires-Dist: pydantic>=2.12.5
Requires-Dist: pydantic-settings>=2.14.0
Requires-Dist: cl-forge[interop] ; extra == 'all'
Requires-Dist: cl-forge[excel] ; extra == 'all'
Requires-Dist: cl-forge[notebook] ; extra == 'all'
Requires-Dist: cl-forge[polars] ; extra == 'analytics'
Requires-Dist: cl-forge[calamine] ; extra == 'analytics'
Requires-Dist: cl-forge[xlsxwriter] ; extra == 'analytics'
Requires-Dist: fastexcel>=0.19.0,<0.20.0 ; extra == 'calamine'
Requires-Dist: cl-forge[calamine] ; extra == 'excel'
Requires-Dist: cl-forge[xlsxwriter] ; extra == 'excel'
Requires-Dist: cl-forge[openpyxl] ; extra == 'excel'
Requires-Dist: cl-forge[polars] ; extra == 'interop'
Requires-Dist: cl-forge[pandas] ; extra == 'interop'
Requires-Dist: ipykernel>=7.1.0,<8.0.0 ; extra == 'notebook'
Requires-Dist: ipywidgets>=8.1.8,<9.0.0 ; extra == 'notebook'
Requires-Dist: notebook>=7.5.3,<8.0.0 ; extra == 'notebook'
Requires-Dist: openpyxl>=3.1.5,<3.2.0 ; extra == 'openpyxl'
Requires-Dist: cl-forge[pyarrow] ; extra == 'pandas'
Requires-Dist: pandas-stubs>=3.0.0.260204,<4.0.0 ; extra == 'pandas'
Requires-Dist: pandas[performance]>=3.0.0,<4.0.0 ; extra == 'pandas'
Requires-Dist: cl-forge[pyarrow] ; extra == 'polars'
Requires-Dist: polars>=1.40.0,<1.50.0 ; extra == 'polars'
Requires-Dist: pyarrow>=23.0.0,<24.0.0 ; extra == 'pyarrow'
Requires-Dist: xlsxwriter>=3.2.9,<3.3.0 ; extra == 'xlsxwriter'
Provides-Extra: all
Provides-Extra: analytics
Provides-Extra: calamine
Provides-Extra: excel
Provides-Extra: interop
Provides-Extra: notebook
Provides-Extra: openpyxl
Provides-Extra: pandas
Provides-Extra: polars
Provides-Extra: pyarrow
Provides-Extra: xlsxwriter
License-File: LICENSE
Summary: Simple yet powerful Chilean and other tools written in Rust and Python.
Keywords: chile,cl,utils,tools,rut,run,validators,api,python,rust
Author-email: Matías Schiaffino Tyrer <matias.scht@gmail.com>
License-Expression: Apache-2.0
Requires-Python: >=3.12, <3.15
Description-Content-Type: text/markdown
Project-URL: Documentation, https://mschiaff.github.io/cl-forge/
Project-URL: Homepage, https://mschiaff.github.io/cl-forge/
Project-URL: Issues, https://github.com/mschiaff/cl-forge/issues
Project-URL: Repository, https://github.com/mschiaff/cl-forge.git

# CL Forge

<p align="center">
  <img src="https://github.com/mschiaff/cl-forge/blob/main/docs/assets/banner.png?raw=true" alt="CL Forge banner">
</p>

<p align="center">
  <strong>Fast, typed Python tools for Chilean data and public APIs.</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/cl-forge/"><img src="https://img.shields.io/pypi/v/cl-forge" alt="PyPI version"></a>
  <a href="https://pypi.org/project/cl-forge/"><img src="https://img.shields.io/pypi/pyversions/cl-forge" alt="Supported Python versions"></a>
  <a href="https://github.com/mschiaff/cl-forge/actions/workflows/python-package.yml"><img src="https://img.shields.io/github/actions/workflow/status/mschiaff/cl-forge/python-package.yml?logo=github&label=tests" alt="Test status"></a>
  <a href="https://github.com/mschiaff/cl-forge/blob/main/LICENSE"><img src="https://img.shields.io/github/license/mschiaff/cl-forge" alt="License"></a>
  <a href="https://mschiaff.github.io/cl-forge/"><img src="https://img.shields.io/badge/docs-GitHub%20Pages-blue?logo=github" alt="Documentation"></a>
</p>

CL Forge combines Rust-backed validation utilities with a clean Python interface for the [CMF](https://api.cmfchile.cl/) and [Mercado Público](https://api.mercadopublico.cl/) APIs. It includes synchronous and asynchronous clients, typed responses, configurable HTTP behavior, and flexible credential providers.

## Install

CL Forge supports Python 3.12–3.14.

```bash
pip install cl-forge
```

Using `uv`:

```bash
uv add cl-forge
```

## Quick start

### Validate Chilean identifiers

```python
from cl_forge import Ppu, calculate_verifier, validate_rut

validate_rut(12_345_678, "5")     # True
calculate_verifier(12_345_678)    # "5"

plate = Ppu("PHZF55")
plate.complete                    # "PHZF55-K"
plate.numeric                     # 69455
```

### Query CMF indicators

```python
from cl_forge import CmfClient

cmf = CmfClient("your-cmf-api-key")

latest_uf = cmf.uf.latest()
ipc_2025 = cmf.ipc.year(2025)
usd_for_day = cmf.usd.day(2025, 12, 1)
```

The CMF client provides resources for `ipc`, `uf`, `utm`, `usd`, `eur` (also `euro`), `tip`, and `tmc`, plus `raw` JSON and XML access.

> [!NOTE]
> CMF requests require an API key. You can request one through the [CMF API portal](https://api.cmfchile.cl/api_cmf/contactanos.jsp).

### Query Mercado Público

```python
from cl_forge import MarketClient

market = MarketClient("your-mercado-publico-ticket")

active_tenders = market.tender.active()
today_orders = market.order.today()
suppliers = market.supplier.search("70.017.820-K")
```

The Mercado Público client includes typed resources for tenders, purchase orders, suppliers, and buyers, plus raw v1 and v2 access.

> [!NOTE]
> Mercado Público requests require an API ticket. See the [Mercado Público API portal](https://api.mercadopublico.cl/modules/api.aspx) for access details.

### Use async clients

The asynchronous clients mirror the synchronous resource interface:

```python
from cl_forge import AsyncCmfClient

cmf = AsyncCmfClient("your-cmf-api-key")
latest_uf = await cmf.uf.latest()
```

## Credentials and configuration

Pass a credential directly, load it from the environment, or read it from a dotenv file:

```bash
export CLFORGE_CMF_API_KEY="your-cmf-api-key"
export CLFORGE_MARKET_API_KEY="your-mercado-publico-ticket"
```

```python
from cl_forge import ClientConfig, CmfClient, DotEnvCredentials, EnvCredentials

cmf = CmfClient(
    credentials=EnvCredentials(),
    config=ClientConfig(timeout=20, http2=True, retries=5),
)

cmf_from_dotenv = CmfClient(DotEnvCredentials(".env"))
```

## API reference

| Area | Public API |
| --- | --- |
| CMF | [`CmfClient`](https://mschiaff.github.io/cl-forge/api/CmfClient/) · [`AsyncCmfClient`](https://mschiaff.github.io/cl-forge/api/AsyncCmfClient/) |
| Mercado Público | [`MarketClient`](https://mschiaff.github.io/cl-forge/api/MarketClient/) · [`AsyncMarketClient`](https://mschiaff.github.io/cl-forge/api/AsyncMarketClient/) |
| Credentials | [`EnvCredentials`](https://mschiaff.github.io/cl-forge/api/EnvCredentials/) · [`DotEnvCredentials`](https://mschiaff.github.io/cl-forge/api/DotEnvCredentials/) |
| HTTP configuration | [`ClientConfig`](https://mschiaff.github.io/cl-forge/api/ClientConfig/) |
| RUT/RUN | [`validate_rut`](https://mschiaff.github.io/cl-forge/api/validate_rut/) · [`calculate_verifier`](https://mschiaff.github.io/cl-forge/api/calculate_verifier/) |
| License plates | [`Ppu`](https://mschiaff.github.io/cl-forge/api/Ppu/) |

Explore the [full documentation](https://mschiaff.github.io/cl-forge/) for installation details and the complete API reference.

## Contributing

Contributions are welcome. Please read the [contributing guide](CONTRIBUTING.md) before opening a pull request.

## License

CL Forge is available under the [Apache License 2.0](LICENSE).

