Adiciona estatísticas de revisão por pares e utilitários de cálculo de datas (#1051)

* feat(dates): add get_days function and Date methods for peer review stats

- Add get_days() function to calculate days between two dates
- Add get_date() method to Date class with estimation support
- Add get_estimated_date() method for partial dates with defaults
- Add received_date and accepted_date properties to FulltextDates
- Add get_peer_reviewed_stats() method for complete peer review timeline
- Fix isoformat property to handle AttributeError

* test(dates): add comprehensive tests for new date functions and methods

- Add tests for get_days() function with various edge cases
- Add tests for Date.get_date() with complete and partial dates
- Add tests for Date.get_estimated_date() with custom defaults
- Add tests for FulltextDates.get_peer_reviewed_stats() method
- Update existing tests to match new data structure (add season field)
- Import get_days function in test module

* style(dates): format code and add serialize_dates option to get_peer_reviewed_stats

- Apply consistent code formatting with Black
- Add serialize_dates parameter to get_peer_reviewed_stats method
- Convert dates to ISO format string when serialize_dates=True
- Improve variable naming for clarity (received_date -> received)
- Fix line spacing and indentation throughout the file
- Maintain backward compatibility with default serialize_dates=False

Author: robertatakenaka

packtools/sps/models/dates.py

@@ -4,40 +4,52 @@
 from packtools.sps.models.article_and_subarticles import Fulltext
 
 
-class XMLWithPreArticlePublicationDateError(Exception):
-    ...
+class XMLWithPreArticlePublicationDateError(Exception): ...
 
 
 @lru_cache(maxsize=200)
 def format_date(year=None, month=None, day=None, **kwargs) -> str:
     """
     Formata uma data de artigo para o formato YYYY-MM-DD.
-    
+
     Args:
         year: Ano como string ou int
         month: Mês como string ou int
         day: Dia como string ou int
-        
+
     Returns:
         String formatada no padrão YYYY-MM-DD
-        
+
     Raises:
         XMLWithPreArticlePublicationDateError: Se a data for inválida
     """
     try:
         # Valida a data criando um objeto date
         d = date(int(year), int(month), int(day))
-        
+
         # Retorna a string formatada
         return f"{year}-{str(month).zfill(2)}-{str(day).zfill(2)}"
-        
+
     except (ValueError, TypeError) as e:
         raise XMLWithPreArticlePublicationDateError(
             f"Unable to format_date "
             f"year={year}, month={month}, day={day}: {type(e).__name__}: {e}"
         )
 
 
+def get_days(start_date, end_date):
+    """
+    Calculate days between two dates Date.
+
+    Returns:
+        int: Number of days between start_date and end_date, or None if not available
+    """
+    try:
+        return (end_date - start_date).days
+    except (AttributeError, TypeError):
+        return None
+
+
 class Date:
     """Represents and processes a single date from an XML node.
 
@@ -101,8 +113,13 @@ def __str__(self):
 
     @cached_property
     def parts(self):
-        return {"year": self.year, "season": self.season, "month": self.month, "day": self.day}
-    
+        return {
+            "year": self.year,
+            "season": self.season,
+            "month": self.month,
+            "day": self.day,
+        }
+
     @cached_property
     def display(self):
         if self.season:
@@ -124,11 +141,32 @@ def date(self):
         except (ValueError, TypeError):
             return None
 
+    def get_date(self, default_day=15, default_month=6):
+        date_ = self.date
+        if date_:
+            return {"date": date_}
+        return {
+            "estimated": True,
+            "date": self.get_estimated_date(
+                default_day=default_day, default_month=default_month
+            ),
+        }
+
+    def get_estimated_date(self, default_day=15, default_month=6):
+        try:
+            return date(
+                int(self.year),
+                int(self.month or default_month),
+                int(self.day or default_day),
+            )
+        except (ValueError, TypeError):
+            return None
+
     @cached_property
     def isoformat(self):
         try:
             return self.date.isoformat()
-        except (ValueError, TypeError):
+        except (AttributeError, ValueError, TypeError):
             return None
 
 
@@ -239,7 +277,7 @@ def data(self):
     def translations(self):
         for node in super().translations:
             yield FulltextDates(node)
-            
+
     @property
     def not_translations(self):
         for node in super().not_translations:
@@ -376,3 +414,86 @@ def ordered_events(self):
     def date_types_ordered_by_date(self):
         # obtem uma lista com os nomes dos eventos ordenados
         return [event[0] for event in self.ordered_events]
+
+    @cached_property
+    def received_date(self):
+        """Get received date as a Date instance.
+
+        Returns:
+            Date: Date instance for the received date, or None if not available
+        """
+        try:
+            node = self.front.xpath(".//history//date[@date-type='received']")[0]
+            return Date(node)
+        except (IndexError, AttributeError):
+            return None
+
+    @cached_property
+    def accepted_date(self):
+        """Get accepted date as a Date instance.
+
+        Returns:
+            Date: Date instance for the accepted date, or None if not available
+        """
+        try:
+            node = self.front.xpath(".//history//date[@date-type='accepted']")[0]
+            return Date(node)
+        except (IndexError, AttributeError):
+            return None
+
+    def get_peer_reviewed_stats(
+        self, default_month=6, default_day=15, serialize_dates=False
+    ):
+        received = {}
+        if self.received_date:
+            received = self.received_date.get_date(
+                default_month=default_month, default_day=default_day
+            )
+        accepted = {}
+        if self.accepted_date:
+            accepted = self.accepted_date.get_date(
+                default_month=default_month, default_day=default_day
+            )
+        published = {}
+        if self.epub_date_model or self.collection_date_model:
+            published = (self.epub_date_model or self.collection_date_model).get_date(
+                default_month=default_month, default_day=default_day
+            )
+
+        received_date = received.get("date")
+        accepted_date = accepted.get("date")
+        published_date = published.get("date")
+
+        stats = {}
+        stats["received_date"] = (
+            received_date.isoformat()
+            if serialize_dates and received_date
+            else received_date
+        )
+        stats["accepted_date"] = (
+            accepted_date.isoformat()
+            if serialize_dates and accepted_date
+            else accepted_date
+        )
+        stats["published_date"] = (
+            published_date.isoformat()
+            if serialize_dates and published_date
+            else published_date
+        )
+        stats["days_from_received_to_accepted"] = get_days(received_date, accepted_date)
+        stats["estimated_days_from_received_to_accepted"] = received.get(
+            "estimated"
+        ) or accepted.get("estimated")
+        stats["days_from_accepted_to_published"] = get_days(
+            accepted_date, published_date
+        )
+        stats["estimated_days_from_accepted_to_published"] = accepted.get(
+            "estimated"
+        ) or published.get("estimated")
+        stats["days_from_received_to_published"] = get_days(
+            received_date, published_date
+        )
+        stats["estimated_days_from_received_to_published"] = received.get(
+            "estimated"
+        ) or published.get("estimated")
+        return stats