python/tests/test_cepis.py, branch v0.2.0Python client for the public CEP API
http://git.cep.is/python/atom?h=v0.2.02026-07-27T23:32:01ZCarry the municipality of a CEP that does not exist2026-07-27T23:32:01ZMurilo Ijancmurilo@ijanc.org2026-07-27T23:32:01Zurn:sha1:b199ae044f8f9cd4b745214cd5e5495f86b5eb54
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.
Initial import2026-07-26T14:44:58ZMurilo Ijancmurilo@ijanc.org2026-07-26T14:44:58Zurn:sha1:a82459630e957a8d94c375394dae66734f3c90c1