"""Python client for the public CEP API at `cep.is <https://cep.is>`_.

Quick use — for a script, the module-level functions are enough::

    import cepis

    address = cepis.lookup("01001-000")
    print(address.localidade, address.uf)   # São Paulo SP

In an application — build a :class:`Client` once and reuse it::

    from cepis import Client

    client = Client(timeout=5.0, total_timeout=15.0)
    address = client.lookup("01001000")

Pointing at a local instance (the API repo brings one up with ``just up``)::

    client = Client(base_url="http://localhost:8080")

Errors are explicit and split by decision — whether retrying helps or not::

    from cepis import CEPNotFound, CepisError

    try:
        address = cepis.lookup(cep_from_form)
    except CEPNotFound:
        ...   # the CEP does not exist: ask the user for another
    except CepisError:
        ...   # network, server, rate limit: retry later

Note on field names: the API surface is English, but the **data fields keep
the API's own Portuguese names** (``logradouro``, ``bairro``, ``localidade``).
What you read in the JSON is what you access on the object.

The module-level functions share one default client. It is built once because
:class:`Client` keeps no state between calls and is thread-safe. Do not mutate
it: it applies process-wide, including to third-party libraries that also use
this module. Anyone needing different settings should build their own.
"""

from __future__ import annotations

__version__ = "0.1.0"

from .client import DEFAULT_URL, MAX_BATCH, Client, normalize_cep
from .errors import (
    CepisError,
    CEPNotFound,
    InvalidCEP,
    InvalidResponse,
    NetworkError,
    RateLimited,
    ServerError,
)
from .models import Address, Geo, Health

__all__ = [
    "DEFAULT_URL",
    "MAX_BATCH",
    "Address",
    "CEPNotFound",
    "CepisError",
    "Client",
    "Geo",
    "Health",
    "InvalidCEP",
    "InvalidResponse",
    "NetworkError",
    "RateLimited",
    "ServerError",
    "__version__",
    "health",
    "lookup",
    "lookup_many",
    "normalize_cep",
]

_default = Client()


def lookup(cep: str) -> Address:
    """Look up a CEP using the default configuration.

    Shorthand for ``Client().lookup(cep)``. See :meth:`Client.lookup`.
    """
    return _default.lookup(cep)


def lookup_many(ceps: list[str]) -> list[Address | None]:
    """Look up many CEPs in one batch, using the default configuration.

    Shorthand for :meth:`Client.lookup_many` — read that one, especially the
    warning that batches carry no coordinate.
    """
    return _default.lookup_many(ceps)


def health() -> Health:
    """Query the API's health using the default configuration.

    Shorthand for :meth:`Client.health`.
    """
    return _default.health()