diff options
Diffstat (limited to 'src/cepis')
| -rw-r--r-- | src/cepis/__init__.py | 13 | ||||
| -rw-r--r-- | src/cepis/client.py | 38 | ||||
| -rw-r--r-- | src/cepis/errors.py | 13 | ||||
| -rw-r--r-- | src/cepis/models.py | 74 |
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`. |