Carry the municipality of a CEP that does not existHEADv0.2.0main

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.

1 files changed, 9 insertions, 4 deletions

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",