errortools 3.0.0__cp314-cp314-win_amd64.whl

_errortools/__init__.py

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

_errortools/_cli.py

@@ -0,0 +1,33 @@
+import sys
+
+from _errortools.metadata import (
+    __author__,
+    __author_email__,
+    __copyright__,
+    __description__,
+    __license__,
+    __url__,
+)
+from _errortools.version import __version__
+
+
+def _cmd_log(message: str, level: str, output: str) -> None:
+    """Emit a single log message via the errortools logger."""
+    from .logging import BaseLogger
+    from .logging.level import get_level
+
+    stream = sys.stdout if output == "stdout" else sys.stderr
+    log = BaseLogger(name="errortools-cli")
+    log.set_level("TRACE")
+    log.add(stream, level=level, colorize=None)
+    log.log(get_level(level), message)
+
+
+def _print_info() -> None:
+    """Print a summary of all package metadata."""
+    print(f"errortools v{__version__}")
+    print(f"  {__description__}")
+    print(f"  Author:    {__author__} <{__author_email__}>")
+    print(f"  License:   {__license__}")
+    print(f"  URL:       {__url__}")
+    print(f"  Copyright: {__copyright__}")

_errortools/_speedup.c

@@ -0,0 +1,58 @@
+#define PY_SSIZE_T_CLEAN
+#include <Python.h>
+
+/* Fast exception type checking */
+static PyObject* fast_issubclass_check(PyObject* self, PyObject* args) {
+    PyObject *typ, *excs;
+    if (!PyArg_ParseTuple(args, "OO", &typ, &excs)) {
+        return NULL;
+    }
+
+    if (typ == Py_None) {
+        Py_RETURN_FALSE;
+    }
+
+    int result = PyObject_IsSubclass(typ, excs);
+    if (result == -1) {
+        return NULL;
+    }
+
+    return PyBool_FromLong(result);
+}
+
+/* Fast exception collector append */
+static PyObject* fast_append_exception(PyObject* self, PyObject* args) {
+    PyObject *list, *exc;
+    if (!PyArg_ParseTuple(args, "OO", &list, &exc)) {
+        return NULL;
+    }
+
+    if (PyList_Append(list, exc) == -1) {
+        return NULL;
+    }
+
+    Py_RETURN_NONE;
+}
+
+/* Method definitions */
+static PyMethodDef SpeedupMethods[] = {
+    {"fast_issubclass_check", fast_issubclass_check, METH_VARARGS,
+     "Fast exception type checking"},
+    {"fast_append_exception", fast_append_exception, METH_VARARGS,
+     "Fast exception list append"},
+    {NULL, NULL, 0, NULL}
+};
+
+/* Module definition */
+static struct PyModuleDef speedupmodule = {
+    PyModuleDef_HEAD_INIT,
+    "_speedup",
+    "C speedup for errortools",
+    -1,
+    SpeedupMethods
+};
+
+/* Module initialization */
+PyMODINIT_FUNC PyInit__speedup(void) {
+    return PyModule_Create(&speedupmodule);
+}

_errortools/classes/__init__.py

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

_errortools/classes/abc.py

@@ -0,0 +1,211 @@
+from typing import Any, Literal, Union
+from abc import ABC, abstractmethod
+import copy
+import shutil
+import csv
+import configparser
+import sys
+
+if sys.version_info >= (3, 15):
+    from typing import disjoint_base
+else:
+    from typing_extensions import disjoint_base
+
+
+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__  # Added type hints for mro var
+    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
+
+
+# ----------------------------------------------------------------------
+# ErrorCodeable
+# ----------------------------------------------------------------------
+
+
+@disjoint_base
+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
+
+
+# ----------------------------------------------------------------------
+# Error
+# ----------------------------------------------------------------------
+
+
+class Error(Exception, ABC):
+    """Abstract Base Class for module-level Error exceptions.
+
+    Any class named **"Error"** (like copy.Error, shutil.Error, csv.Error)
+    is automatically recognised as a virtual subclass of this ABC.
+
+    Virtual subclasses do NOT need to explicitly inherit from this class.
+
+    Example:
+
+        >>> import copy
+        >>> import shutil
+        >>> isinstance(copy.Error(), Error)
+        True
+        >>> isinstance(shutil.Error(), Error)
+        True
+        >>> class MyError:
+        ...     __name__ = "Error"
+        >>> isinstance(MyError(), Error)
+        True
+    """
+
+    __slots__ = ()
+
+    @classmethod
+    def __subclasshook__(cls, subclass: type[Any]) -> bool:
+        if cls is Error:
+            return subclass.__name__ == "Error"
+        return False
+
+
+Error.register(copy.Error)
+Error.register(shutil.Error)
+Error.register(csv.Error)
+Error.register(configparser.Error)

_errortools/classes/errorcodes.py

@@ -0,0 +1,273 @@
+import uuid
+import traceback
+from typing import Any, Optional
+
+__all__ = [
+    "PureBaseException",
+    "ContextException",
+    "BaseErrorCodes",
+    "InvalidInputError",
+    "AccessDeniedError",
+    "NotFoundError",
+    "RuntimeFailure",
+    "TimeoutFailure",
+    "ConfigurationError",
+]
+
+
+# ==============================================
+# 1. Pure Base Exception Class (core structure only, no additional capabilities)
+# ==============================================
+class PureBaseException(Exception):
+    """
+    Pure Base Exception Class
+    Inherits from Exception, providing error code, default prompt, basic initialization and string formatting
+    """
+
+    # Class attributes: default error code and prompt, which can be overridden by subclasses
+    code: int = -1
+    default_detail: str = "An error occurred."
+
+    def __init__(self, detail: str | None = None) -> None:
+        """
+        Pure Base Exception Initialization
+        Args:
+            detail: Custom error prompt, use default prompt (default_detail) when None
+        """
+        self.detail = detail if detail is not None else self.default_detail
+        super().__init__(self.detail)
+
+    def __str__(self) -> str:
+        """
+        Exception String Formatting
+        Returns:
+            Formatted string: [Error Code] Error Prompt
+        """
+        return f"[{self.code}] {self.detail}"
+
+    def __repr__(self) -> str:
+        """
+        Exception Repr Formatting (core attributes)
+        Returns:
+            Repr string including class name, detail, and code
+        """
+        return f"{type(self).__name__}(detail={self.detail!r}, code={self.code!r})"
+
+
+# ==============================================
+# 2. Context/Exception Chain Common Capability Class (core extension functions)
+# ==============================================
+class ContextException(PureBaseException):
+    """
+    Context/Exception Chain Capability Class (extension layer)
+    Inherits from pure base exception, providing trace ID, context management, exception chain, and simplified stack trace
+    """
+
+    def __init__(self, detail: str | None = None) -> None:
+        """
+        Context Exception Initialization
+        Args:
+            detail: Custom error prompt, use default prompt (default_detail) when None
+        """
+        super().__init__(detail)
+        # Extended attributes: trace ID (unique identifier for a single exception), context dictionary, root cause exception
+        self.trace_id: str = uuid.uuid4().hex
+        self.context: dict[str, Any] = {}
+        self.cause: Optional[Exception] = None
+
+    def __repr__(self) -> str:
+        """
+        Exception Repr Formatting (with trace_id)
+        Returns:
+            Repr string including class name, detail, code, and trace_id
+        """
+        return f"{type(self).__name__}(detail={self.detail!r}, code={self.code!r}, trace_id={self.trace_id!r})"
+
+    def with_context(self, **kwargs: Any) -> "ContextException":
+        """
+        Attach Context Data to Exception
+        Args:
+            **kwargs: Context key-value pairs (any type)
+        Returns:
+            Self instance (supports method chaining)
+        """
+        self.context.update(kwargs)
+        return self
+
+    def with_cause(self, cause: Exception) -> "ContextException":
+        """
+        Set Root Cause Exception
+        Args:
+            cause: Root cause exception (any subclass of Exception)
+        Returns:
+            Self instance (supports method chaining)
+        """
+        self.cause = cause
+        self.__cause__ = cause  # Retain native exception chain
+        return self
+
+    @property
+    def chain(self) -> list[dict[str, Any]]:
+        """
+        Exception Chain (current to root cause)
+        Returns:
+            List of dicts, each containing type, code, detail, trace_id, and context
+            for ContextException instances, or type and detail for plain exceptions.
+        """
+        result = []
+        exc: Optional[Exception] = self
+        while exc is not None:
+            if isinstance(exc, ContextException):
+                result.append(
+                    {
+                        "type": exc.__class__.__name__,
+                        "code": exc.code,
+                        "detail": exc.detail,
+                        "trace_id": exc.trace_id,
+                        "context": exc.context,
+                    }
+                )
+                exc = exc.cause
+            else:
+                result.append(
+                    {
+                        "type": exc.__class__.__name__,
+                        "detail": str(exc),
+                    }
+                )
+                exc = exc.__cause__  # type: ignore[assignment]
+        return result
+
+    @property
+    def traceback(self) -> str:
+        """
+        Simplified Stack Trace (limit 4 frames)
+        Returns:
+            Stack trace string with frames joined by |, or "no traceback" if unavailable
+        """
+        tb = self.__traceback__
+        if not tb:
+            return "no traceback"
+        lines = traceback.format_tb(tb, limit=4)
+        return " | ".join(line.strip() for line in lines if line.strip())
+
+
+# ==============================================
+# 3. Common Error Class (business convenience factory methods)
+# ==============================================
+class BaseErrorCodes(ContextException):
+    """
+    Common Error Class (business convenience layer)
+    Inherits from common capability class, providing factory methods for various predefined errors to simplify business exception throwing
+    """
+
+    @classmethod
+    def invalid_input(cls, detail: str | None = None) -> "InvalidInputError":
+        """
+        Input Validation Error (Error Code: 1001)
+        Args:
+            detail: Custom error prompt, use the default prompt of InvalidInputError if not provided
+        Returns:
+            InvalidInputError instance
+        """
+        return InvalidInputError(detail)
+
+    @classmethod
+    def not_found(cls, detail: str | None = None) -> "NotFoundError":
+        """
+        Resource Not Found Error (Error Code: 3001)
+        Args:
+            detail: Custom error prompt, use the default prompt of NotFoundError if not provided
+        Returns:
+            NotFoundError instance
+        """
+        return NotFoundError(detail)
+
+    @classmethod
+    def access_denied(cls, detail: str | None = None) -> "AccessDeniedError":
+        """
+        Access Denied Error (Error Code: 2001)
+        Args:
+            detail: Custom error prompt, use the default prompt of AccessDeniedError if not provided
+        Returns:
+            AccessDeniedError instance
+        """
+        return AccessDeniedError(detail)
+
+    @classmethod
+    def configuration_error(cls, detail: str | None = None) -> "ConfigurationError":
+        """
+        Configuration Error (Error Code: 5001)
+        Args:
+            detail: Custom error prompt, use the default prompt of ConfigurationError if not provided
+        Returns:
+            ConfigurationError instance
+        """
+        return ConfigurationError(detail)
+
+    @classmethod
+    def runtime_failure(cls, detail: str | None = None) -> "RuntimeFailure":
+        """
+        Runtime Failure (Error Code: 4001)
+        Args:
+            detail: Custom error prompt, use the default prompt of RuntimeFailure if not provided
+        Returns:
+            RuntimeFailure instance
+        """
+        return RuntimeFailure(detail)
+
+    @classmethod
+    def timeout_failure(cls, detail: str | None = None) -> "TimeoutFailure":
+        """
+        Timeout Failure (Error Code: 4002)
+        Args:
+            detail: Custom error prompt, use the default prompt of TimeoutFailure if not provided
+        Returns:
+            TimeoutFailure instance
+        """
+        return TimeoutFailure(detail)
+
+
+# ==============================================
+# Specific Business Error Subclasses (unified naming and format, corresponding to common error codes)
+# ==============================================
+class InvalidInputError(BaseErrorCodes):
+    """Input Validation Error (1001): Used for scenarios where parameter or input format validation fails"""
+
+    code = 1001
+    default_detail = "Invalid input."
+
+
+class NotFoundError(BaseErrorCodes):
+    """Resource Not Found Error (3001): Used for scenarios where the queried resource does not exist"""
+
+    code = 3001
+    default_detail = "Resource not found."
+
+
+class AccessDeniedError(BaseErrorCodes):
+    """Access Denied Error (2001): Used for scenarios where access to resources is not permitted"""
+
+    code = 2001
+    default_detail = "Access denied."
+
+
+class ConfigurationError(BaseErrorCodes):
+    """Configuration Error (5001): Used for scenarios where system or service configuration is abnormal"""
+
+    code = 5001
+    default_detail = "Configuration error."
+
+
+class RuntimeFailure(BaseErrorCodes):
+    """Runtime Failure (4001): Used for unknown exception scenarios during system operation"""
+
+    code = 4001
+    default_detail = "Runtime failure."
+
+
+class TimeoutFailure(BaseErrorCodes):
+    """Timeout Failure (4002): Used for request or operation timeout scenarios"""
+
+    code = 4002
+    default_detail = "Operation timed out."

_errortools/classes/group.py

@@ -0,0 +1,121 @@
+"""Base and concrete group classes for collecting and raising exceptions together."""
+
+from abc import abstractmethod, ABC
+import sys
+
+__all__ = [
+    "BaseGroup",
+    "GroupErrors",
+]
+
+
+class BaseGroup(Exception, ABC):
+    """Abstract base for exception collector groups.
+
+    Defines the interface that all group implementations must satisfy:
+    `collect`, `raise_group`, `clear`, and the
+    `errors` property.  Concrete subclasses decide the storage
+    strategy and the type of group they raise.
+
+    Attributes:
+        group_msg: The message attached to the raised group.
+    """
+
+    def __init__(self, group_msg: str = "multiple errors") -> None:
+        """Initialise the group with a message.
+
+        Args:
+            group_msg: Message for the raised group.
+                Defaults to ``"multiple errors"``.
+        """
+        self.group_msg = group_msg
+
+    @property
+    @abstractmethod
+    def errors(self) -> list[Exception]:
+        """A copy of the collected exceptions."""
+
+    @abstractmethod
+    def collect(self, exc: Exception) -> None:
+        """Add *exc* to the group without raising it.
+
+        Args:
+            exc: The exception instance to collect.
+        """
+
+    @abstractmethod
+    def clear(self) -> None:
+        """Remove all collected exceptions."""
+
+    @abstractmethod
+    def raise_group(self) -> None:
+        """Raise all collected exceptions as a group.
+
+        Does nothing if no exceptions have been collected.
+        """
+
+    def __len__(self) -> int:
+        """Return the number of collected exceptions."""
+        return len(self.errors)
+
+    def __bool__(self) -> bool:
+        """Return ``True`` if any exceptions have been collected."""
+        return bool(self.errors)
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}(group_msg={self.group_msg!r}, errors={len(self)})"
+        )
+
+
+if sys.version_info >= (3, 11):
+
+    class GroupErrors(BaseGroup):
+        """A collector that accumulates exceptions and raises them as an ExceptionGroup.
+
+        Call `collect` to add exceptions one by one, then `raise_group`
+        to raise them all at once.  Use `errors` to inspect what has been
+        collected without raising.
+
+        Example:
+
+            >>> g = GroupErrors("validation failed")
+            >>> g.collect(TypeError("expected str"))
+            >>> g.collect(ValueError("value out of range"))
+            >>> g.raise_group()
+            Traceback (most recent call last):
+                ...
+            ExceptionGroup: validation failed (2 sub-exceptions)
+        """
+
+        def __init__(self, group_msg: str = "multiple errors") -> None:
+            super().__init__(group_msg)
+            self._errors: list[Exception] = []
+
+        @property
+        def errors(self) -> list[Exception]:
+            """A copy of the collected exceptions."""
+            return list(self._errors)
+
+        def collect(self, exc: Exception) -> None:
+            """Add *exc* to the group without raising it.
+
+            Args:
+                exc: The exception instance to collect.
+            """
+            self._errors.append(exc)
+
+        def clear(self) -> None:
+            """Remove all collected exceptions."""
+            self._errors.clear()
+
+        def raise_group(self) -> None:
+            """Raise all collected exceptions as an `ExceptionGroup`.
+
+            Does nothing if no exceptions have been collected.
+
+            Raises:
+                ExceptionGroup: Containing every exception added via `collect`.
+            """
+            if self._errors:
+                raise ExceptionGroup(self.group_msg, self._errors)