feat: add convert_uf_to_name

Author: niltonpimentel02

README.md

@@ -81,7 +81,7 @@ False
   - [remove\_symbols\_pis](#remove_symbols_pis)
   - [generate\_pis](#generate_pis)
 - [Processo Jurídico](#processo-jurídico)
-- [is\_valid\_legal\_process](#is_valid_legal_process)
+  - [is\_valid\_legal\_process](#is_valid_legal_process)
   - [format\_legal\_process](#format_legal_process)
   - [remove\_symbols\_legal\_process](#remove_symbols_legal_process)
   - [generate\_legal\_process](#generate_legal_process)
@@ -93,6 +93,7 @@ False
   - [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)
+  - [convert_uf_to_name](#convert_uf_to_name)
 - [Feriados](#feriados)
   - [is_holiday](#is_holiday)
 - [Monetário](#monetário)
@@ -1196,6 +1197,30 @@ None
 None
 ```
 
+### convert_uf_to_name
+Converte um código de UF brasileiro (por exemplo, 'SP') no nome completo do estado ('São Paulo').
+
+A busca é case-insensitive (não diferencia maiúsculas de minúsculas) e ignora espaços em branco ao redor.
+
+Argumentos:
+  * uf (str): Código de UF com duas letras.
+
+Retorna:
+  * str: O nome completo do estado.
+
+Lança:
+  * ValueError: Se `uf` for uma string vazia ou não for um código de UF válido.
+
+Exemplo:
+
+```python
+>>> from brutils.ibge.uf import convert_uf_to_name
+>>> convert_uf_to_name('SP')
+'São Paulo'
+>>> convert_uf_to_name('rj')
+'Rio de Janeiro'
+```
+
 ## Feriados
 
 ### is_holiday

README_EN.md

@@ -93,6 +93,7 @@ False
   - [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)
+  - [convert_uf_to_name](#convert_uf_to_name)
 - [Holidays](#holidays)
   - [is_holiday](#is_holiday)
 - [Monetary](#monetary)
@@ -1200,6 +1201,30 @@ None
 None
 ```
 
+### convert_uf_to_name
+Converts a Brazilian UF code (e.g., 'SP') to the state's full name ('São Paulo').
+
+The lookup is case-insensitive and ignores surrounding whitespace.
+
+Args:
+  * uf (str): Two-letter UF code.
+
+Returns:
+  * str: The state's full name.
+
+Raises:
+  * ValueError: If `uf` is an empty string or is not a valid UF code.
+
+Example:
+
+```python
+>>> from brutils.ibge.uf import convert_uf_to_name
+>>> convert_uf_to_name('SP')
+'São Paulo'
+>>> convert_uf_to_name('rj')
+'Rio de Janeiro'
+```
+
 ## Holidays
 
 ### is_holiday

brutils/__init__.py

@@ -37,7 +37,7 @@
     get_code_by_municipality_name,
     get_municipality_by_code,
 )
-from brutils.ibge.uf import convert_code_to_uf
+from brutils.ibge.uf import convert_code_to_uf, convert_uf_to_name
 
 # Legal Process Imports
 from brutils.legal_process import format_legal_process
@@ -127,6 +127,7 @@
     "is_valid_voter_id",
     # IBGE
     "convert_code_to_uf",
+    "convert_uf_to_name",
     "get_municipality_by_code",
     "get_code_by_municipality_name",
     # Date Utils

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,37 @@ def convert_code_to_uf(code):  # type: (str) -> str | None
         result = CODE_TO_UF(code).name
 
     return result
+
+
+def convert_uf_to_name(uf: str) -> str:
+    """
+    Convert a Brazilian UF code (e.g., 'SP') to its full state name ('São Paulo').
+
+    The lookup is case-insensitive and ignores surrounding whitespace.
+
+    Args:
+        uf (str): Two-letter UF code.
+
+    Returns:
+        str: The full state name.
+
+    Raises:
+        ValueError: If `uf` is not a non-empty string or is not a valid UF code.
+
+    Examples:
+        >>> convert_uf_to_name('SP')
+        'São Paulo'
+        >>> convert_uf_to_name('rj')
+        'Rio de Janeiro'
+    """
+    if not uf or not isinstance(uf, str):
+        raise ValueError('UF must be a non-empty string.')
+
+    federal_unit = uf.strip().upper()
+
+    if federal_unit not in UF.__members__:
+        raise ValueError(f'Invalid UF: {uf}')
+
+    result = UF[federal_unit].value
+
+    return result

tests/ibge/test_uf.py

@@ -1,6 +1,6 @@
 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_name
 
 
 class TestUF(TestCase):
@@ -16,3 +16,17 @@ 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_name(self):
+        # Testes para códigos válidos
+        self.assertEqual(convert_uf_to_name("SP"), "São Paulo")
+        self.assertEqual(convert_uf_to_name("RJ"), "Rio de Janeiro")
+        self.assertEqual(convert_uf_to_name("MG"), "Minas Gerais")
+        self.assertEqual(convert_uf_to_name("DF"), "Distrito Federal")
+        self.assertEqual(convert_uf_to_name("df"), "Distrito Federal")
+
+        # Testes para códigos inválidos
+        with self.assertRaises(ValueError):
+            convert_uf_to_name("XX")
+        with self.assertRaises(ValueError):
+            convert_uf_to_name("")