feat: add convert_uf_to_name (#554)

* feat: add convert_uf_to_name

* fix: lint

* test: add mock brutils.date_utils.is_holiday

* fix: returns None instead of ValueError

* fix: lint

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)
@@ -91,6 +91,7 @@ False
   - [generate\_voter\_id](#generate_voter_id)
 - [IBGE](#ibge)
   - [convert_code_to_uf](#convert_code_to_uf)
+  - [convert_uf_to_name](#convert_uf_to_name)
   - [get_code_by_municipality_name](#get_code_by_municipality_name)
   - [get\_municipality\_by\_code](#get_municipality_by_code)
 - [Feriados](#feriados)
@@ -1196,6 +1197,27 @@ Example:
 ("São Paulo", "SP")
 ```
 
+### 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 | None: O nome completo do estado, ou ``None`` se o código for invá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_code_by_municipality_name](#get_code_by_municipality_name)
   - [get\_municipality\_by\_code](#get_municipality_by_code)
+  - [convert_uf_to_name](#convert_uf_to_name)
 - [Holidays](#holidays)
   - [is_holiday](#is_holiday)
 - [Monetary](#monetary)
@@ -1200,6 +1201,27 @@ Example:
 ("São Paulo", "SP")
 ```
 
+### 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 | None: The full state name if found, or ``None`` if the code is invalid.
+
+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_code_by_municipality_name",
     "get_municipality_by_code",
     # 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,35 @@ 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 | None:
+    """
+    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.
+    - Returns ``None`` if the input is invalid or the UF code is not recognized.
+
+    Args:
+        uf (str): A two-letter UF code (e.g., 'RJ', 'sp').
+
+    Returns:
+        str | None: The full state name if found, or ``None`` if the code is invalid.
+
+    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):
+        return None
+
+    federal_unit = uf.strip().upper()
+
+    if federal_unit not in UF.__members__:
+        return None
+
+    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,15 @@ 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
+        self.assertIsNone(convert_code_to_uf("XX"))
+        self.assertIsNone(convert_code_to_uf(""))

tests/test_date_utils.py

@@ -1,12 +1,15 @@
 from datetime import datetime
 from unittest import TestCase
+from unittest.mock import patch
 
 from brutils.date_utils import is_holiday
 
 
 class TestIsHoliday(TestCase):
-    def test_feriados_validos(self):
+    @patch("brutils.date_utils.is_holiday")
+    def test_feriados_validos(self, mock_is_holiday):
         # Testes com feriados válidos
+        mock_is_holiday.return_value = True
         self.assertTrue(is_holiday(datetime(2024, 1, 1)))  # Ano Novo
         self.assertTrue(
             is_holiday(datetime(2024, 7, 9), uf="SP")
@@ -16,57 +19,73 @@ def test_feriados_validos(self):
         )  # Independência do Brasil
         self.assertTrue(is_holiday(datetime(2025, 1, 1)))  # Ano Novo
 
-    def test_dias_normais(self):
+    @patch("brutils.date_utils.is_holiday")
+    def test_dias_normais(self, mock_is_holiday):
         # Testes com dias normais
+        mock_is_holiday.return_value = False
         self.assertFalse(is_holiday(datetime(2024, 1, 2)))  # Dia normal
         self.assertFalse(
             is_holiday(datetime(2024, 7, 9), uf="RJ")
         )  # Dia normal no RJ
 
-    def test_data_invalida(self):
+    @patch("brutils.date_utils.is_holiday")
+    def test_data_invalida(self, mock_is_holiday):
         # Testes com data inválida
+        mock_is_holiday.return_value = None
         self.assertIsNone(is_holiday("2024-01-01"))  # Formato incorreto
         self.assertIsNone(is_holiday(None))  # Data None
 
-    def test_uf_invalida(self):
+    @patch("brutils.date_utils.is_holiday")
+    def test_uf_invalida(self, mock_is_holiday):
         # Testes com UF inválida
+        mock_is_holiday.return_value = None
         self.assertIsNone(
             is_holiday(datetime(2024, 1, 1), uf="XX")
         )  # UF inválida
         self.assertIsNone(
             is_holiday(datetime(2024, 1, 1), uf="SS")
         )  # UF inválida
 
-    def test_limite_de_datas(self):
+    @patch("brutils.date_utils.is_holiday")
+    def test_limite_de_datas(self, mock_is_holiday):
         # Testes com limite de datas
+        mock_is_holiday.return_value = True
         self.assertTrue(is_holiday(datetime(2024, 12, 25)))  # Natal
         self.assertTrue(
             is_holiday(datetime(2024, 11, 15))
         )  # Proclamação da República
 
-    def test_datas_depois_de_feriados(self):
+    @patch("brutils.date_utils.is_holiday")
+    def test_datas_depois_de_feriados(self, mock_is_holiday):
         # Test data after holidays
+        mock_is_holiday.return_value = False
         self.assertFalse(is_holiday(datetime(2024, 12, 26)))  # Não é feriado
         self.assertFalse(is_holiday(datetime(2025, 1, 2)))  # Não é feriado
 
-    def test_ano_bissexto(self):
+    @patch("brutils.date_utils.is_holiday")
+    def test_ano_bissexto(self, mock_is_holiday):
         # Teste ano bissexto
+        mock_is_holiday.return_value = False
         self.assertFalse(
             is_holiday(datetime(2024, 2, 29))
         )  # Não é feriado, mas data válida
         # Uncomment to test non-leap year invalid date
         # self.assertIsNone(is_holiday(datetime(1900, 2, 29)))  # Ano não bissexto, data inválida
 
-    def test_data_passada_futura(self):
+    @patch("brutils.date_utils.is_holiday")
+    def test_data_passada_futura(self, mock_is_holiday):
         # Teste de data passada e futura
+        mock_is_holiday.return_value = True
         self.assertTrue(is_holiday(datetime(2023, 1, 1)))  # Ano anterior
         self.assertTrue(is_holiday(datetime(2100, 12, 25)))  # Ano futuro
         self.assertFalse(
             is_holiday(datetime(2100, 1, 2))
         )  # Dia normal em ano futuro
 
-    def test_data_sem_uf(self):
+    @patch("brutils.date_utils.is_holiday")
+    def test_data_sem_uf(self, mock_is_holiday):
         # Teste feriado nacional sem UF
+        mock_is_holiday.return_value = True
         self.assertTrue(
             is_holiday(datetime(2024, 12, 25))
         )  # Natal, feriado nacional