click-extended 1.0.7__py3-none-any.whl → 1.0.9__py3-none-any.whl

click_extended/core/nodes/_root_node.py

@@ -664,7 +664,33 @@ class RootNode(Node):
                                     context,
                                 )
 
-                    for validation_node in root.tree.validations:
+                    catch_nodes = [
+                        v
+                        for v in root.tree.validations
+                        if v.__class__.__name__ == "Catch"
+                    ]
+                    other_nodes = [
+                        v
+                        for v in root.tree.validations
+                        if v.__class__.__name__ != "Catch"
+                    ]
+                    root.tree.validations = catch_nodes + other_nodes
+
+                    for i, validation_node in enumerate(root.tree.validations):
+                        if validation_node.__class__.__name__ == "Catch":
+                            if hasattr(
+                                validation_node, "remaining_validations"
+                            ):
+                                validation_node.remaining_validations = (
+                                    root.tree.validations[i + 1 :]
+                                )
+                            validation_node.on_finalize(
+                                custom_context,
+                                *validation_node.process_args,
+                                **validation_node.process_kwargs,
+                            )
+                            break
+
                         validation_node.on_finalize(
                             custom_context,
                             *validation_node.process_args,

click_extended/decorators/misc/__init__.py

@@ -1,5 +1,8 @@
 """Initialization file for the `click_extended.decorators.misc` module."""
 
+# pylint: disable=wrong-import-position
+
+from click_extended.decorators.misc.catch import catch
 from click_extended.decorators.misc.choice import choice
 from click_extended.decorators.misc.confirm_if import confirm_if
 from click_extended.decorators.misc.default import default
@@ -8,6 +11,7 @@ from click_extended.decorators.misc.experimental import experimental
 from click_extended.decorators.misc.now import now
 
 __all__ = [
+    "catch",
     "choice",
     "confirm_if",
     "default",

click_extended/decorators/misc/catch.py

@@ -0,0 +1,343 @@
+"""
+Validation node to catch and handle exceptions from command/group functions.
+"""
+
+# pylint: disable=wrong-import-position
+# pylint: disable=wrong-import-order
+# pylint: disable=ungrouped-imports
+
+import asyncio
+import inspect
+from functools import wraps
+from typing import Any, Callable
+from weakref import WeakKeyDictionary
+
+from click_extended.core.nodes.validation_node import ValidationNode
+from click_extended.core.other._tree import Tree
+from click_extended.core.other.context import Context
+from click_extended.types import Decorator
+
+_catch_handlers: WeakKeyDictionary[
+    Callable[..., Any],
+    list[
+        tuple[tuple[type[BaseException], ...], Callable[..., Any] | None, bool]
+    ],
+] = WeakKeyDictionary()
+
+
+class Catch(ValidationNode):
+    """
+    Catch and handle exceptions from command/group functions and
+    validators.
+
+    Wraps both the validation phase and function execution in a
+    try-except block. When an exception is caught, an optional handler
+    is invoked. Without a handler, exceptions are silently suppressed.
+
+    Catches exceptions from:
+    - Validation decorators (e.g., @exclusive, @requires)
+    - The command/group function itself
+
+    Handler signatures supported:
+    - `handler()` - No arguments, just execute code
+    - `handler(exception)` - Receive the exception object
+    - `handler(exception, context)` - Receive exception and Context object
+
+    Examples:
+        ```py
+        # Catch validation errors from @exclusive
+        @command()
+        @exclusive("--stock", "--query")
+        @catch(ValueError, handler=lambda e: print(f"Error: {e}"))
+        def search(stock, query):
+            pass
+        ```
+
+        ```py
+        # Catch errors from command function
+        @command()
+        @catch(ValueError, handler=lambda e: print(f"Error: {e}"))
+        def cmd():
+            raise ValueError("Count must be positive")
+        ```
+
+        ```py
+        # Access context information
+        @command()
+        @catch(
+            ValueError,
+            handler=lambda e, ctx: print(f"{ctx.info_name}: {e}"),
+        )
+        def cmd():
+            raise ValueError("Failed!")
+        ```
+    """
+
+    def __init__(
+        self,
+        name: str,
+        process_args: tuple[Any, ...] | None = None,
+        process_kwargs: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize Catch validation node with function to wrap."""
+        super().__init__(name, process_args, process_kwargs, **kwargs)
+        self.wrapped_func: Callable[..., Any] | None = None
+        self.remaining_validations: list[ValidationNode] = []
+
+    def on_finalize(self, context: Context, *args: Any, **kwargs: Any) -> None:
+        """
+        Execute remaining validations wrapped in exception handling.
+
+        This catches exceptions from all validators that run after @catch,
+        allowing it to catch validation errors like those from @exclusive.
+
+        Args:
+            context: The execution context
+            *args: Contains exception types tuple at index 0
+            **kwargs: Contains handler, reraise parameters
+        """
+        exception_types: tuple[type[BaseException], ...] = args[0]
+        handler: Callable[..., Any] | None = kwargs.get("handler")
+        reraise: bool = kwargs.get("reraise", False)
+
+        for validation_node in self.remaining_validations:
+            try:
+                if asyncio.iscoroutinefunction(validation_node.on_finalize):
+                    asyncio.run(
+                        validation_node.on_finalize(
+                            context,
+                            *validation_node.process_args,
+                            **validation_node.process_kwargs,
+                        )
+                    )
+                else:
+                    validation_node.on_finalize(
+                        context,
+                        *validation_node.process_args,
+                        **validation_node.process_kwargs,
+                    )
+            except BaseException as exc:
+                if isinstance(exc, exception_types):
+                    if handler is not None:
+                        if asyncio.iscoroutinefunction(handler):
+                            asyncio.run(_call_handler_async(handler, exc))
+                        else:
+                            _call_handler_sync(handler, exc)
+
+                    if not reraise:
+                        return
+
+                raise
+
+
+def catch(
+    *exception_types: type[BaseException],
+    handler: Callable[..., Any] | None = None,
+    reraise: bool = False,
+) -> Decorator:
+    """
+    Catch and handle exceptions from command/group functions.
+
+    Wraps the function in a try-except block. When exceptions occur, an optional
+    handler is invoked. If no exception types are specified, catches Exception.
+
+    Type: `ValidationNode`
+
+    Args:
+        *exception_types: Exception types to catch (defaults to Exception)
+        handler: Optional function with signature `()`, `(exception)`, or
+            `(exception, context)` to handle caught exceptions
+        reraise: If True, re-raise after handling (default: False)
+
+    Returns:
+        Decorator function
+
+    Raises:
+        TypeError: If exception_types contains non-exception classes
+
+    Examples:
+        ```python
+        # Simple notification (no arguments)
+        @command()
+        @catch(ValueError, handler=lambda: print("Error occurred!"))
+        def cmd():
+            raise ValueError("Invalid input")
+        ```
+
+        ```python
+        # Log exception details (exception argument)
+        @command()
+        @catch(ValueError, handler=lambda e: print(f"Error: {e}"))
+        def cmd():
+            raise ValueError("Count must be positive")
+        ```
+
+        ```python
+        # Access context (exception + context arguments)
+        @command()
+        @catch(
+            ValueError,
+            handler=lambda e, ctx: print(f"{ctx.info_name}: {e}"),
+        )
+        def cmd():
+            raise ValueError("Failed!")
+        ```
+
+        ```python
+        # Catch multiple exception types
+        @command()
+        @catch(ValueError, TypeError, handler=lambda e: log_error(e))
+        def cmd():
+            raise ValueError("Something went wrong")
+        ```
+
+        ```python
+        # Silent suppression (no handler)
+        @command()
+        @catch(RuntimeError)
+        def cmd():
+            raise RuntimeError("Silently suppressed")
+        ```
+
+        ```python
+        # Log then re-raise
+        @command()
+        @catch(
+            ValueError,
+            handler=lambda e: print(f"Logging: {e}"),
+            reraise=True,
+        )
+        def cmd():
+            raise ValueError("This will be logged and re-raised")
+        ```
+    """
+    if not exception_types:
+        exception_types = (Exception,)
+
+    for exc_type in exception_types:
+        if not isinstance(exc_type, type) or not issubclass(
+            exc_type, BaseException
+        ):
+            raise TypeError(
+                f"catch() requires exception types, got {exc_type!r}"
+            )
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        """The actual decorator that wraps the function."""
+
+        instance = Catch(
+            name="catch",
+            process_args=(exception_types,),
+            process_kwargs={"handler": handler, "reraise": reraise},
+        )
+
+        Tree.queue_validation(instance)
+
+        original_func = func
+        while hasattr(original_func, "__wrapped__"):
+            original_func = original_func.__wrapped__  # type: ignore
+
+        if original_func not in _catch_handlers:
+            _catch_handlers[original_func] = []
+        _catch_handlers[original_func].insert(
+            0, (exception_types, handler, reraise)
+        )
+
+        # Only wrap if this is the first @catch (check handlers dict)
+        if len(_catch_handlers[original_func]) > 1:
+            return func
+
+        if asyncio.iscoroutinefunction(func):
+
+            @wraps(func)
+            async def async_wrapper(*call_args: Any, **call_kwargs: Any) -> Any:
+                """Async wrapper that catches exceptions."""
+                try:
+                    return await func(*call_args, **call_kwargs)
+                except BaseException as exc:
+                    for exc_types, hdlr, reraise_flag in _catch_handlers.get(
+                        original_func, []
+                    ):
+                        if isinstance(exc, exc_types):
+                            if hdlr is not None:
+                                if asyncio.iscoroutinefunction(hdlr):
+                                    await _call_handler_async(hdlr, exc)
+                                else:
+                                    _call_handler_sync(hdlr, exc)
+
+                            if reraise_flag:
+                                raise
+
+                            return None
+                    raise
+
+            return async_wrapper
+
+        @wraps(func)
+        def sync_wrapper(*call_args: Any, **call_kwargs: Any) -> Any:
+            """Sync wrapper that catches exceptions."""
+            try:
+                return func(*call_args, **call_kwargs)
+            except BaseException as exc:
+                for exc_types, hdlr, reraise_flag in _catch_handlers.get(
+                    original_func, []
+                ):
+                    if isinstance(exc, exc_types):
+                        if hdlr is not None:
+                            if asyncio.iscoroutinefunction(hdlr):
+                                asyncio.run(_call_handler_async(hdlr, exc))
+                            else:
+                                _call_handler_sync(hdlr, exc)
+
+                        if reraise_flag:
+                            raise
+
+                        return None
+                raise
+
+        return sync_wrapper
+
+    return decorator
+
+
+async def _call_handler_async(
+    handler: Callable[..., Any], exc: BaseException
+) -> Any:
+    """Call async handler with appropriate number of arguments."""
+    sig = inspect.signature(handler)
+    params = list(sig.parameters.values())
+
+    if len(params) == 0:
+        return await handler()
+    if len(params) == 1:
+        return await handler(exc)
+
+    import click
+
+    try:
+        ctx = click.get_current_context()
+        custom_context = ctx.meta.get("click_extended", {}).get("context")
+        return await handler(exc, custom_context)
+    except RuntimeError:
+        return await handler(exc, None)
+
+
+def _call_handler_sync(handler: Callable[..., Any], exc: BaseException) -> Any:
+    """Call sync handler with appropriate number of arguments."""
+    sig = inspect.signature(handler)
+    params = list(sig.parameters.values())
+
+    if len(params) == 0:
+        return handler()
+    if len(params) == 1:
+        return handler(exc)
+
+    import click
+
+    try:
+        ctx = click.get_current_context()
+        custom_context = ctx.meta.get("click_extended", {}).get("context")
+        return handler(exc, custom_context)
+    except RuntimeError:
+        return handler(exc, None)

{click_extended-1.0.7.dist-info → click_extended-1.0.9.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: click_extended
-Version: 1.0.7
+Version: 1.0.9
 Summary: An extension to Click with additional features like automatic async support, aliasing and a modular decorator system.
 Author-email: Marcus Fredriksson <marcus@marcusfredriksson.com>
 License: MIT License

{click_extended-1.0.7.dist-info → click_extended-1.0.9.dist-info}/RECORD

@@ -14,7 +14,7 @@ click_extended/core/decorators/prompt.py,sha256=QwySQ6ZK0j0iL_jlwH3AU0U4G1X3MKAJ
 click_extended/core/decorators/selection.py,sha256=5cjWpAwReu8EY0mkziwpqhi_T5ucIlAPx1p-t3MkGJQ,5589
 click_extended/core/decorators/tag.py,sha256=395e6GN59QBj-L0NSBPynQOX3_2LAOIXkj8XKNXrRPs,3055
 click_extended/core/nodes/__init__.py,sha256=jSsKTiHPUpqXdk54cRXDotT0YMmVGezIIb3nQ0rcWko,737
-click_extended/core/nodes/_root_node.py,sha256=PitK6GT7LPYugxPFdVO6blG0-mZV9S2apUupgWCsYI0,43060
+click_extended/core/nodes/_root_node.py,sha256=cNmTPtREVjNi6WZj3chtYFmn9_2iqJh4l32NEmO0Db4,44233
 click_extended/core/nodes/argument_node.py,sha256=gqG4HTDR40Xru_U_beKsbjVtLtwmPKfwwAUmcf5-1iQ,5284
 click_extended/core/nodes/child_node.py,sha256=yIuXmUzdXN0EToR9ohBRvHFBriSZ-xaLkv7P27PbTrA,17095
 click_extended/core/nodes/child_validation_node.py,sha256=Xcqid9EL3pHVrgv_43zz-ZL4W4yFm0Esj2qkk9qhWMc,3807
@@ -97,7 +97,8 @@ click_extended/decorators/math/rounded.py,sha256=bHYZQbtd5zRCd3BOEnjxTGdFAmQAL5l
 click_extended/decorators/math/sqrt.py,sha256=CWZoQpVw2lbP_LNeg-tWW8fz9VEHTX8eQNPNuDVoTcg,834
 click_extended/decorators/math/subtract.py,sha256=A7TMByTUH3coSEe7iRN9NkHW2mv47kufb1H1adomG4A,806
 click_extended/decorators/math/to_percent.py,sha256=39vY13u7Z-pyob1vCoPBDy10FqJasJTVzHcrpTH6ERQ,1374
-click_extended/decorators/misc/__init__.py,sha256=TDLrR2mZj_oqAcWEqB_C19Hxn8ClrZW2CbuTmJNRblU,553
+click_extended/decorators/misc/__init__.py,sha256=Cl2u81f_dkvHoMoSb82L1KuNVM-3b1lzKHUMAuxhmH0,662
+click_extended/decorators/misc/catch.py,sha256=LkBxGHNo7_RrXjUP0LOTYOLvb9q1fTBIULJJIcYXo4Y,11095
 click_extended/decorators/misc/choice.py,sha256=RTVVjl0YUZ2Ti4j6yoHkUpJ0aqNwcnc3rTfmCVr0y0U,4354
 click_extended/decorators/misc/confirm_if.py,sha256=Rf3HcVVTRqz3sGSiPT02yz65_L351Fzkuw2V6pljlmY,4786
 click_extended/decorators/misc/default.py,sha256=TjZJKmHEqNThzyD6hOjQy2_QgHRenKILnAwfV1V5KAw,2473
@@ -143,9 +144,9 @@ click_extended/utils/naming.py,sha256=kNmzOqidgZZ1dE5aMYrxpWt4VwcLuEiFunpumpfHuZ
 click_extended/utils/process.py,sha256=sU3ZCMjBgjKcDnTRLKPdQ_TAjk0AT7Q8SatagD0JyHA,9729
 click_extended/utils/selection.py,sha256=_OQC88pGPUh29boxmS5ugXEi9jZGqAG180S27PeQaj0,9875
 click_extended/utils/time.py,sha256=H5m5caIEau_1GHkiYgKL_LcTtVdw2TkFVbkqJu7A9rQ,1067
-click_extended-1.0.7.dist-info/licenses/AUTHORS.md,sha256=NkShPinjqtnRDQVRyVnfJuOGM56sejauE3WRoYCcbtw,132
-click_extended-1.0.7.dist-info/licenses/LICENSE,sha256=gjO8hzM4mFSBXFikktaXVSgmXGcre91_GPJ-E_yP56E,1075
-click_extended-1.0.7.dist-info/METADATA,sha256=pVmPjkszY_IAx2DP-RM2i2IkhS28n_g6fkFU9itz8y4,10841
-click_extended-1.0.7.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
-click_extended-1.0.7.dist-info/top_level.txt,sha256=2G3bm6tCNv80okRm773jKTk-_z1ElY-seaozZrn_TxA,15
-click_extended-1.0.7.dist-info/RECORD,,
+click_extended-1.0.9.dist-info/licenses/AUTHORS.md,sha256=NkShPinjqtnRDQVRyVnfJuOGM56sejauE3WRoYCcbtw,132
+click_extended-1.0.9.dist-info/licenses/LICENSE,sha256=gjO8hzM4mFSBXFikktaXVSgmXGcre91_GPJ-E_yP56E,1075
+click_extended-1.0.9.dist-info/METADATA,sha256=nY4Le_lb7iE550nRKd8EoLDp1Jp5nsXqg2gAPgc6jy8,10841
+click_extended-1.0.9.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
+click_extended-1.0.9.dist-info/top_level.txt,sha256=2G3bm6tCNv80okRm773jKTk-_z1ElY-seaozZrn_TxA,15
+click_extended-1.0.9.dist-info/RECORD,,