cepx 0.1.0

Busca por CEP integrada aos serviços dos Correios, ViaCEP, WideNet e BrasilAPI (sync e async). Python port do cep-promise.

cepx

Busca por CEP integrada aos serviços dos Correios, ViaCEP, WideNet e BrasilAPI. Python port of cep-promise, with both synchronous and asynchronous APIs.

Providers are queried concurrently and the first successful response wins. The lookup only fails once every provider fails, aggregating each error.

Usage

import cepx

cepx.cep("05010000")
# Address(cep='05010000', state='SP', city='São Paulo',
#         neighborhood='Perdizes', street='Rua Caiubi', provider='brasilapi')

cepx.cep(5010000)                                  # ints are left-padded
cepx.cep("05010000", providers=["viacep"])         # restrict providers
cepx.cep("05010000", timeout=5.0)                  # per-provider timeout (s)

import asyncio
import cepx

asyncio.run(cepx.acep("05010000"))

Errors

cepx.CepxError is raised with a type of either "validation_error" (bad input, before any request) or "provider_error" (all providers failed). Its errors list holds the underlying cepx.ProviderError entries.

Development

uv sync
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run ty check
uv run pre-commit install