feat:retorna codigo do ibge do nome do municipio e da uf (#411)

* feat:retorna codigo do ibge do nome do municipio e da uf * feat:altera estrutura do arquivo json usado para obter os codigos dos municipios do IBGE * update CHANGELOG.md and README about get_code_by_municipality_name function * Apply suggestions from code review * Apply suggestions from code review * Apply suggestions from code review * Update tests/ibge/test_municipality.py --------- Co-authored-by: Carlos Eduardo Caldeira <[email protected]> Co-authored-by: Camila Maia <[email protected]>
brazilian-utils · Dec 19, 2024 · c36d581 · c36d581
1 parent a46eafe
commit c36d581
Show file tree

Hide file tree

Showing 7 changed files with 5,826 additions and 3 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -12,6 +12,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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
 
 ### Added

diff --git a/README.md b/README.md
@@ -90,6 +90,7 @@ False
   - [format_voter_id](#format_voter_id)
   - [generate_voter_id](#generate_voter_id)
 - [IBGE](#ibge)
+  - [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)
 
@@ -1159,6 +1160,36 @@ Example:
 ("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
+```
 # Novos Utilitários e Reportar Bugs
 
 Caso queira sugerir novas funcionalidades ou reportar bugs, basta criar

diff --git a/README_EN.md b/README_EN.md
@@ -92,6 +92,7 @@ False
 - [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)
 
 ## CPF
 
@@ -1160,6 +1161,40 @@ Example:
 ("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
+```
+
 # Feature Request and Bug Report
 
 If you want to suggest new features or report bugs, simply create

diff --git a/brutils/__init__.py b/brutils/__init__.py
@@ -47,11 +47,12 @@
 
 # Email Import
 from brutils.email import is_valid as is_valid_email
+
+# IBGE Imports
 from brutils.ibge.municipality import (
+    get_code_by_municipality_name,
     get_municipality_by_code,
 )
-
-# IBGE Imports
 from brutils.ibge.uf import (
     convert_code_to_uf,
 )
@@ -181,4 +182,5 @@
     # IBGE
     "convert_code_to_uf",
     "get_municipality_by_code",
+    "get_code_by_municipality_name",
 ]