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 brutils

Para usar um de nossos utilitários, basta importar a função necessária, como no exemplo abaixo:

>>> from brutils import is_valid_cpf >>> is_valid_cpf('00011122233') False

• CPF
  • is_valid_cpf
  • format_cpf
  • remove_symbols_cpf
  • generate_cpf
• CNPJ
  • is_valid_cnpj
  • format_cnpj
  • remove_symbols_cnpj
  • generate_cnpj
• CEP
  • is_valid_cep
  • format_cep
  • remove_symbols_cep
  • generate_cep
  • get_address_from_cep
  • get_cep_information_from_address
• Telefone
  • is_valid_phone
  • format_phone
  • remove_symbols_phone
  • remove_international_dialing_code
  • generate_phone
• Email
  • is_valid_email
• Data
  • convert_date_to_text
• Placa de Carro
  • is_valid_license_plate
  • format_license_plate
  • remove_symbols_license_plate
  • generate_license_plate
  • convert_license_plate_to_mercosul
  • get_format_license_plate
• PIS
  • is_valid_pis
  • format_pis
  • remove_symbols_pis
  • generate_pis
• Processo Jurídico
  • is_valid_legal_process
  • format_legal_process
  • remove_symbols_legal_process
  • generate_legal_process
• Titulo Eleitoral
  • is_valid_voter_id
  • format_voter_id
  • generate_voter_id
• IBGE
  • convert_code_to_uf
  • convert_uf_to_name
  • get_code_by_municipality_name
  • get_municipality_by_code
• Feriados
  • is_holiday
• Monetário
  • format_currency
  • convert_real_to_text

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:

>>> from brutils import is_valid_cpf >>> is_valid_cpf("82178537464") True >>> is_valid_cpf('00011122233') False

Formata 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:

>>> from brutils import format_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:

>>> from brutils import remove_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:

>>> from brutils import generate_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 dígitos com o comprimento apropriado. 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:

>>> from brutils import is_valid_cnpj >>> is_valid_cnpj('03560714000142') True >>> is_valid_cnpj('00111222000133') False

Formata 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:

>>> from brutils import format_cnpj >>> format_cnpj("03560714000142") '03.560.714/0001-42' >>> format_cnpj("98765432100100") None

Remove 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:

>>> from brutils import remove_symbols_cnpj >>> remove_symbols_cnpj('00.111.222/0001-00') '00111222000100'

Gera uma string de dígitos CNPJ válida aleatória. Um número de filial opcional pode ser fornecido; o padrão é 1.

Argumentos:

• branch (int): Um número de filial opcional a ser incluído no CNPJ.

Retorna:

• str: Um CNPJ válido gerado aleatoriamente.

Exemplo:

>>> from brutils import generate_cnpj >>> generate_cnpj() '34665388000161' >>> generate_cnpj(1234) "01745284123455"

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:

>>> from brutils import is_valid_cep >>> is_valid_cep('01310200') True >>> is_valid_cep("12345") False >>> is_valid_cep("abcdefgh") False

Formata 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:

>>> from brutils import format_cep >>> format_cep('01310200') '01310-200' >>> format_cep("12345678") "12345-678" >>> format_cep("12345") None

Remove 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:

>>> from brutils import remove_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:

>>> from brutils import generate_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:

>>> from brutils import get_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:

>>> from brutils import get_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:

>>> from brutils import is_valid_phone >>> is_valid_phone('11994029275') True >>> is_valid_phone('11994029275', 'mobile') True >>> is_valid_phone('1938814933', 'landline') True

Formata 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:

>>> from brutils import format_phone >>> format_phone("11994029275") '(11)99402-9275' >>> format_phone("1635014415") '(16)3501-4415' >>> format_phone("333333") None

Remove 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:

>>> from brutils import remove_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:

>>> from brutils import remove_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:

>>> from brutils import generate_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:

from brutils import is_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") False

Converte 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:

>>> from brutils import convert_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 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:

>>> from brutils import is_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') False

Formata 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:

>>> from brutils import format_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") None

Remove 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:

from brutils import remove_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:

from brutils import generate_license_plate >>> generate_license_plate() "ABC1D23" >>> generate_license_plate(format="LLLNLNN") "ABC4D56" >>> generate_license_plate(format="LLLNNNN") "ABC123" >>> generate_license_plate(format="invalid") None

Converte 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:

>>> from brutils import convert_license_plate_to_mercosul >>> convert_license_plate_to_mercosul("ABC123") "ABC1C34" >>> convert_license_plate_to_mercosul("abc123") "ABC1C34" >>> convert_license_plate_to_mercosul("ABC1D23") None

Retorna 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:

from brutils import get_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") None

Verifica se o número PIS/PASEP é valido. Apenas números, formatados como string. Não verifica se o PIS/PASEP realmente existe.

Referências:

• https://www.macoratti.net/alg_pis.htm.

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:

from brutils import is_valid_pis >>> is_valid_pis("82178537464") False >>> is_valid_pis("12082043519") True

Formata 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:

from brutils import format_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:

from brutils import remove_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:

from brutils import generate_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:

>>> from brutils import is_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:

>>> from brutils import format_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:

from brutils import remove_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:

>>> from brutils import generate_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:

>>> from brutils import is_valid_voter_id >>> is_valid_voter_id('123456789011') False >>> is_valid_voter_id('427503840213') True

Formata 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:

>>> from brutils import format_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:

>>> from brutils import generate_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:

>>> from brutils.ibge.uf import convert_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:

>>> from brutils import get_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") None

Retorna 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:

>>> from brutils import get_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 None se o código for inválido.

Exemplo:

>>> from brutils.ibge.uf import convert_uf_to_name >>> convert_uf_to_name('SP') 'São Paulo' >>> convert_uf_to_name('rj') 'Rio de Janeiro'

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: True se a data for um feriado, False se não for, ou None se a data ou UF forem inválidas.

Exemplo:

>>> from datetime import datetime >>> from brutils import is_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") True

Formata 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:

>>> from brutils.currency import format_currency >>> format_currency(1259.03) 'R$ 1.259,03' >>> format_currency(0) 'R$ 0,00' >>> format_currency("not a number") None

Converte 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:

>>> from brutils.currency import convert_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") None

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.