errortools 3.1.0__tar.gz → 3.2.0__tar.gz

errortools-3.2.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: errortools
+Version: 3.2.0
+Summary: errortools - a toolset for working with Python exceptions and warnings and logging.
+Author-email: Evan Yang <quantbit@126.com>
+License: Copyright (c) 2026 authors see AUTHORS.txt
+        
+        Permission is hereby granted, free of charge, to any person obtaining
+        a copy of this software and associated documentation files (the
+        "Software"), to deal in the Software without restriction, including
+        without limitation the rights to use, copy, modify, merge, publish,
+        distribute, sublicense, and/or sell copies of the Software, and to
+        permit persons to whom the Software is furnished to do so, subject to
+        the following conditions:
+        
+        The above copyright notice and this permission notice shall be
+        included in all copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+        EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+        MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+        NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+        LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+        OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+        WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/more-abc/errortools
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+License-File: AUTHORS.txt
+Requires-Dist: namebyauthor==1.0.0
+Requires-Dist: typing_extensions>=4.15.0
+Dynamic: license-file
+
+# errortools
+
+A lightweight Python exception handling utility library.
+
+[![Code Style: Google](https://img.shields.io/badge/style-google-3666d6.svg)](https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings)
+[![PyPI Version](https://img.shields.io/pypi/v/errortools)](https://pypi.org/project/errortools/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/errortools)](https://pypi.org/project/errortools/)
+![This week commits](https://img.shields.io/github/commit-activity/w/more-abc/errortools)
+![This month commits](https://img.shields.io/github/commit-activity/m/more-abc/errortools)
+![Past year commits](https://img.shields.io/github/commit-activity/y/more-abc/errortools)
+![Total commits badge](https://img.shields.io/github/commit-activity/t/more-abc/errortools)
+![OS support](https://img.shields.io/badge/OS-macOS%20Linux%20Windows-red)
+
+## Installation
+### Use pip...
+```bash
+pip install errortools
+```
+### ...or uv
+```bash
+uv add errortools
+```
+
+## Features
+
+- **Suppress**: `ignore()`, `super_fast_ignore()`, `@suppress()` — silence exceptions gracefully
+- **Retry & Timeout**: `@retry()`, `@timeout()` — auto retry with delay, async timeout
+- **Raise & Convert**: `raises()`, `reraise()`, `@convert()` — batch raise, type conversion
+- **Catch & Collect**: `super_fast_catch()`, `ExceptionCollector` — inspect or batch exceptions
+- **Caching**: `@error_cache` — LRU exception cache, like `functools.lru_cache`
+- **Custom Exceptions**: `PureBaseException`, `ContextException`, `BaseErrorCodes`
+- **Logging**: structured logger with sinks, context binding, and exception capture
+
+## Quick Start
+
+```python
+from errortools import ignore, retry, reraise, error_cache, suppress, convert
+from errortools.future import super_fast_ignore, super_fast_catch, ExceptionCollector
+
+# ── Suppress ─────────────────────────────────────────────────
+with ignore(KeyError) as err:               # full metadata
+    _ = {}["missing"]
+# err.be_ignore=True, err.name='KeyError', err.traceback=...
+
+with super_fast_ignore(ValueError):         # zero-overhead
+    int("bad")
+
+@suppress(ZeroDivisionError, default=0)     # decorator form
+def divide(a, b): return a / b
+
+# ── Retry ────────────────────────────────────────────────────
+@retry(times=3, on=ConnectionError, delay=1.0)
+def connect(host: str): ...
+
+# ── Convert ──────────────────────────────────────────────────
+@convert(KeyError, ValueError)              # decorator
+def lookup(d, key): return d[key]
+
+with reraise(KeyError, ValueError):         # context manager
+    raise KeyError("x")                     # → ValueError
+
+# ── Catch & Collect ──────────────────────────────────────────
+with super_fast_catch(ValueError) as ctx:
+    raise ValueError("oops")
+# ctx.exception → ValueError('oops')
+
+collector = ExceptionCollector()
+collector.catch(int, "bad1")
+collector.catch(int, "bad2")
+collector.raise_all()                       # → ExceptionGroup
+
+# ── Cache ────────────────────────────────────────────────────
+@error_cache(maxsize=64)
+def load(uid: int):
+    if uid < 0: raise ValueError(f"invalid: {uid}")
+    return {"id": uid}
+```
+
+## Custom Exceptions
+
+```python
+from errortools import PureBaseException, ContextException, BaseErrorCodes
+
+class AppError(PureBaseException):
+    code = 9000
+    default_detail = "Application error."
+
+err = ContextException("failed").with_context(service="db")
+raise BaseErrorCodes.not_found("user #42")  # NotFoundError [3001]
+```
+
+## Logging
+
+```python
+from errortools.logging import logger
+
+logger.info("Server started on port {}", 8080)
+logger.add("app.log", rotation=10_485_760, retention=5)
+with logger.catch():
+    int("not a number")                     # logged + suppressed
+```
+
+## Documentation
+
+Full docs: [docs](https://errortools.readthedocs.io) | License: [LICENSE](LICENSE.txt)

errortools-3.2.0/README.md

@@ -0,0 +1,105 @@
+# errortools
+
+A lightweight Python exception handling utility library.
+
+[![Code Style: Google](https://img.shields.io/badge/style-google-3666d6.svg)](https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings)
+[![PyPI Version](https://img.shields.io/pypi/v/errortools)](https://pypi.org/project/errortools/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/errortools)](https://pypi.org/project/errortools/)
+![This week commits](https://img.shields.io/github/commit-activity/w/more-abc/errortools)
+![This month commits](https://img.shields.io/github/commit-activity/m/more-abc/errortools)
+![Past year commits](https://img.shields.io/github/commit-activity/y/more-abc/errortools)
+![Total commits badge](https://img.shields.io/github/commit-activity/t/more-abc/errortools)
+![OS support](https://img.shields.io/badge/OS-macOS%20Linux%20Windows-red)
+
+## Installation
+### Use pip...
+```bash
+pip install errortools
+```
+### ...or uv
+```bash
+uv add errortools
+```
+
+## Features
+
+- **Suppress**: `ignore()`, `super_fast_ignore()`, `@suppress()` — silence exceptions gracefully
+- **Retry & Timeout**: `@retry()`, `@timeout()` — auto retry with delay, async timeout
+- **Raise & Convert**: `raises()`, `reraise()`, `@convert()` — batch raise, type conversion
+- **Catch & Collect**: `super_fast_catch()`, `ExceptionCollector` — inspect or batch exceptions
+- **Caching**: `@error_cache` — LRU exception cache, like `functools.lru_cache`
+- **Custom Exceptions**: `PureBaseException`, `ContextException`, `BaseErrorCodes`
+- **Logging**: structured logger with sinks, context binding, and exception capture
+
+## Quick Start
+
+```python
+from errortools import ignore, retry, reraise, error_cache, suppress, convert
+from errortools.future import super_fast_ignore, super_fast_catch, ExceptionCollector
+
+# ── Suppress ─────────────────────────────────────────────────
+with ignore(KeyError) as err:               # full metadata
+    _ = {}["missing"]
+# err.be_ignore=True, err.name='KeyError', err.traceback=...
+
+with super_fast_ignore(ValueError):         # zero-overhead
+    int("bad")
+
+@suppress(ZeroDivisionError, default=0)     # decorator form
+def divide(a, b): return a / b
+
+# ── Retry ────────────────────────────────────────────────────
+@retry(times=3, on=ConnectionError, delay=1.0)
+def connect(host: str): ...
+
+# ── Convert ──────────────────────────────────────────────────
+@convert(KeyError, ValueError)              # decorator
+def lookup(d, key): return d[key]
+
+with reraise(KeyError, ValueError):         # context manager
+    raise KeyError("x")                     # → ValueError
+
+# ── Catch & Collect ──────────────────────────────────────────
+with super_fast_catch(ValueError) as ctx:
+    raise ValueError("oops")
+# ctx.exception → ValueError('oops')
+
+collector = ExceptionCollector()
+collector.catch(int, "bad1")
+collector.catch(int, "bad2")
+collector.raise_all()                       # → ExceptionGroup
+
+# ── Cache ────────────────────────────────────────────────────
+@error_cache(maxsize=64)
+def load(uid: int):
+    if uid < 0: raise ValueError(f"invalid: {uid}")
+    return {"id": uid}
+```
+
+## Custom Exceptions
+
+```python
+from errortools import PureBaseException, ContextException, BaseErrorCodes
+
+class AppError(PureBaseException):
+    code = 9000
+    default_detail = "Application error."
+
+err = ContextException("failed").with_context(service="db")
+raise BaseErrorCodes.not_found("user #42")  # NotFoundError [3001]
+```
+
+## Logging
+
+```python
+from errortools.logging import logger
+
+logger.info("Server started on port {}", 8080)
+logger.add("app.log", rotation=10_485_760, retention=5)
+with logger.catch():
+    int("not a number")                     # logged + suppressed
+```
+
+## Documentation
+
+Full docs: [docs](https://errortools.readthedocs.io) | License: [LICENSE](LICENSE.txt)

errortools-3.2.0/_errortools/__main__.py

@@ -0,0 +1,109 @@
+"""Private debug CLI — run via `python -m _errortools`."""
+
+import argparse
+import shutil
+import sys
+from pathlib import Path
+
+from _errortools.version import __version__
+
+
+def _parse_args(args: list[str] | None = None) -> argparse.Namespace:
+    desc = "errortools internal debug tools"
+
+    if sys.version_info >= (3, 14):
+        parser = argparse.ArgumentParser(prog="_errortools", description=desc, color=True)
+    else:
+        parser = argparse.ArgumentParser(prog="_errortools", description=desc)
+
+    parser.add_argument("--debug", action="store_true", help="Show debug/environment information")
+    parser.add_argument(
+        "--reset", action="store_true", help="Clear all cached data (__pycache__, htmlcov, .pytest_cache, .mypy_cache)"
+    )
+    parser.add_argument("--check", action="store_true", help="Verify installation and dependencies")
+
+    return parser.parse_args(args)
+
+
+def _debug_info() -> None:
+    import platform
+
+    print(f"errortools v{__version__}")
+    print(f"  Python:    {sys.version}")
+    print(f"  Platform:  {platform.platform()}")
+    print(f"  Arch:      {platform.machine()}")
+    print(f"  Prefix:    {sys.prefix}")
+    print(f"  Exec:      {sys.executable}")
+
+    try:
+        __import__("_errortools._speedup")
+        print("  C speedup: available")
+    except ImportError:
+        print("  C speedup: not available (pure Python fallback)")
+
+
+def _reset_cache() -> None:
+    root = Path(__file__).resolve().parent.parent
+    count = 0
+
+    for d in root.rglob("__pycache__"):
+        if d.is_dir():
+            shutil.rmtree(d)
+            count += 1
+
+    for name in ["htmlcov", ".pytest_cache", ".mypy_cache"]:
+        d = root / name
+        if d.is_dir():
+            shutil.rmtree(d)
+            count += 1
+
+    print(f"Reset complete. Cleared {count} cached directories.")
+
+
+def _check_install() -> None:
+    checks: list[tuple[str, bool]] = [("errortools importable", True)]
+
+    for label, import_path in [
+        ("C extension (_speedup)", "_errortools._speedup"),
+        ("pytest", "pytest"),
+        ("logging module", "_errortools.logging"),
+        ("future module", "_errortools.future"),
+        ("typing_extensions", "typing_extensions"),
+    ]:
+        try:
+            __import__(import_path)
+            checks.append((label, True))
+        except ImportError:
+            checks.append((label, False))
+
+    for name, ok in checks:
+        status = "OK" if ok else "MISSING"
+        print(f"  [{status:>7s}] {name}")
+
+    print()
+    if all(ok for _, ok in checks):
+        print("All checks passed.")
+    else:
+        print("Some checks failed. Install missing dependencies.")
+
+
+_FLAG_ACTIONS = {
+    "debug": _debug_info,
+    "reset": _reset_cache,
+    "check": _check_install,
+}
+
+
+def main() -> None:
+    args = _parse_args(sys.argv[1:])
+
+    for flag, action in _FLAG_ACTIONS.items():
+        if getattr(args, flag, False):
+            action()
+            return
+
+    _parse_args(["--help"])
+
+
+if __name__ == "__main__":
+    main()

{errortools-3.1.0 → errortools-3.2.0}/_errortools/_speedup.c

@@ -87,6 +87,45 @@ static PyObject* fast_append_exception(PyObject* self, PyObject* const* args, Py
     Py_RETURN_NONE;
 }
 
+/* Fast suppress exit for context managers
+ *
+ * Combined None-check + issubclass optimized for __exit__ methods.
+ * Returns True (suppress) if typ is not None and is a subclass of excs,
+ * False otherwise. Never raises on None — just returns False.
+ *
+ * Args:
+ *   typ: The exception type (or None if no exception)
+ *   excs: The exception class(es) to match against (tuple)
+ *
+ * Returns:
+ *   True if exception should be suppressed, False otherwise
+ *   NULL on error with exception set
+ */
+static PyObject* fast_suppress_exit(PyObject* self, PyObject* const* args, Py_ssize_t nargs) {
+    if (nargs != 2) {
+        PyErr_Format(PyExc_TypeError,
+                     "fast_suppress_exit() takes exactly 2 arguments (%zd given)",
+                     nargs);
+        return NULL;
+    }
+
+    PyObject *typ = args[0];
+
+    if (typ == Py_None) {
+        Py_RETURN_FALSE;
+    }
+
+    int result = PyObject_IsSubclass(typ, args[1]);
+    if (result == -1) {
+        return NULL;
+    }
+
+    if (result) {
+        Py_RETURN_TRUE;
+    }
+    Py_RETURN_FALSE;
+}
+
 /* Method definitions */
 static PyMethodDef SpeedupMethods[] = {
     {
@@ -106,6 +145,14 @@ static PyMethodDef SpeedupMethods[] = {
         "Append an exception to a list with minimal overhead.\n"
         "Validates that the first argument is a list."
     },
+    {
+        "fast_suppress_exit",
+        (PyCFunction)fast_suppress_exit,
+        METH_FASTCALL,
+        "fast_suppress_exit(typ, excs) -> bool\n\n"
+        "Return True if typ is not None and is a subclass of excs.\n"
+        "Optimized for context manager __exit__ methods."
+    },
     {NULL, NULL, 0, NULL}  /* Sentinel */
 };
 
@@ -116,7 +163,8 @@ static struct PyModuleDef speedupmodule = {
     "C speedup module for errortools\n\n"
     "Provides optimized implementations of exception handling operations:\n"
     "  - fast_issubclass_check: Quick exception type hierarchy checking\n"
-    "  - fast_append_exception: Efficient exception list append operations",
+    "  - fast_append_exception: Efficient exception list append operations\n"
+    "  - fast_suppress_exit: Combined None-check + issubclass for __exit__",
     -1,                         /* size */
     SpeedupMethods               /* methods */
 };

errortools-3.2.0/_errortools/classes/__init__.py

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

errortools-3.2.0/_errortools/classes/abc.py

@@ -0,0 +1,207 @@
+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."""
+
+    @property
+    @abstractmethod
+    def default_detail(self) -> str:
+        """Fallback human-readable message used when no detail is provided."""
+
+
+# ----------------------------------------------------------------------
+# 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``.
+        """
+
+
+# ----------------------------------------------------------------------
+# 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.
+        """
+
+
+# ----------------------------------------------------------------------
+# 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)