brazilian_ids.functions.location package

Submodules

brazilian_ids.functions.location.cep module

Functions to work with CEP (“Código de Endereçamento Postal”, in Brazilian Portuguese), which is the equivalent of zipcodes.

The meaning of numeric codes for region, sub region, etc, are in strict control of a private company in Brazil called Correios. The company has the monopoly in

Brazil and doesn’t provide data besides simply queries with limited results and restricted by captchas to making data scraping more difficult.

See also:

class brazilian_ids.functions.location.cep.CEP(formatted_cep, region, sub_region, sector, sub_sector, division, suffix)

Bases: object

Representation of a CEP.

Should be obtained from the parse function.

Parameters:

  • formatted_cep (str)

  • region (int)

  • sub_region (int)

  • sector (int)

  • sub_sector (int)

  • division (int)

  • suffix (str)

division: int
formatted_cep: str
region: int
sector: int
sub_region: int
sub_sector: int
suffix: str
exception brazilian_ids.functions.location.cep.CepInvalidStateError(state_code)

Bases: ValueError

Error for CEP associated with a invalid state code.

class brazilian_ids.functions.location.cep.CepRange(*args, **kwargs)

Bases: object

Representation of all the CEPs range by state, as documented by Correios.

all_ranges()

Go through all the CEP ranges per state, returning a pair CEP instances, where the index 0 is the first CEP in the range and the index 2 the last one.

Return type:

Generator[tuple[CEP, CEP], None, None]

ranges_by_state(state)

Return the a pair of CEPs related to a given state code.

See brazilian_ids.functions.location.states module for all valid states codes.

Parameters:

state (str)

Return type:

tuple[CEP, CEP]

exception brazilian_ids.functions.location.cep.InvalidCepError(id, message=None)

Bases: InvalidIdError

Exception for an invalid CEP.

Parameters:

  • id (str)

  • message (None | str)

Return type:

None

id_type(cep)

Return the ID type. Subclasses must override this method.

Parameters:

cep (str)

class brazilian_ids.functions.location.cep.Singleton

Bases: type

Implement the singleton pattern.

brazilian_ids.functions.location.cep.format(cep)

Applies typical 00000-000 formatting to CEP.

Parameters:

cep (str)

Return type:

str

brazilian_ids.functions.location.cep.is_valid(cep, raw=False, digits=0)

Check if a CEP is valid or not.

The raw parameter is a small optimization: if you’re sure that the CEP string only contains numbers, then you you can skip one of the steps required to validate it. If you’re unsure, just use the default value.

The digits parameter is also used to skip one of the validations steps, if you already know before hand the length of the cep string (for any reason). Of course, if you didn’t need this information elsewhere, there is use to do len(cep) before calling this function and passing the result as digits.

Parameters:

  • cep (str)

  • raw (bool)

  • digits (int)

Return type:

bool

brazilian_ids.functions.location.cep.is_valid_extended(cep, raw=False, digits=0, state=None)

Check if a CEP is valid or not.

This function does everything that is_valid function does, plus some additional verifications that will take a longer time to finish.

Those verifications are not perfect, since Correios doesn’t allow anymore online verifications, but it does rely on published information that is still public.

If you’re are able to inform the state that you believe the CEP should be part of, then that will speed up the validation process.

Parameters:

  • cep (str)

  • raw (bool)

  • digits (int)

  • state (str | None)

Return type:

bool

brazilian_ids.functions.location.cep.parse(cep)

Split a CEP into region, sub-region, sector, subsector, division.

Parameters:

cep (str)

Return type:

CEP

brazilian_ids.functions.location.municipio module

Functions to handle Brazilian município (county) codes.

Although the municipio code has a verification digit, there are 9 known codes where those digits are invalid.

This module contains those municipio codes in the INVALID dict.

See also: - ‘Nota ténica 2008’ - IBGE

exception brazilian_ids.functions.location.municipio.InvalidMunicipioFederalUnitError(federal_unit)

Bases: ValueError

exception brazilian_ids.functions.location.municipio.InvalidMunicipioLengthError(municipio, expected_digits=7)

Bases: InvalidMunicipioTypeMixin, InvalidIdLengthError

Exception for invalid município length error.

Parameters:

  • municipio (str)

  • expected_digits (int)

Return type:

None

class brazilian_ids.functions.location.municipio.InvalidMunicipioTypeMixin

Bases: object

Mixin class for município errors.

id_type()
class brazilian_ids.functions.location.municipio.Municipio(unidade_federativa, municipio, control_digits)

Bases: object

Representation of a município based on it’s complete code.

Parameters:

  • unidade_federativa (str)

  • municipio (str)

  • control_digits (str)

property control_digits: str

Return the ‘control digits’ created by IBGE.

property federal_unit: str

Return the name of the Brazilian UF.

property federal_unit_code: str

Return the code of the ‘unidade federativa’ (UF), corresponding to one of the Brazil states or the capital.

static federal_units()
Return type:

dict[str, str]

property municipio: str

Return the município code.

brazilian_ids.functions.location.municipio.is_valid(municipio)

Check whether município code is valid.

It’s hard to check if a code is valid completely since the control digits are defined internally by IBGE and, to this date, there are 5,570 municípios in Brazil.

This function tries to check more basic aspects that are possible without copying a large amount of text to the Python code.

Also, those codes are always changing.

Parameters:

municipio (str)

Return type:

bool

brazilian_ids.functions.location.municipio.parse(municipio)
Parameters:

municipio (str)

Return type:

Municipio

Module contents