Adicionando utilitário convert_uf_to_text

brutils/__init__.py

@@ -55,6 +55,7 @@
 )
 from brutils.ibge.uf import (
     convert_code_to_uf,
+    convert_uf_to_text,
 )
 
 # Legal Process Imports
@@ -180,7 +181,8 @@
     "generate_voter_id",
     "is_valid_voter_id",
     # IBGE
-    "convert_code_to_uf",
     "get_municipality_by_code",
     "get_code_by_municipality_name",
+    "convert_code_to_uf",
+    "convert_uf_to_text",
 ]

brutils/ibge/uf.py

@@ -1,4 +1,4 @@
-from brutils.data.enums.uf import CODE_TO_UF
+from brutils.data.enums.uf import CODE_TO_UF, UF
 
 
 def convert_code_to_uf(code):  # type: (str) -> str | None
@@ -30,3 +30,32 @@ def convert_code_to_uf(code):  # type: (str) -> str | None
         result = CODE_TO_UF(code).name
 
     return result
+
+
+def convert_uf_to_text(uf):  # type: (str) -> str | None
+    """
+    Converts a given Brazilian state code (UF) to its full state name.
+
+    This function takes a 2-letter UF code and returns the corresponding full state name.
+    It handles all Brazilian states and the Federal District.
+
+    Args:
+        uf (str): The 2-letter UF code to be converted.
+
+    Returns:
+        str or None: The full name of the state corresponding to the UF code,
+            or None if the UF code is invalid.
+
+    Example:
+        >>> convert_uf_to_text('SP')
+        "São Paulo"
+        >>> convert_uf_to_text('RJ')
+        "Rio de Janeiro"
+        >>> convert_uf_to_text('XX')
+        None
+    """
+
+    try:
+        return UF[uf.upper()].value
+    except KeyError:
+        return None

tests/ibge/test_uf.py

@@ -1,6 +1,9 @@
 from unittest import TestCase
 
-from brutils.ibge.uf import convert_code_to_uf
+from brutils.ibge.uf import (
+  convert_code_to_uf, 
+  convert_uf_to_text,
+)
 
 
 class TestUF(TestCase):
@@ -16,3 +19,22 @@ def test_convert_code_to_uf(self):
         self.assertIsNone(convert_code_to_uf("00"))
         self.assertIsNone(convert_code_to_uf(""))
         self.assertIsNone(convert_code_to_uf("AB"))
+
+    def test_convert_uf_to_text(self):
+        # Testes para códigos válidos
+        self.assertEqual(convert_uf_to_text("SP"), "São Paulo")
+        self.assertEqual(convert_uf_to_text("RJ"), "Rio de Janeiro")
+        self.assertEqual(convert_uf_to_text("MG"), "Minas Gerais")
+        self.assertEqual(convert_uf_to_text("DF"), "Distrito Federal")
+        self.assertEqual(convert_uf_to_text("df"), "Distrito Federal")
+
+        # Testes para códigos inválidos
+        self.assertIsNone(convert_uf_to_text("XX"))  # Código não existe
+        self.assertIsNone(convert_uf_to_text(""))  # Código vazio
+
+        # Implementar mais casos de teste aqui
+        # Testes com espaços em branco
+        self.assertIsNone(convert_uf_to_text(" SP "))  # UF com espaços ao redor
+        self.assertIsNone(convert_uf_to_text(" "))  # Apenas espaços
+        self.assertIsNone(convert_uf_to_text("S"))  # Apenas 1 letra
+        self.assertIsNone(convert_uf_to_text("SPX"))  # Mais de 2 letras