Merge branch 'main' into 426

.github/workflows/run-tests.yml

@@ -18,7 +18,7 @@ jobs:
           python-version: ${{ matrix.python-version }}
       - name: Generate Report
         run: |
-          pip install coverage
+          pip install coverage num2words
           coverage run -m unittest discover tests/
       - name: Upload Coverage to Codecov
         uses: codecov/codecov-action@v4

CHANGELOG.md

@@ -9,6 +9,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Utilitário `convert_code_to_uf` [#397](https://github.com/brazilian-utils/brutils-python/pull/410)
+- Utilitário `convert_date_to_text`[#394](https://github.com/brazilian-utils/brutils-python/pull/415)
+- Utilitário `get_municipality_by_code` [412](https://github.com/brazilian-utils/brutils-python/pull/412)
+
+- Utilitário `get_code_by_municipality_name` [#399](https://github.com/brazilian-utils/brutils-python/issues/399)
 
 ## [2.2.0] - 2024-09-12
 

CONTRIBUTING.md

@@ -98,7 +98,7 @@ emulate bash -c '. .../bin/activate'
 Para testar se o ambiente virtual está ativo corretamente, execute o comando e verifique se a resposta é algo parecido com a seguinte:
 
 ```sh
-$ poetry env inf
+$ poetry env info
 Virtualenv
 Python:         3.x.y
 Implementation: CPython

README.md

@@ -66,6 +66,8 @@ False
   - [generate\_phone](#generate_phone)
 - [Email](#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)
@@ -89,6 +91,9 @@ False
   - [generate\_voter\_id](#generate_voter_id)
 - [IBGE](#ibge)
   - [convert\_code\_to\_uf](#convert_code_to_uf)
+  - [get_code_by_municipality_name](#get_code_by_municipality_name)
+  - [convert_code_to_uf](#convert_code_to_uf)
+  - [get\_municipality\_by\_code](#get_municipality_by_code)
 - [Monetário](#monetário)
   - [format\_currency](#format_currency)
 
@@ -630,6 +635,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
@@ -1089,6 +1121,7 @@ Exemplo:
 ```
 
 ## IBGE
+
 ### convert_code_to_uf
 Converte um determinado código do IBGE (string de 2 dígitos) para sua UF (abreviatura estadual) correspondente.
 
@@ -1111,6 +1144,56 @@ Exemplo:
 >>>
 ```
 
+### 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")
+```
+
+### 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
+```
+
 ## Monetário
 
 ### format_currency

README_EN.md

@@ -58,6 +58,8 @@ False
   - [generate\_cep](#generate_cep)
   - [get\_address\_from\_cep](#get_address_from_cep)
   - [get\_cep\_information\_from\_address](#get_cep_information_from_address)
+- [Date](#date)
+  - [convert\_date\_to_text](#convert_date_to_text) 
 - [Phone](#phone)
   - [is\_valid\_phone](#is_valid_phone)
   - [format\_phone](#format_phone)
@@ -89,6 +91,8 @@ False
   - [generate_voter_id](#generate_voter_id)
 - [IBGE](#ibge)
   - [convert_code_to_uf](#convert_code_to_uf)
+  - [get\_municipality\_by\_code](#get_municipality_by_code)
+  - [get_code_by_municipality_name](#get_code_by_municipality_name)
 - [Monetary](#monetary)
   - [format_currency](#format_currency)
 
@@ -450,6 +454,32 @@ Example:
 ]
 ```
 
+## Date
+
+### convert_date_to_text 
+Convert a brazilian date (dd/mm/yyyy) format in their portuguese textual representation.
+
+Args:
+ - date (str): A date in a string format dd/mm/yyyy.
+
+Return:
+ - (str) | None: A portuguese textual representation of the date or None case a date is invalid.
+
+
+Example:
+
+````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"
+````
+
 ## Phone
 
 ### is_valid_phone
@@ -1092,6 +1122,7 @@ Example:
 ```
 
 ## IBGE
+
 ### convert_code_to_uf
 Converts a given IBGE code (2-digit string) to its corresponding UF (state abbreviation).
 
@@ -1114,6 +1145,59 @@ Exemplo:
 >>>
 ```
 
+### get_municipality_by_code
+
+Returns the municipality name and UF for a given IBGE code.
+
+Args:
+  * code (str): The IBGE code of the municipality.
+
+Returns:
+  * tuple: Returns a tuple formatted as ("Município", "UF").
+  * None: Returns None if the code is not valid.
+
+Example:
+
+```python
+>>> from brutils import get_municipality_by_code
+>>> get_municipality_by_code(3550308)
+("São Paulo", "SP")
+```
+
+### get_code_by_municipality_name
+
+Returns the IBGE code for a given municipality name and uf code.
+
+This function takes a string representing a municipality's name
+and uf's code and returns the corresponding IBGE code (string). The function
+will handle names by ignoring differences in case, accents, and
+treating the character ç as c and ignoring case differences for the uf code.
+
+Args:
+  * municipality_name (str): The name of the municipality.
+  * uf (str): The uf code of the state.
+
+Returns:
+  * str: The IBGE code of the municipality. Returns None if the name is not valid or does not exist.
+
+Example:
+
+```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
+```
+
 ## Monetary
 
 ### format_currency

brutils/__init__.py

@@ -20,15 +20,23 @@
 from brutils.cpf import is_valid as is_valid_cpf
 from brutils.cpf import remove_symbols as remove_symbols_cpf
 
-# Currency
 # Currency
 from brutils.currency import format_currency
 
+# Date imports
+from brutils.date import convert_date_to_text
+
 # Email Import
 from brutils.email import is_valid as is_valid_email
 
 # IBGE Imports
-from brutils.ibge.uf import convert_code_to_uf
+from brutils.ibge.municipality import (
+    get_code_by_municipality_name,
+    get_municipality_by_code,
+)
+from brutils.ibge.uf import (
+    convert_code_to_uf,
+)
 
 # Legal Process Imports
 from brutils.legal_process import format_legal_process
@@ -85,6 +93,8 @@
     "generate_cpf",
     "is_valid_cpf",
     "remove_symbols_cpf",
+    # Date
+    "convert_date_to_text",
     # Email
     "is_valid_email",
     # Legal Process
@@ -116,6 +126,8 @@
     "is_valid_voter_id",
     # IBGE
     "convert_code_to_uf",
+    "get_municipality_by_code",
+    "get_code_by_municipality_name",
     # Currency
     "format_currency",
 ]