brutils 2.1.1__tar.gz → 2.3.0__tar.gz

{brutils-2.1.1 → brutils-2.3.0}/PKG-INFO

@@ -1,12 +1,12 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: brutils
-Version: 2.1.1
+Version: 2.3.0
 Summary: Utils library for specific Brazilian businesses
-Home-page: https://github.com/brazilian-utils/brutils
 License: MIT
+License-File: LICENSE
 Keywords: cpf,cnpj,cep,document,validation,brazil,brazilian
 Author: The Brazilian Utils Organization
-Requires-Python: >=3.8.1,<4.0.0
+Requires-Python: >=3.10,<4.0
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Natural Language :: English
@@ -14,15 +14,18 @@ Classifier: Natural Language :: Portuguese
 Classifier: Natural Language :: Portuguese (Brazilian)
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Topic :: Office/Business
 Classifier: Topic :: Software Development :: Internationalization
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: coverage (>=7.2.7,<8.0.0)
+Requires-Dist: holidays (>=0.58,<0.59)
+Requires-Dist: num2words (==0.5.14)
 Project-URL: Repository, https://github.com/brazilian-utils/brutils
 Description-Content-Type: text/markdown
 
@@ -31,12 +34,10 @@ Description-Content-Type: text/markdown
 
 <p>Utils library for Brazilian-specific businesses.</p>
 
-
 [![codecov](https://codecov.io/gh/brazilian-utils/brutils-python/branch/main/graph/badge.svg?token=5KNECS8JYF)](https://codecov.io/gh/brazilian-utils/brutils-python)
 [![Downloads per Month](https://shields.io/pypi/dm/brutils)](https://pypistats.org/packages/brutils)
 [![Package version](https://shields.io/pypi/v/brutils)](https://pypi.org/project/brutils/)
 
-
 ### [Looking for the english version?](README_EN.md)
 
 </div>
@@ -55,7 +56,7 @@ desenvolvimento de aplicações para o business Brasileiro.
 
 # Instalação
 
-```
+```bash
 pip install brutils
 ```
 
@@ -72,48 +73,63 @@ False
 # Utilitários
 
 - [CPF](#cpf)
-  - [is_valid_cpf](#is_valid_cpf)
-  - [format_cpf](#format_cpf)
-  - [remove_symbols_cpf](#remove_symbols_cpf)
-  - [generate_cpf](#generate_cpf)
+  - [is\_valid\_cpf](#is_valid_cpf)
+  - [format\_cpf](#format_cpf)
+  - [remove\_symbols\_cpf](#remove_symbols_cpf)
+  - [generate\_cpf](#generate_cpf)
 - [CNPJ](#cnpj)
-  - [is_valid_cnpj](#is_valid_cnpj)
-  - [format_cnpj](#format_cnpj)
-  - [remove_symbols_cnpj](#remove_symbols_cnpj)
-  - [generate_cnpj](#generate_cnpj)
+  - [is\_valid\_cnpj](#is_valid_cnpj)
+  - [format\_cnpj](#format_cnpj)
+  - [remove\_symbols\_cnpj](#remove_symbols_cnpj)
+  - [generate\_cnpj](#generate_cnpj)
 - [CEP](#cep)
-  - [is_valid_cep](#is_valid_cep)
-  - [format_cep](#format_cep)
-  - [remove_symbols_cep](#remove_symbols_cep)
-  - [generate_cep](#generate_cep)
+  - [is\_valid\_cep](#is_valid_cep)
+  - [format\_cep](#format_cep)
+  - [remove\_symbols\_cep](#remove_symbols_cep)
+  - [generate\_cep](#generate_cep)
+  - [get\_address\_from\_cep](#get_address_from_cep)
+  - [get\_cep\_information\_from\_address](#get_cep_information_from_address)
 - [Telefone](#telefone)
-  - [is_valid_phone](#is_valid_phone)
-  - [format_phone](#format_phone)
-  - [remove_symbols_phone](#remove_symbols_phone)
-  - [remove_international_dialing_code](#remove_international_dialing_code)
-  - [generate_phone](#generate_phone)
+  - [is\_valid\_phone](#is_valid_phone)
+  - [format\_phone](#format_phone)
+  - [remove\_symbols\_phone](#remove_symbols_phone)
+  - [remove\_international\_dialing\_code](#remove_international_dialing_code)
+  - [generate\_phone](#generate_phone)
 - [Email](#email)
-  - [is_valid_email](#is_valid_email)
+  - [is\_valid\_email](#is_valid_email)
+- [Data](#date)
+  - [convert\_date\_to_text](#convert_date_to_text)
 - [Placa de Carro](#placa-de-carro)
-  - [is_valid_license_plate](#is_valid_license_plate)
-  - [format_license_plate](#format_license_plate)
-  - [remove_symbols_license_plate](#remove_symbols_license_plate)
-  - [generate_license_plate](#generate_license_plate)
-  - [convert_license_plate_to_mercosul](#convert_license_plate_to_mercosul)
-  - [get_format_license_plate](#get_format_license_plate)
+  - [is\_valid\_license\_plate](#is_valid_license_plate)
+  - [format\_license\_plate](#format_license_plate)
+  - [remove\_symbols\_license\_plate](#remove_symbols_license_plate)
+  - [generate\_license\_plate](#generate_license_plate)
+  - [convert\_license\_plate\_to\_mercosul](#convert_license_plate_to_mercosul)
+  - [get\_format\_license\_plate](#get_format_license_plate)
 - [PIS](#pis)
-  - [is_valid_pis](#is_valid_pis)
-  - [format_pis](#format_pis)
-  - [remove_symbols_pis](#remove_symbols_pis)
-  - [generate_pis](#generate_pis)
+  - [is\_valid\_pis](#is_valid_pis)
+  - [format\_pis](#format_pis)
+  - [remove\_symbols\_pis](#remove_symbols_pis)
+  - [generate\_pis](#generate_pis)
 - [Processo Jurídico](#processo-jurídico)
-  - [is_valid_legal_process](#is_valid_legal_process)
-  - [format_legal_process](#format_legal_process)
-  - [remove_symbols_legal_process](#remove_symbols_legal_process)
-  - [generate_legal_process](#generate_legal_process)
-
-- [Título Eleitoral](#titulo-eleitoral)
-  - [is_valid_voter_id](#is_valid_voter_id)
+  - [is\_valid\_legal\_process](#is_valid_legal_process)
+  - [format\_legal\_process](#format_legal_process)
+  - [remove\_symbols\_legal\_process](#remove_symbols_legal_process)
+  - [generate\_legal\_process](#generate_legal_process)
+- [Titulo Eleitoral](#titulo-eleitoral)
+  - [is\_valid\_voter\_id](#is_valid_voter_id)
+  - [format\_voter\_id](#format_voter_id)
+  - [generate\_voter\_id](#generate_voter_id)
+- [IBGE](#ibge)
+  - [convert_code_to_uf](#convert_code_to_uf)
+  - [convert_uf_to_name](#convert_uf_to_name)
+  - [get_code_by_municipality_name](#get_code_by_municipality_name)
+  - [get\_municipality\_by\_code](#get_municipality_by_code)
+- [Feriados](#feriados)
+  - [is_holiday](#is_holiday)
+- [Monetário](#monetário)
+  - [format\_currency](#format_currency)
+  - [convert\_real\_to\_text](#convert_real_to_text)
 
 ## CPF
 
@@ -124,10 +140,12 @@ correspondem ao seu número base. Esta função não verifica a existência do C
 ela apenas valida o formato da string.
 
 Argumentos:
-  * cpf (str): O CPF a ser validado, uma string de 11 dígitos
+
+- 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,
+
+- bool: Verdadeiro se os dígitos de verificação corresponderem ao número base,
           Falso caso contrário.
 
 Exemplo:
@@ -147,10 +165,12 @@ 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.
+
+- cpf (str): Uma string de CPF contendo apenas números.
 
 Retorna:
-  * str: O CPF formatado com símbolos visuais se for válido,
+
+- str: O CPF formatado com símbolos visuais se for válido,
          None se não for válido.
 
 Exemplo:
@@ -170,10 +190,12 @@ brasileiro). Esta função recebe como entrada uma string de CPF e remove todas
 ocorrências dos caracteres '.', '-' dela.
 
 Argumentos:
-  * cpf (str): A string de CPF contendo os símbolos a serem removidos.
+
+- cpf (str): A string de CPF contendo os símbolos a serem removidos.
 
 Retorna:
-  * str: Uma nova string com os símbolos especificados removidos.
+
+- str: Uma nova string com os símbolos especificados removidos.
 
 Exemplo:
 
@@ -188,7 +210,8 @@ Exemplo:
 Gerar uma string de dígitos de CPF válida aleatória.
 
 Retorna:
-  * str: Um CPF válido gerado aleatoriamente.
+
+- str: Um CPF válido gerado aleatoriamente.
 
 Exemplo:
 
@@ -210,10 +233,12 @@ 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.
+
+- cnpj (str): O CNPJ a ser validado.
 
 Retorna:
-  * bool: True se os dígitos de verificação corresponderem ao número base,
+
+- bool: True se os dígitos de verificação corresponderem ao número base,
         False caso contrário.
 
 Exemplo:
@@ -234,10 +259,12 @@ 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.
+
+- 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.
+
+- str: O CNPJ formatado com símbolos visuais se for válido, None se não for válido.
 
 Exemplo:
 
@@ -257,10 +284,12 @@ 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.
+
+- 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.
+
+- str: Uma nova string com os símbolos especificados removidos.
 
 Exemplo:
 
@@ -276,10 +305,12 @@ 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.
+
+- branch (int): Um número de filial opcional a ser incluído no CNPJ.
 
 Retorna:
-  * str: Um CNPJ válido gerado aleatoriamente.
+
+- str: Um CNPJ válido gerado aleatoriamente.
 
 Exemplo:
 
@@ -287,7 +318,7 @@ Exemplo:
 >>> from brutils import generate_cnpj
 >>> generate_cnpj()
 '34665388000161'
->>> generate(1234)
+>>> generate_cnpj(1234)
 "01745284123455"
 ```
 
@@ -301,10 +332,12 @@ 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.
+
+- 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.
+
+- bool: True se o CEP for válido (8 dígitos), False caso contrário.
 
 Exemplo:
 
@@ -325,11 +358,13 @@ 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
+
+- 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
+
+- str: O CEP formatado no formato "12345-678" se for válido, None se não for
         válido.
 
 Example:
@@ -351,11 +386,13 @@ fornecido. Esta função recebe um CEP como entrada e remove todas as ocorrênci
 dos caracteres '.' e '-' dele.
 
 Argumentos:
-  * cep (str): O CEP (Código de Endereçamento Postal) de entrada que contém os
+
+- 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.
+
+- str: Uma nova string com os símbolos especificados removidos.
 
 Exemplo:
 
@@ -375,7 +412,8 @@ Gera um número de CEP (Código de Endereçamento Postal) aleatório de 8 dígit
 como uma string.
 
 Retorna:
-  * str: Um número de 8 dígitos gerado aleatoriamente.
+
+- str: Um número de 8 dígitos gerado aleatoriamente.
 
 Exemplo:
 
@@ -387,34 +425,105 @@ Exemplo:
 '29641407'
 ```
 
+### get_address_from_cep
+
+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:
+
+```python
+>>> 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"
+}
+```
+
+### get_cep_information_from_address
+
+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:
+
+```python
+>>> 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"
+    }
+]
+```
+
 ## Telefone
 
 ### is_valid_phone
 
 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
+- 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.
+
+- bool: True se o número é válido, False caso contrário.
 
 Exemplo:
 
@@ -429,15 +538,19 @@ True
 ```
 
 ### format_phone
+
 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.
+
+- 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.
+
+- str: O número de telefone formatado para exibição ou None se não for válido.
 
 Exemplo:
+
 ```python
 >>> from brutils import format_phone
 >>> format_phone("11994029275")
@@ -445,7 +558,7 @@ Exemplo:
 >>> format_phone("1635014415")
 '(16)3501-4415'
 >>> format_phone("333333")
->>>
+None
 ```
 
 ### remove_symbols_phone
@@ -453,12 +566,15 @@ Exemplo:
 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.
+
+- 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.
+
+- str: Uma nova string com os símbolos especificados removidos.
 
 Exemplo:
+
 ```python
 >>> from brutils import remove_symbols_phone
 >>> remove_symbols_phone('(21)2569-6969')
@@ -474,12 +590,15 @@ Exemplo:
 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.
+
+- 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.
+
+- str: Uma nova string sem o código internacional, preservando outros caracteres especiais.
 
 Exemplo:
+
 ```python
 >>> from brutils import remove_international_dialing_code
 >>> remove_international_dialing_code("5521994029275")
@@ -499,12 +618,14 @@ Exemplo:
 Gera um número de telefone aleatório válido.
 
 Argumentos:
-  * type (str): Pode ser "landline" ou "mobile".
+
+- 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.
+
+- str: Um número de telefone válido gerado aleatoriamente.
 
 Exemplo:
 
@@ -525,10 +646,12 @@ Exemplo:
 Verificar se uma string corresponde a um endereço de e-mail válido.
 
 Argumentos:
-  * email (str): A string de entrada a ser verificada.
+
+- 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
+
+- bool: Verdadeiro se o email for um endereço de e-mail válido, Falso
           caso contrário.
 
 Exemplo:
@@ -546,6 +669,33 @@ False
 False
 ```
 
+## Data
+
+## convert_date_to_text
+
+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:
+
+````python
+>>> 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"
+````
+
+
 ## Placa de Carro
 
 ### is_valid_license_plate
@@ -555,12 +705,14 @@ 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".
+
+- 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.
+
+- bool: True se a placa de carro for válida, False caso contrário.
 
 Exemplo:
 
@@ -584,26 +736,28 @@ 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.
+
+- license_plate (str): Uma string representando uma placa de carro.
 
 Retorna:
-  * str: A string da placa de carro formatada ou
+
+- str: A string da placa de carro formatada ou
          'None' se a entrada for inválida.
 
 Exemplo:
 
 ```python
 >>> from brutils import format_license_plate
->>> format_license_plate("ABC1234") 
+>>> format_license_plate("ABC1234")
 "ABC-1234"
 # formato antigo (contém traço)
->>> format_license_plate("abc1234") 
+>>> format_license_plate("abc1234")
 "ABC-1234"
 # formato antigo (contém traço)
->>> format_license_plate("ABC1D23") 
+>>> format_license_plate("ABC1D23")
 "ABC1D23"
 # formato mercosul
->>> format_license_plate("abc1d23") 
+>>> format_license_plate("abc1d23")
 "ABC1D23"
 # formato mercosul
 >>> format_license_plate("ABCD123")
@@ -615,10 +769,12 @@ 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.
+
+- 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.
+
+- str: A string da placa de carro com os símbolos especificados removidos.
 
 Exemplo:
 
@@ -639,10 +795,12 @@ from brutils import remove_symbols_license_plate
 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'.
+
+- 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
+
+- str: Um número de placa de carro gerado aleatoriamente ou
    None se o formato for inválido.
 
 Exemplo:
@@ -664,10 +822,12 @@ 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.
+
+- 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.
+
+- str: A placa Mercosul convertida (LLLNLNN) ou None se a entrada for inválida.
 
 Exemplo:
 
@@ -687,10 +847,12 @@ 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.
+
+- license_plate (str): Uma string de placa de carro sem símbolos.
 
 Retorna:
-  * str: O formato da placa de carro (LLLNNNN, LLLNLNN) ou
+
+- str: O formato da placa de carro (LLLNNNN, LLLNLNN) ou
          'None' se o formato for inválido.
 
 Exemplo:
@@ -716,15 +878,19 @@ 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.
+
+- <https://www.macoratti.net/alg_pis.htm>.
 
 Argumentos:
-  * pis (str): Número PIS como uma string com o comprimento apropriado.
+
+- 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.
+
+- bool: True se o PIS for válido, False caso contrário.
 
 Exemplo:
+
 ```python
 from brutils import is_valid_pis
 >>> is_valid_pis("82178537464")
@@ -738,10 +904,12 @@ 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.
+
+- 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.
+
+- str: Uma string de PIS formatada com símbolos visuais padrão ou None se a entrada for inválida.
 
 Exemplo:
 
@@ -758,10 +926,12 @@ from brutils import format_pis
 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.
+
+- 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.
+
+- str: Uma string de PIS limpa, sem símbolos de formatação.
 
 Exemplo:
 
@@ -781,7 +951,8 @@ from brutils import 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.
+
+- str: Um número PIS válido gerado aleatoriamente como string.
 
 Exemplo:
 
@@ -801,11 +972,13 @@ Verifica se um ID de processo jurídico é válido, não verifica se o ID de pro
 jurídico real; ela apenas valida o formato da string.
 
 Argumentos:
-  * legal_process_id (str): Uma string contendo apenas dígitos que representa
+
+- 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
+
+- bool: True se o ID do processo jurídico for válido, False caso
           contrário.
 
 Examplo:
@@ -828,11 +1001,13 @@ 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
+
+- 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.
+
+- str: O ID do processo jurídico formatado ou None se a entrada for inválida.
 
 Exemplo:
 
@@ -853,11 +1028,13 @@ 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
+
+- 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.
+
+- str: A string do processo jurídico com os símbolos especificados removidos.
 
 Exemplo:
 
@@ -876,13 +1053,15 @@ from brutils import remove_symbols_legal_process
 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).
+
+- 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
+- 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.
+
+- str: Um ID de processo jurídico gerado aleatoriamente.
          None caso algum dos argumento seja inválido.
 
 Exemplo:
@@ -903,17 +1082,20 @@ Exemplo:
 
 ### is_valid_voter_id
 
-Verifica se um número de título de eleitor brasileiro é válido. Não verifica se realmente existe.
+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/
+
+- <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.
+
+- 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.
+
+- bool: True se o número do título de eleitor for válido. False, caso contrário.
 
 Exemplo:
 
@@ -925,6 +1107,243 @@ False
 True
 ```
 
+### format_voter_id
+
+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:
+
+```python
+>>> 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")
+>>>
+```
+
+### generate_voter_id
+
+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:
+
+```python
+>>> from brutils import generate_voter_id
+>>> generate_voter_id()
+'183475722801'
+>>> generate_voter_id(federative_union ="MG")
+'950125640248'
+```
+
+## IBGE
+
+### convert_code_to_uf
+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:
+
+```python
+>>> 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")
+>>>
+```
+
+### get_code_by_municipality_name
+
+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:
+
+```python
+>>> 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
+```
+
+### get_municipality_by_code
+
+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:
+
+```python
+>>> from brutils import get_municipality_by_code
+>>> get_municipality_by_code(3550308)
+("São Paulo", "SP")
+```
+
+### convert_uf_to_name
+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:
+
+```python
+>>> 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'
+```
+
+## Feriados
+
+### is_holiday
+
+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:
+
+```python
+>>> 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
+```
+
+## Monetário
+
+### format_currency
+
+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:
+
+```python
+>>> 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
+```
+
+### convert_real_to_text
+
+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:
+
+```python
+>>> 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
+```
+
 # Novos Utilitários e Reportar Bugs
 
 Caso queira sugerir novas funcionalidades ou reportar bugs, basta criar
@@ -956,3 +1375,11 @@ Vamos construir juntos! 🚀🚀
 [github-issues-doc]: https://docs.github.com/pt/issues/tracking-your-work-with-issues/creating-an-issue
 [github-issues]: https://github.com/brazilian-utils/brutils-python/issues
 
+## ❤️ Quem já Contribuiu
+
+<a href="https://github.com/brazilian-utils/brutils-python/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=brazilian-utils/brutils-python" />
+</a></br></br>
+
+_Feito por [contrib.rocks](https://contrib.rocks)._
+