Conversão de código do estado do IBGE para a sigla do Estado (#410)

Co-authored-by: Fernando Bezerra fsbezerra@outlook.com

CHANGELOG.md

@@ -6,6 +6,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+### Added
+
+- Utilitário `convert_code_to_uf` [#397](https://github.com/brazilian-utils/brutils-python/pull/410)
 
 ## [2.2.0] - 2024-09-12
 

README.md

@@ -87,6 +87,8 @@ False
   - [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)
 
 ## CPF
 
@@ -1084,6 +1086,29 @@ Exemplo:
 '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")
+>>>
+```
+
 
 # Novos Utilitários e Reportar Bugs
 

README_EN.md

@@ -87,6 +87,8 @@ False
   - [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)
 
 ## CPF
 
@@ -1087,6 +1089,29 @@ Example:
 '950125640248'
 ```
 
+## IBGE
+### convert_code_to_uf
+Converts a given IBGE code (2-digit string) to its corresponding UF (state abbreviation).
+
+Args:
+  * code (str): The 2-digit IBGE code to be converted.
+
+Retorna:
+  * str or None: The UF code corresponding to the IBGE code, or None if the
+                 IBGE code is invalid.
+
+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")
+>>>
+```
+
 # Feature Request and Bug Report
 
 If you want to suggest new features or report bugs, simply create

brutils/__init__.py

@@ -45,6 +45,11 @@
 # Email Import
 from brutils.email import is_valid as is_valid_email
 
+# IBGE Imports
+from brutils.ibge.uf import (
+    convert_code_to_uf,
+)
+
 # Legal Process Imports
 from brutils.legal_process import (
     format_legal_process,
@@ -165,4 +170,6 @@
     "format_voter_id",
     "generate_voter_id",
     "is_valid_voter_id",
+    # IBGE
+    "convert_code_to_uf",
 ]

brutils/data/enums/__init__.py

@@ -1 +1 @@
-from .uf import UF
+from .uf import CODE_TO_UF, UF

brutils/data/enums/uf.py

@@ -29,3 +29,33 @@ class UF(BetterEnum):
     SP = "São Paulo"
     SE = "Sergipe"
     TO = "Tocantins"
+
+
+class CODE_TO_UF(BetterEnum):
+    AC = "12"
+    AL = "27"
+    AP = "16"
+    AM = "13"
+    BA = "29"
+    CE = "23"
+    DF = "53"
+    ES = "32"
+    GO = "52"
+    MA = "21"
+    MT = "51"
+    MS = "52"
+    MG = "31"
+    PA = "15"
+    PB = "25"
+    PR = "41"
+    PE = "26"
+    PI = "22"
+    RJ = "33"
+    RN = "24"
+    RS = "43"
+    RO = "11"
+    RR = "14"
+    SC = "42"
+    SP = "35"
+    SE = "28"
+    TO = "17"

brutils/ibge/uf.py

@@ -0,0 +1,32 @@
+from brutils.data.enums.uf import CODE_TO_UF
+
+
+def convert_code_to_uf(code):  # type: (str) -> str | None
+    """
+    Converts a given IBGE code (2-digit string) to its corresponding UF (state abbreviation).
+
+    This function takes a 2-digit IBGE code and returns the corresponding UF code.
+    It handles all Brazilian states and the Federal District.
+
+    Args:
+        code (str): The 2-digit IBGE code to be converted.
+
+    Returns:
+        str or None: The UF code corresponding to the IBGE code,
+            or None if the IBGE code is invalid.
+
+    Example:
+        >>> convert_code_to_uf('12')
+        'AC'
+        >>> convert_code_to_uf('33')
+        'RJ'
+        >>> convert_code_to_uf('99')
+        >>>
+    """
+
+    result = None
+
+    if code in CODE_TO_UF.values:
+        result = CODE_TO_UF(code).name
+
+    return result

tests/ibge/test_uf.py

@@ -0,0 +1,18 @@
+from unittest import TestCase
+
+from brutils.ibge.uf import convert_code_to_uf
+
+
+class TestUF(TestCase):
+    def test_convert_code_to_uf(self):
+        # Testes para códigos válidos
+        self.assertEqual(convert_code_to_uf("12"), "AC")
+        self.assertEqual(convert_code_to_uf("33"), "RJ")
+        self.assertEqual(convert_code_to_uf("31"), "MG")
+        self.assertEqual(convert_code_to_uf("52"), "GO")
+
+        # Testes para códigos inválidos
+        self.assertIsNone(convert_code_to_uf("99"))
+        self.assertIsNone(convert_code_to_uf("00"))
+        self.assertIsNone(convert_code_to_uf(""))
+        self.assertIsNone(convert_code_to_uf("AB"))