Metadata-Version: 2.4
Name: chile-public-market-sdk
Version: 0.9.1
Summary: Typed synchronous and asynchronous SDK for Chile's Mercado Público APIs.
License-Expression: MIT
License-File: LICENSE.md
Author: Eli-ezer Reuven Ramirez Ruiz
Author-email: ramirez.ruiz.eliezer.reuven@gmail.com
Requires-Python: >=3.12
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Provides-Extra: dev
Provides-Extra: docs
Requires-Dist: httpx (>=0.27,<1)
Requires-Dist: mkdocs (>=1.6) ; extra == "docs"
Requires-Dist: mkdocs-material (>=9.5) ; extra == "docs"
Requires-Dist: mkdocstrings[python] (>=0.26) ; extra == "docs"
Requires-Dist: mypy (>=1.11) ; extra == "dev"
Requires-Dist: pydantic (>=2.8,<3)
Requires-Dist: pyright (>=1.1.411,<2) ; extra == "dev"
Requires-Dist: pytest (>=8.3) ; extra == "dev"
Requires-Dist: pytest-asyncio (>=0.24) ; extra == "dev"
Requires-Dist: pytest-cov (>=5) ; extra == "dev"
Requires-Dist: ruff (>=0.6) ; extra == "dev"
Project-URL: Documentation, https://www.chilecompra.cl/api/
Project-URL: Repository, https://github.com/ezer-mackenzie/chile-public-market-sdk
Description-Content-Type: text/markdown

# Chile Public Market SDK

Unofficial, typed, synchronous and asynchronous Python SDK for Chile's
[Mercado Público APIs](https://www.chilecompra.cl/api/).

> Status: alpha (`0.4.0`). The upstream services include legacy contracts and
> may add fields. Models validate known fields while preserving new ones.

## Requirements

- Python 3.12 or newer.
- An access ticket requested through ChileCompra.

## Installation

```bash
pip install chile-public-market-sdk
```

## Secure configuration

The SDK never includes or manages tickets. Pass one explicitly:

```python
from chile_public_market_sdk import SyncChilePublicMarketSDK

sdk = SyncChilePublicMarketSDK(ticket="YOUR_TICKET")
```

Or define `CHILE_PUBLIC_MARKET_TICKET`:

```bash
export CHILE_PUBLIC_MARKET_TICKET="YOUR_TICKET"
```

Git ignores `.env` and `env.yaml`. Loading them through Docker Compose,
Kubernetes, `envyaml`, `python-dotenv`, or another secret-management mechanism
is the consumer application's responsibility. The SDK itself does not read
configuration files.

## Synchronous usage

```python
from datetime import date

from chile_public_market_sdk import SyncChilePublicMarketSDK
from chile_public_market_sdk.core.enums import TenderStatus

with SyncChilePublicMarketSDK() as client:
    response = client.get_tenders(
        date=date(2026, 6, 12),
        status=TenderStatus.PUBLISHED,
    )
    for tender in response.items:
        print(tender.external_code, tender.name)

    order = client.get_purchase_orders(code="2097-241-SE14")
    supplier = client.find_supplier("70.017.820-k")
    buyers = client.get_buyers()
```

## Asynchronous usage

```python
import asyncio

from chile_public_market_sdk import AsyncChilePublicMarketSDK
from chile_public_market_sdk.core.enums import AgilePurchaseStatus


async def main() -> None:
    async with AsyncChilePublicMarketSDK() as client:
        page = await client.get_agile_purchases(
            last_change_ttl_ms=300_000,
            statuses=[AgilePurchaseStatus.PUBLISHED],
            page_size=50,
        )
        detail = await client.get_agile_purchase(page.items[0].code)
        print(detail.name)


asyncio.run(main())
```

## Endpoint coverage

| Resource | SDK method | API |
|---|---|---|
| Tenders | `get_tenders` | v1 |
| Purchase orders | `get_purchase_orders` | v1 |
| Suppliers | `find_supplier` | v1 |
| Buyer organizations | `get_buyers` | v1 |
| Agile Purchase listing and filters | `get_agile_purchases` | v2 |
| Agile Purchase details | `get_agile_purchase` | v2 |

V1 date filters accept a `date` or the original `ddmmyyyy` format. Agile
Purchase accepts ISO-8601 dates, multiple statuses and regions, pagination,
and sorting.

## Client classes and API versions

The SDK exposes separate synchronous and asynchronous classes:

- `SyncChilePublicMarketClient` / `SyncChilePublicMarketSDK`
- `AsyncChilePublicMarketClient` / `AsyncChilePublicMarketSDK`

SDK classes construct and own a client through `sdk.client`. Their context
managers return that managed client, while endpoint methods remain on client
classes.

ChileCompra endpoint contracts are versioned independently under
`chile_public_market_sdk.api.v1` and `chile_public_market_sdk.api.v2`. Future
upstream contracts will follow `api.v{version}`. SDK releases remain `0.x`
until the public Python API is stable enough for `1.0.0`.

## Errors

Every public exception inherits from `ChilePublicMarketError`:

- `ConfigurationError`: no ticket was supplied.
- `RequestValidationError`: incompatible or invalid filters.
- `AuthenticationError`: HTTP 401 or 403.
- `NotFoundError`: HTTP 404.
- `RateLimitError`: HTTP 429; exposes `retry_after`.
- `APIError`: any other API error.
- `RequestTimeoutError`: a configured timeout was exceeded.
- `NetworkError`: a connection or network protocol failed.
- `TransportError`: another HTTP transport failure.
- `ResponseValidationError`: invalid JSON or an unexpected contract.

## Reliability

The SDK uses HTTPX directly. Pass a native `httpx.Timeout` for granular limits:

```python
import httpx

from chile_public_market_sdk import ClientConfig, SyncChilePublicMarketSDK

config = ClientConfig(
    ticket="YOUR_TICKET",
    timeout=httpx.Timeout(connect=5, read=30, write=10, pool=5),
)

with SyncChilePublicMarketSDK(config=config) as client:
    tenders = client.get_tenders()
```

Applications that need retries can inject an HTTPX client configured for their
own policy. The SDK does not hide HTTPX behind another transport abstraction.

## Development

```bash
poetry install --extras "dev docs"
poetry run pytest
poetry run ruff check .
poetry run mypy
poetry run pyright
poetry build
```

Read [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md) before
submitting changes or reporting vulnerabilities.

