{"id":13501233,"url":"https://github.com/brazilian-utils/brutils-python","last_synced_at":"2025-03-29T08:32:15.836Z","repository":{"id":48515432,"uuid":"78506265","full_name":"brazilian-utils/brutils-python","owner":"brazilian-utils","description":"Biblioteca de utilitários projetada para validar, gerar e manipular dados de acordo com as particularidades do Brasil 🇧🇷","archived":false,"fork":false,"pushed_at":"2025-03-17T03:25:47.000Z","size":590,"stargazers_count":286,"open_issues_count":49,"forks_count":73,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-03-18T17:58:59.533Z","etag":null,"topics":["brazil","cnpj","cpf","email","hacktoberfest","pip","pis","placa-de-carro","processo-juridico","python","tituloeleitor","validation"],"latest_commit_sha":null,"homepage":"https://pypi.python.org/pypi/brutils","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brazilian-utils.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["cumbucadev","camilamaia"]}},"created_at":"2017-01-10T06:52:22.000Z","updated_at":"2025-03-13T20:05:22.000Z","dependencies_parsed_at":"2022-09-21T07:15:14.790Z","dependency_job_id":"dfa7ff87-fc93-4145-8b67-47d51da54605","html_url":"https://github.com/brazilian-utils/brutils-python","commit_stats":{"total_commits":207,"total_committers":16,"mean_commits":12.9375,"dds":0.6666666666666667,"last_synced_commit":"f8889b280e459824130e874b8818dd0124b79abc"},"previous_names":["luizberti/brutils","brazilian-utils/brutils"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brazilian-utils%2Fbrutils-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brazilian-utils%2Fbrutils-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brazilian-utils%2Fbrutils-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brazilian-utils%2Fbrutils-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brazilian-utils","download_url":"https://codeload.github.com/brazilian-utils/brutils-python/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246162092,"owners_count":20733351,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["brazil","cnpj","cpf","email","hacktoberfest","pip","pis","placa-de-carro","processo-juridico","python","tituloeleitor","validation"],"created_at":"2024-07-31T22:01:30.023Z","updated_at":"2025-03-29T08:32:15.829Z","avatar_url":"https://github.com/brazilian-utils.png","language":"Python","funding_links":["https://github.com/sponsors/cumbucadev","https://github.com/sponsors/camilamaia"],"categories":["Python","Uncategorized"],"sub_categories":["Uncategorized"],"readme":"\u003cdiv align=\"center\"\u003e\n\u003ch1\u003e🇧🇷 Brazilian Utils\u003c/h1\u003e\n\n\u003cp\u003eUtils library for Brazilian-specific businesses.\u003c/p\u003e\n\n[![codecov](https://codecov.io/gh/brazilian-utils/brutils-python/branch/main/graph/badge.svg?token=5KNECS8JYF)](https://codecov.io/gh/brazilian-utils/brutils-python)\n[![Downloads per Month](https://shields.io/pypi/dm/brutils)](https://pypistats.org/packages/brutils)\n[![Package version](https://shields.io/pypi/v/brutils)](https://pypi.org/project/brutils/)\n\n### [Looking for the english version?](README_EN.md)\n\n\u003c/div\u003e\n\n# Introdução\n\nBrazilian Utils é uma biblioteca com foco na resolução de problemas que enfrentamos diariamente no\ndesenvolvimento de aplicações para o business Brasileiro.\n\n- [Instalação](#instalação)\n- [Utilização](#utilização)\n- [Utilitários](#utilitários)\n- [Novos Utilitários e Reportar Bugs](#novos-utilitários-e-reportar-bugs)\n- [Dúvidas? Ideias?](#dúvidas-ideias)\n- [Contribuindo com o Código do Projeto](#contribuindo-com-o-código-do-projeto)\n\n# Instalação\n\n```bash\npip install brutils\n```\n\n# Utilização\n\nPara usar um de nossos utilitários, basta importar a função necessária, como no exemplo abaixo:\n\n```python\n\u003e\u003e\u003e from brutils import is_valid_cpf\n\u003e\u003e\u003e is_valid_cpf('00011122233')\nFalse\n```\n\n# Utilitários\n\n- [CPF](#cpf)\n  - [is\\_valid\\_cpf](#is_valid_cpf)\n  - [format\\_cpf](#format_cpf)\n  - [remove\\_symbols\\_cpf](#remove_symbols_cpf)\n  - [generate\\_cpf](#generate_cpf)\n- [CNPJ](#cnpj)\n  - [is\\_valid\\_cnpj](#is_valid_cnpj)\n  - [format\\_cnpj](#format_cnpj)\n  - [remove\\_symbols\\_cnpj](#remove_symbols_cnpj)\n  - [generate\\_cnpj](#generate_cnpj)\n- [CEP](#cep)\n  - [is\\_valid\\_cep](#is_valid_cep)\n  - [format\\_cep](#format_cep)\n  - [remove\\_symbols\\_cep](#remove_symbols_cep)\n  - [generate\\_cep](#generate_cep)\n  - [get\\_address\\_from\\_cep](#get_address_from_cep)\n  - [get\\_cep\\_information\\_from\\_address](#get_cep_information_from_address)\n- [Telefone](#telefone)\n  - [is\\_valid\\_phone](#is_valid_phone)\n  - [format\\_phone](#format_phone)\n  - [remove\\_symbols\\_phone](#remove_symbols_phone)\n  - [remove\\_international\\_dialing\\_code](#remove_international_dialing_code)\n  - [generate\\_phone](#generate_phone)\n- [Email](#email)\n  - [is\\_valid\\_email](#is_valid_email)\n- [Data](#date)\n  - [convert\\_date\\_to_text](#convert_date_to_text) \n- [Placa de Carro](#placa-de-carro)\n  - [is\\_valid\\_license\\_plate](#is_valid_license_plate)\n  - [format\\_license\\_plate](#format_license_plate)\n  - [remove\\_symbols\\_license\\_plate](#remove_symbols_license_plate)\n  - [generate\\_license\\_plate](#generate_license_plate)\n  - [convert\\_license\\_plate\\_to\\_mercosul](#convert_license_plate_to_mercosul)\n  - [get\\_format\\_license\\_plate](#get_format_license_plate)\n- [PIS](#pis)\n  - [is\\_valid\\_pis](#is_valid_pis)\n  - [format\\_pis](#format_pis)\n  - [remove\\_symbols\\_pis](#remove_symbols_pis)\n  - [generate\\_pis](#generate_pis)\n- [Processo Jurídico](#processo-jurídico)\n- [is\\_valid\\_legal\\_process](#is_valid_legal_process)\n  - [format\\_legal\\_process](#format_legal_process)\n  - [remove\\_symbols\\_legal\\_process](#remove_symbols_legal_process)\n  - [generate\\_legal\\_process](#generate_legal_process)\n- [Titulo Eleitoral](#titulo-eleitoral)\n  - [is\\_valid\\_voter\\_id](#is_valid_voter_id)\n  - [format\\_voter\\_id](#format_voter_id)\n  - [generate\\_voter\\_id](#generate_voter_id)\n- [IBGE](#ibge)\n  - [get_code_by_municipality_name](#get_code_by_municipality_name)\n  - [convert_code_to_uf](#convert_code_to_uf)\n  - [get\\_municipality\\_by\\_code](#get_municipality_by_code)\n- [Feriados](#feriados)\n  - [is_holiday](#is_holiday)\n- [Monetário](#monetário)\n  - [format\\_currency](#format_currency)\n\n## CPF\n\n### is_valid_cpf\n\nRetorna se os dígitos de verificação do CPF fornecido\ncorrespondem ao seu número base. Esta função não verifica a existência do CPF;\nela apenas valida o formato da string.\n\nArgumentos:\n\n- cpf (str): O CPF a ser validado, uma string de 11 dígitos\n\nRetorna:\n\n- bool: Verdadeiro se os dígitos de verificação corresponderem ao número base,\n          Falso caso contrário.\n\nExemplo:\n\n```python\n\u003e\u003e\u003e from brutils import is_valid_cpf\n\u003e\u003e\u003e is_valid_cpf(\"82178537464\")\nTrue\n\u003e\u003e\u003e is_valid_cpf('00011122233')\nFalse\n```\n\n### format_cpf\n\nFormata um CPF (Cadastro de Pessoa Física brasileiro) para exibição visual.\nEsta função recebe uma string de CPF contendo apenas números como entrada e\nadiciona símbolos de formatação padrão para exibição.\n\nArgumentos:\n\n- cpf (str): Uma string de CPF contendo apenas números.\n\nRetorna:\n\n- str: O CPF formatado com símbolos visuais se for válido,\n         None se não for válido.\n\nExemplo:\n\n```python\n\u003e\u003e\u003e from brutils import format_cpf\n\u003e\u003e\u003e format_cpf('82178537464')\n'821.785.374-64'\n\u003e\u003e\u003e format_cpf(\"55550207753\")\n'555.502.077-53'\n```\n\n### remove_symbols_cpf\n\nRemove símbolos específicos de uma string de CPF (Cadastro de Pessoa Física\nbrasileiro). Esta função recebe como entrada uma string de CPF e remove todas as\nocorrências dos caracteres '.', '-' dela.\n\nArgumentos:\n\n- cpf (str): A string de CPF contendo os símbolos a serem removidos.\n\nRetorna:\n\n- str: Uma nova string com os símbolos especificados removidos.\n\nExemplo:\n\n```python\n\u003e\u003e\u003e from brutils import remove_symbols_cpf\n\u003e\u003e\u003e remove_symbols_cpf('000.111.222-33')\n'00011122233'\n```\n\n### generate_cpf\n\nGerar uma string de dígitos de CPF válida aleatória.\n\nRetorna:\n\n- str: Um CPF válido gerado aleatoriamente.\n\nExemplo:\n\n```python\n\u003e\u003e\u003e from brutils import generate_cpf\n\u003e\u003e\u003e generate_cpf()\n'17433964657'\n\u003e\u003e\u003e generate_cpf()\n\"10895948109\"\n```\n\n## CNPJ\n\n### is_valid_cnpj\n\nVerifica se os dígitos de verificação do CNPJ (Cadastro Nacional da Pessoa\nJurídica) fornecido correspondem ao seu número base. A entrada deve ser uma\nstring de dígitos com o comprimento apropriado. Esta função não verifica a\nexistência do CNPJ; ela só valida o formato da string.\n\nArgumentos:\n\n- cnpj (str): O CNPJ a ser validado.\n\nRetorna:\n\n- bool: True se os dígitos de verificação corresponderem ao número base,\n        False caso contrário.\n\nExemplo:\n\n```python\n\u003e\u003e\u003e from brutils import is_valid_cnpj\n\u003e\u003e\u003e is_valid_cnpj('03560714000142')\nTrue\n\u003e\u003e\u003e is_valid_cnpj('00111222000133')\nFalse\n```\n\n### format_cnpj\n\nFormata uma string de CNPJ (Cadastro Nacional da Pessoa Jurídica) para exibição\nvisual.\nEsta função recebe uma string de CNPJ como entrada, valida seu formato e a\nformata com símbolos visuais padrão para fins de exibição.\n\nArgumentos:\n\n- cnpj (str): A string de CNPJ a ser formatada para exibição.\n\nRetorna:\n\n- str: O CNPJ formatado com símbolos visuais se for válido, None se não for válido.\n\nExemplo:\n\n```python\n\u003e\u003e\u003e from brutils import format_cnpj\n\u003e\u003e\u003e format_cnpj(\"03560714000142\")\n'03.560.714/0001-42'\n\u003e\u003e\u003e format_cnpj(\"98765432100100\")\nNone\n```\n\n### remove_symbols_cnpj\n\nRemove símbolos específicos de uma string de CNPJ (Cadastro Nacional da Pessoa\nJurídica).\nEsta função recebe uma string de CNPJ como entrada e remove todas as\nocorrências dos caracteres '.', '/' e '-' dela.\n\nArgumentos:\n\n- cnpj (str): A string de CNPJ que contém os símbolos a serem removidos.\n\nRetorna:\n\n- str: Uma nova string com os símbolos especificados removidos.\n\nExemplo:\n\n```python\n\u003e\u003e\u003e from brutils import remove_symbols_cnpj\n\u003e\u003e\u003e remove_symbols_cnpj('00.111.222/0001-00')\n'00111222000100'\n```\n\n### generate_cnpj\n\nGera uma string de dígitos CNPJ válida aleatória. Um número de filial\nopcional pode ser fornecido; o padrão é 1.\n\nArgumentos:\n\n- branch (int): Um número de filial opcional a ser incluído no CNPJ.\n\nRetorna:\n\n- str: Um CNPJ válido gerado aleatoriamente.\n\nExemplo:\n\n```python\n\u003e\u003e\u003e from brutils import generate_cnpj\n\u003e\u003e\u003e generate_cnpj()\n'34665388000161'\n\u003e\u003e\u003e generate_cnpj(1234)\n\"01745284123455\"\n```\n\n## CEP\n\n### is_valid_cep\n\nVerifica se um CEP (Código de Endereçamento Postal) brasileiro é válido.\nPara que um CEP seja considerado válido, a entrada deve ser uma string contendo\nexatamente 8 dígitos. Esta função não verifica se o CEP é um CEP real, pois\nvalida apenas o formato da string.\n\nArgumentos:\n\n- cep (str): A string contendo o CEP a ser verificado.\n\nRetorno:\n\n- bool: True se o CEP for válido (8 dígitos), False caso contrário.\n\nExemplo:\n\n```python\n\u003e\u003e\u003e from brutils import is_valid_cep\n\u003e\u003e\u003e is_valid_cep('01310200')\nTrue\n\u003e\u003e\u003e is_valid_cep(\"12345\")\nFalse\n\u003e\u003e\u003e is_valid_cep(\"abcdefgh\")\nFalse\n```\n\n### format_cep\n\nFormata um CEP (Código de Endereçamento Postal) brasileiro em um formato padrão.\nEsta função recebe um CEP como entrada e, se for um CEP válido com 8 dígitos,\no formata no padrão \"12345-678\".\n\nArgumentos:\n\n- cep (str): O CEP (Código de Endereçamento Postal) de entrada a ser\n              formatado.\n\nRetorna:\n\n- str: O CEP formatado no formato \"12345-678\" se for válido, None se não for\n        válido.\n\nExample:\n\n```python\n\u003e\u003e\u003e from brutils import format_cep\n\u003e\u003e\u003e format_cep('01310200')\n'01310-200'\n\u003e\u003e\u003e format_cep(\"12345678\")\n\"12345-678\"\n\u003e\u003e\u003e format_cep(\"12345\")\nNone\n```\n\n### remove_symbols_cep\n\nRemove símbolos específicos de um CEP (Código de Endereçamento Postal)\nfornecido. Esta função recebe um CEP como entrada e remove todas as ocorrências\ndos caracteres '.' e '-' dele.\n\nArgumentos:\n\n- cep (str): O CEP (Código de Endereçamento Postal) de entrada que contém os\n               símbolos a serem removidos.\n\nRetorna:\n\n- str: Uma nova string com os símbolos especificados removidos.\n\nExemplo:\n\n```python\n\u003e\u003e\u003e from brutils import remove_symbols_cep\n\u003e\u003e\u003e remove_symbols_cep('01310-200')\n'01310200'\n\u003e\u003e\u003e remove_symbols_cep(\"123-45.678.9\")\n\"123456789\"\n\u003e\u003e\u003e remove_symbols_cep(\"abc.xyz\")\n\"abcxyz\"\n```\n\n### generate_cep\n\nGera um número de CEP (Código de Endereçamento Postal) aleatório de 8 dígitos\ncomo uma string.\n\nRetorna:\n\n- str: Um número de 8 dígitos gerado aleatoriamente.\n\nExemplo:\n\n```python\n\u003e\u003e\u003e from brutils import generate_cep\n\u003e\u003e\u003e generate_cep()\n'77520503'\n\u003e\u003e\u003e generate_cep()\n'29641407'\n```\n\n### get_address_from_cep\n\nBusca as informações de endereço a partir de um CEP (Código de Endereçamento Postal) utilizando a API da ViaCEP.\n\nArgumentos:\n\n- cep (str): O CEP a ser utilizado na busca.\n- raise_exceptions (bool, opcional): Se deve gerar exceções quando o CEP for inválido ou não for encontrado. O padrão é False.\n\nRetorna:\n\n- Address | None: Um objeto Address (TypedDict) contendo as informações de endereço se o CEP for encontrado, caso contrário, None.\n\nExemplo:\n\n```python\n\u003e\u003e\u003e from brutils import get_address_from_cep\n\u003e\u003e\u003e get_address_from_cep(\"12345678\")\n{\n    \"cep\": \"12345-678\",\n    \"logradouro\": \"Rua Example\",\n    \"complemento\": \"\",\n    \"bairro\": \"Example\",\n    \"localidade\": \"Example\",\n    \"uf\": \"EX\",\n    \"ibge\": \"1234567\",\n    \"gia\": \"1234\",\n    \"ddd\": \"12\",\n    \"siafi\": \"1234\"\n}\n```\n\n### get_cep_information_from_address\n\nBusca o CEP e outras informações a partir de um endereço utilizando a API da ViaCEP.\n\nArgumentos:\n\n- federal_unit (str): Abreviação de duas letras do estado brasileiro.\n- city (str): Nome da cidade.\n- street (str): Nome (ou substring) da rua.\n- raise_exceptions (bool, opcional): Se deve gerar exceções quando o endereço é inválido ou não foi encontrado. O padrão é False.\n\nRetorna:\n\n- 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.\n\nExemplo:\n\n```python\n\u003e\u003e\u003e from brutils import get_cep_information_from_address\n\u003e\u003e\u003e get_cep_information_from_address(\"EX\", \"Example\", \"Rua Example\")\n[\n    {\n        \"cep\": \"12345-678\",\n        \"logradouro\": \"Rua Example\",\n        \"complemento\": \"\",\n        \"bairro\": \"Example\",\n        \"localidade\": \"Example\",\n        \"uf\": \"EX\",\n        \"ibge\": \"1234567\",\n        \"gia\": \"1234\",\n        \"ddd\": \"12\",\n        \"siafi\": \"1234\"\n    }\n]\n```\n\n## Telefone\n\n### is_valid_phone\n\nRetorna se um número de telefone brasileiro é válido conforme o formato da string.\nNão verifica se o número realmente existe.\n```\n\nis_valid_phone(phone_number, type)\n\n```\n\nArgumentos:\n\n- phone_number (str):\n  - o número de telefone a ser validado\n  - apenas dígitos, sem símbolos\n  - sem o código do país\n  - deve incluir o número de DDD com dois dígitos\n  - exemplo: '+55 48 9999 9999' deve ser utilizado como '4899999999'\n  - obrigatório\n\n- type (str):\n  - 'mobile' para validar apenas números de celular\n  - 'landline' para validar apenas números de telefone fixo\n  - caso não especificado, valida para um para o outro.\n  - opcional\n\nRetorna:\n\n- bool: True se o número é válido, False caso contrário.\n\nExemplo:\n\n```python\n\u003e\u003e\u003e from brutils import is_valid_phone\n\u003e\u003e\u003e is_valid_phone('11994029275')\nTrue\n\u003e\u003e\u003e is_valid_phone('11994029275', 'mobile')\nTrue\n\u003e\u003e\u003e is_valid_phone('1938814933', 'landline')\nTrue\n```\n\n### format_phone\n\nFormata 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.\n\nArgumentos:\n\n- phone (str): Uma string representando um número de telefone.\n\nRetorna:\n\n- str: O número de telefone formatado para exibição ou None se não for válido.\n\nExemplo:\n\n```python\n\u003e\u003e\u003e from brutils import format_phone\n\u003e\u003e\u003e format_phone(\"11994029275\")\n'(11)99402-9275'\n\u003e\u003e\u003e format_phone(\"1635014415\")\n'(16)3501-4415'\n\u003e\u003e\u003e format_phone(\"333333\")\nNone\n```\n\n### remove_symbols_phone\n\nRemove 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 ' '.\n\nArgumentos:\n\n- phone (str): O número de telefone de entrada que contém os símbolos a serem removidos.\n\nRetorna:\n\n- str: Uma nova string com os símbolos especificados removidos.\n\nExemplo:\n\n```python\n\u003e\u003e\u003e from brutils import remove_symbols_phone\n\u003e\u003e\u003e remove_symbols_phone('(21)2569-6969')\n'2125696969'\n\u003e\u003e\u003e remove_symbols_phone('11 9999-8888')\n'1199998888'\n\u003e\u003e\u003e remove_symbols_phone('333333')\n'333333'\n```\n\n### remove_international_dialing_code\n\nRemove o código internacional (+55) de uma string que contém um número de telefone brasileiro, mantendo outros caracteres especiais.\n\nArgumentos:\n\n- phone (str): O número de telefone de entrada que pode conter o código internacional.\n\nRetorna:\n\n- str: Uma nova string sem o código internacional, preservando outros caracteres especiais.\n\nExemplo:\n\n```python\n\u003e\u003e\u003e from brutils import remove_international_dialing_code\n\u003e\u003e\u003e remove_international_dialing_code(\"5521994029275\")\n\"21994029275\"\n\u003e\u003e\u003e remove_international_dialing_code(\"+5521994029275\")\n\"+21994029275\"\n\u003e\u003e\u003e remove_international_dialing_code(\"5555994029275\")\n\"55994029275\"\n\u003e\u003e\u003e remove_international_dialing_code(\"21994029275\")\n\"21994029275\"\n\u003e\u003e\u003e remove_international_dialing_code(\"(+55)21994029275\")\n\"(+)21994029275\"\n```\n\n### generate_phone\n\nGera um número de telefone aleatório válido.\n\nArgumentos:\n\n- type (str): Pode ser \"landline\" ou \"mobile\".\n                Se não for especificado, a função gera um número\n                aleatório de qualquer tipo.\n\nRetorna:\n\n- str: Um número de telefone válido gerado aleatoriamente.\n\nExemplo:\n\n```python\n\u003e\u003e\u003e from brutils import generate_phone\n\u003e\u003e\u003e generate_phone()\n\"5929797740\"\n\u003e\u003e\u003e generate_phone(\"mobile\")\n\"1899115895\"\n\u003e\u003e\u003e generate_phone(\"landline\")\n\"5535317900\"\n```\n\n## Email\n\n### is_valid_email\n\nVerificar se uma string corresponde a um endereço de e-mail válido.\n\nArgumentos:\n\n- email (str): A string de entrada a ser verificada.\n\nRetorna:\n\n- bool: Verdadeiro se o email for um endereço de e-mail válido, Falso\n          caso contrário.\n\nExemplo:\n\n```python\nfrom brutils import is_valid_email\n\n\u003e\u003e\u003e is_valid_email(\"joao.ninguem@gmail.com\")\nTrue\n\u003e\u003e\u003e is_valid_email(\".joao.ninguem@gmail.com\")\nFalse\n\u003e\u003e\u003e is_valid_email(\"joao.ninguem@gmail.\")\nFalse\n\u003e\u003e\u003e is_valid_email(\"joao ninguem@gmail.com\")\nFalse\n```\n\n## Data\n\n## convert_date_to_text\n\nConverte uma data em sua representação textual.\n\nArgumentos:\n - date (str): Uma string no formato dd/mm/aaaa\n\nRetorna:\n - A represetação textual da data ou None caso a data esteja mal formatada ou a data seja inválida.\n\nExemplo:\n\n````python\n\u003e\u003e\u003e from brutils import convert_date_to_text\n\u003e\u003e\u003e convert_date_to_text(\"25/12/2000\")\n\"Vinte e cinco de dezembro de dois mil\"\n\u003e\u003e\u003e convert_date_to_text(\"31/02/2000\")\nNone\n\u003e\u003e\u003e convert_date_to_text(\"29/02/2024\")\n\"Vinte e nove de fevereiro de dois mil e vinte e quatro\"\n\u003e\u003e\u003e convert_date_to_text(\"1/08/2024\")\n\"Primeiro de agosto de dois mil e vinte e quatro\"\n````\n\n\n## Placa de Carro\n\n### is_valid_license_plate\n\nVerifica se uma placa de carro é válida.\nEsta função não verifica se a placa de carro é uma placa de carro real,\napenas valida o formato da string.\n\nArgumentos:\n\n- license_plate (str): Uma string representando uma placa de carro.\n- type (str): \"old_format\" ou \"mercosul\".\n                Se não especificado, verifica um ou outro.\n\nRetorna:\n\n- bool: True se a placa de carro for válida, False caso contrário.\n\nExemplo:\n\n```python\n\u003e\u003e\u003e from brutils import is_valid_license_plate\n\u003e\u003e\u003e is_valid_license_plate('ABC1234')\nTrue\n\u003e\u003e\u003e is_valid_license_plate('def5678', type=\"old_format\")\nTrue\n\u003e\u003e\u003e is_valid_license_plate('ABC4E67')\nTrue\n\u003e\u003e\u003e is_valid_license_plate('ABC4E67', type=\"mercosul\")\nTrue\n\u003e\u003e\u003e is_valid_license_plate('GHI-4567')\nFalse\n```\n\n### format_license_plate\n\nFormata uma placa de carro no padrão correto.\nEsta função recebe uma placa de carro em qualquer formato (LLLNNNN ou LLLNLNN) e retorna uma versão formatada.\n\nArgumentos:\n\n- license_plate (str): Uma string representando uma placa de carro.\n\nRetorna:\n\n- str: A string da placa de carro formatada ou\n         'None' se a entrada for inválida.\n\nExemplo:\n\n```python\n\u003e\u003e\u003e from brutils import format_license_plate\n\u003e\u003e\u003e format_license_plate(\"ABC1234\")\n\"ABC-1234\"\n# formato antigo (contém traço)\n\u003e\u003e\u003e format_license_plate(\"abc1234\")\n\"ABC-1234\"\n# formato antigo (contém traço)\n\u003e\u003e\u003e format_license_plate(\"ABC1D23\")\n\"ABC1D23\"\n# formato mercosul\n\u003e\u003e\u003e format_license_plate(\"abc1d23\")\n\"ABC1D23\"\n# formato mercosul\n\u003e\u003e\u003e format_license_plate(\"ABCD123\")\nNone\n```\n\n### remove_symbols_license_plate\n\nRemove o símbolo de hífen (-) de uma string de placa de carro.\n\nArgumentos:\n\n- license_plate_number (str): Uma string de placa de carro contendo símbolos a serem removidos.\n\nRetorna:\n\n- str: A string da placa de carro com os símbolos especificados removidos.\n\nExemplo:\n\n```python\nfrom brutils import remove_symbols_license_plate\n\u003e\u003e\u003e remove_symbols_license_plate(\"ABC-123\")\n\"ABC123\"\n\u003e\u003e\u003e remove_symbols_license_plate(\"abc123\")\n\"abc123\"\n\u003e\u003e\u003e remove_symbols_license_plate(\"ABCD123\")\n\"ABCD123\"\n\u003e\u003e\u003e remove_symbols_license_plate(\"@abc#-#123@\")\n\"@abc##123@\"\n```\n\n### generate_license_plate\n\nGera uma placa de carro válida no formato especificado. Caso nenhum formato seja fornecido, ele retornará uma placa de carro no formato Mercosul.\n\nArgumentos:\n\n- 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'.\n\nRetorna:\n\n- str: Um número de placa de carro gerado aleatoriamente ou\n   None se o formato for inválido.\n\nExemplo:\n\n```python\nfrom brutils import generate_license_plate\n\u003e\u003e\u003e generate_license_plate()\n\"ABC1D23\"\n\u003e\u003e\u003e generate_license_plate(format=\"LLLNLNN\")\n\"ABC4D56\"\n\u003e\u003e\u003e generate_license_plate(format=\"LLLNNNN\")\n\"ABC123\"\n\u003e\u003e\u003e generate_license_plate(format=\"invalid\")\nNone\n```\n\n### convert_license_plate_to_mercosul\n\nConverte uma placa de carro no formato antigo (LLLNNNN) para o formato Mercosul (LLLNLNN).\n\nArgumentos:\n\n- license_plate(str): Uma string com o tamanho adequado que representa a placa no formato antigo.\n\nRetorna:\n\n- str: A placa Mercosul convertida (LLLNLNN) ou None se a entrada for inválida.\n\nExemplo:\n\n```python\n\u003e\u003e\u003e from brutils import convert_license_plate_to_mercosul\n\u003e\u003e\u003e convert_license_plate_to_mercosul(\"ABC123\")\n\"ABC1C34\"\n\u003e\u003e\u003e convert_license_plate_to_mercosul(\"abc123\")\n\"ABC1C34\"\n\u003e\u003e\u003e convert_license_plate_to_mercosul(\"ABC1D23\")\nNone\n```\n\n### get_format_license_plate\n\nRetorna o formato de uma placa de carro. 'LLLNNNN' para o formato antigo e\n'LLLNLNN' para o formato Mercosul.\n\nArgumentos:\n\n- license_plate (str): Uma string de placa de carro sem símbolos.\n\nRetorna:\n\n- str: O formato da placa de carro (LLLNNNN, LLLNLNN) ou\n         'None' se o formato for inválido.\n\nExemplo:\n\n```python\nfrom brutils import get_format_license_plate\n\u003e\u003e\u003e get_format_license_plate(\"ABC123\")\n\"LLLNNNN\"\n\u003e\u003e\u003e get_format_license_plate(\"abc123\")\n\"LLLNNNN\"\n\u003e\u003e\u003e get_format_license_plate(\"ABC1D23\")\n\"LLLNLNN\"\n\u003e\u003e\u003e get_format_license_plate(\"abc1d23\")\n\"LLLNLNN\"\n\u003e\u003e\u003e get_format_license_plate(\"ABCD123\")\nNone\n```\n\n## PIS\n\n### is_valid_pis\n\nVerifica se o número PIS/PASEP é valido. Apenas números, formatados como string. Não verifica se o PIS/PASEP realmente existe.\n\nReferências:\n\n- \u003chttps://www.macoratti.net/alg_pis.htm\u003e.\n\nArgumentos:\n\n- pis (str): Número PIS como uma string com o comprimento apropriado.\n\nRetorna:\n\n- bool: True se o PIS for válido, False caso contrário.\n\nExemplo:\n\n```python\nfrom brutils import is_valid_pis\n\u003e\u003e\u003e is_valid_pis(\"82178537464\")\nFalse\n\u003e\u003e\u003e is_valid_pis(\"12082043519\")\nTrue\n```\n\n### format_pis\n\nFormata 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.\n\nArgumentos:\n\n- pis (str): Uma string válida de PIS contendo apenas números.\n\nRetorna:\n\n- str: Uma string de PIS formatada com símbolos visuais padrão ou None se a entrada for inválida.\n\nExemplo:\n\n```python\nfrom brutils import format_pis\n\u003e\u003e\u003e format_pis(\"17033259504\")\n'170.33259.50-4'\n\u003e\u003e\u003e format_pis(\"12013128292\")\n'120.13128.29-2'\n```\n\n### remove_symbols_pis\n\nEsta 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.\n\nArgumentos:\n\n- pis (str): Uma string de PIS que pode conter símbolos de formatação.\n\nRetorna:\n\n- str: Uma string de PIS limpa, sem símbolos de formatação.\n\nExemplo:\n\n```python\nfrom brutils import remove_symbols_pis\n\n\u003e\u003e\u003e remove_symbols_pis('170.33259.50-4')\n'17033259504'\n\u003e\u003e\u003e remove_symbols_pis(\"123.456.789-09\")\n'12345678909'\n\u003e\u003e\u003e remove_symbols_pis('/._')\n'/_'\n```\n\n### generate_pis\n\nGera uma string de dígitos contendo um número de um PIS brasileiro válido aleatório.\n\nRetorna:\n\n- str: Um número PIS válido gerado aleatoriamente como string.\n\nExemplo:\n\n```python\nfrom brutils import generate_pis\n\u003e\u003e\u003e generate_pis()\n'61352489741'\n\u003e\u003e\u003e generate_pis()\n'73453349671'\n```\n\n## Processo Jurídico\n\n## is_valid_legal_process\n\nVerifica se um ID de processo jurídico é válido, não verifica se o ID de processo jurídico é um ID de processo\njurídico real; ela apenas valida o formato da string.\n\nArgumentos:\n\n- legal_process_id (str): Uma string contendo apenas dígitos que representa\n                            o ID do processo jurídico.\n\nRetorna:\n\n- bool: True se o ID do processo jurídico for válido, False caso\n          contrário.\n\nExamplo:\n\n```python\n\u003e\u003e\u003e from brutils import is_valid_legal_process\n\u003e\u003e\u003e is_valid_legal_process('10188748220234018200')\nTrue\n\u003e\u003e\u003e is_valid_legal_process('45532346920234025107')\nTrue\n\u003e\u003e\u003e is_valid_legal_process('00000000000000000000')\nFalse\n\u003e\u003e\u003e is_valid_legal_process('455323423QQWEQWSsasd\u0026*(()')\nFalse\n\u003e\u003e\u003e\n```\n\n### format_legal_process\n\nFormata um ID de processo jurídico em um formato padrão.\n\nArgumentos:\n\n- legal_process_id (str): Uma string de 20 dígitos que representa o ID do\n                            processo jurídico.\n\nRetorna:\n\n- str: O ID do processo jurídico formatado ou None se a entrada for inválida.\n\nExemplo:\n\n```python\n\u003e\u003e\u003e from brutils import format_legal_process\n\u003e\u003e\u003e format_legal_process('23141945820055070079')\n'2314194-58.2005.5.07.0079'\n\u003e\u003e\u003e format_legal_process('00000000000000000000')\n'0000000-00.0000.0.00.0000'\n\u003e\u003e\u003e\n```\n\n### remove_symbols_legal_process\n\nRemove símbolos específicos de um processo jurídico fornecido.\n\nEsta função recebe um processo jurídico como entrada e remove todas as\nocorrências dos caracteres '.' e '-' dele.\n\nArgumentos:\n\n- legal_process (str): Um processo jurídico contendo símbolos a serem\n                         removidos.\n\nRetorna:\n\n- str: A string do processo jurídico com os símbolos especificados removidos.\n\nExemplo:\n\n```python\nfrom brutils import remove_symbols_legal_process\n\u003e\u003e\u003e remove_symbols_legal_process(\"6439067-89.2023.4.04.5902\")\n\"64390678920234045902\"\n\u003e\u003e\u003e remove_symbols_legal_process(\"4976023-82.2012.7.00.2263\")\n\"49760238220127002263\"\n\u003e\u003e\u003e remove_symbols_legal_process(\"4976023-82.2012.7.00.2263*!*\u0026#\")\n\"49760238220127002263*!*\u0026#\"\n```\n\n### generate_legal_process\n\nGera um número válido aleatório de ID de processo jurídico.\n\nArgumentos:\n\n- year (int): O ano para o ID do processo jurídico (o padrão é o ano atual).\n                Não pode ser um ano do passado.\n- orgao (int): O órgão (1-9) para o ID do processo jurídico\n                 (o padrão é aleatório).\n\nRetorna:\n\n- str: Um ID de processo jurídico gerado aleatoriamente.\n         None caso algum dos argumento seja inválido.\n\nExemplo:\n\n```python\n\u003e\u003e\u003e from brutils import generate_legal_process\n\u003e\u003e\u003e generate_legal_process()\n\"45676401020238170592\"\n\u003e\u003e\u003e generate_legal_process(ano=2025)\n\"32110268020258121130\"\n\u003e\u003e\u003e generate_legal_process(orgao=5)\n\"37573041520235090313\"\n\u003e\u003e\u003e generate_legal_process(ano=2024, orgao=4)\n\"33158248820244017105\"\n```\n\n## Titulo Eleitoral\n\n### is_valid_voter_id\n\nVerifica se um número de Título de Eleitor brasileiro é válido. Não verifica se realmente existe.\n\nReferências:\n\n- \u003chttps://pt.wikipedia.org/wiki/T%C3%ADtulo_de_eleitor\u003e\n- \u003chttp://clubes.obmep.org.br/blog/a-matematica-nos-documentos-titulo-de-eleitor/\u003e\n\nArgumentos:\n\n- voter_id (str): string representando o número do título de eleitor a ser verificado.\n\nRetorna:\n\n- bool: True se o número do título de eleitor for válido. False, caso contrário.\n\nExemplo:\n\n```python\n\u003e\u003e\u003e from brutils import is_valid_voter_id\n\u003e\u003e\u003e is_valid_voter_id('123456789011')\nFalse\n\u003e\u003e\u003e is_valid_voter_id('427503840213')\nTrue\n```\n\n### format_voter_id\n\nFormata um número de Título de Eleitor para exibição visual.\n\nEsta função recebe uma string de Título de Eleitor contendo\napenas números como entrada e adiciona os espaços de formatação\npadrão para exibição.\n\nArgumentos:\n  * voter_id (str): Uma string de Título de Eleitor contendo apenas números.\n\nRetorna:\n  * str: O Título de Eleitor formatado com os espaços, se for válido.\n         Retorna None se não for válido.\n\nExemplo:\n\n```python\n\u003e\u003e\u003e from brutils import format_voter_id\n\u003e\u003e\u003e format_voter_id(\"246593980493\")\n'2465 9398 04 93'\n\u003e\u003e\u003e format_voter_id(\"202715292895\")\n'2027 1529 28 95'\n\u003e\u003e\u003e format_voter_id(\"739035552205\")\n\u003e\u003e\u003e\n```\n\n### generate_voter_id\n\nGera uma string de dígitos de Título de Eleitor válida aleatória a partir de um estado brasileiro informado.\n\nArgs:\n  * 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.\n\nRetorna:\n  * str: Um Título de Eleitor válido gerado aleatoriamente.\n\nExemplo:\n\n```python\n\u003e\u003e\u003e from brutils import generate_voter_id\n\u003e\u003e\u003e generate_voter_id()\n'183475722801'\n\u003e\u003e\u003e generate_voter_id(federative_union =\"MG\")\n'950125640248'\n```\n\n## IBGE\n\n### convert_code_to_uf\nConverte um determinado código do IBGE (string de 2 dígitos) para sua UF (abreviatura estadual) correspondente.\n\nArgs:\n  * code (str): O código IBGE de 2 dígitos a ser convertido.\n\nRetorna:\n  * str or None: O código UF correspondente ao código IBGE, ou None se o\n                 código IBGE for inválido.\n\nExemplo:\n\n```python\n\u003e\u003e\u003e from brutils.ibge.uf import convert_code_to_uf\n\u003e\u003e\u003e convert_code_to_uf(\"12\")\n'AC'\n\u003e\u003e\u003e convert_code_to_uf(\"33\")\n'RJ'\n\u003e\u003e\u003e convert_code_to_uf(\"99\")\n\u003e\u003e\u003e\n```\n\n### get_municipality_by_code\n\nRetorna o nome do município e a UF para um código do IBGE.\n\nArgs:\n  * code (str): O código do IBGE para o município.\n\nReturns:\n  * tuple: Retorna uma Tupla formatado como (\"Município\", \"UF\").\n  * None: Retorna None se o código for inválido.\n\nExample:\n\n```python\n\u003e\u003e\u003e from brutils import get_municipality_by_code\n\u003e\u003e\u003e get_municipality_by_code(3550308)\n(\"São Paulo\", \"SP\")\n```\n\n### get_code_by_municipality_name\n\nRetorna o código IBGE para um dado nome de município e código de UF.\n\nEssa 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.\n\nArgumentos:\n  * municipality_name (str): O nome do município.\n  * uf (str): O código UF do estado.\n\nRetorna:\n  * str: O código IBGE do município. Retorna None se o nome não for válido ou não existir.\n\nExemplo:\n\n```python\n\u003e\u003e\u003e from brutils import get_code_by_municipality_name\n\u003e\u003e\u003e get_code_by_municipality_name(\"São Paulo\", \"SP\")\n\"3550308\"\n\u003e\u003e\u003e get_code_by_municipality_name(\"goiania\", \"go\")\n\"5208707\"\n\u003e\u003e\u003e get_code_by_municipality_name(\"Conceição do Coité\", \"BA\")\n\"2908408\"\n\u003e\u003e\u003e get_code_by_municipality_name(\"conceicao do Coite\", \"Ba\")\n\"2908408\"\n\u003e\u003e\u003e get_code_by_municipality_name(\"Municipio Inexistente\", \"\")\nNone\n\u003e\u003e\u003e get_code_by_municipality_name(\"Municipio Inexistente\", \"RS\")\nNone\n```\n\n## Feriados\n\n### is_holiday\n\nVerifica se uma determinada data é um feriado nacional ou estadual no Brasil.\n\nEsta 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.\n\nArgumentos:\n\n- `date (datetime)`: A data a ser verificada.\n- `uf (str, opcional)`: A abreviação do estado (UF) para verificar feriados estaduais. Se não fornecido, apenas feriados nacionais são considerados.\n\nRetorna:\n\n- `bool | None`: `True` se a data for um feriado, `False` se não for, ou `None` se a data ou UF forem inválidas.\n\nExemplo:\n\n```python\n\u003e\u003e\u003e from datetime import datetime\n\u003e\u003e\u003e from brutils import is_holiday\n\n\u003e\u003e\u003e is_holiday(datetime(2024, 1, 1))\nTrue\n\u003e\u003e\u003e is_holiday(datetime(2024, 1, 2))\nFalse\n\u003e\u003e\u003e is_holiday(datetime(2024, 3, 2), uf=\"SP\")\nFalse\n\u003e\u003e\u003e is_holiday(datetime(2024, 12, 25), uf=\"RJ\")\nTrue\n```\n\n## Monetário\n\n### format_currency\n\nFormata um número seguindo o padrão monetário brasileiro. O número será formatado\nadicionando o símbolo R$ como prefixo, vírgula como separador decimal, e ponto como \nagrupador de milhar.\n\nArgumentos:\n  * float ou Decimal: Um número com ou sem casas decimais.\n\nRetorna:\n  * str ou None: O número formatado seguindo o padrão brasileiro.\n\nExemplo:\n\n```python\n\u003e\u003e\u003e from brutils.currency import format_currency\n\u003e\u003e\u003e format_currency(1259.03)\n'R$ 1.259,03'\n\u003e\u003e\u003e format_currency(0)\n'R$ 0,00'\n\u003e\u003e\u003e format_currency(\"not a number\")\nNone\n```\n\n# Novos Utilitários e Reportar Bugs\n\nCaso queira sugerir novas funcionalidades ou reportar bugs, basta criar\numa nova [issue][github-issues] e iremos lhe responder por lá!\n\n(Para saber mais sobre github issues, confira a [documentação oficial do GitHub][github-issues-doc]).\n\n# Dúvidas? Ideias?\n\nDúvidas de como utilizar a biblioteca? Novas ideias para o projeto?\nQuer compartilhar algo com a gente? Fique à vontade para criar um tópico no nosso\n[Discussions][github-discussions] que iremos interagir por lá!\n\n(Para saber mais sobre github discussions, confira a\n[documentação oficial do GitHub][github-discussions-doc]).\n\n# Contribuindo com o Código do Projeto\n\nSua colaboração é sempre muito bem-vinda! Preparamos o arquivo [CONTRIBUTING.md][contributing] para\nte ajudar nos primeiros passos. Lá você encontrará toda a informação necessária para contribuir com\no projeto. Não hesite em nos perguntar utilizando o [GitHub Discussions][github-discussions] caso\nhaja qualquer dificuldade ou dúvida. Toda ajuda conta!\n\nVamos construir juntos! 🚀🚀\n\n[contributing]: CONTRIBUTING.md\n[github-discussions-doc]: https://docs.github.com/pt/discussions\n[github-discussions]: https://github.com/brazilian-utils/brutils-python/discussions\n[github-issues-doc]: https://docs.github.com/pt/issues/tracking-your-work-with-issues/creating-an-issue\n[github-issues]: https://github.com/brazilian-utils/brutils-python/issues\n\n## ❤️ Quem já Contribuiu\n\n\u003ca href=\"https://github.com/brazilian-utils/brutils-python/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=brazilian-utils/brutils-python\" /\u003e\n\u003c/a\u003e\u003c/br\u003e\u003c/br\u003e\n\n_Feito por [contrib.rocks](https://contrib.rocks)._","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrazilian-utils%2Fbrutils-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrazilian-utils%2Fbrutils-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrazilian-utils%2Fbrutils-python/lists"}