perf: Document new error classes

Author: Rodrigo Roldán

README.es.md

@@ -66,6 +66,10 @@ print(z.diff_for_humans("2025-06-20", locale="es"))  # → hace 5 días
 Podés agregar más idiomas creando un archivo en `eones/locales/` con las
 traducciones para tu idioma. Por ejemplo, `fr.py` para francés.
 
+Manejo de errores
+
+Eones muestra excepciones claras derivadas de `EonesError`. Las zonas horarias no válidas generan `InvalidTimezoneError`, mientras que las cadenas no analizables generan `InvalidFormatError`.
+
 ---
 
 ## 🧾 Comparación con otras librerías

README.md

@@ -65,6 +65,12 @@ print(z.diff_for_humans("2025-06-20", locale="es"))  # → hace 5 días
 You can add more languages by creating a new file in `eones/locales/` with the
 translations for your locale. For example, `fr.py` for French.
 
+Error Handling
+
+Eones surfaces clear exceptions derived from `EonesError`. Invalid timezones
+raise `InvalidTimezoneError`, while unparsable strings raise
+`InvalidFormatError`.
+
 ---
 
 ## 🧾 Comparison with other libraries

src/eones/core/date.py

@@ -5,9 +5,10 @@
 from calendar import monthrange
 from datetime import datetime, timedelta, timezone
 from typing import TYPE_CHECKING, Any, Literal, Optional, Union
-from zoneinfo import ZoneInfo
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
 
 from eones.constants import VALID_KEYS
+from eones.errors import InvalidTimezoneError
 from eones.humanize import diff_for_humans as _diff_for_humans
 
 if TYPE_CHECKING:  # pragma: no cover - import for type checking only
@@ -31,7 +32,11 @@ def __init__(
         tz: Optional[str] = "UTC",
         naive: Literal["utc", "local", "raise"] = "raise",
     ):
-        self._zone = ZoneInfo(tz)
+        try:
+            self._zone = ZoneInfo(tz)
+
+        except ZoneInfoNotFoundError as exc:
+            raise InvalidTimezoneError(tz) from exc
 
         if dt is None:
             self._dt = datetime.now(self._zone)
@@ -103,7 +108,7 @@ def __add__(self, delta: Union[timedelta, "Delta"]) -> Date:
         Returns:
             Date: The resulting shifted date.
         """
-        from eones.core.delta import Delta
+        from eones.core.delta import Delta  # pylint: disable=import-outside-toplevel
 
         if isinstance(delta, Delta):
             return delta.apply(self)
@@ -113,7 +118,10 @@ def __add__(self, delta: Union[timedelta, "Delta"]) -> Date:
 
         return NotImplemented
 
-    def __sub__(self, other: Union[Date, timedelta, "Delta"]) -> Union[Date, timedelta]:
+    def __sub__(
+        self,
+        other: Union[Date, timedelta, "Delta"],
+    ) -> Union[Date, timedelta]:
         """Subtract ``other`` from this date.
 
         ``other`` may be a :class:`datetime.timedelta` or a
@@ -125,7 +133,7 @@ def __sub__(self, other: Union[Date, timedelta, "Delta"]) -> Union[Date, timedel
             Union[Date, timedelta]: ``Date`` or time difference depending on the
             operand type.
         """
-        from eones.core.delta import Delta
+        from eones.core.delta import Delta  # pylint: disable=import-outside-toplevel
 
         if isinstance(other, Delta):
             return other.invert().apply(self)
@@ -297,7 +305,12 @@ def from_iso(cls, iso_str: str, tz: Optional[str] = "UTC") -> Date:
         Returns:
             Date: Parsed Date.
         """
-        dt = datetime.fromisoformat(iso_str)
+        try:
+            dt = datetime.fromisoformat(iso_str)
+
+        except ZoneInfoNotFoundError as exc:
+            raise InvalidTimezoneError(tz) from exc
+
         if dt.tzinfo is None:
             dt = dt.replace(tzinfo=ZoneInfo(tz))
         return cls(dt, tz)
@@ -313,7 +326,12 @@ def from_unix(cls, timestamp: float, tz: Optional[str] = "UTC") -> Date:
         Returns:
             Date: Parsed Date.
         """
-        dt = datetime.fromtimestamp(timestamp, tz=ZoneInfo(tz))
+        try:
+            dt = datetime.fromtimestamp(timestamp, tz=ZoneInfo(tz))
+
+        except ZoneInfoNotFoundError as exc:
+            raise InvalidTimezoneError(tz) from exc
+
         return cls(dt, tz)
 
     def is_within(self, other: Date, check_month: bool = True) -> bool:
@@ -403,7 +421,11 @@ def as_zone(self, zone: str) -> datetime:
         Returns:
             datetime: Datetime in the new timezone.
         """
-        return self._dt.astimezone(ZoneInfo(zone))
+        try:
+            return self._dt.astimezone(ZoneInfo(zone))
+
+        except ZoneInfoNotFoundError as exc:
+            raise InvalidTimezoneError(zone) from exc
 
     def truncate(self, unit: str) -> Date:
         """Truncate the Date to the specified unit (e.g., 'day', 'hour', etc.)."""

src/eones/core/delta.py

@@ -1,6 +1,7 @@
 """core.delta.py"""
 
 import re
+from datetime import timedelta
 from typing import Dict
 
 from eones.constants import DELTA_KEYS
@@ -277,8 +278,6 @@ def from_iso(cls, iso: str) -> "Delta":
     @classmethod
     def from_timedelta(cls, td: "timedelta") -> "Delta":
         """Create a Delta instance from :class:`datetime.timedelta`."""
-        from datetime import timedelta
-
         if not isinstance(td, timedelta):
             raise TypeError(f"'td' must be timedelta, got {type(td).__name__}")
 

src/eones/core/parser.py

@@ -4,10 +4,11 @@
 
 from datetime import datetime
 from typing import Dict, List, Optional, Union
-from zoneinfo import ZoneInfo
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
 
 from eones.constants import VALID_KEYS
 from eones.core.date import Date
+from eones.errors import InvalidFormatError, InvalidTimezoneError
 
 EonesLike = Union[str, datetime, Dict[str, int], Date]
 
@@ -29,7 +30,12 @@ def __init__(self, tz: str = "UTC", formats: Optional[List[str]] = None) -> None
             tz (str): Timezone string (e.g., 'UTC', 'America/New_York').
             formats (Optional[List[str]]): List of datetime string formats to try.
         """
-        self._zone = ZoneInfo(tz)
+        try:
+            self._zone = ZoneInfo(tz)
+
+        except ZoneInfoNotFoundError as exc:
+            raise InvalidTimezoneError(tz) from exc
+
         self._formats = formats if formats else ["%Y-%m-%d", "%d/%m/%Y"]
 
     def parse(
@@ -114,7 +120,9 @@ def _from_str(self, date_str: str) -> "Date":
             except ValueError:
                 continue
 
-        raise ValueError(f"Date string '{date_str}' does not match expected formats.")
+        raise InvalidFormatError(
+            f"Date string '{date_str}' does not match expected formats {self._formats}"
+        )
 
     def to_eones_date(self, value: EonesLike) -> Date:
         """

src/eones/core/range.py

@@ -7,6 +7,7 @@
 from typing import Tuple
 
 from eones.core.date import Date
+from eones.core.delta import Delta
 
 
 class Range:
@@ -112,8 +113,6 @@ def custom_range(
         Returns:
             Tuple[datetime, datetime]: Resulting start and end datetimes.
         """
-        from eones.core.delta import Delta  # local import to avoid circular
-
         if not isinstance(start_delta, Delta) or not isinstance(end_delta, Delta):
             raise TypeError("start_delta and end_delta must be Delta instances")
 

src/eones/errors.py

@@ -21,6 +21,14 @@ def __init__(self, message: str = "Invalid or unsupported date format") -> None:
         super().__init__(message)
 
 
+class InvalidTimezoneError(EonesError):
+    """Raised when an invalid timezone string is provided."""
+
+    def __init__(self, tz: str) -> None:
+        """Initialize InvalidTimezoneError with the problematic timezone."""
+        super().__init__(f"Invalid timezone: {tz}")
+
+
 class UnsupportedInputError(EonesError):
     """Raised when the input type is not supported by the parser."""
 

tests/test_parser.py

@@ -7,6 +7,7 @@
 from eones.constants import DEFAULT_FORMATS
 from eones.core.date import Date
 from eones.core.parser import Parser
+from eones.errors import InvalidFormatError, InvalidTimezoneError
 
 # ==== FIXTURE ====
 
@@ -16,6 +17,11 @@ def parser():
     return Parser(tz="UTC", formats=["%Y-%m-%d"])  # solo año-mes-día
 
 
+def test_invalid_timezone_raises():
+    with pytest.raises(InvalidTimezoneError):
+        Parser(tz="Mars/Phobos")
+
+
 # ==== VALID INPUTS ====
 
 
@@ -41,9 +47,11 @@ def test_parse_existing_date_returns_same_instance(parser):
 # ==== INVALID INPUTS ====
 
 
-@pytest.mark.parametrize("invalid_input", [12345, "15/06/2025"])
-def test_parse_invalid_inputs_raise(parser, invalid_input):
-    with pytest.raises(ValueError):
+@pytest.mark.parametrize(
+    "invalid_input, exc", [(12345, ValueError), ("15/06/2025", InvalidFormatError)]
+)
+def test_parse_invalid_inputs_raise(parser, invalid_input, exc):
+    with pytest.raises(exc):
         parser.parse(invalid_input)
 
 
@@ -107,7 +115,7 @@ def test_multiple_formats_fallback_success():
 def test_multiple_formats_fallback_failure():
     formats = ["%d/%m/%Y", "%Y-%m-%d"]
     p = Parser(tz="UTC", formats=formats)
-    with pytest.raises(ValueError):
+    with pytest.raises(InvalidFormatError):
         p.parse("15.06.2025")  # no matching format