click-extended 0.0.4__py3-none-any.whl → 0.1.0__py3-none-any.whl

click_extended/__init__.py

@@ -1,7 +1,11 @@
 """Initialization file for the 'click_extended' module."""
 
-from click_extended.core._child_node import ChildNode
+from click_extended.core._child_node import ChildNode, ProcessContext
+from click_extended.core._global_node import GlobalNode
+from click_extended.core._node import Node
 from click_extended.core._parent_node import ParentNode
+from click_extended.core._root_node import RootNode
+from click_extended.core._tree import Tree
 from click_extended.core.argument import argument
 from click_extended.core.command import command
 from click_extended.core.env import env
@@ -11,7 +15,12 @@ from click_extended.core.tag import tag
 
 __all__ = [
     "ChildNode",
+    "ProcessContext",
+    "GlobalNode",
+    "Node",
     "ParentNode",
+    "RootNode",
+    "Tree",
     "argument",
     "command",
     "env",

click_extended/errors.py

@@ -3,21 +3,100 @@
 # pylint: disable=too-many-arguments
 # pylint: disable=too-many-positional-arguments
 
+import typing as t
+
+import click
+from click import ClickException
+from click._compat import get_text_stderr
+from click.utils import echo
+
 
 class ClickExtendedError(Exception):
     """Base exception for exceptions defined in the `click_extended` library."""
 
+
+class CatchableError(ClickExtendedError):
+    """Base exception for exceptions raised inside a child node.
+
+    These exceptions are caught by the framework and reformatted with
+    parameter context before being displayed to the user.
+    """
+
     def __init__(self, message: str) -> None:
         """
-        Initialize a new `ClickExtendedError` instance.
+        Initialize a CatchableError.
 
         Args:
-            message (str):
-                The message to show.
+            message: The error message describing what went wrong.
         """
         super().__init__(message)
 
 
+class ValidationError(CatchableError):
+    """Exception raised when validation fails in a child node."""
+
+
+class TransformError(CatchableError):
+    """Exception raised when transformation fails in a child node."""
+
+
+class ParameterError(ClickException):
+    """Exception raised when parameter validation or transformation fails.
+
+    This exception is raised by the framework after catching a CatchableError
+    and adding parameter context information.
+    """
+
+    exit_code = 2  # Match Click's UsageError exit code
+
+    def __init__(
+        self,
+        message: str,
+        param_hint: str | None = None,
+        ctx: click.Context | None = None,
+    ) -> None:
+        """
+        Initialize a ParameterError.
+
+        Args:
+            message: The error message from the validator/transformer.
+            param_hint: The parameter name (e.g., '--config', 'PATH').
+            ctx: The Click context for displaying usage information.
+        """
+        super().__init__(message)
+        self.param_hint = param_hint
+        self.ctx = ctx
+
+    def format_message(self) -> str:
+        """Format the error message with parameter context."""
+        if self.param_hint:
+            return f"({self.param_hint}): {self.message}"
+        return self.message
+
+    def show(self, file: t.IO[t.Any] | None = None) -> None:
+        """Display the error with usage information (like Click does)."""
+        if file is None:
+            file = get_text_stderr()
+
+        color = None
+
+        if self.ctx is not None:
+            color = self.ctx.color
+
+            echo(self.ctx.get_usage(), file=file, color=color)
+
+            if self.ctx.command.get_help_option(self.ctx) is not None:
+                hint = (
+                    f"Try '{self.ctx.command_path} "
+                    f"{self.ctx.help_option_names[0]}' for help."
+                )
+                echo(hint, file=file, color=color)
+
+            echo("", file=file)
+
+        echo(f"Error {self.format_message()}", file=file, color=color)
+
+
 class NoParentError(ClickExtendedError):
     """Exception raised when no `ParentNode` has been defined."""
 
@@ -126,3 +205,42 @@ class DuplicateNameError(ClickExtendedError):
             f"must be unique within a command."
         )
         super().__init__(message)
+
+
+class TypeMismatchError(ClickExtendedError):
+    """Exception raised when a child node doesn't support the parent's type."""
+
+    def __init__(
+        self,
+        name: str,
+        parent_name: str,
+        parent_type: type | None,
+        supported_types: list[type],
+    ) -> None:
+        """
+        Initialize a new `TypeMismatchError` instance.
+
+        Args:
+            name (str):
+                The name of the decorator.
+            parent_name (str):
+                The name of the parent node.
+            parent_type (type | None):
+                The actual type of the parent.
+            supported_types (list[type]):
+                List of types supported by the child node.
+        """
+
+        def get_type_name(type_obj: type) -> str:
+            """Get type name, handling both regular types and UnionType."""
+            return getattr(type_obj, "__name__", str(type_obj))
+
+        type_names = ", ".join(get_type_name(t) for t in supported_types)
+        parent_type_name = get_type_name(parent_type) if parent_type else "None"
+
+        message = (
+            f"Decorator '{name}' does not support "
+            f"parent '{parent_name}' with type '{parent_type_name}'. "
+            f"Supported types: {type_names}"
+        )
+        super().__init__(message)

click_extended/types.py

@@ -1,10 +1,9 @@
 """Types used in `click_extended` which can be useful for users."""
 
-from click_extended.core._child_node import ChildNode
-from click_extended.core._node import Node
-from click_extended.core._parent_node import ParentNode
-from click_extended.core._root_node import RootNode
-from click_extended.core._tree import Tree
+# pylint: disable=invalid-name
+
+from typing import TYPE_CHECKING, Any, Callable
+
 from click_extended.core.argument import Argument
 from click_extended.core.command import Command
 from click_extended.core.env import Env
@@ -12,17 +11,17 @@ from click_extended.core.group import Group
 from click_extended.core.option import Option
 from click_extended.core.tag import Tag
 
+if TYPE_CHECKING:
+    from click_extended.core._parent_node import ParentNode
+
 Tags = dict[str, Tag]
 Siblings = list[str]
-Parent = ParentNode | Tag
+Parent = "ParentNode | Tag"
+Decorator = Callable[[Callable[..., Any]], Callable[..., Any]]
 
 __all__ = [
-    "ChildNode",
-    "Node",
+    "Decorator",
     "Parent",
-    "ParentNode",
-    "RootNode",
-    "Tree",
     "Argument",
     "Command",
     "Env",

{click_extended-0.0.4.dist-info → click_extended-0.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: click_extended
-Version: 0.0.4
+Version: 0.1.0
 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
@@ -80,10 +80,10 @@ An extension of the [Click](https://github.com/pallets/click) library with addit
 ## Features
 
 - **Aliasing**: Add multiple aliases to a group or command.
-- **Async supprt**: Automatically run both synchronous and asynchronous functions.
+- **Async support**: Automatically run both synchronous and asynchronous functions.
 - **Extensible decorator API**: Extend the Click decorator API with custom decorators like validators, transformers, and more.
+- **Type-hint First**: Built using the type-hinting system to it's full potential.
 - **Environment variables**: Automatically validate and inject environment variables into the function.
-- **Fully type-hinted**: The library is fully type-hinted and provides good types for easy development.
 - **Help alias**: The `-h` and `--help` automatically show the help menu unless overridden.
 
 ## Installation
@@ -191,17 +191,18 @@ $ python app.py
 Using token: secret12...
 ```
 
-### Value Validation
+### Custom Validators
 
 ```python
-from click_extended import command, option, ChildNode
+from click_extended import command, option, ChildNode, ProcessContext
+from click_extended.errors import ValidationError
 
 class IsPositive(ChildNode):
     """Validate that a number is positive."""
 
-    def process(self, value, *args, **kwargs):
+    def process(self, value: float | int, context: ProcessContext):
         if value <= 0:
-            raise ValueError(f"Value must be positive, got {value}")
+            raise ValidationError(f"{value} is not positive")
 
 def is_positive(*args, **kwargs):
     """Validate positive numbers."""
@@ -222,7 +223,10 @@ if __name__ == "__main__":
 $ python app.py --count 5
 Processing 5 items
 $ python app.py --count -1
-Error: Value must be positive, got -1
+Usage: app.py [OPTIONS]
+Try 'app.py --help' for help.
+
+Error (--count): -1 is not positive
 ```
 
 ## Documentation

click_extended-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+click_extended/__init__.py,sha256=wBUV7-CmgDBKSnDj3_MbYCjHv2zAaATQ795Y9Xs-0NE,858
+click_extended/errors.py,sha256=hHKYsi61__uksU33-S80gANZg2ZsoHGhLdz6qR49r-I,7774
+click_extended/types.py,sha256=tiz-toTYABwFTsxUMIDRhPiq3H_V3nhrAcV8VGEKyzA,786
+click_extended-0.1.0.dist-info/licenses/AUTHORS.md,sha256=NkShPinjqtnRDQVRyVnfJuOGM56sejauE3WRoYCcbtw,132
+click_extended-0.1.0.dist-info/licenses/LICENSE,sha256=gjO8hzM4mFSBXFikktaXVSgmXGcre91_GPJ-E_yP56E,1075
+click_extended-0.1.0.dist-info/METADATA,sha256=-nzGqQFMk7dsfpMQIiVD7edfV3yGZVvRuymWP73WiSk,8295
+click_extended-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+click_extended-0.1.0.dist-info/top_level.txt,sha256=2G3bm6tCNv80okRm773jKTk-_z1ElY-seaozZrn_TxA,15
+click_extended-0.1.0.dist-info/RECORD,,

click_extended-0.0.4.dist-info/RECORD

@@ -1,9 +0,0 @@
-click_extended/__init__.py,sha256=dqtS3EH0att5KwxtbvkSdvN9CzvISgys6YT1OAzgsT8,568
-click_extended/errors.py,sha256=nFhxTtEHYJBO1tWwx1YdMwEKFvenEOD5dLfuZY9yCzI,4099
-click_extended/types.py,sha256=Xed59Ss7tRr0RQOXCgqRIAMCI7uopkOY4LrvT43Qu40,867
-click_extended-0.0.4.dist-info/licenses/AUTHORS.md,sha256=NkShPinjqtnRDQVRyVnfJuOGM56sejauE3WRoYCcbtw,132
-click_extended-0.0.4.dist-info/licenses/LICENSE,sha256=gjO8hzM4mFSBXFikktaXVSgmXGcre91_GPJ-E_yP56E,1075
-click_extended-0.0.4.dist-info/METADATA,sha256=lhsHDcllPzdiP-7pcQGi4wCCGr5kmbzpGcR1zo_lfA4,8181
-click_extended-0.0.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-click_extended-0.0.4.dist-info/top_level.txt,sha256=2G3bm6tCNv80okRm773jKTk-_z1ElY-seaozZrn_TxA,15
-click_extended-0.0.4.dist-info/RECORD,,