Metadata-Version: 2.5
Name: prontiq
Version: 0.3.0
Summary: The official Python SDK for the Prontiq Address API
Project-URL: Homepage, https://prontiq.dev
Project-URL: Repository, https://github.com/prontiq/prontiq-python
Author-email: Prontiq <support@prontiq.dev>
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: attrs>=25.3
Requires-Dist: httpx<1,>=0.28
Description-Content-Type: text/markdown

# Prontiq Python SDK

Python 3.11+ client generated from the public Prontiq OpenAPI contract.

```bash
pip install 'prontiq>=0.3,<0.4'
```

```python
import os
import httpx
from prontiq import AuthenticatedClient
from prontiq.api.address import autocomplete_address
from prontiq.models import AddressErrorResponse, AutocompleteAddressResponse

with AuthenticatedClient(
    base_url="https://api.prontiq.dev",
    token=os.environ["PRONTIQ_API_KEY"],
    auth_header_name="X-Api-Key",
    prefix="",
    raise_on_unexpected_status=True,
    timeout=httpx.Timeout(10.0),
) as client:
    response = autocomplete_address.sync_detailed(client=client, q="200 George Street Sydney")
    if isinstance(response.parsed, AutocompleteAddressResponse):
        for suggestion in response.parsed.suggestions:
            print(suggestion.address_label)
    elif isinstance(response.parsed, AddressErrorResponse):
        print(response.parsed.error.code)
```

Set a finite HTTP timeout as shown above; the generated transport otherwise has
no timeout. Use `async with` and `await autocomplete_address.asyncio_detailed(...)` for async
applications. All six operation modules support sync and async calls:

| Module in `prontiq.api.address` | Required arguments |
| --- | --- |
| `autocomplete_address` | `q` |
| `validate_address` | `q` |
| `enrich_address` | `id` |
| `reverse_geocode_address` | `lat`, `lon` |
| `lookup_postcode` | `postcode` |
| `lookup_suburb` | `suburb` |

The detailed response retains HTTP status, headers and the parsed success/error
model. Documented errors return `AddressErrorResponse`; unexpected statuses raise
`prontiq.errors.UnexpectedStatus` when enabled above. Transport failures raise
HTTPX exceptions. Retries are caller-owned; use the response's `Retry-After` header
when retrying rate-limited requests.
With `raise_on_unexpected_status=False`, unexpected responses retain their numeric
status, headers and body with `parsed=None`, including nonstandard proxy statuses.

## Migrating from 0.2

Version 0.3 replaces Stainless with pinned `openapi-python-client` generation.
It requires Python 3.11+, and changes the client interface:

- Replace `Prontiq` / `AsyncProntiq` and `client.address.*` calls with the client
  and operation modules shown above. Configure `X-Api-Key` with an empty prefix;
  the generated client's generic default is Bearer authentication.
- Replace `APIStatusError` handling with detailed response status/model handling.
- Full address records now require `fallbackGeocode` object/null. Models expose
  `fallback_geocode` and `source_data_release`, and support state `OT`.
- Fallback-only records retain `location=None`; fallback precision and decimal
  coordinates remain separate from primary locations.

Coordinate publication of 0.3 with the schema 1.1 API rollout. It expects the
schema 1.1 response contract and is not a drop-in replacement for 0.2.

## Development

```bash
uv sync --frozen
uv run python scripts/generate.py
uv run python scripts/generate.py --check
uv run pytest
uv run ruff check .
uv run mypy
uv build
uv run python scripts/check_package.py
```

`spec/openapi.json` is copied from the committed **public** platform contract by
the platform's Generate SDKs workflow, which opens a PR here. Edit routes and
schemas in `prontiq/prontiq-platform`; do not hand-edit `src/prontiq`.
Generation fails on warnings, and CI checks that regenerated bytes match the
committed client. The generator normalizes annotation-only scalar intersections
without removing validation constraints, restores the installed-package typing
marker, disables client representations that would expose credentials, and
preserves HTTP statuses outside Python's standard enum.
CI also installs the built wheel and checks its runtime and consumer typing.

Release from a reviewed `v<version>` tag matching `pyproject.toml` on `main`; the PyPI
workflow validates generation and tests before publishing with `PYPI_TOKEN`.
