From b199ae044f8f9cd4b745214cd5e5495f86b5eb54 Mon Sep 17 00:00:00 2001 From: Murilo Ijanc Date: Mon, 27 Jul 2026 20:32:01 -0300 Subject: Carry the municipality of a CEP that does not exist MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A failing CEP is rarely random: it is someone who knows the city and guessed the number, and the classic guess is the -000 that 957 municipalities never received. The API now answers those 404s with a faixa block naming the municipality the CEP would have belonged to, so a caller can ask "did you mean somewhere in Areal/RJ?" instead of "invalid CEP". CEPNotFound gains faixa, defaulting to None. It stays a 404 and stays an exception — the field is context for the error, never a demotion of it into a partial success. Parsing is deliberately total: anything missing, empty or malformed under faixa yields None, because turning a clean not-found into a parse failure over an optional courtesy field would be strictly worse than not having the field at all. Faixa's cep_ini/cep_fim are the smallest and largest CEP that actually exist there, not the bounds the Correios publish, and the range in between is sparse — hence ceps, so the pair is never read as a list of valid numbers. --- src/cepis/__init__.py | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) (limited to 'src/cepis/__init__.py') diff --git a/src/cepis/__init__.py b/src/cepis/__init__.py index bc98d29..f32754a 100644 --- a/src/cepis/__init__.py +++ b/src/cepis/__init__.py @@ -24,8 +24,12 @@ Errors are explicit and split by decision — whether retrying helps or not:: try: address = cepis.lookup(cep_from_form) - except CEPNotFound: - ... # the CEP does not exist: ask the user for another + except CEPNotFound as exc: + # The CEP does not exist. The API often knows which municipality it + # would have belonged to — enough to ask a better question than + # "invalid CEP". Still an error: `exc.faixa` is not an address. + if exc.faixa: + ... # f"no such CEP in {exc.faixa.label}" except CepisError: ... # network, server, rate limit: retry later @@ -41,7 +45,7 @@ this module. Anyone needing different settings should build their own. from __future__ import annotations -__version__ = "0.1.0" +__version__ = "0.2.0" from .client import DEFAULT_URL, MAX_BATCH, Client, normalize_cep from .errors import ( @@ -53,7 +57,7 @@ from .errors import ( RateLimited, ServerError, ) -from .models import Address, Geo, Health +from .models import Address, Faixa, Geo, Health __all__ = [ "DEFAULT_URL", @@ -62,6 +66,7 @@ __all__ = [ "CEPNotFound", "CepisError", "Client", + "Faixa", "Geo", "Health", "InvalidCEP", -- cgit v1.3