cl-forge 0.5.0

Simple yet powerful Chilean and other tools written in Rust and Python.

cl-forge 🇨🇱

Simple yet powerful Chilean and other tools written in Rust and Python.

cl-forge provides a collection of high-performance utilities for common Chilean data formats and API integrations. The core logic is implemented in Rust for maximum speed, with a clean and easy-to-use Python interface.

Features

• Verify: Efficiently validate and manipulate Chilean RUT/RUN and PPU (License Plates).
• CMF API: A simple client to interact with the Chilean Financial Market Commission (CMF) API.
• High Performance: Core logic written in Rust.
• Lazy Loading: Submodules are loaded only when needed to keep the initial import fast.
• Type Safety: Full type hints and .pyi stubs for excellent IDE support.

Installation

From PyPI

pip install cl-forge

Or using uv:

uv add cl-forge

From Source

Using uv (Recommended)

uv pip install git+https://github.com/mschiaff/cl-forge.git

Using pip

pip install git+https://github.com/mschiaff/cl-forge.git

Note: Building from source requires a Rust toolchain installed on your system.

Usage

Verification (RUT & PPU)

from cl_forge import verify

# Validate a RUT
is_valid = verify.validate_rut("12345678", "5")
print(f"RUT is valid: {is_valid}")

# Calculate RUT verifier
dv = verify.calculate_verifier("12345678")
print(f"Verifier digit: {dv}")

# Generate random RUTs
ruts = verify.generate(n=3, min=1_000_000, max=2_000_000, seed=42)
print(ruts)
# [{'correlative': 1133512, 'verifier': '9'}, ...]

# Work with PPUs (License Plates)
ppu = verify.Ppu("PHZF55")
print(f"Normalized: {ppu.normalized}")  # PHZF55
print(f"Verifier: {ppu.verifier}")      # K
print(f"Complete: {ppu.complete}")      # PHZF55-K

CMF API Client

To use the CMF API, you need an API key. You can request one at CMF Chile.

Generic Client

from cl_forge.cmf import CmfClient

client = CmfClient(api_key="your_api_key_here")

# Get IPC data
ipc_data = client.get(path="/ipc")
print(ipc_data) # {'IPCs': [{'Valor': '-0,2', 'Fecha': '2025-12-01'}]}

IPC Specialist Client

The Ipc class provides a more convenient way to interact with IPC-related endpoints, returning parsed Pydantic objects.

from cl_forge.cmf import Ipc

ipc_client = Ipc(api_key="your_api_key_here")

# Get current IPC
current_ipc = ipc_client.current()
print(f"Date: {current_ipc.date}, Value: {current_ipc.value}")

# Get IPC for a specific year
year_ipc = ipc_client.year(2024)
for record in year_ipc:
    print(f"{record.date.strftime('%Y-%m')}: {record.value}")

See the CMF API documentation for details about the available endpoints.

Development

This project uses maturin to build the Rust extension.

Setup

1. Clone the repository:

   git clone https://github.com/mschiaff/cl-forge.git
   cd cl-forge
   

2. Install development dependencies (using uv):

   uv sync --all-groups
   

3. Build the Rust extension in develop mode:

   uv run maturin develop
   

Running Tests

uv run pytest

License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.