errortools 3.0.0__tar.gz → 3.2.0__tar.gz

errortools-3.2.0/AUTHORS.txt

@@ -0,0 +1,12 @@
+# (Lines starting with # are comments)
+# Tips:
+#   Contributors are not sorted by initials, 
+#   but by contribution time.
+# Here are the real contributors
+aiwonderland
+qorexdev
+vgauraha62
+yangphysics
+# And here are bot contributors
+dependabot[bot]
+AbaAbaAba-bot-like[bot]

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.2.0/_errortools/_speedup.c

@@ -0,0 +1,175 @@
+#define PY_SSIZE_T_CLEAN
+#include <Python.h>
+
+/* Fast exception type checking
+ * 
+ * Optimized check for exception type hierarchy using PyObject_IsSubclass.
+ * Returns False immediately if typ is None, otherwise checks if typ is a
+ * subclass of excs.
+ * 
+ * Args:
+ *   typ: The type object to check (or None)
+ *   excs: The exception class(es) to check against
+ * 
+ * Returns:
+ *   True if typ is a subclass of excs, False otherwise
+ *   NULL on error with exception set
+ */
+static PyObject* fast_issubclass_check(PyObject* self, PyObject* const* args, Py_ssize_t nargs) {
+    if (nargs != 2) {
+        PyErr_Format(PyExc_TypeError, 
+                     "fast_issubclass_check() takes exactly 2 arguments (%zd given)", 
+                     nargs);
+        return NULL;
+    }
+
+    PyObject *typ = args[0];
+    PyObject *excs = args[1];
+
+    /* Handle None case explicitly */
+    if (typ == Py_None) {
+        Py_RETURN_FALSE;
+    }
+
+    /* Validate that excs is a class or tuple of classes */
+    if (!PyType_Check(excs) && !PyTuple_Check(excs)) {
+        PyErr_SetString(PyExc_TypeError, 
+                        "second argument must be a class or tuple of classes");
+        return NULL;
+    }
+
+    int result = PyObject_IsSubclass(typ, excs);
+    if (result == -1) {
+        return NULL;  /* Exception already set by PyObject_IsSubclass */
+    }
+
+    /* Return bool directly instead of going through PyBool_FromLong */
+    if (result == 1) {
+        Py_RETURN_TRUE;
+    } else {
+        Py_RETURN_FALSE;
+    }
+}
+
+/* Fast exception collector append
+ * 
+ * Optimized append operation for adding exceptions to a list.
+ * 
+ * Args:
+ *   list: The list object to append to
+ *   exc: The exception object to append
+ * 
+ * Returns:
+ *   None on success
+ *   NULL on error with exception set
+ */
+static PyObject* fast_append_exception(PyObject* self, PyObject* const* args, Py_ssize_t nargs) {
+    if (nargs != 2) {
+        PyErr_Format(PyExc_TypeError, 
+                     "fast_append_exception() takes exactly 2 arguments (%zd given)", 
+                     nargs);
+        return NULL;
+    }
+
+    PyObject *list = args[0];
+    PyObject *exc = args[1];
+
+    /* Validate that first argument is actually a list */
+    if (!PyList_Check(list)) {
+        PyErr_SetString(PyExc_TypeError, "first argument must be a list");
+        return NULL;
+    }
+
+    if (PyList_Append(list, exc) == -1) {
+        return NULL;  /* Exception already set by PyList_Append */
+    }
+
+    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[] = {
+    {
+        "fast_issubclass_check",
+        (PyCFunction)fast_issubclass_check,
+        METH_FASTCALL,
+        "fast_issubclass_check(typ, excs) -> bool\n\n"
+        "Check if typ is a subclass of excs exception type(s).\n"
+        "Returns False if typ is None, otherwise uses PyObject_IsSubclass.\n"
+        "Optimized for exception handling performance."
+    },
+    {
+        "fast_append_exception",
+        (PyCFunction)fast_append_exception,
+        METH_FASTCALL,
+        "fast_append_exception(list, exc) -> None\n\n"
+        "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 */
+};
+
+/* Module definition */
+static struct PyModuleDef speedupmodule = {
+    PyModuleDef_HEAD_INIT,
+    "_speedup",                 /* name */
+    "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\n"
+    "  - fast_suppress_exit: Combined None-check + issubclass for __exit__",
+    -1,                         /* size */
+    SpeedupMethods               /* methods */
+};
+
+/* Module initialization */
+PyMODINIT_FUNC PyInit__speedup(void) {
+    return PyModule_Create(&speedupmodule);
+}

{errortools-3.0.0 → errortools-3.2.0}/_errortools/classes/abc.py

@@ -69,13 +69,11 @@ class ErrorCodeable(ABC):
     @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
 
 
 # ----------------------------------------------------------------------
@@ -123,7 +121,6 @@ class Warnable(ABC):
             stacklevel: Passed to ``warnings.warn``; ``2`` points at the
                 caller of ``emit``.
         """
-        pass
 
 
 # ----------------------------------------------------------------------
@@ -166,7 +163,6 @@ class Raiseable(ABC):
         Raises:
             self: Or a derived exception wrapping this object.
         """
-        pass
 
 
 # ----------------------------------------------------------------------