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.

4 files changed, 126 insertions, 12 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",
diff --git a/src/cepis/client.py b/src/cepis/client.py
index bebc6e6..ffd1332 100644
--- a/src/cepis/client.py
+++ b/src/cepis/client.py
@@ -35,7 +35,7 @@ from .errors import (
     RateLimited,
     ServerError,
 )
-from .models import Address, Health
+from .models import Address, Faixa, Health
 
 DEFAULT_URL = "https://cep.is"
 
@@ -160,6 +160,16 @@ class Client:
         API's own message: the format already passed local validation, so the
         server knows something this client does not.
 
+        A 404 may carry the municipality the CEP would have belonged to, in
+        `CEPNotFound.faixa` (see :class:`cepis.Faixa`) — still a 404, still an
+        error, but usually enough to ask a better question than "invalid CEP"::
+
+            try:
+                address = client.lookup(cep)
+            except CEPNotFound as exc:
+                if exc.faixa:
+                    print(f"no such CEP in {exc.faixa.label}")
+
         :raises InvalidCEP: the CEP is not 8 digits (no request is made).
         :raises CEPNotFound: well-formed, but not in the database.
         :raises RateLimited: 429 after every attempt.
@@ -170,7 +180,11 @@ class Client:
         status, body, _ = self._request(f"/{number}")
 
         if status == 404:
-            raise CEPNotFound(f"CEP {number} does not exist in the DNE database")
+            faixa = Faixa.from_json(self._error_json(body).get("faixa"))
+            message = f"CEP {number} does not exist in the DNE database"
+            if faixa is not None:
+                message = f"{message} (it would be in {faixa.label})"
+            raise CEPNotFound(message, faixa=faixa)
         if status == 400:
             raise InvalidCEP(self._error_message(body, f"CEP {number} rejected"))
 
@@ -258,15 +272,23 @@ class Client:
         return data
 
     @staticmethod
-    def _error_message(body: bytes, fallback: str) -> str:
-        """Pull `mensagem` out of an error body, falling back to a default."""
+    def _error_json(body: bytes) -> dict[str, Any]:
+        """Decode an error body, or return `{}`.
+
+        Unlike :meth:`_json` this never raises. An error response is already
+        the bad news; whether its body could be parsed only decides how much
+        detail the exception carries, never whether one is raised.
+        """
         try:
             data = json.loads(body.decode("utf-8"))
-            if isinstance(data, dict) and data.get("mensagem"):
-                return str(data["mensagem"])
         except (ValueError, UnicodeDecodeError):
-            pass
-        return fallback
+            return {}
+        return data if isinstance(data, dict) else {}
+
+    def _error_message(self, body: bytes, fallback: str) -> str:
+        """Pull `mensagem` out of an error body, falling back to a default."""
+        message = self._error_json(body).get("mensagem")
+        return str(message) if message else fallback
 
     def _backoff(self, attempt: int, retry_after: float | None) -> float:
         """How long to wait before the next attempt.
diff --git a/src/cepis/errors.py b/src/cepis/errors.py
index 1698972..12862df 100644
--- a/src/cepis/errors.py
+++ b/src/cepis/errors.py
@@ -19,6 +19,8 @@ before it ever leaves the machine.
 
 from __future__ import annotations
 
+from .models import Faixa
+
 
 class CepisError(Exception):
     """Base of every error. Catch this to handle any failure."""
@@ -45,8 +47,19 @@ class CEPNotFound(CepisError, KeyError):
     `KeyError.__str__` wraps the message in quotes (inherited from dict
     behaviour), which is why `__str__` is overridden here — otherwise every
     message would come out with spurious quotes around it.
+
+    `faixa` is the municipality the CEP *would* have belonged to, when the API
+    could work it out: see :class:`cepis.Faixa`. It is `None` whenever the API
+    did not say — either because the CEP falls in a band no municipality owns,
+    or because the server is older than this field. Either way the exception is
+    the same exception: `faixa` is context for the error, never a demotion of
+    it into a partial success.
     """
 
+    def __init__(self, message: str, faixa: Faixa | None = None) -> None:
+        super().__init__(message)
+        self.faixa = faixa
+
     def __str__(self) -> str:
         return self.args[0] if self.args else ""
 
diff --git a/src/cepis/models.py b/src/cepis/models.py
index b6f29fd..5750012 100644
--- a/src/cepis/models.py
+++ b/src/cepis/models.py
@@ -140,6 +140,80 @@ class Address:
 
 
 @dataclass(frozen=True)
+class Faixa:
+    """The municipality a CEP *would* belong to, when it does not exist.
+
+    This is context for an error, **not an address**. It arrives on the 404
+    body of `GET /{cep}` and is exposed as :attr:`cepis.CEPNotFound.faixa`. The
+    CEP asked for still does not exist; nothing here says otherwise, and
+    treating a `Faixa` as if it were an :class:`Address` is the one mistake
+    this type makes possible.
+
+    It exists because a failing CEP is rarely random: it is usually someone who
+    knows the city and guessed the number — most often the `-000` that 957
+    municipalities never received. Knowing which municipality was meant is
+    enough to ask a much better question than "invalid CEP".
+
+    `cep_ini` and `cep_fim` are the **smallest and largest CEP that actually
+    exist** in that municipality — not the bounds the Correios publish. For
+    Areal/RJ the DNE's own start is `25845000`, which is precisely the CEP that
+    just failed; `cep_ini` is `25845001`.
+
+    The range is **sparse**. Areal's 118 CEPs are scattered across the ~4,900
+    numbers between `25845001` and `25849899`. `ceps` is how many there really
+    are, and it is there so the pair is never read as "everything in between is
+    valid": iterating the range would produce mostly CEPs that do not exist.
+    """
+
+    localidade: str
+    uf: str
+    estado: str
+    regiao: str
+    ibge: str
+    cep_ini: str
+    cep_fim: str
+    ceps: int
+
+    @property
+    def label(self) -> str:
+        """The municipality as `Areal/RJ`, for a message shown to a person."""
+        return f"{self.localidade}/{self.uf}"
+
+    @classmethod
+    def from_json(cls, block: Any) -> Faixa | None:
+        """Build from the `faixa` block of a 404 body, or return `None`.
+
+        Takes whatever was under the `faixa` key — including nothing at all —
+        because the field is **omitted, never null**, when the CEP falls in a
+        band no municipality owns. Absent, empty, not a dict, or malformed all
+        give the same answer: `None`.
+
+        Nothing in here may raise. The caller is already on its way to raising
+        :class:`cepis.CEPNotFound`, and turning that clean "does not exist"
+        into a parse error over an optional courtesy field would be a strictly
+        worse outcome than simply not having the field.
+        """
+        if not isinstance(block, dict):
+            return None
+        try:
+            localidade = str(block["localidade"])
+            if not localidade:
+                return None
+            return cls(
+                localidade=localidade,
+                uf=str(block.get("uf", "")),
+                estado=str(block.get("estado", "")),
+                regiao=str(block.get("regiao", "")),
+                ibge=str(block.get("ibge", "")),
+                cep_ini=str(block.get("cep_ini", "")),
+                cep_fim=str(block.get("cep_fim", "")),
+                ceps=int(block.get("ceps") or 0),
+            )
+        except (KeyError, TypeError, ValueError):
+            return None
+
+
+@dataclass(frozen=True)
 class Health:
     """The response of `GET /health`.