perf: minor changes on some modules

Author: Rodrigo Roldán

.dockerignore

@@ -0,0 +1,3 @@
+# Explicitly re-ignore some folders
+.*
+**/__pycache__

src/eones/__init__.py

@@ -7,7 +7,157 @@
 reason about time — not just measure it.
 """
 
+from datetime import datetime, timedelta
+from typing import Any, List, Union
+
+from eones.core.date import Date
+from eones.core.parser import Parser
+from eones.errors import InvalidFormatError, InvalidTimezoneError
 from eones.interface import Eones
 
+
+# Utility functions for backward compatibility and convenience
+def parse_date(
+    value: Union[str, dict, datetime], tz: str = "UTC", formats: List[str] = None
+) -> Date:
+    """Parse a date from various input formats.
+
+    Args:
+        value: Date input (string, dict, or datetime)
+        tz: Timezone string
+        formats: List of format strings for parsing
+
+    Returns:
+        Date: Parsed date object
+    """
+    # Include common datetime formats including ISO with timezone if none provided
+    if formats is None:
+        formats = [
+            "%Y-%m-%d",
+            "%d/%m/%Y",
+            "%Y-%m-%d %H:%M:%S",
+            "%Y-%m-%d %H:%M",
+            "%d/%m/%Y %H:%M:%S",
+            "%d/%m/%Y %H:%M",
+            "%Y-%m-%dT%H:%M:%S%z",
+            "%Y-%m-%dT%H:%M:%S",
+        ]
+    parser = Parser(tz=tz, formats=formats)
+    return parser.parse(value)
+
+
+def format_date(date: Union[Date, datetime], fmt: str) -> str:
+    """Format a date using the given format string.
+
+    Args:
+        date: Date object or datetime to format
+        fmt: Format string
+
+    Returns:
+        str: Formatted date string
+    """
+    if isinstance(date, Date):
+        return date.format(fmt)
+    elif isinstance(date, datetime):
+        return date.strftime(fmt)
+    else:
+        raise TypeError(f"Expected Date or datetime object, got {type(date).__name__}")
+
+
+def add_days(date: Date, days: int) -> Date:
+    """Add days to a date.
+
+    Args:
+        date: Date object
+        days: Number of days to add (can be negative)
+
+    Returns:
+        Date: New date with days added
+    """
+    if not isinstance(date, Date):
+        raise ValueError("Expected Date object")
+    return date.shift(timedelta(days=days))
+
+
+def date_diff_days(date1: Date, date2: Date) -> int:
+    """Calculate the difference in days between two dates.
+
+    Args:
+        date1: First date
+        date2: Second date
+
+    Returns:
+        int: Difference in days (date2 - date1)
+    """
+    if not isinstance(date1, Date) or not isinstance(date2, Date):
+        raise ValueError("Expected Date objects")
+    return (date2.to_datetime() - date1.to_datetime()).days
+
+
+def date_range(start: Date, end: Date, step_days: int = 1) -> List[Date]:
+    """Generate a range of dates from start to end.
+
+    Args:
+        start: Start date
+        end: End date (inclusive)
+        step_days: Step size in days
+
+    Returns:
+        List[Date]: List of dates in the range
+    """
+    if not isinstance(start, Date) or not isinstance(end, Date):
+        raise ValueError("Expected Date objects")
+
+    dates = []
+    current = start
+
+    while current.to_datetime().date() <= end.to_datetime().date():
+        dates.append(current)
+        current = current.shift(timedelta(days=step_days))
+
+    return dates
+
+
+def to_timestamp(date: Union[Date, datetime]) -> int:
+    """Convert a date to Unix timestamp.
+
+    Args:
+        date: Date object or datetime
+
+    Returns:
+        int: Unix timestamp
+    """
+    if isinstance(date, Date):
+        return int(date.to_unix())
+    elif isinstance(date, datetime):
+        return int(date.timestamp())
+    else:
+        raise ValueError("Expected Date or datetime object")
+
+
+def from_timestamp(timestamp: Union[int, float], tz: str = "UTC") -> Date:
+    """Create a Date from Unix timestamp.
+
+    Args:
+        timestamp: Unix timestamp (int or float)
+        tz: Timezone (default: "UTC")
+
+    Returns:
+        Date: Date object
+    """
+    return Date.from_unix(float(timestamp), tz=tz)
+
+
 __version__ = "1.2.0"
-__all__ = ["Eones"]
+__all__ = [
+    "Eones",
+    "InvalidFormatError",
+    "InvalidTimezoneError",
+    "parse_date",
+    "format_date",
+    "add_days",
+    "date_diff_days",
+    "date_range",
+    "to_timestamp",
+    "from_timestamp",
+]

src/eones/core/date.py

@@ -308,7 +308,7 @@ def from_iso(cls, iso_str: str, tz: Optional[str] = "UTC") -> Date:
         try:
             dt = datetime.fromisoformat(iso_str)
 
-        except ZoneInfoNotFoundError as exc:
+        except ValueError as exc:
             raise InvalidTimezoneError(tz) from exc
 
         if dt.tzinfo is None:

src/eones/humanize.py

@@ -26,7 +26,7 @@ def diff_for_humans(
     if other is None:
         from eones.core.date import Date  # pylint: disable=import-outside-toplevel
 
-        other = Date.now(tz=date.timezone)
+        other = Date.now(tz=date.timezone, naive="utc")
 
     diff_seconds = (date.to_datetime() - other.to_datetime()).total_seconds()
     future = diff_seconds > 0

src/eones/interface.py

@@ -298,3 +298,44 @@ def _coerce_to_date(self, other) -> "Date":
             return other
 
         return self._parser.parse(other)
+
+    @staticmethod
+    def is_valid_format(date_str: str, formats: List[str]) -> bool:
+        """Check if a date string matches any of the provided formats.
+
+        Args:
+            date_str: Date string to validate
+            formats: List of format strings to try
+
+        Returns:
+            bool: True if the string matches any format
+        """
+        from datetime import datetime
+
+        for fmt in formats:
+            try:
+                datetime.strptime(date_str, fmt)
+                return True
+            except ValueError:
+                continue
+        return False
+
+    @staticmethod
+    def sanitize_formats(formats: List[Any]) -> List[str]:
+        """Remove duplicates and invalid formats from a format list.
+
+        Args:
+            formats: List of format strings (may contain duplicates or invalid types)
+
+        Returns:
+            List[str]: Clean list of unique format strings
+        """
+        seen = set()
+        result = []
+
+        for fmt in formats:
+            if isinstance(fmt, str) and fmt not in seen:
+                seen.add(fmt)
+                result.append(fmt)
+
+        return result