Adicionando utilitário convert_uf_to_text

brutils/__init__.py

@@ -45,6 +45,11 @@
 # Email Import
 from brutils.email import is_valid as is_valid_email
 
+# UF Imports
+from brutils.ibge.uf import (
+    convert_uf_to_text,
+)
+
 # Legal Process Imports
 from brutils.legal_process import (
     format_legal_process,
@@ -161,6 +166,8 @@
     "generate_pis",
     "is_valid_pis",
     "remove_symbols_pis",
+    # UF
+    "convert_uf_to_text",
     # Voter ID
     "format_voter_id",
     "generate_voter_id",

brutils/ibge/uf.py

@@ -0,0 +1,29 @@
+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
+    """
+
+    from brutils.data.enums.uf import UF
+
+    try:
+        return UF[uf.upper()].value
+    except KeyError:
+        return None

pyproject.toml

@@ -27,6 +27,7 @@ classifiers = [
 
 [tool.poetry.dependencies]
 python = "^3.8.1"
+ruff = "^0.6.9"
 
 [tool.poetry.group.test.dependencies]
 coverage = "^7.2.7"

tests/ibge/test_uf.py

@@ -0,0 +1,24 @@
+from unittest import TestCase
+
+from brutils.ibge.uf import convert_uf_to_text
+
+
+class TestUF(TestCase):
+    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