click-extended 0.0.3__tar.gz → 0.1.0__tar.gz

click_extended-0.1.0/PKG-INFO

@@ -0,0 +1,257 @@
+Metadata-Version: 2.4
+Name: click_extended
+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
+        
+        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.1.0/README.md

@@ -0,0 +1,194 @@
+![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.0.3 → click_extended-0.1.0}/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-0.0.3 → click_extended-0.1.0}/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-0.0.3 → click_extended-0.1.0}/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",