click-extended 0.3.1__py3-none-any.whl → 0.4.0__py3-none-any.whl

click_extended/__init__.py

@@ -1,11 +1,5 @@
 """Initialization file for the 'click_extended' module."""
 
-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
@@ -14,13 +8,6 @@ from click_extended.core.option import option
 from click_extended.core.tag import tag
 
 __all__ = [
-    "ChildNode",
-    "ProcessContext",
-    "GlobalNode",
-    "Node",
-    "ParentNode",
-    "RootNode",
-    "Tree",
     "argument",
     "command",
     "env",

click_extended/classes.py

@@ -0,0 +1,21 @@
+"""Classes used in `click_extended`."""
+
+from click_extended.core.argument_node import ArgumentNode
+from click_extended.core.child_node import ChildNode
+from click_extended.core.command import Command
+from click_extended.core.group import Group
+from click_extended.core.node import Node
+from click_extended.core.option_node import OptionNode
+from click_extended.core.parent_node import ParentNode
+from click_extended.core.tag import Tag
+
+__all__ = [
+    "Node",
+    "ChildNode",
+    "ParentNode",
+    "ArgumentNode",
+    "OptionNode",
+    "Command",
+    "Group",
+    "Tag",
+]

click_extended/errors.py

@@ -1,334 +1,450 @@
-"""Exceptions used in the `click_extended` library."""
+"""Error module for the `click_extended` library."""
 
-# pylint: disable=too-many-arguments
-# pylint: disable=too-many-positional-arguments
-
-import inspect
-from typing import IO, Any
+import sys
+from typing import Any
 
 import click
-from click import ClickException
-from click._compat import get_text_stderr
 from click.utils import echo
 
-from click_extended.utils.format import format_list
+from click_extended.utils.humanize import humanize_iterable
 
 
 class ClickExtendedError(Exception):
-    """Base exception for exceptions defined in the `click_extended` library."""
-
+    """Base exception for all click-extended errors."""
 
-# Catchable errors
-class CatchableError(ClickExtendedError):
-    """Base exception for exceptions raised inside a child node.
+    def __init__(self, message: str, tip: str | None = None) -> None:
+        """
+        Initialize a ClickExtendedError.
 
-    These exceptions are caught by the framework and reformatted with
-    parameter context before being displayed to the user.
-    """
+        Args:
+            message (str):
+                The error message describing what went wrong.
+            tip (str):
+                Optional helpful guidance for resolving the error.
+        """
+        self.message = message
+        self.tip = tip
+        super().__init__(message)
 
-    def __init__(self, message: str) -> None:
+    def show(self, file: Any = None) -> None:
         """
-        Initialize a CatchableError.
+        Display the error message.
+
+        Subclasses should override this to provide custom formatting.
 
         Args:
-            message: The error message describing what went wrong.
+            file (Any, optional):
+                The file to write to (defaults to sys.stderr).
         """
-        super().__init__(message)
+        if file is None:
+            file = sys.stderr
+
+        echo(f"Error: {self.message}", file=file)
 
+        if self.tip:
+            echo(f"\nTip: {self.tip}", file=file)
 
-class ChildNodeProcessError(CatchableError):
+
+class ContextAwareError(ClickExtendedError):
     """
-    Base class for exceptions which must be raised inside
-    the `process()` method of a `ChildNode`.
+    Base exception for errors that occur within Click context.
+
+    These errors have access to the full node hierarchy and are formatted
+    with Click-style usage information and node context.
+
+    It can only be raised during `phase 3` or `phase 4`.
     """
 
-    def __init__(self, message: str, **kwargs: str) -> None:
+    context: click.Context | None
+
+    def __init__(self, message: str, tip: str | None = None) -> None:
         """
-        Initialize a new `ChildNodeProcessError` instance.
+        Initialize a new `ContextAwareError` instance.
 
         Args:
             message (str):
-                The error message. If child_name is found, it will be
-                prefixed automatically. Subclasses can access child_name
-                via self.child_name to format custom messages.
+                The error message describing what went wrong.
+            tip (str):
+                Optional helpful guidance for resolving the error.
+        """
+        super().__init__(message, tip)
+        try:
+            self.context = click.get_current_context()
+            self._node_name = self._resolve_node_name()
+        except RuntimeError:
+            self.context = None
+            self._node_name = "unknown"
+
+    def _resolve_node_name(self) -> str:
+        """
+        Get the most specific node name from context.
 
-        Raises:
-            RuntimeError:
-                If raised outside a ChildNode context.
+        If inside a child node, that will be used, otherwise it checks if a
+        parent is defined, and if not that, the root node will be used.
+
+        Returns:
+            str:
+                The name of the most specific node in the current scope.
         """
-        self.child_name: str | None = None
-        frame = inspect.currentframe()
-
-        if frame:
-            current_frame = frame.f_back
-            depth = 0
-            max_depth = 10
-
-            while current_frame and depth < max_depth:
-                caller_locals = current_frame.f_locals
-                if "self" in caller_locals:
-                    self_obj = caller_locals["self"]
-                    if hasattr(self_obj, "name") and hasattr(
-                        self_obj, "process"
-                    ):
-                        self.child_name = self_obj.name
-                        break
-                current_frame = current_frame.f_back
-                depth += 1
-
-        if not self.child_name:
-            raise RuntimeError(
-                f"{self.__class__.__name__} must be raised from within a "
-                f"ChildNode.process() method. The exception was raised outside "
-                f"a valid ChildNode context."
-            )
+        if self.context is None:
+            return "unknown"
 
-        formatted_message = message.format(name=self.child_name, **kwargs)
-        super().__init__(formatted_message)
+        meta = self.context.meta.get("click_extended", {})
 
+        if meta.get("child_node"):
+            return str(meta["child_node"].name)
+        if meta.get("parent_node"):
+            return str(meta["parent_node"].name)
+        if meta.get("root_node"):
+            return str(meta["root_node"].name)
 
-class UnhandledValueError(ChildNodeProcessError):
-    """Exception raised when a value in the `process()` method is unexpected."""
+        return "unknown"
 
-    def __init__(self, value: Any) -> None:
+    def show(self, file: Any = None) -> None:
         """
-        Initialize a new `UnhandledValueError` instance.
+        Display the error with Click-style formatting.
+
+        Format:
+            Usage: cli [OPTIONS] COMMAND [ARGS]...
+            Try 'cli --help' for help.
+
+            Error (node_name): message
+            Tip: helpful guidance
 
         Args:
-            value (Any):
-                The unexpected value.
+            file (Any, optional):
+                The file to write to (defaults to `sys.stderr`).
         """
-        message = "Received unexpected value for '{name}' of type '{type}'"
-        super().__init__(message, type=type(value).__name__)
+        if file is None:
+            file = sys.stderr
 
+        if self.context is None:
+            super().show(file)
+            return
 
-class ValidationError(CatchableError):
-    """Exception raised when validation fails in a child node."""
+        echo(self.context.get_usage(), file=file, color=self.context.color)
 
+        if self.context.command.get_help_option(self.context) is not None:
+            hint = f"Try '{self.context.command_path} --help' for help."
+            echo(hint, file=file, color=self.context.color)
 
-class TransformError(CatchableError):
-    """Exception raised when transformation fails in a child node."""
+        echo("", file=file)
 
+        exception_name = self.__class__.__name__
+        echo(
+            f"{exception_name} ({self._node_name}): {self.message}",
+            file=file,
+            color=self.context.color,
+        )
 
-class UnknownError(ChildNodeProcessError):
-    """
-    Exception raised when an unexpected error occurs or parts of code
-    which is unhandled.
-    """
+        if self.tip:
+            echo(f"Tip: {self.tip}", file=file, color=self.context.color)
 
 
-class ParameterError(ClickException):
-    """Exception raised when parameter validation or transformation fails.
+class MissingValueError(ContextAwareError):
+    """
+    Exception raised when a value is missing.
 
-    This exception is raised by the framework after catching a CatchableError
-    and adding parameter context information.
+    This exception is context-aware and can only be raised during `phase 3` or
+    `phase 4`.
     """
 
-    exit_code = 2
+    def __init__(self) -> None:
+        """Initialize a new `MissingValueError` instance."""
+        super().__init__(
+            message="Value not provided.", tip=self._generate_tip()
+        )
 
-    def __init__(
-        self,
-        message: str,
-        param_hint: str | None = None,
-        ctx: click.Context | None = None,
-    ) -> None:
-        """
-        Initialize a ParameterError.
+    def _generate_tip(self) -> str:
+        """Generate a context-aware tip based on the parent node type."""
+        try:
+            ctx = click.get_current_context()
+            meta = ctx.meta.get("click_extended", {})
 
-        Args:
-            message (str):
-                The error message from the validator/transformer.
-            param_hint (str, optional):
-                The parameter name (e.g., '--config', 'PATH').
-            ctx (click.Context, optional):
-                The Click context for displaying usage information.
-        """
-        super().__init__(message)
-        self.param_hint = param_hint
-        self.ctx = ctx
+            parent = meta.get("parent_node")
 
-    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
+            if parent is not None:
+                return self._tip_for_parent(parent)
+        except (RuntimeError, AttributeError):
+            pass
 
-    def show(self, file: IO[Any] | None = None) -> None:
-        """Display the error with usage information (like Click does)."""
-        if file is None:
-            file = get_text_stderr()
+        return (
+            "Provide a value or set the default parameter to make it optional."
+        )
 
-        color = None
+    # pylint: disable=too-many-return-statements
+    def _tip_for_parent(self, parent: Any) -> str:
+        """Generate tip based on parent type."""
+        parent_type = parent.__class__.__name__
+        parent_name = parent.name
 
-        if self.ctx is not None:
-            color = self.ctx.color
+        if parent_type == "Option":
+            return "".join(
+                f"Use --{parent_name.replace('_', '-')} to specify a value, "
+                "or set the default parameter to make it optional."
+            )
+        if parent_type == "Argument":
+            return "".join(
+                f"Provide the {parent_name} argument, or set the default "
+                "parameter to make it optional."
+            )
+        if parent_type == "Env":
+            env_var = getattr(parent, "env_name", parent_name.upper())
+            return "".join(
+                f"Set the {env_var} environment variable, or set the "
+                f"default parameter to make it optional."
+            )
+        return "".join(
+            "Provide a value or set the default parameter to "
+            "make it optional."
+        )
 
-            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)
+class NoRootError(ContextAwareError):
+    """Exception raised when no root node has been defined."""
 
-            echo("", file=file)
+    def __init__(self, tip: str | None = None) -> None:
+        """
+        Initialize a new `NoRootError` instance.
 
-        echo(f"Error {self.format_message()}", file=file, color=color)
+        Args:
+            tip (str):
+                Optional helpful guidance (defaults to standard tip).
+        """
+        super().__init__(
+            "No root node has been defined",
+            tip=tip or "Use @click_extended.root() decorator first",
+        )
 
 
-# Node errors
-class NoParentError(ClickExtendedError):
-    """Exception raised when no `ParentNode` has been defined."""
+class NoParentError(ContextAwareError):
+    """Exception raised when a child node has no parent to attach to."""
 
-    def __init__(self, name: str) -> None:
+    def __init__(self, child_name: str, tip: str | None = None) -> None:
         """
         Initialize a new `NoParentError` instance.
 
         Args:
-            name (str):
+            child_name (str):
                 The name of the child node.
+            tip (str):
+                Optional helpful guidance (defaults to standard tip).
         """
-
-        message = (
-            f"Failed to register the child node '{name}' as no parent is "
-            "defined. Ensure a parent node is registered before registering a "
-            "child node."
+        tip_msg = (
+            tip
+            or "Ensure a parent node (option/argument) is defined "
+            "before child nodes"
+        )
+        super().__init__(
+            f"Cannot register child node '{child_name}' "
+            f"as no parent is defined",
+            tip=tip_msg,
         )
-        super().__init__(message)
-
-
-class NoRootError(ClickExtendedError):
-    """Exception raised when there is no `RootNode` defined."""
-
-    def __init__(self, message: str | None = None) -> None:
-        """Initialize a new `NoRootError` instance."""
-        super().__init__(message or "No root node is defined in the tree.")
 
 
-class ParentNodeExistsError(ClickExtendedError):
-    """Exception raised when a parent node already exists with the same name."""
+class RootExistsError(ContextAwareError):
+    """Exception raised when attempting to define multiple root nodes."""
 
-    def __init__(self, name: str) -> None:
+    def __init__(self, tip: str | None = None) -> None:
         """
-        Initialize a new `ParentNodeExistsError` instance.
+        Initialize a new `RootExistsError` instance.
 
         Args:
-            name (str):
-                The name of the parent node.
+            tip (str, optional):
+                Optional helpful guidance (defaults to standard tip).
         """
-        message = (
-            f"Cannot register parent node '{name}' as a parent node with this "
-            "name already exists. "
-            f"Parent node names must be unique within the tree."
+        super().__init__(
+            "A root node has already been defined",
+            tip=tip or "Only one @root() decorator is allowed per command",
         )
-        super().__init__(message)
 
 
-class RootNodeExistsError(ClickExtendedError):
-    """Exception raised when a root node already exists for the tree."""
+class ParentExistsError(ContextAwareError):
+    """Exception raised when attempting to register duplicate parent names."""
 
-    def __init__(self) -> None:
-        """Initialize a new `RootNodeExistsError` instance."""
-        message = (
-            "Cannot register root node as a root node has already been "
-            "defined. Only one root node is allowed per tree instance."
+    def __init__(self, name: str, tip: str | None = None) -> None:
+        """
+        Initialize a new `ParentExistsError` instance.
+
+        Args:
+            name (str):
+                The name of the duplicate parent node.
+            tip (str | None, optional):
+                Optional helpful guidance (defaults to standard tip).
+        """
+        super().__init__(
+            f"Parent node '{name}' already exists",
+            tip=tip or "Parent node names must be unique within a command",
         )
-        super().__init__(message)
 
 
-class InvalidChildOnTagError(ClickExtendedError):
-    """Exception raised when a transformation child is attached to a tag."""
+class TypeMismatchError(ContextAwareError):
+    """
+    Exception raised when a child's process() signature is incompatible
+    with the parent's type.
+    """
 
-    def __init__(self, child_name: str, tag_name: str) -> None:
+    # pylint: disable=too-many-arguments
+    # pylint: disable=too-many-positional-arguments
+    def __init__(
+        self,
+        child_name: str,
+        parent_name: str,
+        parent_type: str,
+        supported_types: list[str],
+        tip: str | None = None,
+    ) -> None:
         """
-        Initialize a new `InvalidChildOnTagError` instance.
+        Initialize a new `TypeMismatchError` instance.
 
         Args:
             child_name (str):
                 The name of the child node.
-            tag_name (str):
-                The name of the tag.
+            parent_name (str):
+                The name of the parent node.
+            parent_type (str):
+                The type of the parent (as string).
+            supported_types (list[str]):
+                List of supported type names.
+            tip (str | None, optional):
+                Optional helpful guidance (defaults to supported types).
         """
         message = (
-            f"Cannot attach transformation child '{child_name}' to tag "
-            f"'{tag_name}'. Tags can only have validation-only children "
-            "(no return statement or return None)."
+            f"Child '{child_name}' does not support parent '{parent_name}' "
+            f"with type '{parent_type}'"
         )
-        super().__init__(message)
 
+        if tip is None:
+            types_str = ", ".join(f"<{t}>" for t in supported_types)
+            tip = f"Supported types: {types_str}"
 
-class DuplicateNameError(ClickExtendedError):
+        super().__init__(message, tip=tip)
+
+
+class NameExistsError(ContextAwareError):
     """Exception raised when a name collision is detected."""
 
-    def __init__(
-        self, name: str, type1: str, type2: str, location1: str, location2: str
-    ) -> None:
+    def __init__(self, name: str, tip: str | None = None) -> None:
         """
-        Initialize a new `DuplicateNameError` instance.
+        Initialize a new `NameExistsError` instance.
 
         Args:
             name (str):
                 The conflicting name.
-            type1 (str):
-                The type of the first node (e.g., "option", "tag").
-            type2 (str):
-                The type of the second node.
-            location1 (str):
-                Description of where the first node is defined.
-            location2 (str):
-                Description of where the second node is defined.
+            tip (str | None, optional):
+                Optional helpful guidance (defaults to standard tip).
         """
-        message = (
-            f"The name '{name}' is used by both "
-            f"{type1} {location1} and {type2} {location2}. "
-            f"All names (options, arguments, environment variables, and tags) "
-            f"must be unique within a command."
+        super().__init__(
+            f"The name '{name}' is already used",
+            tip=tip or "All names 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."""
+class UnhandledTypeError(ContextAwareError):
+    """
+    Exception raised when a child node doesn't implement a handler
+    for the value type.
+    """
 
     def __init__(
         self,
-        name: str,
-        parent_name: str,
-        parent_type: type | None,
-        supported_types: list[type],
+        child_name: str,
+        value_type: str,
+        implemented_handlers: list[str],
+        tip: str | None = None,
     ) -> None:
         """
-        Initialize a new `TypeMismatchError` instance.
+        Initialize a new `UnhandledTypeError` 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.
+            child_name (str):
+                The name of the child node.
+            value_type (str):
+                The type of value that couldn't be handled.
+            implemented_handlers (list[str]):
+                List of handler names that are implemented.
+            tip (str, optional):
+                Optional helpful guidance (defaults to list of handlers).
         """
+        message = "Child '{}' does not handle values of type '{}'."
+        message = message.format(child_name, value_type)
+
+        if tip is None:
+            if implemented_handlers:
+                tip = (
+                    f"Missing handler for '{value_type}', only "
+                    + humanize_iterable(
+                        implemented_handlers,
+                        wrap="'",
+                        suffix_singular=" is supported.",
+                        suffix_plural=" are supported.",
+                    )
+                )
+            else:
+                tip = "".join(
+                    "No handlers are implemented. Override handle_all() "
+                    "or a specific handler method."
+                )
 
-        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))
+        super().__init__(message, tip=tip)
 
-        parent_type_name = get_type_name(parent_type) if parent_type else "None"
 
-        type_names = [get_type_name(t) for t in supported_types]
-        formatted_types = format_list(
-            type_names,
-            prefix_singular="Supported type is ",
-            prefix_plural="Supported types are ",
-            wrap=("<", ">"),
-        )
+class ProcessError(ContextAwareError):
+    """
+    Exception raised when user code in `child.process()` raises an exception.
 
-        message = (
-            f"Decorator '{name}' does not support "
-            f"parent '{parent_name}' with type '{parent_type_name}'. "
-            f"{formatted_types}"
+    This error wraps standard Python exceptions (ValueError, TypeError, etc.)
+    raised by user code and adds node context for better error messages.
+    """
+
+    def __init__(self, message: str, tip: str | None = None) -> None:
+        """
+        Initialize a new `ProcessError` instance.
+
+        Args:
+            message (str):
+                The error message from the wrapped exception.
+            tip (str | None, optional):
+                Optional helpful guidance for resolving the error.
+        """
+        super().__init__(message, tip=tip)
+
+
+class InvalidHandlerError(ContextAwareError):
+    """Exception raised when a handler returns an invalid value."""
+
+    def __init__(self, message: str, tip: str | None = None) -> None:
+        """
+        Initialize an new `InvalidHandlerError` instance.
+
+        Args:
+            message (str):
+                Description of the invalid handler behavior.
+            tip (str | None, optional):
+                Optional helpful guidance for correcting the handler.
+        """
+        super().__init__(message, tip=tip)
+
+
+class InternalError(ContextAwareError):
+    """
+    Exception raised for unexpected errors in framework code.
+
+    This indicates a bug in `click-extended` or an unreachable code path.
+    """
+
+    def __init__(self, message: str, tip: str | None = None) -> None:
+        """
+        Initialize a new `InternalError` instance.
+
+        Args:
+            message (str):
+                Description of the internal error.
+            tip (str | None, optional):
+                Optional helpful guidance (defaults to bug report message).
+        """
+        super().__init__(
+            message,
+            tip=tip
+            or "This is likely a bug in click-extended. Please report it.",
         )
-        super().__init__(message)

click_extended/types.py

@@ -1,33 +1,12 @@
-"""Types used in `click_extended` which can be useful for users."""
+"""Types used in `click_extended`."""
 
-# pylint: disable=invalid-name
+from typing import Any, Callable
 
-from typing import TYPE_CHECKING, Any, Callable
+from click_extended.core.context import Context
 
-from click_extended.core.argument import Argument
-from click_extended.core.command import Command
-from click_extended.core.env import Env
-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"
 Decorator = Callable[[Callable[..., Any]], Callable[..., Any]]
 
 __all__ = [
+    "Context",
     "Decorator",
-    "Parent",
-    "Argument",
-    "Command",
-    "Env",
-    "Group",
-    "Option",
-    "Siblings",
-    "Tag",
-    "Tags",
 ]

click_extended-0.4.0.dist-info/METADATA

@@ -0,0 +1,261 @@
+Metadata-Version: 2.4
+Name: click_extended
+Version: 0.4.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
+        
+        Copyright (c) 2025 Marcus Fredriksson
+        
+        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/marcusfrdk/click-extended
+Project-URL: Repository, https://github.com/marcusfrdk/click-extended
+Project-URL: Issues, https://github.com/marcusfrdk/click-extended/issues
+Keywords: click,cli,command-line,alias,aliasing,command,group,decorator,terminal,console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Shells
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: AUTHORS.md
+Requires-Dist: click>=8.3.0
+Requires-Dist: python-dotenv>=1.2.1
+Provides-Extra: build
+Requires-Dist: build; extra == "build"
+Requires-Dist: twine; extra == "build"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.4.2; extra == "dev"
+Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.2.0; extra == "dev"
+Requires-Dist: mypy>=1.18.2; extra == "dev"
+Requires-Dist: pylint>=3.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: black>=25.9.0; extra == "dev"
+Requires-Dist: pre-commit>=4.3.0; extra == "dev"
+Dynamic: license-file
+
+![Banner](./assets/click-extended-banner.png)
+
+# Click Extended
+
+![top language](https://img.shields.io/github/languages/top/marcusfrdk/click-extended)
+![code size](https://img.shields.io/github/languages/code-size/marcusfrdk/click-extended)
+![last commit](https://img.shields.io/github/last-commit/marcusfrdk/click-extended)
+![tests](https://github.com/marcusfrdk/click-extended/actions/workflows/tests.yml/badge.svg)
+![release](https://github.com/marcusfrdk/click-extended/actions/workflows/release.yml/badge.svg)
+![issues](https://img.shields.io/github/issues/marcusfrdk/click-extended)
+![contributors](https://img.shields.io/github/contributors/marcusfrdk/click-extended)
+![pypi](https://img.shields.io/pypi/v/click-extended)
+![license](https://img.shields.io/github/license/marcusfrdk/click-extended)
+![downloads](https://static.pepy.tech/badge/click-extended)
+![monthly downloads](https://static.pepy.tech/badge/click-extended/month)
+
+An extension of the [Click](https://github.com/pallets/click) library with additional features like aliasing, asynchronous support, an extended decorator API and more.
+
+## Features
+
+- **Decorator API**: Extend the functionality your command line by adding custom data sources, data processing pipelines, and more.
+- **Aliasing**: Use aliases for groups and commands to reduce boilerplate and code repetition.
+- **Tags**: Use tags to group several data sources together to apply batch processing.
+- **Async Support**: Native support for declaring functions and methods asynchronous.
+- **Environment Variables**: Built-in support for loading and using environment variables as a data source.
+- **Full Type Support**: Built with type-hinting from the ground up, meaning everything is fully typed.
+- **Improved Errors**: Improved error output like tips, debugging, and more.
+
+## Installation
+
+```bash
+pip install click-extended
+```
+
+## Requirements
+
+- **Python**: 3.10 or higher
+
+## Quick Start
+
+### Basic Command
+
+```python
+from click_extended import command, argument, option
+
+@command(aliases="ping")
+@argument("value")
+@option("--count", "-c", default=1)
+def my_function(value: str, count: int):
+    """This is the help message for my_function."""
+    if _ in range(count):
+        print(value)
+
+if __name__ == "__main__":
+    my_function()
+
+# $ python cli.py "Hello world"
+# Hello world
+
+# $ python cli.py "Hello world" --count 3
+# Hello world
+# Hello world
+# Hello world
+```
+
+### Basic Command Line Interface
+
+```python
+from click_extended import group, argument, option
+
+@group()
+def my_group():
+    """This is the help message for my_group."""
+    print("Running initialization code...")
+
+@my_group.command(aliases=["ping", "repeat"])
+@argument("value")
+@option("--count", "-c", default=1)
+def my_function(value: str, count: int):
+    """This is the help message for my_function."""
+    if _ in range(count):
+        print(value)
+
+if __name__ == "__main__":
+    my_group()
+
+# $ python cli.py my_function "Hello world"
+# Running initialization code...
+# Hello world
+
+# $ python cli.py my_function "Hello world" --count 3
+# Running initialization code...
+# Hello world
+# Hello world
+# Hello world
+```
+
+### Using Environment Variables
+
+```python
+from click_extended import group, command, env
+
+@group()
+def my_group():
+    """This is the help message for my_group."""
+
+@my_group.command()
+@env("API_KEY")
+def my_function_1(api_key: str | None):
+    """This is the help message for my_function."""
+    print(f"The API key is: {api_key}")
+
+@my_group.command()
+@env("API_KEY", required=True)
+def my_function_2(api_key: str):
+    """This is the help message for my_function."""
+    print(f"The API key is: {api_key}")
+
+if __name__ == "__main__":
+    my_group()
+
+# $ python cli.py my_function_1
+# The API key is: None
+
+# $ API_KEY=api-key python cli.py my_function_1
+# The API key is: api-key
+
+# $ python cli.py my_function_2
+# ProcessError (my_function_2): Required environment variable 'API_KEY' is not set.
+
+# $ API_KEY=api-key python cli.py my_function_2
+# The API key is: api-key
+```
+
+### Custom Children
+
+```python
+from typing import Any
+
+from click_extended import group, argument, option
+from click_extended.classes import ChildNode
+from click_extended.types import Context, Decorator
+
+class MyCustomChild(ChildNode):
+    def handle_primitive(
+        self,
+        value: str,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> str:
+        if value == "invalid":
+            raise ValueError("The value 'invalid' is not valid")
+
+        return value.upper()
+
+def my_custom_child() -> Decorator:
+    """Checks if the value is invalid and converts it to uppercase."""
+    return MyCustomChild.as_decorator()
+
+
+@group()
+def my_group():
+    """This is the help message for my_group."""
+    print("Running initialization code...")
+
+@my_group.command(aliases=["ping", "repeat"])
+@argument("value")
+@my_custom_child()
+def my_function(value: str):
+    """This is the help message for my_function."""
+    print(f"The value '{value}' should be uppercase.")
+
+if __name__ == "__main__":
+    my_group()
+
+# $ python cli.py my_function valid
+# The value 'VALID' should be uppercase.
+
+# $ python cli.py my_function invalid
+# ValueError (my_function): "The value 'invalid' is not valid"
+```
+
+## Documentation
+
+The full documentation is [available here](./docs/README.md) and goes through the full library, from explaining design choices, how to use the library, and much more.
+
+## Contributing
+
+Contributors are more than welcome to work on this project. Read the [contribution documentation](./CONTRIBUTING.md) to learn more.
+
+## License
+
+This project is licensed under the MIT License, see the [license file](./LICENSE) for details.
+
+## Acknowledgements
+
+This project is built on top of the [Click](https://github.com/pallets/click) library.

click_extended-0.4.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+click_extended/__init__.py,sha256=WC8SbG5_xnIKiEgdnTNWBR03hbXlJNF0FEz5gZyNfag,423
+click_extended/classes.py,sha256=6qc3cY0iS4WS5jQkKwcQCOYn_jl7t4j8DzykqzRCURw,576
+click_extended/errors.py,sha256=tkvAXs4oUZ8SFgX37KhYrHAlsxmOGrSFLIezCH9NDQI,13897
+click_extended/types.py,sha256=ZYRHjA_wWiLcZ80AYwiVw-kEaHTKSWHKozfPEVay_WE,232
+click_extended-0.4.0.dist-info/licenses/AUTHORS.md,sha256=NkShPinjqtnRDQVRyVnfJuOGM56sejauE3WRoYCcbtw,132
+click_extended-0.4.0.dist-info/licenses/LICENSE,sha256=gjO8hzM4mFSBXFikktaXVSgmXGcre91_GPJ-E_yP56E,1075
+click_extended-0.4.0.dist-info/METADATA,sha256=ffz3zK1urIlLLYS10HMgXAy4_-kkqOLPWXmwmu-roIU,8860
+click_extended-0.4.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+click_extended-0.4.0.dist-info/top_level.txt,sha256=2G3bm6tCNv80okRm773jKTk-_z1ElY-seaozZrn_TxA,15
+click_extended-0.4.0.dist-info/RECORD,,

click_extended-0.3.1.dist-info/METADATA

@@ -1,257 +0,0 @@
-Metadata-Version: 2.4
-Name: click_extended
-Version: 0.3.1
-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
-        
-        Copyright (c) 2025 Marcus Fredriksson
-        
-        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/marcusfrdk/click-extended
-Project-URL: Repository, https://github.com/marcusfrdk/click-extended
-Project-URL: Issues, https://github.com/marcusfrdk/click-extended/issues
-Keywords: click,cli,command-line,alias,aliasing,command,group,decorator,terminal,console
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-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: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Topic :: System :: Shells
-Classifier: Topic :: Utilities
-Classifier: Typing :: Typed
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-License-File: AUTHORS.md
-Requires-Dist: click>=8.3.0
-Requires-Dist: python-dotenv>=1.2.1
-Provides-Extra: build
-Requires-Dist: build; extra == "build"
-Requires-Dist: twine; extra == "build"
-Provides-Extra: dev
-Requires-Dist: pytest>=8.4.2; extra == "dev"
-Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
-Requires-Dist: pytest-asyncio>=1.2.0; extra == "dev"
-Requires-Dist: mypy>=1.18.2; extra == "dev"
-Requires-Dist: pylint>=3.0.0; extra == "dev"
-Requires-Dist: isort>=5.12.0; extra == "dev"
-Requires-Dist: black>=25.9.0; extra == "dev"
-Requires-Dist: pre-commit>=4.3.0; extra == "dev"
-Dynamic: license-file
-
-![Banner](./assets/click-extended-banner.png)
-
-# Click Extended
-
-![top language](https://img.shields.io/github/languages/top/marcusfrdk/click-extended)
-![code size](https://img.shields.io/github/languages/code-size/marcusfrdk/click-extended)
-![last commit](https://img.shields.io/github/last-commit/marcusfrdk/click-extended)
-![issues](https://img.shields.io/github/issues/marcusfrdk/click-extended)
-![contributors](https://img.shields.io/github/contributors/marcusfrdk/click-extended)
-![PyPI](https://img.shields.io/pypi/v/click-extended)
-![License](https://img.shields.io/github/license/marcusfrdk/click-extended)
-![Downloads](https://static.pepy.tech/badge/click-extended)
-![Monthly Downloads](https://static.pepy.tech/badge/click-extended/month)
-
-An extension of the [Click](https://github.com/pallets/click) library with additional features like aliasing, asynchronous support, an extended decorator API and more.
-
-## Features
-
-- **Aliasing**: Add multiple aliases to a group or command.
-- **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.
-- **Help alias**: The `-h` and `--help` automatically show the help menu unless overridden.
-
-## Installation
-
-```bash
-pip install click-extended
-```
-
-## Requirements
-
-- **Python**: 3.10 or higher
-
-## Quick Start
-
-### Basic Command
-
-```python
-from click_extended import command, option
-
-@command()
-@option("--name", default="World", help="Name to greet")
-@option("--count", type=int, default=1, help="Number of greetings")
-def greet(name: str, count: int):
-    """Greet someone multiple times."""
-    for _ in range(count):
-        print(f"Hello, {name}!")
-
-if __name__ == "__main__":
-    greet()
-```
-
-```bash
-$ python app.py --name Alice --count 3
-Hello, Alice!
-Hello, Alice!
-Hello, Alice!
-```
-
-### Async Support
-
-```python
-import asyncio
-
-from click_extended import command, option
-
-@command()
-@option("--url", required=True, help="URL to fetch")
-async def fetch(url: str):
-    """Fetch data from a URL asynchronously."""
-    await asyncio.sleep(1)
-    print(f"Fetched data from {url}")
-
-if __name__ == "__main__":
-    fetch()
-```
-
-### Command Aliases
-
-```python
-from click_extended import command, option
-
-@command(aliases=["hi", "hello"])
-@option("--name", default="World")
-def greet(name: str):
-    """Greet someone."""
-    print(f"Hello, {name}!")
-
-if __name__ == "__main__":
-    greet()
-```
-
-```bash
-$ python app.py greet --name Alice
-Hello, Alice!
-$ python app.py hi --name Bob
-Hello, Bob!
-$ python app.py hello --name Charlie
-Hello, Charlie!
-```
-
-### Environment Variables
-
-Environment variables are automatically loaded from the `.env` file, but as long as the variable is defined in your system environment, it will work.
-
-```txt
-API_TOKEN=secret123
-```
-
-```python
-from click_extended import command, option, env
-
-@command()
-@option("--token", help="API token")
-@env("API_TOKEN", name="token", required=True)
-def api_call(token: str):
-    """Make an API call with authentication."""
-    print(f"Using token: {token[:8]}...")
-
-if __name__ == "__main__":
-    api_call()
-```
-
-```bash
-$ python app.py
-Using token: secret12...
-```
-
-### Custom Validators
-
-```python
-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: float | int, context: ProcessContext):
-        if value <= 0:
-            raise ValidationError(f"{value} is not positive")
-
-def is_positive(*args, **kwargs):
-    """Validate positive numbers."""
-    return IsPositive.as_decorator(*args, **kwargs)
-
-@command()
-@option("--count", type=int, required=True)
-@is_positive()
-def process(count: int):
-    """Process a positive number of items."""
-    print(f"Processing {count} items")
-
-if __name__ == "__main__":
-    process()
-```
-
-```bash
-$ python app.py --count 5
-Processing 5 items
-$ python app.py --count -1
-Usage: app.py [OPTIONS]
-Try 'app.py --help' for help.
-
-Error (--count): -1 is not positive
-```
-
-## Documentation
-
-### Core Concepts
-
-- [Commands and Groups](./docs/ROOT_NODE.md) - CLI entry points
-- [Options, Arguments, and Environment Variables](./docs/PARENT_NODE.md) - Parameter sources
-- [Validators and Transformers](./docs/CHILD_NODE.md) - Value processing
-- [Global Nodes](./docs/GLOBAL_NODE.md) - Tree-level operations
-- [Tags](./docs/TAG.md) - Cross-parameter validation
-- [Tree Architecture](./docs/TREE.md) - Internal structure
-
-### Guides
-
-- [Migrating from Click](./docs/MIGRATING_FROM_CLICK.md) - Upgrade guide
-
-## Contributing
-
-Contributors are more than welcome to work on this project. Read the [contribution documentation](./CONTRIBUTING.md) to learn more.
-
-## License
-
-This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
-
-## Acknowledgements
-
-This project is built on top of the [Click](https://github.com/pallets/click) library.

click_extended-0.3.1.dist-info/RECORD

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