errortools 2.0.0__tar.gz → 2.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: errortools
-Version: 2.0.0
+Version: 2.2.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

errortools-2.2.0/_errortools/descriptor/__init__.py

@@ -0,0 +1,2 @@
+# Why add this file?
+# See https://github.com/more-abc/errortools/issues/27

errortools-2.2.0/_errortools/descriptor/errormsg.py

@@ -0,0 +1,37 @@
+from typing import Optional, NoReturn
+
+
+# NOTE: The attribute returns the preset message when accessed.
+# Any attempt to modify or delete it raises an ``AttributeError``.
+class ErrorMsg:
+    """Descriptor that creates a read-only attribute with a fixed message.
+
+    Args:
+        message: The fixed string returned when the attribute is accessed.
+
+    Example:
+
+        >>> class MyClass:
+        ...     status = ErrorMsg("This attribute is read-only")
+        >>> obj = MyClass()
+        >>> obj.status
+        'This attribute is read-only'
+        >>> obj.status = "new"  # doctest: +SKIP
+        AttributeError: Modification of this attribute is not allowed!
+        >>> del obj.status  # doctest: +SKIP
+        AttributeError: Deletion of this attribute is not allowed!
+    """
+
+    __slots__ = ("_message",)
+
+    def __init__(self, message: str) -> None:
+        self._message = message
+
+    def __get__(self, instance: Optional[object], owner: type[object]) -> str:
+        return self._message
+
+    def __set__(self, instance: object, value: object) -> NoReturn:
+        raise AttributeError("Modification of this attribute is not allowed!")
+
+    def __delete__(self, instance: object) -> NoReturn:
+        raise AttributeError("Deletion of this attribute is not allowed!")

errortools-2.2.0/_errortools/descriptor/nonblankmsg.py

@@ -0,0 +1,52 @@
+from typing import Any, Optional
+
+
+# NOTE: Validates the value is a string and not empty
+# after trimming leading/trailing whitespace.
+# Stores the cleaned (stripped) value on the instance.
+class NonBlankErrorMsg:
+    """Descriptor that validates an attribute is a non-blank string after stripping whitespace.
+
+    Args:
+        message: Name/label used in error messages for validation failures.
+
+    Example:
+        >>> class ApiError:
+        ...     message = NonBlankErrorMsg("Error message")
+        ...     def __init__(self, msg: str):
+        ...         self.message = msg
+        >>> err = ApiError("Invalid token")
+        >>> err.message
+        'Invalid token'
+        >>> err = ApiError("   ")  # doctest: +SKIP
+        ValueError: Error message can't be blank, must provide a valid error message
+    """
+
+    __slots__ = ("_message",)
+
+    def __init__(self, message: str) -> None:
+        self._message = message
+
+    def __get__(self, instance: Optional[object], owner: type[object]) -> str:
+        if instance is None:
+            return self._message
+        return instance.__dict__[self._message]  # type: ignore
+
+    def __set__(self, instance: object, value: Any) -> None:
+        validated_value = self.validate(self._message, value)
+        instance.__dict__[self._message] = validated_value
+
+    def __delete__(self, instance: object) -> None:
+        raise AttributeError("Deletion of this attribute is not allowed!")
+
+    def validate(self, name: str, value: str) -> str:
+        if not isinstance(value, str):
+            raise ValueError(f"{name} must be a string type")
+
+        stripped_value = value.strip()
+        if not stripped_value:
+            raise ValueError(
+                f"{name} can't be blank, must provide a valid error message"
+            )
+
+        return stripped_value

{errortools-2.0.0 → errortools-2.2.0}/_errortools/version.py

@@ -1,5 +1,5 @@
-__version__: str = "2.0.0"
-__version_tuple__: tuple[int, int, int] = (2, 0, 0)
+__version__: str = "2.2.0"
+__version_tuple__: tuple[int, int, int] = (2, 2, 0)
 __commit_id__: str | None = None
 
 version = __version__

errortools-2.2.0/_errortools/wrappers/__init__.py

@@ -0,0 +1,2 @@
+# Why add this file?
+# See https://github.com/more-abc/errortools/issues/27

errortools-2.2.0/_errortools/wrappers/cache.py

@@ -0,0 +1,95 @@
+from collections import OrderedDict
+from collections.abc import Hashable, Callable
+from typing import Any, Generic, TypeVar, Optional, TypeAlias, NamedTuple
+
+_T = TypeVar("_T", bound=Callable[..., Any])
+_Key: TypeAlias = tuple[
+    str, tuple[Hashable, ...], tuple[tuple[Hashable, Hashable], ...]
+]
+
+
+class CacheInfo(NamedTuple):
+    """Cache statistics, compatible with functools.lru_cache CacheInfo."""
+
+    hits: int
+    misses: int
+    maxsize: int | None
+    currsize: int
+
+
+class ErrorCacheWrapper(Generic[_T]):
+    """Wrapper class for error-cached functions."""
+
+    def __init__(self, func: _T, maxsize: int | None = 128) -> None:
+        self.__wrapped__ = func  # Required for inspect module compatibility
+        self._func_name = func.__name__
+
+        # Validate maxsize
+        if maxsize is not None and maxsize < 0:
+            raise ValueError(
+                f"maxsize must be None or a non-negative integer, got {maxsize!r}"
+            )
+        self._maxsize = maxsize
+        self._cache: OrderedDict[_Key, Exception] = OrderedDict()
+
+        # Cache statistics
+        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:
+            if cache_key in self._cache:
+                self._hits += 1
+            else:
+                self._misses += 1
+
+            # Store in cache only if maxsize allows it (maxsize=0 means no caching)
+            if self._maxsize != 0:
+                self._cache[cache_key] = exc
+                # 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."""
+        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."""
+        self._cache.clear()
+        self._hits = 0
+        self._misses = 0
+
+    def cache_info(self) -> CacheInfo:
+        """Return cache statistics as a named tuple (compatible with lru_cache)."""
+        return CacheInfo(
+            hits=self._hits,
+            misses=self._misses,
+            maxsize=self._maxsize,
+            currsize=len(self._cache),
+        )

errortools-2.2.0/_errortools/wrappers/ignore.py

@@ -0,0 +1,115 @@
+import traceback
+from collections.abc import Callable
+from typing import Any, Generic, TypeVar, Optional, TypeAlias
+
+_T = TypeVar("_T", bound=Callable[..., Any])
+_ExcType: TypeAlias = type[Exception]
+
+
+class IgnoredError:
+    """Information holder for ignored exceptions."""
+
+    __slots__ = (
+        "name",
+        "be_ignore",
+        "count",
+        "traceback",
+        "exception",
+    )
+
+    def __init__(self) -> None:
+        self.name: Optional[str] = None
+        self.be_ignore: bool = False
+        self.count: int = 0
+        self.traceback: Optional[str] = None
+        self.exception: Optional[Exception] = None
+
+    def reset(self) -> None:
+        self.name = None
+        self.be_ignore = False
+        self.traceback = None
+        self.exception = None
+
+
+class ErrorIgnoreWrapper(Generic[_T]):
+    """Context manager & decorator to ignore specified exceptions with rich info.
+
+    Catches and suppresses the given exception types within a ``with`` block
+    or when used as a decorator, while recording detailed information about
+    any suppressed exception.
+
+    When used as a context manager, ``__enter__`` returns an ``IgnoredError``
+    instance that provides the following attributes after the block executes.
+    """
+
+    #     Attributes:
+    #     be_ignore (bool):
+    #         ``True`` if an exception was suppressed during the block,
+    #         ``False`` otherwise.
+
+    #     name (str | None):
+    #         The class name of the suppressed exception
+    #         (e.g. ``'KeyError'``, ``'ValueError'``).
+    #         ``None`` if no exception occurred.
+
+    #     count (int):
+    #         Number of exceptions suppressed in this context block.
+    #         Typically 1 unless the context manager is reused.
+
+    #     exception (Exception | None):
+    #         The original exception instance that was caught and suppressed.
+    #         ``None`` if no exception occurred.
+
+    #     traceback (str | None):
+    #         Formatted traceback string showing where the suppressed exception
+    #         occurred.  Useful for debugging.  ``None`` if no exception occurred.
+
+    # Example:
+    #     >>> from errortools import ignore
+    #     >>> with ignore(KeyError) as err:
+    #     ...     _ = {}["missing"]
+    #     >>> err.be_ignore
+    #     True
+    #     >>> err.name
+    #     'KeyError'
+
+    def __init__(self, *excs: _ExcType) -> None:
+        for exc in excs:
+            if not isinstance(exc, type) or not issubclass(exc, Exception):
+                raise TypeError(f"Expected Exception subclass, got {exc!r}")
+
+        self._excs = excs
+        self._info = IgnoredError()
+
+    def __enter__(self) -> IgnoredError:
+        self._info.reset()
+        return self._info
+
+    def __exit__(
+        self,
+        exc_type: Optional[_ExcType],
+        exc_val: Optional[Exception],
+        exc_tb: Optional[Any],
+    ) -> bool:
+        if exc_type is None:
+            return False
+
+        if exc_type not in self._excs:
+            return False
+
+        self._info.name = exc_type.__name__
+        self._info.be_ignore = True
+        self._info.count += 1
+        self._info.traceback = "".join(
+            traceback.format_exception(exc_type, exc_val, exc_tb)
+        )
+        self._info.exception = exc_val
+        return True
+
+    def __call__(self, func: _T) -> _T:
+        def wrapped(*args: Any, **kwargs: Any) -> Any:
+            with self:
+                return func(*args, **kwargs)
+
+        wrapped.__wrapped__ = func  # type: ignore
+        return wrapped  # type: ignore

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: errortools
-Version: 2.0.0
+Version: 2.2.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

{errortools-2.0.0 → errortools-2.2.0}/errortools.egg-info/SOURCES.txt

@@ -22,6 +22,9 @@ _errortools/classes/warn.py
 _errortools/decorator/__init__.py
 _errortools/decorator/cache.py
 _errortools/decorator/deprecated.py
+_errortools/descriptor/__init__.py
+_errortools/descriptor/errormsg.py
+_errortools/descriptor/nonblankmsg.py
 _errortools/logging/__init__.py
 _errortools/logging/base.py
 _errortools/logging/level.py
@@ -33,6 +36,9 @@ _errortools/methods/errorattr.py
 _errortools/methods/errordelattr.py
 _errortools/methods/errorhasattr.py
 _errortools/methods/errorsetattr.py
+_errortools/wrappers/__init__.py
+_errortools/wrappers/cache.py
+_errortools/wrappers/ignore.py
 errortools/__init__.py
 errortools/__main__.py
 errortools.egg-info/PKG-INFO

{errortools-2.0.0 → errortools-2.2.0}/setup.py

@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
 
 setup(
     name="errortools",
-    version="2.0.0",
+    version="2.2.0",
     description="errortools - a toolset for working with Python exceptions and warnings and logging.",
     long_description=open("README.md", encoding="utf-8").read(),
     long_description_content_type="text/markdown",