Biblioteca de utilitários projetada para validar, gerar e manipular dados de acordo com as particularidades do Brasil
Brazilian Utils é uma biblioteca com foco na resolução de problemas que enfrentamos diariamente no desenvolvimento de aplicações para o business Brasileiro.
- Instalação
- Utilização
- Utilitários
- Novos Utilitários e Reportar Bugs
- Dúvidas? Ideias?
- Contribuindo com o Código do Projeto
pip install brutilsPara usar um de nossos utilitários, basta importar a função necessária, como no exemplo abaixo:
>>>frombrutilsimportis_valid_cpf>>>is_valid_cpf('00011122233')
False- CPF
- CNPJ
- CEP
- Telefone
- Data
- CNH
- Placa de Carro
- PIS
- Processo Jurídico
- RENAVAM
- Titulo Eleitoral
- IBGE
- Feriados
- Monetário
- Natureza Jurídica
- Passaporte
Retorna se os dígitos de verificação do CPF fornecido correspondem ao seu número base. Esta função não verifica a existência do CPF; ela apenas valida o formato da string.
Argumentos:
- cpf (str): O CPF a ser validado, uma string de 11 dígitos
Retorna:
- bool: Verdadeiro se os dígitos de verificação corresponderem ao número base, Falso caso contrário.
Exemplo:
>>>frombrutilsimportis_valid_cpf>>>is_valid_cpf("82178537464")
True>>>is_valid_cpf('00011122233')
FalseFormata um CPF (Cadastro de Pessoa Física brasileiro) para exibição visual. Esta função recebe uma string de CPF contendo apenas números como entrada e adiciona símbolos de formatação padrão para exibição.
Argumentos:
- cpf (str): Uma string de CPF contendo apenas números.
Retorna:
- str: O CPF formatado com símbolos visuais se for válido, None se não for válido.
Exemplo:
>>>frombrutilsimportformat_cpf>>>format_cpf('82178537464')
'821.785.374-64'>>>format_cpf("55550207753")
'555.502.077-53'Remove símbolos específicos de uma string de CPF (Cadastro de Pessoa Física brasileiro). Esta função recebe como entrada uma string de CPF e remove todas as ocorrências dos caracteres '.', '-' dela.
Argumentos:
- cpf (str): A string de CPF contendo os símbolos a serem removidos.
Retorna:
- str: Uma nova string com os símbolos especificados removidos.
Exemplo:
>>>frombrutilsimportremove_symbols_cpf>>>remove_symbols_cpf('000.111.222-33')
'00011122233'Gerar uma string de dígitos de CPF válida aleatória.
Retorna:
- str: Um CPF válido gerado aleatoriamente.
Exemplo:
>>>frombrutilsimportgenerate_cpf>>>generate_cpf()
'17433964657'>>>generate_cpf()
"10895948109"Verifica se os dígitos de verificação do CNPJ (Cadastro Nacional da Pessoa Jurídica) fornecido correspondem ao seu número base. A entrada deve ser uma string de 14 caracteres, permitindo dígitos e letras maiúsculas nas 12 primeiras posições e dígitos nas 2 últimas. Esta função não verifica a existência do CNPJ; ela só valida o formato da string.
Argumentos:
- cnpj (str): O CNPJ a ser validado.
Retorna:
- bool: True se os dígitos de verificação corresponderem ao número base, False caso contrário.
Exemplo:
>>>frombrutilsimportis_valid_cnpj>>>is_valid_cnpj('03560714000142')
True>>>is_valid_cnpj('00111222000133')
FalseFormata uma string de CNPJ (Cadastro Nacional da Pessoa Jurídica) para exibição visual. Esta função recebe uma string de CNPJ como entrada, valida seu formato e a formata com símbolos visuais padrão para fins de exibição.
Argumentos:
- cnpj (str): A string de CNPJ a ser formatada para exibição.
Retorna:
- str: O CNPJ formatado com símbolos visuais se for válido, None se não for válido.
Exemplo:
>>>frombrutilsimportformat_cnpj>>>format_cnpj("03560714000142")
'03.560.714/0001-42'>>>format_cnpj("98765432100100")
NoneRemove símbolos específicos de uma string de CNPJ (Cadastro Nacional da Pessoa Jurídica). Esta função recebe uma string de CNPJ como entrada e remove todas as ocorrências dos caracteres '.', '/' e '-' dela.
Argumentos:
- cnpj (str): A string de CNPJ que contém os símbolos a serem removidos.
Retorna:
- str: Uma nova string com os símbolos especificados removidos.
Exemplo:
>>>frombrutilsimportremove_symbols_cnpj>>>remove_symbols_cnpj('00.111.222/0001-00')
'00111222000100'Gera uma string de CNPJ válida aleatória. Um número de filial opcional pode ser
fornecido; o padrão é 1. Use alphanumeric=True para gerar um CNPJ cujas 12
primeiras posições podem conter dígitos e letras maiúsculas.
Argumentos:
- branch (int | str): Um número de filial opcional a ser incluído no CNPJ.
Valores de filial alfanuméricos são aceitos apenas com
alphanumeric=True. - alphanumeric (bool): Define se o CNPJ gerado deve ser alfanumérico.
Retorna:
- str: Um CNPJ válido gerado aleatoriamente.
Exemplo:
>>>frombrutilsimportgenerate_cnpj>>>generate_cnpj()
'34665388000161'>>>generate_cnpj(1234)
"01745284123455">>>generate_cnpj(alphanumeric=True)
"9359QAG9000184">>>generate_cnpj(branch="AB12", alphanumeric=True)
"BR2026UTAB1290">>>generate_cnpj(branch="CD34", alphanumeric=True)
# CNPJ inválido para exemplos de validação:"NX9K79E2CD3400"Verifica se um CEP (Código de Endereçamento Postal) brasileiro é válido. Para que um CEP seja considerado válido, a entrada deve ser uma string contendo exatamente 8 dígitos. Esta função não verifica se o CEP é um CEP real, pois valida apenas o formato da string.
Argumentos:
- cep (str): A string contendo o CEP a ser verificado.
Retorno:
- bool: True se o CEP for válido (8 dígitos), False caso contrário.
Exemplo:
>>>frombrutilsimportis_valid_cep>>>is_valid_cep('01310200')
True>>>is_valid_cep("12345")
False>>>is_valid_cep("abcdefgh")
FalseFormata um CEP (Código de Endereçamento Postal) brasileiro em um formato padrão. Esta função recebe um CEP como entrada e, se for um CEP válido com 8 dígitos, o formata no padrão "12345-678".
Argumentos:
- cep (str): O CEP (Código de Endereçamento Postal) de entrada a ser formatado.
Retorna:
- str: O CEP formatado no formato "12345-678" se for válido, None se não for válido.
Example:
>>>frombrutilsimportformat_cep>>>format_cep('01310200')
'01310-200'>>>format_cep("12345678")
"12345-678">>>format_cep("12345")
NoneRemove símbolos específicos de um CEP (Código de Endereçamento Postal) fornecido. Esta função recebe um CEP como entrada e remove todas as ocorrências dos caracteres '.' e '-' dele.
Argumentos:
- cep (str): O CEP (Código de Endereçamento Postal) de entrada que contém os símbolos a serem removidos.
Retorna:
- str: Uma nova string com os símbolos especificados removidos.
Exemplo:
>>>frombrutilsimportremove_symbols_cep>>>remove_symbols_cep('01310-200')
'01310200'>>>remove_symbols_cep("123-45.678.9")
"123456789">>>remove_symbols_cep("abc.xyz")
"abcxyz"Gera um número de CEP (Código de Endereçamento Postal) aleatório de 8 dígitos como uma string.
Retorna:
- str: Um número de 8 dígitos gerado aleatoriamente.
Exemplo:
>>>frombrutilsimportgenerate_cep>>>generate_cep()
'77520503'>>>generate_cep()
'29641407'Busca as informações de endereço a partir de um CEP (Código de Endereçamento Postal) utilizando a API da ViaCEP.
Argumentos:
- cep (str): O CEP a ser utilizado na busca.
- raise_exceptions (bool, opcional): Se deve gerar exceções quando o CEP for inválido ou não for encontrado. O padrão é False.
Retorna:
- Address | None: Um objeto Address (TypedDict) contendo as informações de endereço se o CEP for encontrado, caso contrário, None.
Exemplo:
>>>frombrutilsimportget_address_from_cep>>>get_address_from_cep("12345678")
{
"cep": "12345-678",
"logradouro": "Rua Example",
"complemento": "",
"bairro": "Example",
"localidade": "Example",
"uf": "EX",
"ibge": "1234567",
"gia": "1234",
"ddd": "12",
"siafi": "1234"
}Busca o CEP e outras informações a partir de um endereço utilizando a API da ViaCEP.
Argumentos:
- federal_unit (str): Abreviação de duas letras do estado brasileiro.
- city (str): Nome da cidade.
- street (str): Nome (ou substring) da rua.
- raise_exceptions (bool, opcional): Se deve gerar exceções quando o endereço é inválido ou não foi encontrado. O padrão é False.
Retorna:
- list[Address] | None: Uma lista de objetos Address (TypedDict) contendo as informações de endereço se o endereço for encontrado, None caso contrário.
Exemplo:
>>>frombrutilsimportget_cep_information_from_address>>>get_cep_information_from_address("EX", "Example", "Rua Example")
[
{
"cep": "12345-678",
"logradouro": "Rua Example",
"complemento": "",
"bairro": "Example",
"localidade": "Example",
"uf": "EX",
"ibge": "1234567",
"gia": "1234",
"ddd": "12",
"siafi": "1234"
}
]Retorna se um número de telefone brasileiro é válido conforme o formato da string. Não verifica se o número realmente existe.
is_valid_phone(phone_number, type)
Argumentos:
phone_number (str):
- o número de telefone a ser validado
- apenas dígitos, sem símbolos
- sem o código do país
- deve incluir o número de DDD com dois dígitos
- exemplo: '+55 48 9999 9999' deve ser utilizado como '4899999999'
- obrigatório
type (str):
- 'mobile' para validar apenas números de celular
- 'landline' para validar apenas números de telefone fixo
- caso não especificado, valida para um para o outro.
- opcional
Retorna:
- bool: True se o número é válido, False caso contrário.
Exemplo:
>>>frombrutilsimportis_valid_phone>>>is_valid_phone('11994029275')
True>>>is_valid_phone('11994029275', 'mobile')
True>>>is_valid_phone('1938814933', 'landline')
TrueFormata um número de telefone para exibição visual. Esta função recebe uma string representando um número de telefone contendo apenas números como entrada e adiciona símbolos de formatação padrão para exibição.
Argumentos:
- phone (str): Uma string representando um número de telefone.
Retorna:
- str: O número de telefone formatado para exibição ou None se não for válido.
Exemplo:
>>>frombrutilsimportformat_phone>>>format_phone("11994029275")
'(11)99402-9275'>>>format_phone("1635014415")
'(16)3501-4415'>>>format_phone("333333")
NoneRemove símbolos do número de telefone. Esta função recebe um número de telefone como entrada e remove todos os símbolos, como parênteses '()', traços '-' e espaços ' '.
Argumentos:
- phone (str): O número de telefone de entrada que contém os símbolos a serem removidos.
Retorna:
- str: Uma nova string com os símbolos especificados removidos.
Exemplo:
>>>frombrutilsimportremove_symbols_phone>>>remove_symbols_phone('(21)2569-6969')
'2125696969'>>>remove_symbols_phone('11 9999-8888')
'1199998888'>>>remove_symbols_phone('333333')
'333333'Remove o código internacional (+55) de uma string que contém um número de telefone brasileiro, mantendo outros caracteres especiais.
Argumentos:
- phone (str): O número de telefone de entrada que pode conter o código internacional.
Retorna:
- str: Uma nova string sem o código internacional, preservando outros caracteres especiais.
Exemplo:
>>>frombrutilsimportremove_international_dialing_code>>>remove_international_dialing_code("5521994029275")
"21994029275">>>remove_international_dialing_code("+5521994029275")
"+21994029275">>>remove_international_dialing_code("5555994029275")
"55994029275">>>remove_international_dialing_code("21994029275")
"21994029275">>>remove_international_dialing_code("(+55)21994029275")
"(+)21994029275"Gera um número de telefone aleatório válido.
Argumentos:
- type (str): Pode ser "landline" ou "mobile". Se não for especificado, a função gera um número aleatório de qualquer tipo.
Retorna:
- str: Um número de telefone válido gerado aleatoriamente.
Exemplo:
>>>frombrutilsimportgenerate_phone>>>generate_phone()
"5929797740">>>generate_phone("mobile")
"1899115895">>>generate_phone("landline")
"5535317900"Verificar se uma string corresponde a um endereço de e-mail válido.
Argumentos:
- email (str): A string de entrada a ser verificada.
Retorna:
- bool: Verdadeiro se o email for um endereço de e-mail válido, Falso caso contrário.
Exemplo:
frombrutilsimportis_valid_email>>>is_valid_email("joao.ninguem@gmail.com")
True>>>is_valid_email(".joao.ninguem@gmail.com")
False>>>is_valid_email("joao.ninguem@gmail.")
False>>>is_valid_email("joao ninguem@gmail.com")
FalseConverte uma data em sua representação textual.
Argumentos:
- date (str): Uma string no formato dd/mm/aaaa
Retorna:
- A represetação textual da data ou None caso a data esteja mal formatada ou a data seja inválida.
Exemplo:
>>>frombrutilsimportconvert_date_to_text>>>convert_date_to_text("25/12/2000")
"Vinte e cinco de dezembro de dois mil">>>convert_date_to_text("31/02/2000")
None>>>convert_date_to_text("29/02/2024")
"Vinte e nove de fevereiro de dois mil e vinte e quatro">>>convert_date_to_text("1/08/2024")
"Primeiro de agosto de dois mil e vinte e quatro"Verifica se o número de registro de CNH (Carteira de Habilitação Nacional) brasileiro é válido. Para que um número de CNH seja considerado válido, a entrada deve ser uma string contendo exatamente 11 dígitos numéricos. Esta função não verifica se o número da CNH é real, apenas valida os dígitos verificadores.
Argumentos:
- cnh (str): A string contendo o número de registro de CNH a ser verificado.
Retorno:
- bool: True se o número de registro da CNHN for válido (11 dígitos), False caso contrário.
Exemplo:
>>>frombrutilsimportis_valid_cnh>>>is_valid_cnh("12345678901")
False>>>is_valid_cnh("A2C45678901")
False>>>is_valid_cnh("98765432100")
True>>>is_valid_cnh("987654321-00")
TrueVerifica se uma placa de carro é válida. Esta função não verifica se a placa de carro é uma placa de carro real, apenas valida o formato da string.
Argumentos:
- license_plate (str): Uma string representando uma placa de carro.
- type (str): "old_format" ou "mercosul". Se não especificado, verifica um ou outro.
Retorna:
- bool: True se a placa de carro for válida, False caso contrário.
Exemplo:
>>>frombrutilsimportis_valid_license_plate>>>is_valid_license_plate('ABC1234')
True>>>is_valid_license_plate('def5678', type="old_format")
True>>>is_valid_license_plate('ABC4E67')
True>>>is_valid_license_plate('ABC4E67', type="mercosul")
True>>>is_valid_license_plate('GHI-4567')
FalseFormata uma placa de carro no padrão correto. Esta função recebe uma placa de carro em qualquer formato (LLLNNNN ou LLLNLNN) e retorna uma versão formatada.
Argumentos:
- license_plate (str): Uma string representando uma placa de carro.
Retorna:
- str: A string da placa de carro formatada ou 'None' se a entrada for inválida.
Exemplo:
>>>frombrutilsimportformat_license_plate>>>format_license_plate("ABC1234")
"ABC-1234"# formato antigo (contém traço)>>>format_license_plate("abc1234")
"ABC-1234"# formato antigo (contém traço)>>>format_license_plate("ABC1D23")
"ABC1D23"# formato mercosul>>>format_license_plate("abc1d23")
"ABC1D23"# formato mercosul>>>format_license_plate("ABCD123")
NoneRemove o símbolo de hífen (-) de uma string de placa de carro.
Argumentos:
- license_plate_number (str): Uma string de placa de carro contendo símbolos a serem removidos.
Retorna:
- str: A string da placa de carro com os símbolos especificados removidos.
Exemplo:
frombrutilsimportremove_symbols_license_plate>>>remove_symbols_license_plate("ABC-123")
"ABC123">>>remove_symbols_license_plate("abc123")
"abc123">>>remove_symbols_license_plate("ABCD123")
"ABCD123">>>remove_symbols_license_plate("@abc#-#123@")
"@abc##123@"Gera uma placa de carro válida no formato especificado. Caso nenhum formato seja fornecido, ele retornará uma placa de carro no formato Mercosul.
Argumentos:
- format (str): O formato desejado para a placa de carro. 'LLLNNNN' para o formato antigo ou 'LLLNLNN' para o formato Mercosul. O padrão é 'LLLNLNN'.
Retorna:
- str: Um número de placa de carro gerado aleatoriamente ou None se o formato for inválido.
Exemplo:
frombrutilsimportgenerate_license_plate>>>generate_license_plate()
"ABC1D23">>>generate_license_plate(format="LLLNLNN")
"ABC4D56">>>generate_license_plate(format="LLLNNNN")
"ABC123">>>generate_license_plate(format="invalid")
NoneConverte uma placa de carro no formato antigo (LLLNNNN) para o formato Mercosul (LLLNLNN).
Argumentos:
- license_plate(str): Uma string com o tamanho adequado que representa a placa no formato antigo.
Retorna:
- str: A placa Mercosul convertida (LLLNLNN) ou None se a entrada for inválida.
Exemplo:
>>>frombrutilsimportconvert_license_plate_to_mercosul>>>convert_license_plate_to_mercosul("ABC123")
"ABC1C34">>>convert_license_plate_to_mercosul("abc123")
"ABC1C34">>>convert_license_plate_to_mercosul("ABC1D23")
NoneRetorna o formato de uma placa de carro. 'LLLNNNN' para o formato antigo e 'LLLNLNN' para o formato Mercosul.
Argumentos:
- license_plate (str): Uma string de placa de carro sem símbolos.
Retorna:
- str: O formato da placa de carro (LLLNNNN, LLLNLNN) ou 'None' se o formato for inválido.
Exemplo:
frombrutilsimportget_format_license_plate>>>get_format_license_plate("ABC123")
"LLLNNNN">>>get_format_license_plate("abc123")
"LLLNNNN">>>get_format_license_plate("ABC1D23")
"LLLNLNN">>>get_format_license_plate("abc1d23")
"LLLNLNN">>>get_format_license_plate("ABCD123")
NoneVerifica se o número PIS/PASEP é valido. Apenas números, formatados como string. Não verifica se o PIS/PASEP realmente existe.
Referências:
Argumentos:
- pis (str): Número PIS como uma string com o comprimento apropriado.
Retorna:
- bool: True se o PIS for válido, False caso contrário.
Exemplo:
frombrutilsimportis_valid_pis>>>is_valid_pis("82178537464")
False>>>is_valid_pis("12082043519")
TrueFormata uma string de PIS (Programa de Integração Social) válida com símbolos e adiciona símbolos de formatação padrão para exibição.
Argumentos:
- pis (str): Uma string válida de PIS contendo apenas números.
Retorna:
- str: Uma string de PIS formatada com símbolos visuais padrão ou None se a entrada for inválida.
Exemplo:
frombrutilsimportformat_pis>>>format_pis("17033259504")
'170.33259.50-4'>>>format_pis("12013128292")
'120.13128.29-2'Esta função recebe uma string de PIS (Programa de Integração Social) com símbolos de formatação e retorna uma versão limpa sem símbolos. Remove apenas os símbolos "-" e "." , propositalmente não remove outros símbolos.
Argumentos:
- pis (str): Uma string de PIS que pode conter símbolos de formatação.
Retorna:
- str: Uma string de PIS limpa, sem símbolos de formatação.
Exemplo:
frombrutilsimportremove_symbols_pis>>>remove_symbols_pis('170.33259.50-4')
'17033259504'>>>remove_symbols_pis("123.456.789-09")
'12345678909'>>>remove_symbols_pis('/._')
'/_'Gera uma string de dígitos contendo um número de um PIS brasileiro válido aleatório.
Retorna:
- str: Um número PIS válido gerado aleatoriamente como string.
Exemplo:
frombrutilsimportgenerate_pis>>>generate_pis()
'61352489741'>>>generate_pis()
'73453349671'Verifica se um ID de processo jurídico é válido, não verifica se o ID de processo jurídico é um ID de processo jurídico real; ela apenas valida o formato da string.
Argumentos:
- legal_process_id (str): Uma string contendo apenas dígitos que representa o ID do processo jurídico.
Retorna:
- bool: True se o ID do processo jurídico for válido, False caso contrário.
Examplo:
>>>frombrutilsimportis_valid_legal_process>>>is_valid_legal_process('10188748220234018200')
True>>>is_valid_legal_process('45532346920234025107')
True>>>is_valid_legal_process('00000000000000000000')
False>>>is_valid_legal_process('455323423QQWEQWSsasd&*(()')
False>>>Formata um ID de processo jurídico em um formato padrão.
Argumentos:
- legal_process_id (str): Uma string de 20 dígitos que representa o ID do processo jurídico.
Retorna:
- str: O ID do processo jurídico formatado ou None se a entrada for inválida.
Exemplo:
>>>frombrutilsimportformat_legal_process>>>format_legal_process('23141945820055070079')
'2314194-58.2005.5.07.0079'>>>format_legal_process('00000000000000000000')
'0000000-00.0000.0.00.0000'>>>Remove símbolos específicos de um processo jurídico fornecido.
Esta função recebe um processo jurídico como entrada e remove todas as ocorrências dos caracteres '.' e '-' dele.
Argumentos:
- legal_process (str): Um processo jurídico contendo símbolos a serem removidos.
Retorna:
- str: A string do processo jurídico com os símbolos especificados removidos.
Exemplo:
frombrutilsimportremove_symbols_legal_process>>>remove_symbols_legal_process("6439067-89.2023.4.04.5902")
"64390678920234045902">>>remove_symbols_legal_process("4976023-82.2012.7.00.2263")
"49760238220127002263">>>remove_symbols_legal_process("4976023-82.2012.7.00.2263*!*&#")
"49760238220127002263*!*&#"Gera um número válido aleatório de ID de processo jurídico.
Argumentos:
- year (int): O ano para o ID do processo jurídico (o padrão é o ano atual). Não pode ser um ano do passado.
- orgao (int): O órgão (1-9) para o ID do processo jurídico (o padrão é aleatório).
Retorna:
- str: Um ID de processo jurídico gerado aleatoriamente. None caso algum dos argumento seja inválido.
Exemplo:
>>>frombrutilsimportgenerate_legal_process>>>generate_legal_process()
"45676401020238170592">>>generate_legal_process(ano=2025)
"32110268020258121130">>>generate_legal_process(orgao=5)
"37573041520235090313">>>generate_legal_process(ano=2024, orgao=4)
"33158248820244017105"Verifica se um número de Título de Eleitor brasileiro é válido. Não verifica se realmente existe.
Referências:
- https://pt.wikipedia.org/wiki/T%C3%ADtulo_de_eleitor
- http://clubes.obmep.org.br/blog/a-matematica-nos-documentos-titulo-de-eleitor/
Argumentos:
- voter_id (str): string representando o número do título de eleitor a ser verificado.
Retorna:
- bool: True se o número do título de eleitor for válido. False, caso contrário.
Exemplo:
>>>frombrutilsimportis_valid_voter_id>>>is_valid_voter_id('123456789011')
False>>>is_valid_voter_id('427503840213')
TrueFormata um número de Título de Eleitor para exibição visual.
Esta função recebe uma string de Título de Eleitor contendo apenas números como entrada e adiciona os espaços de formatação padrão para exibição.
Argumentos:
- voter_id (str): Uma string de Título de Eleitor contendo apenas números.
Retorna:
- str: O Título de Eleitor formatado com os espaços, se for válido. Retorna None se não for válido.
Exemplo:
>>>frombrutilsimportformat_voter_id>>>format_voter_id("246593980493")
'2465 9398 04 93'>>>format_voter_id("202715292895")
'2027 1529 28 95'>>>format_voter_id("739035552205")
>>>Gera uma string de dígitos de Título de Eleitor válida aleatória a partir de um estado brasileiro informado.
Args:
- federative_union (str): Unidade Federativa para o título de eleitor que será gerado. O valor padrão "ZZ" é usado para Títulos de Eleitor emitidos para estrangeiros.
Retorna:
- str: Um Título de Eleitor válido gerado aleatoriamente.
Exemplo:
>>>frombrutilsimportgenerate_voter_id>>>generate_voter_id()
'183475722801'>>>generate_voter_id(federative_union="MG")
'950125640248'Converte um determinado código do IBGE (string de 2 dígitos) para sua UF (abreviatura estadual) correspondente.
Args:
- code (str): O código IBGE de 2 dígitos a ser convertido.
Retorna:
- str or None: O código UF correspondente ao código IBGE, ou None se o código IBGE for inválido.
Exemplo:
>>>frombrutils.ibge.ufimportconvert_code_to_uf>>>convert_code_to_uf("12")
'AC'>>>convert_code_to_uf("33")
'RJ'>>>convert_code_to_uf("99")
>>>Retorna o código IBGE para um dado nome de município e código de UF.
Essa função recebe uma string representando o nome de um município e o código da UF, e retorna o código IBGE correspondente (string). A função lida com os nomes ignorando diferenças de maiúsculas, acentos, tratando o caractere "ç" como "c", e ignorando diferenças de maiúsculas para o código da UF.
Argumentos:
- municipality_name (str): O nome do município.
- uf (str): O código UF do estado.
Retorna:
- str: O código IBGE do município. Retorna None se o nome não for válido ou não existir.
Exemplo:
>>>frombrutilsimportget_code_by_municipality_name>>>get_code_by_municipality_name("São Paulo", "SP")
"3550308">>>get_code_by_municipality_name("goiania", "go")
"5208707">>>get_code_by_municipality_name("Conceição do Coité", "BA")
"2908408">>>get_code_by_municipality_name("conceicao do Coite", "Ba")
"2908408">>>get_code_by_municipality_name("Municipio Inexistente", "")
None>>>get_code_by_municipality_name("Municipio Inexistente", "RS")
NoneRetorna o nome do município e a UF para um código do IBGE.
Args:
- code (str): O código do IBGE para o município.
Returns:
- tuple: Retorna uma Tupla formatado como ("Município", "UF").
- None: Retorna None se o código for inválido.
Example:
>>>frombrutilsimportget_municipality_by_code>>>get_municipality_by_code(3550308)
("São Paulo", "SP")Converte um código de UF brasileiro (por exemplo, 'SP') no nome completo do estado ('São Paulo').
A busca é case-insensitive (não diferencia maiúsculas de minúsculas) e ignora espaços em branco ao redor.
Argumentos:
- uf (str): Código de UF com duas letras.
Retorna:
- str | None: O nome completo do estado, ou
Nonese o código for inválido.
Exemplo:
>>>frombrutils.ibge.ufimportconvert_uf_to_name>>>convert_uf_to_name('SP')
'São Paulo'>>>convert_uf_to_name('rj')
'Rio de Janeiro'Converte o nome completo de um estado brasileiro para seu código UF.
Esta função recebe o nome completo de um estado brasileiro e retorna o código UF de duas letras correspondente. A comparação ignora maiúsculas/minúsculas e acentos.
Argumentos:
- state_name (str): O nome completo do estado (por exemplo, 'São Paulo', 'sao paulo').
Retorna:
- str | None: O código UF se encontrado, ou None se o nome do estado for inválido.
Exemplo:
>>>frombrutils.ibge.ufimportconvert_name_to_uf>>>convert_name_to_uf('São Paulo')
'SP'>>>convert_name_to_uf('sao paulo')
'SP'>>>convert_name_to_uf('Rio de Janeiro')
'RJ'>>>convert_name_to_uf('rio de janeiro')
'RJ'>>>convert_name_to_uf('Estado Inválido')
>>>Verifica se uma determinada data é um feriado nacional ou estadual no Brasil.
Esta função recebe um objeto datetime como a data e uma UF opcional (Unidade Federativa) para especificar feriados estaduais. Retorna True se a data for um feriado, False se não for, ou None se a data ou UF forem inválidas. Nota: a função não abrange feriados municipais.
Argumentos:
date (datetime): A data a ser verificada.uf (str, opcional): A abreviação do estado (UF) para verificar feriados estaduais. Se não fornecido, apenas feriados nacionais são considerados.
Retorna:
bool | None:Truese a data for um feriado,Falsese não for, ouNonese a data ou UF forem inválidas.
Exemplo:
>>>fromdatetimeimportdatetime>>>frombrutilsimportis_holiday>>>is_holiday(datetime(2024, 1, 1))
True>>>is_holiday(datetime(2024, 1, 2))
False>>>is_holiday(datetime(2024, 3, 2), uf="SP")
False>>>is_holiday(datetime(2024, 12, 25), uf="RJ")
TrueFormata um número seguindo o padrão monetário brasileiro. O número será formatado adicionando o símbolo R$ como prefixo, vírgula como separador decimal, e ponto como agrupador de milhar.
Argumentos:
- float ou Decimal: Um número com ou sem casas decimais.
Retorna:
- str ou None: O número formatado seguindo o padrão brasileiro.
Exemplo:
>>>frombrutils.currencyimportformat_currency>>>format_currency(1259.03)
'R$ 1.259,03'>>>format_currency(0)
'R$ 0,00'>>>format_currency("not a number")
NoneConverte um valor monetário em reais para sua representação por extenso. Esta função recebe um número decimal representando um valor monetário em reais e o converte para uma string com o valor escrito por extenso em português do Brasil. Ela trata tanto a parte inteira (reais) quanto a parte fracionária (centavos), respeitando a gramática correta para os casos de singular e plural, bem como casos especiais como zero e valores negativos.
Argumentos:
- amount (decimal): O valor monetário a ser convertido por extenso.
- A parte inteira representa os reais.
- A parte decimal representa os centavos.
- 2 casas decimais.
Retorna:
- str: Uma string com o valor monetário escrito por extenso em português do Brasil.
- Retorna "Zero reais" para o valor 0,00.
- Retorna None se o valor for inválido ou absolutamente maior que 1 quatrilhão.
- Trata valores negativos, adicionando "Menos" no início da string.
Limitações:
- Esta função pode perder precisão em ±1 centavo para casos em que o valor absoluto ultrapasse trilhões devido a erros de arredondamento de ponto flutuante.
Exemplo:
>>>frombrutils.currencyimportconvert_real_to_text>>>convert_real_to_text(1523.45)
'Mil, quinhentos e vinte e três reais e quarenta e cinco centavos'>>>convert_real_to_text(0.01)
'Um centavo'>>>convert_real_to_text(0.00)
'Zero reais'>>>convert_real_to_text(-50.25)
'Menos cinquenta reais e vinte e cinco centavos'>>>convert_real_to_text("invalid")
NoneValida se o código informado existe na tabela oficial. Aceita NNNN ou NNN-N.
O valor é normalizado antes da checagem: remove espaços, mantém apenas dígitos e aceita hífen entre o 3º e 4º dígitos.
Argumentos
code (str): Código de 4 dígitos (ex.:"2062"ou"206-2")
Retorna
bool:Truese existir na tabela,Falsecaso contrário.
Exemplo
>>>frombrutilsimportlegal_nature>>>legal_nature.is_valid("2062") True>>>legal_nature.is_valid("206-2") True>>>legal_nature.is_valid("9999") FalseRetorna a descrição oficial do código de Natureza Jurídica. Aceita NNNN ou NNN-N. Aplica a mesma normalização do is_valid.
Argumentos
code (str): Código de 4 dígitos
Retorna
str | None: Descrição correspondente ouNonese o código for inválido ou inexistente.
Exemplo
>>>frombrutilsimportlegal_nature>>>legal_nature.get_description("2062") 'Sociedade Empresária Limitada'>>>legal_nature.get_description("101-5") 'Órgão Público do Poder Executivo Federal'>>>legal_nature.get_description("0000") NoneRetorna uma cópia do dicionário completo {codigo: descricao}.
Retorna
dict[str, str]: Mapeamento de todos os códigos para suas descrições.
Exemplo
>>>frombrutilsimportlegal_nature>>>data=legal_nature.list_all()
>>>len(data) >0True>>>data["2062"] 'Sociedade Empresária Limitada'Valida se os dígitos de verificação do RENAVAM fornecido correspondem aos seus 10 dígitos iniciais. Esta função não verifica a existência do veículo; ela apenas valida o formato da string e o dígito verificador.
Argumentos:
- renavam (str): O RENAVAM a ser validado, uma string de 11 dígitos.
Retorna:
- bool: Verdadeiro se o RENAVAM for válido
Falso caso contrário.
Exemplo:
>>>frombrutilsimportis_valid_renavam>>>is_valid_renavam("86769597308")
True>>>is_valid_renavam("12345678901")
FalseVerifica se um número de passaporte brasileiro é válido.
Para ser considerado válido, a entrada deve ser uma string contendo exatamente dois caracteres alfabéticos seguidos de exatamente seis dígitos numéricos.
Esta função não verifica se a entrada é um número de passaporte real, pois não existem dígitos verificadores para o passaporte brasileiro.
Argumentos:
- passport (str): A string contendo o número do passaporte a ser verificado.
Retorna:
- bool: True se o número do passaporte for válido (2 letras seguidas de 6 dígitos). False caso contrário.
Exemplo:
>>>frombrutilsimportis_valid_passport>>>is_valid_passport("Ab123456")
True>>>is_valid_passport("12345678")
False>>>is_valid_passport("DC-221345")
FalseFormata um número de passaporte brasileiro para exibição.
Esta função recebe uma string representando um número de passaporte válido e o retorna formatado (maiúsculas, sem símbolos).
Argumentos:
- passport (str | None): Um número de passaporte brasileiro (minúsculas ou maiúsculas, possivelmente incluindo símbolos)
Retorna:
- str: O número do passaporte formatado (maiúsculas, sem símbolos) ou None se a entrada for inválida
Exemplo:
>>>frombrutilsimportformat_passport>>>format_passport("Ab123456")
AB123456>>>format_passport("Ab-123456")
AB123456>>>format_passport("111111")
NoneRemove símbolos ('-', '.' e espaços em branco) de um número de passaporte.
Esta função recebe uma string com um número de passaporte como entrada e remove todas as ocorrências dos caracteres '.', '-' e espaço em branco.
Argumentos:
- passport (str): A string contendo um número de passaporte
Retorna:
- str: O número do passaporte com hífens (-), pontos (.) e espaços em branco ( ) removidos.
Exemplo:
>>>frombrutilsimportremove_symbols_passport>>>remove_symbols_passport("Ab123456")
Ab123456>>>remove_symbols_passport("Ab-123456")
Ab123456>>>remove_symbols_passport("Ab -. 123456")
Ab123456Gera uma string com um número de passaporte brasileiro válido aleatório.
Esta função gera uma string com um número de passaporte brasileiro aleatório.
Retorna:
- str: Uma string com um número de passaporte válido aleatório.
Exemplo:
>>>frombrutilsimportgenerate_passport>>>generate_passport()
"RY393097">>>generate_passport()
"ZS840088"Caso queira sugerir novas funcionalidades ou reportar bugs, basta criar uma nova issue e iremos lhe responder por lá!
(Para saber mais sobre github issues, confira a documentação oficial do GitHub).
Dúvidas de como utilizar a biblioteca? Novas ideias para o projeto? Quer compartilhar algo com a gente? Fique à vontade para criar um tópico no nosso Discussions que iremos interagir por lá!
(Para saber mais sobre github discussions, confira a documentação oficial do GitHub).
Sua colaboração é sempre muito bem-vinda! Preparamos o arquivo CONTRIBUTING.md para te ajudar nos primeiros passos. Lá você encontrará toda a informação necessária para contribuir com o projeto. Não hesite em nos perguntar utilizando o GitHub Discussions caso haja qualquer dificuldade ou dúvida. Toda ajuda conta!
Vamos construir juntos! 🚀🚀
Feito por contrib.rocks.