Package: brutils
🇧🇷 Brazilian UtilsUtils library for Brazilian-specific businesses.Looking for the english version?IntroduçãoBrazilian Utils é uma biblioteca com foco na resolução de problemas que enfrentamos diariamente no
desenvolvimento de aplicações para o business Brasileiro.InstalaçãoUtilizaçãoUtilitáriosNovos Utilitários e Reportar BugsDúvidas? Ideias?Contribuindo com o Código do ProjetoInstalaçãopip install brutilsUtilizaçãoPara usar um de nossos utilitários, basta importar a função necessária, como no exemplo abaixo:>>>frombrutilsimportis_valid_cpf>>>is_valid_cpf('00011122233')FalseUtilitáriosCPFis_valid_cpfformat_cpfremove_symbols_cpfgenerate_cpfCNPJis_valid_cnpjformat_cnpjremove_symbols_cnpjgenerate_cnpjCEPis_valid_cepformat_cepremove_symbols_cepgenerate_cepTelefoneis_valid_phoneformat_phoneremove_symbols_phoneremove_international_dialing_codegenerate_phoneEmailis_valid_emailPlaca de Carrois_valid_license_plateformat_license_plateremove_symbols_license_plategenerate_license_plateconvert_license_plate_to_mercosulget_format_license_platePISis_valid_pisformat_pisremove_symbols_pisgenerate_pisProcesso Jurídicois_valid_legal_processformat_legal_processremove_symbols_legal_processgenerate_legal_processTítulo Eleitoralis_valid_voter_idCPFis_valid_cpfRetorna 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ígitosRetorna: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')Falseformat_cpfFormata 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_symbols_cpfRemove 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'generate_cpfGerar 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"CNPJis_valid_cnpjVerifica 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:>>>frombrutilsimportis_valid_cnpj>>>is_valid_cnpj('03560714000142')True>>>is_valid_cnpj('00111222000133')Falseformat_cnpjFormata 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_symbols_cnpjRemove 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'generate_cnpjGera 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:>>>frombrutilsimportgenerate_cnpj>>>generate_cnpj()'34665388000161'>>>generate(1234)"01745284123455"CEPis_valid_cepVerifica 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")Falseformat_cepFormata 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_symbols_cepRemove 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"generate_cepGera 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'Telefoneis_valid_phoneRetorna 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 validadoapenas dígitos, sem símbolossem o código do paísdeve incluir o número de DDD com dois dígitosexemplo: '+55 48 9999 9999' deve ser utilizado como '4899999999'obrigatóriotype (str):'mobile' para validar apenas números de celular'landline' para validar apenas números de telefone fixocaso não especificado, valida para um para o outro.opcionalRetorna: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')Trueformat_phoneFormata 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")>>>remove_symbols_phoneRemove 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_international_dialing_codeRemove 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"generate_phoneGera 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"Emailis_valid_emailVerificar 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")FalsePlaca de Carrois_valid_license_plateVerifica 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')Falseformat_license_plateFormata 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_symbols_license_plateRemove 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@"generate_license_plateGera 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")Noneconvert_license_plate_to_mercosulConverte 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")Noneget_format_license_plateRetorna 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")NonePISis_valid_pisVerifica 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:frombrutilsimportis_valid_pis>>>is_valid_pis("82178537464")False>>>is_valid_pis("12082043519")Trueformat_pisFormata 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'remove_symbols_pisEsta 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('/._')'/_'generate_pisGera 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'Processo Jurídicois_valid_legal_processVerifica 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>>>format_legal_processFormata 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_symbols_legal_processRemove 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*!*&#"generate_legal_processGera 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"Titulo Eleitoralis_valid_voter_idVerifica 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_eleitorhttp://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')TrueNovos Utilitários e Reportar BugsCaso queira sugerir novas funcionalidades ou reportar bugs, basta criar
uma novaissuee iremos lhe responder por lá!(Para saber mais sobre github issues, confira adocumentação oficial do GitHub).Dúvidas? Ideias?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 nossoDiscussionsque iremos interagir por lá!(Para saber mais sobre github discussions, confira adocumentação oficial do GitHub).Contribuindo com o Código do ProjetoSua colaboração é sempre muito bem-vinda! Preparamos o arquivoCONTRIBUTING.mdpara
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 oGitHub Discussionscaso
haja qualquer dificuldade ou dúvida. Toda ajuda conta!Vamos construir juntos! 🚀🚀