errortools 2.2.0__tar.gz → 2.4.0__tar.gz

{errortools-2.2.0/errortools.egg-info → errortools-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: errortools
-Version: 2.2.0
+Version: 2.4.0
 Summary: errortools - a toolset for working with Python exceptions and warnings and logging.
 Home-page: https://github.com/more-abc/errortools
 Author: Evan Yang
@@ -20,6 +20,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE.txt
 License-File: AUTHORS.txt
 Requires-Dist: namebyauthor==1.0.0
+Requires-Dist: typing_extensions>=4.8.0
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
@@ -38,6 +39,7 @@ A lightweight Python exception handling utility library.
 ## Features
 - **Raise Exceptions**: `raises()`, `raises_all()`, `reraise()` — batch raising and exception conversion
 - **Catch & Suppress**: `ignore()`, `ignore_subclass()`, `ignore_warns()`, `fast_ignore()`, `super_fast_ignore()`, `timeout()`, `retry()` — graceful suppression of exceptions and warnings, with automatic retry
+- **Future Utilities**: `super_fast_catch()`, `super_fast_reraise()`, `ExceptionCollector` — lightweight exception handling for high-performance scenarios
 - **Exception Caching**: `error_cache` — cache exceptions raised by functions (similar to `lru_cache`)
 - **Custom Exceptions**: `PureBaseException`, `ContextException`, `BaseErrorCodes`, `BaseWarning` — structured exception classes with error codes, trace IDs, and context
 - **Attribute Error Mixin**: Customize error behavior for attribute access, assignment, and deletion
@@ -61,7 +63,7 @@ from errortools import (
     error_cache,
     PureBaseException, ContextException, BaseErrorCodes, BaseWarning,
 )
-from errortools.future import super_fast_ignore
+from errortools.future import super_fast_ignore, super_fast_catch, super_fast_reraise, ExceptionCollector
 
 # ── 1. ignore ── context manager with full metadata ──────────────────────────
 with ignore(KeyError) as err:
@@ -153,7 +155,27 @@ raises_all(
 exc = assert_raises(int, [ValueError], "not-a-number")
 print(exc)   # invalid literal for int() with base 10: 'not-a-number'
 
-# ── 10. error_cache ── cache exceptions by call arguments ─────────────────────
+# ── 10. super_fast_catch ── lightweight exception capture ──────────────────────
+with super_fast_catch(ValueError) as ctx:
+    raise ValueError("oops")
+    
+assert ctx.exception is not None
+print(ctx.exception)  # ValueError('oops')
+
+# ── 11. super_fast_reraise ── lightweight exception type conversion ────────────
+with super_fast_reraise(KeyError, ValueError):
+    raise KeyError("missing")           # → ValueError: 'missing'
+
+# ── 12. ExceptionCollector ── batch collect exceptions ───────────────────────────
+collector = ExceptionCollector()
+collector.catch(int, "bad1")
+collector.catch(int, "bad2")
+
+if collector.has_errors:
+    print(f"Collected {collector.count} errors")
+    collector.raise_all("batch operation failed")  # → ExceptionGroup (2 sub-exceptions)
+
+# ── 13. error_cache ── cache exceptions by call arguments ─────────────────────
 @error_cache(maxsize=64)
 def load(user_id: int) -> dict:
     if user_id < 0:
@@ -166,7 +188,7 @@ with ignore(ValueError):
 print(load.cache_info())  # CacheInfo(hits=0, misses=1, maxsize=64, currsize=1)
 load.clear_cache()
 
-# ── 11. Custom exceptions — three layers ──────────────────────────────────────
+# ── 14. Custom exceptions — three layers ──────────────────────────────────────
 
 # Layer 1: PureBaseException — code + detail only
 class AppError(PureBaseException):
@@ -202,7 +224,7 @@ raise BaseErrorCodes.runtime_failure("crash")             # RuntimeFailure     [
 raise BaseErrorCodes.timeout_failure()                    # TimeoutFailure     [4002]
 raise BaseErrorCodes.configuration_error("missing key")   # ConfigurationError [5001]
 
-# ── 12. BaseWarning ── structured warnings with factory methods ───────────────
+# ── 15. BaseWarning ── structured warnings with factory methods ───────────────
 class ExperimentalWarning(BaseWarning):
     default_detail = "This feature is experimental."
 

{errortools-2.2.0 → errortools-2.4.0}/README.md

@@ -4,6 +4,7 @@ A lightweight Python exception handling utility library.
 ## Features
 - **Raise Exceptions**: `raises()`, `raises_all()`, `reraise()` — batch raising and exception conversion
 - **Catch & Suppress**: `ignore()`, `ignore_subclass()`, `ignore_warns()`, `fast_ignore()`, `super_fast_ignore()`, `timeout()`, `retry()` — graceful suppression of exceptions and warnings, with automatic retry
+- **Future Utilities**: `super_fast_catch()`, `super_fast_reraise()`, `ExceptionCollector` — lightweight exception handling for high-performance scenarios
 - **Exception Caching**: `error_cache` — cache exceptions raised by functions (similar to `lru_cache`)
 - **Custom Exceptions**: `PureBaseException`, `ContextException`, `BaseErrorCodes`, `BaseWarning` — structured exception classes with error codes, trace IDs, and context
 - **Attribute Error Mixin**: Customize error behavior for attribute access, assignment, and deletion
@@ -27,7 +28,7 @@ from errortools import (
     error_cache,
     PureBaseException, ContextException, BaseErrorCodes, BaseWarning,
 )
-from errortools.future import super_fast_ignore
+from errortools.future import super_fast_ignore, super_fast_catch, super_fast_reraise, ExceptionCollector
 
 # ── 1. ignore ── context manager with full metadata ──────────────────────────
 with ignore(KeyError) as err:
@@ -119,7 +120,27 @@ raises_all(
 exc = assert_raises(int, [ValueError], "not-a-number")
 print(exc)   # invalid literal for int() with base 10: 'not-a-number'
 
-# ── 10. error_cache ── cache exceptions by call arguments ─────────────────────
+# ── 10. super_fast_catch ── lightweight exception capture ──────────────────────
+with super_fast_catch(ValueError) as ctx:
+    raise ValueError("oops")
+    
+assert ctx.exception is not None
+print(ctx.exception)  # ValueError('oops')
+
+# ── 11. super_fast_reraise ── lightweight exception type conversion ────────────
+with super_fast_reraise(KeyError, ValueError):
+    raise KeyError("missing")           # → ValueError: 'missing'
+
+# ── 12. ExceptionCollector ── batch collect exceptions ───────────────────────────
+collector = ExceptionCollector()
+collector.catch(int, "bad1")
+collector.catch(int, "bad2")
+
+if collector.has_errors:
+    print(f"Collected {collector.count} errors")
+    collector.raise_all("batch operation failed")  # → ExceptionGroup (2 sub-exceptions)
+
+# ── 13. error_cache ── cache exceptions by call arguments ─────────────────────
 @error_cache(maxsize=64)
 def load(user_id: int) -> dict:
     if user_id < 0:
@@ -132,7 +153,7 @@ with ignore(ValueError):
 print(load.cache_info())  # CacheInfo(hits=0, misses=1, maxsize=64, currsize=1)
 load.clear_cache()
 
-# ── 11. Custom exceptions — three layers ──────────────────────────────────────
+# ── 14. Custom exceptions — three layers ──────────────────────────────────────
 
 # Layer 1: PureBaseException — code + detail only
 class AppError(PureBaseException):
@@ -168,7 +189,7 @@ raise BaseErrorCodes.runtime_failure("crash")             # RuntimeFailure     [
 raise BaseErrorCodes.timeout_failure()                    # TimeoutFailure     [4002]
 raise BaseErrorCodes.configuration_error("missing key")   # ConfigurationError [5001]
 
-# ── 12. BaseWarning ── structured warnings with factory methods ───────────────
+# ── 15. BaseWarning ── structured warnings with factory methods ───────────────
 class ExperimentalWarning(BaseWarning):
     default_detail = "This feature is experimental."
 

{errortools-2.2.0 → errortools-2.4.0}/_errortools/_cli.py

@@ -1,32 +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.add(stream, level="TRACE", 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__}")
+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-2.2.0 → errortools-2.4.0}/_errortools/classes/abc.py

@@ -5,6 +5,7 @@ import shutil
 import csv
 import configparser
 
+from typing_extensions import disjoint_base  # I use 3.14.3
 from ..methods import (
     ErrorAttrMixin,
     ErrorAttrCheckMixin,
@@ -30,6 +31,7 @@ def _check_methods(C: type[Any], *methods: str) -> Union[bool, Literal[NotImplem
     return True
 
 
+@disjoint_base
 class ErrorAttrable(ABC):
     """
     Abstract Base Class (ABC) for classes supporting custom attribute error handling.
@@ -175,6 +177,7 @@ ErrorAttrable.register(ErrorSetAttrMixin)
 # ----------------------------------------------------------------------
 
 
+@disjoint_base
 class ErrorCodeable(ABC):
     """Abstract Base Class for exceptions that carry a machine-readable error code.
 

{errortools-2.2.0 → errortools-2.4.0}/_errortools/cli.py

@@ -14,107 +14,95 @@ from .metadata import (
     __url__,
 )
 from .version import __version__
-from tests.run_tests import run_tests
 
 
 def parse_args(args: list[str] | None = None) -> argparse.Namespace:
     """Parse command line arguments."""
+    is_logger = "logger" in sys.argv[0]
+
+    if is_logger:
+        parser = argparse.ArgumentParser(
+            prog="logger",
+            description="Logger CLI - Emit log messages from command line",
+        )
+        parser.add_argument("message", help="Log message")
+        parser.add_argument(
+            "--level",
+            "-l",
+            default="info",
+            choices=[
+                "trace",
+                "debug",
+                "info",
+                "success",
+                "warning",
+                "error",
+                "critical",
+            ],
+        )
+        parser.add_argument(
+            "--output", "-o", choices=["stderr", "stdout"], default="stderr"
+        )
+        return parser.parse_args(args)
+
+    prog = "errortools"
+    desc = __description__
+
     if sys.version_info >= (3, 14):
-        parser = argparse.ArgumentParser(description=__description__, color=True)
+        parser = argparse.ArgumentParser(description=desc, prog=prog, color=True)
     else:
-        parser = argparse.ArgumentParser(description=__description__)
+        parser = argparse.ArgumentParser(description=desc, prog=prog)
 
     parser.add_argument(
         "-v", "--version", action="store_true", help="Show version and exit"
     )
-
     parser.add_argument(
         "-c", "--copyrights", action="store_true", help="Show copyright information"
     )
-
     parser.add_argument("-a", "--author", action="store_true", help="Show author name")
-
     parser.add_argument("-e", "--email", action="store_true", help="Show author email")
-
     parser.add_argument(
         "-l", "--license", action="store_true", help="Show license type"
     )
-
     parser.add_argument("-u", "--url", action="store_true", help="Show project URL")
-
     parser.add_argument(
         "-i", "--info", action="store_true", help="Show all package information"
     )
-
     parser.add_argument(
-        "--run-tests",
-        action="store_true",
-        help="Run tests for errortools module. (Using pytest)",
-    )
-
-    subparsers = parser.add_subparsers(dest="subcommand")
-
-    log_parser = subparsers.add_parser(
-        "log",
-        help="Emit a log message from the command line",
-    )
-    log_parser.add_argument(
-        "message",
-        help="The message to log",
-    )
-    log_parser.add_argument(
-        "--level",
-        "-l",
-        default="info",
-        choices=["trace", "debug", "info", "success", "warning", "error", "critical"],
-        help="Log level (default: info)",
-    )
-    log_parser.add_argument(
-        "--output",
-        "-o",
-        choices=["stderr", "stdout"],
-        default="stderr",
-        help="Output stream (default: stderr)",
+        "--run-tests", action="store_true", help="Run tests using pytest"
     )
 
     return parser.parse_args(args)
 
 
-def log_main() -> None:
-    """Logging main CLI entry point."""
+def main() -> None:
     args = parse_args(sys.argv[1:])
 
-    if args.subcommand == "log":
+    if "logger" in sys.argv[0]:
         _cmd_log(args.message, args.level, args.output)
-
-
-def main() -> None:
-    """Main CLI entry point."""
-    args = parse_args(sys.argv[1:])
+        return
 
     if args.version:
         print(f"v{__version__}")
-
     elif args.copyrights:
         print(__copyright__)
-
     elif args.author:
         print(f"Author: {__author__}")
-
     elif args.email:
         print(f"Email: {__author_email__}")
-
     elif args.license:
         print(f"License: {__license__}")
-
     elif args.url:
         print(f"URL: {__url__}")
-
     elif args.run_tests:
-        run_tests()
+        from tests.run_tests import run_tests
 
+        run_tests()
     elif args.info:
         _print_info()
-
     else:
         parse_args(["--help"])
+
+
+if __name__ == "__main__":
+    main()

{errortools-2.2.0 → errortools-2.4.0}/_errortools/const.py

@@ -1,10 +1,12 @@
 """Constants for errortools module."""
 
+from typing import Final
+
 # ------------------------------------------------------------------
 # error_cache constants
 # ------------------------------------------------------------------
 
-DEFAULT_ERROR_CACHE_SIZE: int = 128
-SMALL_ERROR_CACHE_SIZE: int = 64
-LARGE_ERROR_CACHE_SIZE: int = 1024
-UNLIMITED_ERROR_CACHE: None = None
+DEFAULT_ERROR_CACHE_SIZE: Final[int] = 128
+SMALL_ERROR_CACHE_SIZE: Final[int] = 64
+LARGE_ERROR_CACHE_SIZE: Final[int] = 1024
+UNLIMITED_ERROR_CACHE: Final[None] = None

{errortools-2.2.0 → errortools-2.4.0}/_errortools/decorator/deprecated.py

@@ -31,3 +31,31 @@ def deprecated(
         return wrapper
 
     return decorator
+
+
+def experimental(
+    reason: str = "This function is experimental and may change in future versions.",
+) -> Callable:
+    """Decorator that marks a function as experimental.
+
+    Emits a UserWarning when the decorated function is called.
+
+    Args:
+        reason: Optional message explaining the experimental status and any caveats.
+
+    Example:
+        >>> @experimental(reason="API may change without notice.")
+        ... def new_feature():
+        ...     pass
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            msg = f"{func.__name__} is experimental. {reason}"
+            warnings.warn(msg, UserWarning, stacklevel=2)
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

errortools-2.4.0/_errortools/errno.py

@@ -0,0 +1,86 @@
+"""Lightweight utilities for errno error code inspection and handling."""
+
+import errno
+
+
+def get_errno_name(code: int) -> str | None:
+    """Get the symbolic name for an errno code.
+
+    Args:
+        code: The numeric errno code (e.g., 2 for ENOENT)
+
+    Returns:
+        The symbolic errno name (e.g., "ENOENT") or None if not found
+    """
+    for name in dir(errno):
+        if name.isupper() and getattr(errno, name) == code:
+            return name
+    return None
+
+
+def get_errno_message(code: int) -> str:
+    """Get the corresponding message description for an errno code.
+
+    Args:
+        code: The numeric errno code
+
+    Returns:
+        The message string corresponding to the errno code
+
+    Raises:
+        ValueError: If the given errno code is invalid
+    """
+    if not is_valid_errno(code):
+        raise ValueError(f"Unknown error code: {code}")
+
+    return errno.errorcode.get(code, f"Unknown error {code}")
+
+
+def get_all_errno_codes() -> dict[str, int]:
+    """Get a dictionary of all errno constant names and their numeric codes.
+
+    Returns:
+        Dictionary mapping uppercase errno names to their integer values
+    """
+    codes = {}
+    for name in dir(errno):
+        if name.isupper():
+            try:
+                value = getattr(errno, name)
+                if isinstance(value, int):
+                    codes[name] = value
+            except (AttributeError, TypeError):
+                pass
+    return codes
+
+
+def is_valid_errno(code: int) -> bool:
+    """Check whether a given integer is a valid system errno code.
+
+    Args:
+        code: The numeric code to validate
+
+    Returns:
+        True if the code corresponds to a known errno constant, False otherwise
+    """
+    return get_errno_name(code) is not None
+
+
+def strerror(code: int) -> str:
+    """Get the human-readable system error message for an errno code.
+
+    Args:
+        code: The numeric errno code
+
+    Returns:
+        Human-readable error message string
+
+    Raises:
+        ValueError: If the error code is not recognized by the system
+    """
+    import os
+
+    try:
+        return os.strerror(code)
+    except (ValueError, OSError):
+        raise ValueError(f"Unknown error code: {code}")

errortools-2.4.0/_errortools/future.py

@@ -0,0 +1,165 @@
+"""Future-focused lightweight exception handling utilities."""
+
+from __future__ import annotations
+
+from typing import TypeAlias, cast, Literal
+
+__all__ = [
+    "super_fast_ignore",
+    "super_fast_catch",
+    "super_fast_reraise",
+    "ExceptionCollector",
+]
+
+_ExcType: TypeAlias = type[BaseException]
+
+
+class super_fast_ignore:
+    """Ultra-lightweight context manager to suppress exceptions."""
+
+    __slots__ = ("excs",)
+
+    def __init__(self, *excs: _ExcType) -> None:
+        self.excs = excs
+
+    def __enter__(self) -> None:
+        return
+
+    def __exit__(self, typ: _ExcType | None, *_) -> bool:
+        if typ is None:
+            return False
+        excs = self.excs
+        return issubclass(typ, excs)
+
+
+class super_fast_catch:
+    """Ultra-lightweight context manager to catch and store exceptions.
+
+    Args:
+        *excs: Exception types to catch. Empty means catch all.
+
+    Example:
+        >>> with super_fast_catch(ValueError) as ctx:
+        ...     raise ValueError("oops")
+        >>> print(ctx.exception)
+    """
+
+    __slots__ = ("excs", "exception")
+
+    def __init__(self, *excs: _ExcType) -> None:
+        self.excs = excs if excs else (BaseException,)
+        self.exception: BaseException | None = None
+
+    def __enter__(self) -> "super_fast_catch":
+        return self
+
+    def __exit__(self, typ: _ExcType | None, val, *_) -> bool:
+        if typ is None or not issubclass(typ, self.excs):
+            return False
+        self.exception = val
+        return True
+
+
+class super_fast_reraise:
+    """Ultra-lightweight context manager to convert exception types.
+
+    Args:
+        catch: Exception type(s) to intercept.
+        raise_as: Exception type to raise instead.
+
+    Example:
+        >>> with super_fast_reraise(KeyError, ValueError):
+        ...     raise KeyError("missing")
+        >>> # Raises ValueError: missing
+    """
+
+    __slots__ = ("catch", "raise_as")
+
+    def __init__(
+        self,
+        catch: _ExcType | tuple[_ExcType, ...],
+        raise_as: _ExcType,
+    ) -> None:
+        self.catch = catch if isinstance(catch, tuple) else (catch,)
+        self.raise_as = raise_as
+
+    def __enter__(self) -> None:
+        return
+
+    def __exit__(self, typ: _ExcType | None, val, *_) -> Literal[False]:
+        if typ is None or not issubclass(typ, self.catch):
+            return False
+        raise self.raise_as(str(val)) from val
+
+
+class ExceptionCollector:
+    """Collect multiple exceptions and raise together at the end.
+
+    Useful for batch operations where you want all errors, not just the first.
+
+    Example:
+        >>> collector = ExceptionCollector()
+        >>> with collector:
+        ...     collector.catch(int, "bad1")
+        ...     collector.catch(int, "bad2")
+        >>> if collector.has_errors:
+        ...     collector.raise_all()
+    """
+
+    __slots__ = ("_exceptions", "_stop_on_first")
+
+    def __init__(self, stop_on_first: bool = False) -> None:
+        self._exceptions: list[BaseException] = []
+        self._stop_on_first = stop_on_first
+
+    def __enter__(self) -> ExceptionCollector:
+        return self
+
+    def __exit__(self, exc_typ, exc_val, *_) -> bool:
+        if exc_typ is not None:
+            self._exceptions.append(exc_val)
+            if self._stop_on_first:
+                return False
+            return True
+        return False
+
+    def catch(self, func, *args, **kwargs) -> bool:
+        """Try to call func and catch any exception. Returns True if exception caught."""
+        try:
+            func(*args, **kwargs)
+            return False
+        except BaseException as exc:
+            self._exceptions.append(exc)
+            if self._stop_on_first:
+                raise
+            return True
+
+    def add(self, exc: BaseException) -> None:
+        """Manually add an exception."""
+        self._exceptions.append(exc)
+        if self._stop_on_first:
+            raise exc
+
+    @property
+    def has_errors(self) -> bool:
+        """Check if any exceptions were collected."""
+        return len(self._exceptions) > 0
+
+    @property
+    def count(self) -> int:
+        """Get number of collected exceptions."""
+        return len(self._exceptions)
+
+    @property
+    def exceptions(self) -> list[BaseException]:
+        """Get the list of exceptions."""
+        return self._exceptions
+
+    def raise_all(self, message: str = "collected errors") -> None:
+        """Raise all collected exceptions as ExceptionGroup."""
+        if self._exceptions:
+            raise ExceptionGroup(message, cast(list[Exception], self._exceptions))
+
+    def clear(self) -> None:
+        """Clear all exceptions."""
+        self._exceptions.clear()