errortools 1.0.0__py3-none-any.whl

_errortools/__init__.py

@@ -0,0 +1 @@
+# Nothing here!

_errortools/_metadata.py

@@ -0,0 +1,9 @@
+__author__: str = "Evan Yang"
+__author_email__: str = "quantbit@126.com"
+__copyright__: str = "Copyright 2026 (C) aiwonderland Evan Yang"
+__description__: str = (
+    "errortools - a toolset for working with Python exceptions and warnings"
+)
+__license__: str = "MIT"
+__title__: str = "errortools"
+__url__: str = "https://github.com/more-abc/errortools"

_errortools/_types.py

@@ -0,0 +1,21 @@
+import sys
+import types
+
+# Acquire the internal interpreter types for traceback objects and frame objects.
+
+# This module uses a raised exception to safely obtain the runtime types
+# of traceback and frame objects, for compatibility with older Python versions
+# where these types are not easily importable from the types module.
+if sys.version_info >= (3, 7):
+    # No docstrings are provided for standard library versions.
+    TracebackType = types.TracebackType
+    FrameType = types.FrameType
+else:
+    try:
+        raise TypeError
+    except TypeError as exc:
+        TracebackType = type(exc.__traceback__)
+        """The type of traceback objects returned by exception.__traceback__."""
+
+        FrameType = type(exc.__traceback__.tb_frame)  # type: ignore
+        """The type of frame objects representing an execution frame in the call stack."""

_errortools/_version.py

@@ -0,0 +1,7 @@
+__version__: str = "1.0.0"
+__version_tuple__: tuple[int, int, int] = (1, 0, 0)
+__commit_id__: str | None = None
+
+version = __version__
+version_tuple = __version_tuple__
+commit_id = __commit_id__

_errortools/abc.py

@@ -0,0 +1,333 @@
+from typing import Any, Literal, Union
+from abc import ABC, abstractmethod
+
+from .tools.error_msg import (
+    ErrorAttrableRaiseNotImplementedErrorMessage as ErrorAttrNotImplementedMsg,
+)
+from .methods import (
+    ErrorAttrMixin,
+    ErrorAttrCheckMixin,
+    ErrorAttrDeletionMixin,
+    ErrorSetAttrMixin,
+)
+from .classes.errorcodes import (
+    BaseErrorCodes,
+    NotFoundError,
+    AccessDeniedError,
+    InvalidInputError,
+    ConfigurationError,
+    RuntimeFailure,
+    TimeoutFailure,
+)
+from .classes.warn import (
+    BaseWarning,
+    DeprecatedWarning,
+    PerformanceWarning,
+    ConfigurationWarning,
+    ResourceUsageWarning,
+    RuntimeBehaviourWarning,
+)
+
+
+def _check_methods(C: type[Any], *methods: str) -> Union[bool, Literal[NotImplemented]]:  # type: ignore
+    """Check methods in `C`. If has, return `True`, else `NotImplemented`.
+    from `_collections_abc.py`.
+    Copyright 2007 Google, Inc. All Rights Reserved.
+    Licensed to PSF under a Contributor Agreement.
+    """
+    mro: tuple[type[Any], ...] = C.__mro__
+    for method in methods:
+        for B in mro:
+            if method in B.__dict__:
+                if B.__dict__[method] is None:
+                    return NotImplemented
+                break
+        else:
+            return NotImplemented
+    return True
+
+
+class ErrorAttrable(ABC):
+    """
+    Abstract Base Class (ABC) for classes supporting custom attribute error handling.
+
+    This class follows the design pattern of `collections.abc` (e.g., Iterable, Mapping):
+    - Uses `__subclasshook__` + `_check_methods` to validate subclass compliance
+    - Enforces implementation of attribute error handling methods via abstract methods
+    - Implements native attribute magic methods to forward errors to custom handlers
+
+    Core behavior:
+        When attribute operations (get/delete/check/set) fail, the corresponding native
+        magic methods automatically invoke custom error handling methods implemented by subclasses.
+    """
+
+    __slots__ = ()
+
+    @classmethod
+    def __subclasshook__(cls, C: type[Any]) -> Union[bool, Literal[NotImplemented]]:  # type: ignore
+        """
+        Check if a class is a subclass of ErrorAttrable (per `collections.abc` style).
+
+        This method enables `issubclass()` to recognize classes that implement the core
+        __errorattr__ method (base requirement), matching the behavior of standard ABCs.
+
+        Args:
+            C: The class to check for compliance with ErrorAttrable interface
+
+        Returns:
+            True if C implements __errorattr__, NotImplemented otherwise
+        """
+        if cls is ErrorAttrable:
+            return _check_methods(C, "__errorattr__")
+        return NotImplemented
+
+    def __getattr__(self, name: str) -> Any:
+        """
+        Native magic method: Automatically invoked for missing attribute access.
+
+        Forwards the attribute lookup failure to the custom `__errorattr__` method.
+        """
+        return self.__errorattr__(name)
+
+    @abstractmethod
+    def __errorattr__(self, name: str) -> Any:
+        """
+        Abstract method for custom missing attribute handling (MUST be implemented).
+
+        Args:
+            name: Name of the missing attribute being accessed
+
+        Raises:
+            NotImplementedError: If not overridden
+            AttributeError: Recommended error type for missing attributes
+        """
+        raise NotImplementedError(ErrorAttrNotImplementedMsg)
+
+    def __delattr__(self, name: str) -> None:
+        """
+        Native magic method: Automatically invoked for attribute deletion errors.
+
+        Forwards to __errordelattr__ if implemented, else raises standard error.
+        """
+        if hasattr(self, "__errordelattr__"):
+            self.__errordelattr__(name)
+        else:
+            super().__delattr__(name)
+
+    def __errordelattr__(self, name: str) -> None:
+        """
+        Custom handler for attribute deletion errors (OPTIONAL to implement).
+
+        Args:
+            name: Name of the attribute being deleted
+        """
+        raise NotImplementedError(ErrorAttrNotImplementedMsg)
+
+    def __contains__(self, name: str) -> bool:
+        """
+        Alternative to __hasattr__: Check if attribute exists (customizable).
+
+        Forwards to __errorhasattr__ if implemented, else uses standard check.
+        """
+        if hasattr(self, "__errorhasattr__"):
+            return self.__errorhasattr__(name)
+        else:
+            return hasattr(super(), name)
+
+    def __errorhasattr__(self, name: str) -> bool:
+        """
+        Custom handler for attribute existence checks (OPTIONAL to implement).
+
+        Args:
+            name: Name of the attribute to check
+
+        Returns:
+            bool: True if attribute exists (custom logic), False otherwise
+        """
+        raise NotImplementedError(ErrorAttrNotImplementedMsg)
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        """
+        Native magic method: Automatically invoked for attribute setting errors.
+
+        Forwards to __errorsetattr__ if implemented, else uses standard setting.
+        """
+        if hasattr(self, "__errorsetattr__"):
+            self.__errorsetattr__(name, value)
+        else:
+            super().__setattr__(name, value)
+
+    def __errorsetattr__(self, name: str, value: Any) -> None:
+        """
+        Custom handler for attribute setting errors (OPTIONAL to implement).
+
+        Args:
+            name: Name of the attribute to set
+            value: Value to assign to the attribute
+        """
+        raise NotImplementedError(ErrorAttrNotImplementedMsg)
+
+
+# register four Mixin's
+ErrorAttrable.register(ErrorAttrMixin)
+ErrorAttrable.register(ErrorAttrDeletionMixin)
+ErrorAttrable.register(ErrorAttrCheckMixin)
+ErrorAttrable.register(ErrorSetAttrMixin)
+
+
+# ----------------------------------------------------------------------
+# ErrorCodeable
+# ----------------------------------------------------------------------
+
+
+class ErrorCodeable(ABC):
+    """Abstract Base Class for exceptions that carry a machine-readable error code.
+
+    Follows the ``collections.abc`` pattern: any class that exposes both a
+    ``code`` class attribute (``int``) and a ``default_detail`` class attribute
+    (``str``) is recognised as a virtual subclass automatically, without
+    explicit inheritance.
+
+    Concrete subclasses **must** implement:
+        - ``code``         — integer error code (class variable)
+        - ``default_detail`` — fallback human-readable message (class variable)
+
+    Example:
+
+        >>> class PaymentError(ErrorCodeable, Exception):
+        ...     code = 6001
+        ...     default_detail = "Payment failed."
+        >>> issubclass(PaymentError, ErrorCodeable)
+        True
+    """
+
+    __slots__ = ()
+
+    @classmethod
+    def __subclasshook__(cls, C: type[Any]) -> Union[bool, Literal[NotImplemented]]:  # type: ignore
+        """Recognise any class that defines ``code`` and ``default_detail``."""
+        if cls is ErrorCodeable:
+            return _check_methods(C, "code", "default_detail")
+        return NotImplemented
+
+    @property
+    @abstractmethod
+    def code(self) -> int:
+        """Integer error code identifying this exception type."""
+        pass
+
+    @property
+    @abstractmethod
+    def default_detail(self) -> str:
+        """Fallback human-readable message used when no detail is provided."""
+        pass
+
+
+# ----------------------------------------------------------------------
+# Warnable
+# ----------------------------------------------------------------------
+
+
+class Warnable(ABC):
+    """Abstract Base Class for warning classes that can emit themselves.
+
+    Any class that exposes an ``emit`` classmethod is recognised as a
+    virtual subclass automatically via ``__subclasshook__``.
+
+    Concrete subclasses **must** implement:
+        - ``emit(cls, detail, stacklevel)`` — issue the warning via ``warnings.warn``
+
+    Example:
+
+        >>> class SlowWarning(Warnable, Warning):
+        ...     default_detail = "This operation is slow."
+        ...     @classmethod
+        ...     def emit(cls, detail=None, stacklevel=2):
+        ...         import warnings
+        ...         warnings.warn(cls(detail), stacklevel=stacklevel)
+        >>> issubclass(SlowWarning, Warnable)
+        True
+    """
+
+    __slots__ = ()
+
+    @classmethod
+    def __subclasshook__(cls, C: type[Any]) -> Union[bool, Literal[NotImplemented]]:  # type: ignore
+        """Recognise any class that defines an ``emit`` classmethod."""
+        if cls is Warnable:
+            return _check_methods(C, "emit")
+        return NotImplemented
+
+    @classmethod
+    @abstractmethod
+    def emit(cls, detail: str | None = None, stacklevel: int = 2) -> None:
+        """Issue this warning via ``warnings.warn``.
+
+        Args:
+            detail: Optional message override.
+            stacklevel: Passed to ``warnings.warn``; ``2`` points at the
+                caller of ``emit``.
+        """
+        pass
+
+
+# ----------------------------------------------------------------------
+# Raiseable
+# ----------------------------------------------------------------------
+
+
+class Raiseable(ABC):
+    """Abstract Base Class for objects that know how to raise themselves.
+
+    Concrete subclasses **must** implement ``raise_it()``, which should
+    raise ``self`` (or a derived exception).  Any class that exposes a
+    ``raise_it`` method is recognised as a virtual subclass automatically.
+
+    Example:
+
+        >>> class MyError(Raiseable, Exception):
+        ...     def raise_it(self):
+        ...         raise self
+        >>> e = MyError("oops")
+        >>> e.raise_it()
+        Traceback (most recent call last):
+            ...
+        MyError: oops
+    """
+
+    __slots__ = ()
+
+    @classmethod
+    def __subclasshook__(cls, C: type[Any]) -> Union[bool, Literal[NotImplemented]]:  # type: ignore
+        """Recognise any class that defines a ``raise_it`` method."""
+        if cls is Raiseable:
+            return _check_methods(C, "raise_it")
+        return NotImplemented
+
+    @abstractmethod
+    def raise_it(self) -> None:
+        """Raise this object as an exception.
+
+        Raises:
+            self: Or a derived exception wrapping this object.
+        """
+        pass
+
+
+# ----------------------------------------------------------------------
+# Register existing concrete classes as virtual subclasses
+# ----------------------------------------------------------------------
+
+ErrorCodeable.register(BaseErrorCodes)
+ErrorCodeable.register(NotFoundError)
+ErrorCodeable.register(AccessDeniedError)
+ErrorCodeable.register(InvalidInputError)
+ErrorCodeable.register(ConfigurationError)
+ErrorCodeable.register(RuntimeFailure)
+ErrorCodeable.register(TimeoutFailure)
+Warnable.register(BaseWarning)
+Warnable.register(DeprecatedWarning)
+Warnable.register(PerformanceWarning)
+Warnable.register(ConfigurationWarning)
+Warnable.register(ResourceUsageWarning)
+Warnable.register(RuntimeBehaviourWarning)

_errortools/cached/__init__.py

@@ -0,0 +1 @@
+"""Cache tools in `errortools`."""

_errortools/cached/cache.py

@@ -0,0 +1,82 @@
+"""A helper tool for caching exceptions raised by functions, like lru_cache."""
+
+import functools
+from typing import (
+    Callable,
+    Any,
+    Optional,
+    TypeVar,
+    overload,
+)
+
+from _errortools.cached.wrapper import ErrorCacheWrapper
+
+_T = TypeVar("_T", bound=Callable[..., Any])
+
+# fmt: off
+
+
+@overload
+def error_cache(func: _T) -> ErrorCacheWrapper[_T]:
+    ...
+
+
+@overload
+def error_cache(maxsize: Optional[int] = 128) -> Callable[[_T], ErrorCacheWrapper[_T]]:
+    ...
+# fmt: on
+
+
+def error_cache(  # type: ignore
+    func: Optional[_T] = None, maxsize: Optional[int] = 128
+) -> Any:
+    """
+    Decorator to cache exceptions raised by a function (like functools.lru_cache).
+
+    This decorator automatically caches exceptions thrown by the wrapped function,
+    keyed by the function's arguments. If the function succeeds, the cached exception
+    (if any) for those arguments is removed.
+
+    Key features (aligned with lru_cache):
+    - maxsize: Maximum number of cached errors (None = unlimited, default=128)
+    - LRU eviction: Evicts least recently used entries when maxsize is reached
+    - cache_info(): Returns hits/misses/maxsize/currsize stats
+    - clear_cache(): Clears cache and resets statistics
+
+    Usage (same as lru_cache):
+
+        @error_cache  # Default maxsize=128
+        def risky_func(x: int) -> int: ...
+
+        @error_cache(maxsize=32)  # Custom maxsize
+        def risky_func(x: int) -> int: ...
+
+        @error_cache(maxsize=None)  # Unlimited cache
+        def risky_func(x: int) -> int: ...
+
+        @error_cache()  # Explicit empty args (maxsize=128)
+        def risky_func(x: int) -> int: ...
+
+    Args:
+        func: The function to wrap (auto-passed when using @error_cache without args).
+        maxsize: Maximum number of cached errors (None = unlimited, default=128).
+
+    Returns:
+        Wrapped function with error caching functionality.
+
+    Raises:
+        TypeError: If non-hashable arguments are passed (same as lru_cache).
+    """
+
+    def decorator(f: _T) -> ErrorCacheWrapper[_T]:
+        if not callable(f):
+            raise TypeError(f"Expected a callable, got {type(f).__name__} instead")
+
+        wrapper = ErrorCacheWrapper(f, maxsize=maxsize)
+        functools.update_wrapper(wrapper, f)
+        return wrapper
+
+    # Handle both @error_cache and @error_cache(...) usage
+    if func is None:
+        return decorator
+    return decorator(func)

_errortools/cached/wrapper.py

@@ -0,0 +1,76 @@
+from collections import OrderedDict
+from collections.abc import Hashable, Callable
+from typing import Any, Generic, TypeVar, Optional, TypeAlias
+
+_T = TypeVar("_T", bound=Callable[..., Any])
+_Key: TypeAlias = tuple[
+    str, tuple[Hashable, ...], tuple[tuple[Hashable, Hashable], ...]
+]
+
+
+class ErrorCacheWrapper(Generic[_T]):
+    """Wrapper class for error-cached functions (mimics lru_cache's wrapper style)."""
+
+    def __init__(self, func: _T, maxsize: Optional[int] = 128) -> None:
+        self.__wrapped__ = func  # Required for inspect module compatibility
+        self._func_name = func.__name__
+
+        # LRU cache with maxsize support (OrderedDict preserves access order)
+        self._maxsize = maxsize if (maxsize is None or maxsize > 0) else None
+        self._cache: OrderedDict[_Key, Exception] = OrderedDict()
+
+        # Cache statistics (1:1 with lru_cache)
+        self._hits = 0
+        self._misses = 0
+
+    def __call__(self, *args: Hashable, **kwargs: Hashable) -> Any:
+        """Execute the wrapped function and cache exceptions if raised (with LRU)."""
+        cache_key = self._make_key(args, kwargs)
+
+        try:
+            result = self.__wrapped__(*args, **kwargs)
+        except Exception as exc:
+            # Cache exception and enforce LRU eviction
+            self._cache[cache_key] = exc
+            self._misses += 1
+
+            # Evict least recently used if maxsize is exceeded
+            if self._maxsize is not None and len(self._cache) > self._maxsize:
+                self._cache.popitem(last=False)  # FIFO = LRU for insert order
+            raise
+        else:
+            # Auto-clear cache for successful calls
+            self._cache.pop(cache_key, None)
+            return result
+
+    def _make_key(
+        self, args: tuple[Hashable, ...], kwargs: dict[str, Hashable]
+    ) -> _Key:
+        """Generate a unique hashable key (consistent with lru_cache's logic)."""
+        sorted_kwargs = tuple(sorted(kwargs.items()))
+        return (self._func_name, args, sorted_kwargs)
+
+    # ---------------------- Cache control methods (like lru_cache) ----------------------
+    def get_cached_error(
+        self, *args: Hashable, **kwargs: Hashable
+    ) -> Optional[Exception]:
+        """Get the cached exception for the given arguments (if exists)."""
+        cache_key = self._make_key(args, kwargs)
+        if cache_key in self._cache:
+            self._hits += 1
+            self._cache.move_to_end(cache_key)  # Update LRU order (most recent)
+            return self._cache[cache_key]
+        return None
+
+    def clear_cache(self) -> None:
+        """Clear all cached exceptions and reset statistics (mimics lru_cache.clear)."""
+        self._cache.clear()
+        self._hits = 0
+        self._misses = 0
+
+    def cache_info(self) -> str:
+        """Return cache statistics (1:1 with lru_cache.cache_info)."""
+        return (
+            f"ErrorCacheInfo(hits={self._hits}, misses={self._misses}, "
+            f"maxsize={self._maxsize}, currsize={len(self._cache)})"
+        )

_errortools/classes/__init__.py

@@ -0,0 +1 @@
+"""Base classes."""

_errortools/classes/errorcodes.py

@@ -0,0 +1,148 @@
+"""Base exception classes with general-purpose error code support."""
+
+from .base.base import ErrorToolsBaseException
+
+__all__ = [
+    "BaseErrorCodes",
+    "InvalidInputError",
+    "NotFoundError",
+    "AccessDeniedError",
+    "ConfigurationError",
+    "RuntimeFailure",
+    "TimeoutFailure",
+]
+
+
+class BaseErrorCodes(ErrorToolsBaseException):
+    """A base exception with class-level error code and default detail.
+
+    Subclass and override `code` and `default_detail` to define
+    domain-specific exceptions with stable, machine-readable codes.  The
+    ``detail`` passed at raise-time overrides the class default.
+
+    Error code ranges (by convention):
+
+    - ``1xxx`` — input / validation
+    - ``2xxx`` — access / permission
+    - ``3xxx`` — resource lookup
+    - ``4xxx`` — runtime / execution
+    - ``5xxx`` — configuration / setup
+    - ``-1``   — unspecified
+
+    Attributes:
+        code: Integer error code for this exception class.  Defaults to ``-1``.
+        default_detail: Fallback message used when no *detail* is supplied.
+
+    Example:
+        >>> class PaymentError(BaseErrorCodes):
+        ...     code = 6001
+        ...     default_detail = "Payment processing failed."
+        >>> raise PaymentError()
+        Traceback (most recent call last):
+            ...
+        PaymentError: [6001] Payment processing failed.
+        >>> raise PaymentError("card declined")
+        Traceback (most recent call last):
+            ...
+        PaymentError: [6001] card declined
+    """
+
+    code: int = -1
+    default_detail: str = "An error occurred."
+
+    def __init__(self, detail: str | None = None) -> None:
+        """Initialise the exception with an optional detail message.
+
+        Args:
+            detail: Human-readable description of the error.  Falls back to
+                `default_detail` when ``None``.
+        """
+        self.detail = detail if detail is not None else self.default_detail
+        super().__init__(self.detail)
+
+    def __str__(self) -> str:
+        return f"[{self.code}] {self.detail}"
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(detail={self.detail!r}, code={self.code!r})"
+
+    # ------------------------------------------------------------------
+    # Factory classmethods
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def invalid_input(cls, detail: str | None = None) -> InvalidInputError:
+        """Return an `InvalidInputError` (1001) instance."""
+        return InvalidInputError(detail)
+
+    @classmethod
+    def not_found(cls, detail: str | None = None) -> NotFoundError:
+        """Return a `NotFoundError` (3001) instance."""
+        return NotFoundError(detail)
+
+    @classmethod
+    def access_denied(cls, detail: str | None = None) -> AccessDeniedError:
+        """Return an `AccessDeniedError` (2001) instance."""
+        return AccessDeniedError(detail)
+
+    @classmethod
+    def configuration_error(cls, detail: str | None = None) -> ConfigurationError:
+        """Return a `ConfigurationError` (5001) instance."""
+        return ConfigurationError(detail)
+
+    @classmethod
+    def runtime_failure(cls, detail: str | None = None) -> RuntimeFailure:
+        """Return a `RuntimeFailure` (4001) instance."""
+        return RuntimeFailure(detail)
+
+    @classmethod
+    def timeout_failure(cls, detail: str | None = None) -> TimeoutFailure:
+        """Return a `TimeoutFailure` (4002) instance."""
+        return TimeoutFailure(detail)
+
+
+# ----------------------------------------------------------------------
+# Predefined subclasses — general application categories
+# ----------------------------------------------------------------------
+
+
+class InvalidInputError(BaseErrorCodes):
+    """1001 — Input failed validation or is of the wrong type/format."""
+
+    code = 1001
+    default_detail = "Invalid input."
+
+
+class AccessDeniedError(BaseErrorCodes):
+    """2001 — The caller lacks permission to perform the requested action."""
+
+    code = 2001
+    default_detail = "Access denied."
+
+
+class NotFoundError(BaseErrorCodes):
+    """3001 — The requested resource or item could not be located."""
+
+    code = 3001
+    default_detail = "Resource not found."
+
+
+class RuntimeFailure(BaseErrorCodes):
+    """4001 — An unexpected failure occurred during execution."""
+
+    code = 4001
+    default_detail = "Runtime failure."
+
+
+class TimeoutFailure(BaseErrorCodes):
+    """4002 — An operation exceeded its allowed time limit."""
+
+    code = 4002
+    default_detail = "Operation timed out."
+
+
+class ConfigurationError(BaseErrorCodes):
+    """5001 — The application is misconfigured or missing required settings."""
+
+    code = 5001
+    default_detail = "Configuration error."