refactor(date-utils): unifica date e date-utils (#576)

também refatora `is_holiday` e `convert_date_to_text`

Author: camilamaia

brutils/__init__.py

@@ -23,11 +23,8 @@
 # Currency
 from brutils.currency import convert_real_to_text, format_currency
 
-# Date imports
-from brutils.date import convert_date_to_text
-
 # Date Utils Import
-from brutils.date_utils import is_holiday
+from brutils.date_utils import convert_date_to_text, is_holiday
 
 # Email Import
 from brutils.email import is_valid as is_valid_email
@@ -94,8 +91,6 @@
     "generate_cpf",
     "is_valid_cpf",
     "remove_symbols_cpf",
-    # Date
-    "convert_date_to_text",
     # Email
     "is_valid_email",
     # Legal Process
@@ -132,6 +127,7 @@
     "get_municipality_by_code",
     # Date Utils
     "is_holiday",
+    "convert_date_to_text",
     # Currency
     "format_currency",
     "convert_real_to_text",

brutils/date.py

@@ -1,10 +1,15 @@
+import re
 from datetime import datetime
-from typing import Union
 
 import holidays
+from num2words import num2words
 
+from brutils.data.enums.months import MonthsEnum
 
-def is_holiday(target_date: datetime, uf: str = None) -> Union[bool, None]:
+DATE_REGEX = re.compile(r"^\d{2}/\d{2}/\d{4}$")
+
+
+def is_holiday(target_date: datetime, uf: str = None) -> bool | None:
     """
     Checks if the given date is a national or state holiday in Brazil.
 
@@ -41,18 +46,50 @@ def is_holiday(target_date: datetime, uf: str = None) -> Union[bool, None]:
         >>> is_holiday(datetime(2024, 12, 25), uf="RJ")
         True
     """
-
     if not isinstance(target_date, datetime):
         return None
 
-    valid_ufs = holidays.Brazil().subdivisions
+    national_holidays = holidays.Brazil(years=target_date.year)
+    valid_ufs = national_holidays.subdivisions
+
     if uf is not None and uf not in valid_ufs:
         return None
 
-    national_holidays = holidays.Brazil(years=target_date.year)
-
     if uf is None:
         return target_date in national_holidays
 
     state_holidays = holidays.Brazil(prov=uf, years=target_date.year)
     return target_date in state_holidays
+
+
+def convert_date_to_text(date: str) -> str | None:
+    """
+    Converts a given date in Brazilian format (dd/mm/yyyy) to its textual representation.
+
+    This function takes a date as a string in the format dd/mm/yyyy and converts it
+    to a string with the date written out in Brazilian Portuguese, including the full
+    month name and the year.
+
+    Args:
+        date (str): The date to be converted into text. Expected format: dd/mm/yyyy.
+
+    Returns:
+        str | None: A string with the date written out in Brazilian Portuguese,
+        or None if the date is invalid.
+
+    """
+    if not DATE_REGEX.match(date):
+        return None
+
+    try:
+        dt = datetime.strptime(date, "%d/%m/%Y")
+    except ValueError:
+        return None
+
+    day, month, year = dt.day, dt.month, dt.year
+
+    day_str = "Primeiro" if day == 1 else num2words(day, lang="pt")
+    month_enum = MonthsEnum(month)
+    year_str = num2words(year, lang="pt")
+
+    return f"{day_str.capitalize()} de {month_enum.month_name} de {year_str}"

brutils/date_utils.py

@@ -2,6 +2,10 @@
 from unittest import TestCase
 from unittest.mock import patch
 
+from num2words import num2words
+
+from brutils import convert_date_to_text
+from brutils.data.enums.months import MonthsEnum
 from brutils.date_utils import is_holiday
 
 
@@ -92,3 +96,78 @@ def test_data_sem_uf(self, mock_is_holiday):
         self.assertFalse(
             is_holiday(datetime(2024, 7, 9))
         )  # Data estadual de SP, sem UF
+
+
+class TestNum2Words(TestCase):
+    def test_num_conversion(self) -> None:
+        """
+        Smoke test of the num2words library.
+        This test is used to guarantee that our dependency still works.
+        """
+        self.assertEqual(num2words(30, lang="pt-br"), "trinta")
+        self.assertEqual(num2words(42, lang="pt-br"), "quarenta e dois")
+        self.assertEqual(
+            num2words(2024, lang="pt-br"), "dois mil e vinte e quatro"
+        )
+        self.assertEqual(num2words(0, lang="pt-br"), "zero")
+        self.assertEqual(num2words(-1, lang="pt-br"), "menos um")
+
+
+class TestConvertDateToText(TestCase):
+    def test_convert_date_to_text(self):
+        self.assertEqual(
+            convert_date_to_text("15/08/2024"),
+            "Quinze de agosto de dois mil e vinte e quatro",
+        )
+        self.assertEqual(
+            convert_date_to_text("01/01/2000"),
+            "Primeiro de janeiro de dois mil",
+        )
+        self.assertEqual(
+            convert_date_to_text("31/12/1999"),
+            "Trinta e um de dezembro de mil novecentos e noventa e nove",
+        )
+
+        self.assertIsNone(convert_date_to_text("30/02/2020"), None)
+        self.assertIsNone(convert_date_to_text("30/00/2020"), None)
+        self.assertIsNone(convert_date_to_text("30/02/2000"), None)
+        self.assertIsNone(convert_date_to_text("50/09/2000"), None)
+        self.assertIsNone(convert_date_to_text("25/15/2000"), None)
+        self.assertIsNone(convert_date_to_text("29/02/2019"), None)
+
+        # Invalid date pattern.
+        self.assertIsNone(convert_date_to_text("Invalid"))
+        self.assertIsNone(convert_date_to_text("25/1/2020"))
+        self.assertIsNone(convert_date_to_text("1924/08/20"))
+        self.assertIsNone(convert_date_to_text("5/09/2020"))
+        self.assertIsNone(convert_date_to_text("00/09/2020"))
+        self.assertIsNone(convert_date_to_text("32/09/2020"))
+
+        self.assertEqual(
+            convert_date_to_text("29/02/2020"),
+            "Vinte e nove de fevereiro de dois mil e vinte",
+        )
+        self.assertEqual(
+            convert_date_to_text("01/01/1900"),
+            "Primeiro de janeiro de mil e novecentos",
+        )
+
+    months_year = [
+        (1, "janeiro"),
+        (2, "fevereiro"),
+        (3, "marco"),
+        (4, "abril"),
+        (5, "maio"),
+        (6, "junho"),
+        (7, "julho"),
+        (8, "agosto"),
+        (9, "setembro"),
+        (10, "outubro"),
+        (11, "novembro"),
+        (12, "dezembro"),
+    ]
+
+    def testMonthEnum(self):
+        for number_month, name_month in self.months_year:
+            month = MonthsEnum(number_month)
+            self.assertEqual(month.month_name, name_month)