click-extended 0.4.0__tar.gz → 1.0.1__tar.gz

{click_extended-0.4.0/click_extended.egg-info → click_extended-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: click_extended
-Version: 0.4.0
+Version: 1.0.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
@@ -37,6 +37,7 @@ 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: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: System :: Shells
 Classifier: Topic :: Utilities
@@ -47,6 +48,10 @@ License-File: LICENSE
 License-File: AUTHORS.md
 Requires-Dist: click>=8.3.0
 Requires-Dist: python-dotenv>=1.2.1
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: email-validator>=2.3.0
+Requires-Dist: python-slugify>=8.0.4
+Requires-Dist: tomli>=2.0.0; python_version < "3.11"
 Provides-Extra: build
 Requires-Dist: build; extra == "build"
 Requires-Dist: twine; extra == "build"
@@ -59,6 +64,8 @@ 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"
+Requires-Dist: types-PyYAML>=6.0.12.20250915; extra == "dev"
+Requires-Dist: tomli>=2.0.0; extra == "dev"
 Dynamic: license-file
 
 ![Banner](./assets/click-extended-banner.png)
@@ -88,6 +95,7 @@ An extension of the [Click](https://github.com/pallets/click) library with addit
 - **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.
+- **Short Flag Concatenation**: Automatically support concatenating short hand flags where `-r -f` is the same as `-rf`.
 
 ## Installation
 
@@ -116,14 +124,18 @@ def my_function(value: str, count: int):
 
 if __name__ == "__main__":
     my_function()
+```
 
-# $ python cli.py "Hello world"
-# Hello world
+```bash
+$ python cli.py "Hello world"
+Hello world
+```
 
-# $ python cli.py "Hello world" --count 3
-# Hello world
-# Hello world
-# Hello world
+```bash
+$ python cli.py "Hello world" --count 3
+Hello world
+Hello world
+Hello world
 ```
 
 ### Basic Command Line Interface
@@ -146,16 +158,20 @@ def my_function(value: str, count: int):
 
 if __name__ == "__main__":
     my_group()
+```
 
-# $ python cli.py my_function "Hello world"
-# Running initialization code...
-# Hello world
+```bash
+$ 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
+```bash
+$ python cli.py my_function "Hello world" --count 3
+Running initialization code...
+Hello world
+Hello world
+Hello world
 ```
 
 ### Using Environment Variables
@@ -181,21 +197,72 @@ def my_function_2(api_key: str):
 
 if __name__ == "__main__":
     my_group()
+```
+
+```bash
+$ python cli.py my_function_1
+The API key is: None
+```
+
+```bash
+$ API_KEY=api-key python cli.py my_function_1
+The API key is: api-key
+```
+
+```bash
+$ python cli.py my_function_2
+ProcessError (my_function_2): Required environment variable 'API_KEY' is not set.
+```
+
+```bash
+$ API_KEY=api-key python cli.py my_function_2
+The API key is: api-key
+```
+
+### Load CSV Data
+
+```python
+import pandas as pd
+from click_extended import command, argument
+from click_extended.decorators import to_path, load_csv
+
+@command()
+@argument("file", param="data")
+@to_path(extensions=["csv"], exists=True)
+@load_csv()
+def my_command(data: dict[str, Any], *args: Any, **kwargs: Any) -> None:
+    df = pd.DataFrame(data)
+    print(df.head())
+```
 
-# $ python cli.py my_function_1
-# The API key is: None
+_Note: `pandas` is not installed in this library and must be installed manually due to size._
 
-# $ API_KEY=api-key python cli.py my_function_1
-# The API key is: api-key
+### Pre-Built Children
 
-# $ python cli.py my_function_2
-# ProcessError (my_function_2): Required environment variable 'API_KEY' is not set.
+This library includes a vast number of pre-built children, everything from checking values to transforming values.
 
-# $ API_KEY=api-key python cli.py my_function_2
-# The API key is: api-key
+```python
+from click_extended import command, argument, option
+from click_extended.decorators import to_snake_case, strip, is_email, minimum, dependencies
+
+@command()
+@dependencies("username", "email", "password")
+@argument("username")
+@to_snake_case()
+@strip()
+@option("email")
+@is_email()
+@option("password")
+@minimum(8)
+def create_account(username: str, email: str, password: str) -> None:
+    print("Username:", username)
+    print("Email:", email)
+    print("Password:", password)
 ```
 
-### Custom Children
+### Custom Nodes
+
+If the library does not include a decorator you need, you can easily create your own. Read more about creating your own [children](./docs/core/CHILD_NODE.md), [validators](./docs/core/VALIDATION_NODE.md), [child validators](./docs/core/CHILD_VALIDATION_NODE.md) or [parents](./docs/core/PARENT_NODE.md).
 
 ```python
 from typing import Any
@@ -205,7 +272,7 @@ from click_extended.classes import ChildNode
 from click_extended.types import Context, Decorator
 
 class MyCustomChild(ChildNode):
-    def handle_primitive(
+    def handle_string(
         self,
         value: str,
         context: Context,
@@ -236,12 +303,16 @@ def my_function(value: str):
 
 if __name__ == "__main__":
     my_group()
+```
 
-# $ python cli.py my_function valid
-# The value 'VALID' should be uppercase.
+```bash
+$ 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"
+```bash
+$ python cli.py my_function invalid
+ValueError (my_function): "The value 'invalid' is not valid"
 ```
 
 ## Documentation

{click_extended-0.4.0 → click_extended-1.0.1}/README.md

@@ -25,6 +25,7 @@ An extension of the [Click](https://github.com/pallets/click) library with addit
 - **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.
+- **Short Flag Concatenation**: Automatically support concatenating short hand flags where `-r -f` is the same as `-rf`.
 
 ## Installation
 
@@ -53,14 +54,18 @@ def my_function(value: str, count: int):
 
 if __name__ == "__main__":
     my_function()
+```
 
-# $ python cli.py "Hello world"
-# Hello world
+```bash
+$ python cli.py "Hello world"
+Hello world
+```
 
-# $ python cli.py "Hello world" --count 3
-# Hello world
-# Hello world
-# Hello world
+```bash
+$ python cli.py "Hello world" --count 3
+Hello world
+Hello world
+Hello world
 ```
 
 ### Basic Command Line Interface
@@ -83,16 +88,20 @@ def my_function(value: str, count: int):
 
 if __name__ == "__main__":
     my_group()
+```
 
-# $ python cli.py my_function "Hello world"
-# Running initialization code...
-# Hello world
+```bash
+$ 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
+```bash
+$ python cli.py my_function "Hello world" --count 3
+Running initialization code...
+Hello world
+Hello world
+Hello world
 ```
 
 ### Using Environment Variables
@@ -118,21 +127,72 @@ def my_function_2(api_key: str):
 
 if __name__ == "__main__":
     my_group()
+```
+
+```bash
+$ python cli.py my_function_1
+The API key is: None
+```
+
+```bash
+$ API_KEY=api-key python cli.py my_function_1
+The API key is: api-key
+```
+
+```bash
+$ python cli.py my_function_2
+ProcessError (my_function_2): Required environment variable 'API_KEY' is not set.
+```
+
+```bash
+$ API_KEY=api-key python cli.py my_function_2
+The API key is: api-key
+```
+
+### Load CSV Data
+
+```python
+import pandas as pd
+from click_extended import command, argument
+from click_extended.decorators import to_path, load_csv
+
+@command()
+@argument("file", param="data")
+@to_path(extensions=["csv"], exists=True)
+@load_csv()
+def my_command(data: dict[str, Any], *args: Any, **kwargs: Any) -> None:
+    df = pd.DataFrame(data)
+    print(df.head())
+```
 
-# $ python cli.py my_function_1
-# The API key is: None
+_Note: `pandas` is not installed in this library and must be installed manually due to size._
 
-# $ API_KEY=api-key python cli.py my_function_1
-# The API key is: api-key
+### Pre-Built Children
 
-# $ python cli.py my_function_2
-# ProcessError (my_function_2): Required environment variable 'API_KEY' is not set.
+This library includes a vast number of pre-built children, everything from checking values to transforming values.
 
-# $ API_KEY=api-key python cli.py my_function_2
-# The API key is: api-key
+```python
+from click_extended import command, argument, option
+from click_extended.decorators import to_snake_case, strip, is_email, minimum, dependencies
+
+@command()
+@dependencies("username", "email", "password")
+@argument("username")
+@to_snake_case()
+@strip()
+@option("email")
+@is_email()
+@option("password")
+@minimum(8)
+def create_account(username: str, email: str, password: str) -> None:
+    print("Username:", username)
+    print("Email:", email)
+    print("Password:", password)
 ```
 
-### Custom Children
+### Custom Nodes
+
+If the library does not include a decorator you need, you can easily create your own. Read more about creating your own [children](./docs/core/CHILD_NODE.md), [validators](./docs/core/VALIDATION_NODE.md), [child validators](./docs/core/CHILD_VALIDATION_NODE.md) or [parents](./docs/core/PARENT_NODE.md).
 
 ```python
 from typing import Any
@@ -142,7 +202,7 @@ from click_extended.classes import ChildNode
 from click_extended.types import Context, Decorator
 
 class MyCustomChild(ChildNode):
-    def handle_primitive(
+    def handle_string(
         self,
         value: str,
         context: Context,
@@ -173,12 +233,16 @@ def my_function(value: str):
 
 if __name__ == "__main__":
     my_group()
+```
 
-# $ python cli.py my_function valid
-# The value 'VALID' should be uppercase.
+```bash
+$ 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"
+```bash
+$ python cli.py my_function invalid
+ValueError (my_function): "The value 'invalid' is not valid"
 ```
 
 ## Documentation

click_extended-1.0.1/click_extended/__init__.py

@@ -0,0 +1,21 @@
+"""Initialization file for the 'click_extended' module."""
+
+from click_extended.core.decorators.argument import argument
+from click_extended.core.decorators.command import command
+from click_extended.core.decorators.env import env
+from click_extended.core.decorators.group import group
+from click_extended.core.decorators.option import option
+from click_extended.core.decorators.prompt import prompt
+from click_extended.core.decorators.selection import selection
+from click_extended.core.decorators.tag import tag
+
+__all__ = [
+    "argument",
+    "command",
+    "env",
+    "group",
+    "option",
+    "prompt",
+    "selection",
+    "tag",
+]

click_extended-1.0.1/click_extended/classes.py

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

click_extended-1.0.1/click_extended/core/__init__.py

@@ -0,0 +1,10 @@
+"""Initialization file for the 'click_extended.core' module."""
+
+from click_extended.core.decorators import *
+from click_extended.core.decorators import __all__ as decorators_all
+from click_extended.core.nodes import *
+from click_extended.core.nodes import __all__ as nodes_all
+from click_extended.core.other import *
+from click_extended.core.other import __all__ as other_all
+
+__all__ = [*decorators_all, *nodes_all, *other_all]  # type: ignore

click_extended-1.0.1/click_extended/core/decorators/__init__.py

@@ -0,0 +1,21 @@
+"""Initialization file for the `click_extended.core.decorators` module."""
+
+from click_extended.core.decorators.argument import Argument
+from click_extended.core.decorators.command import Command
+from click_extended.core.decorators.env import Env
+from click_extended.core.decorators.group import Group
+from click_extended.core.decorators.option import Option
+from click_extended.core.decorators.prompt import Prompt
+from click_extended.core.decorators.selection import Selection
+from click_extended.core.decorators.tag import Tag
+
+__all__ = [
+    "Argument",
+    "Command",
+    "Env",
+    "Group",
+    "Option",
+    "Prompt",
+    "Selection",
+    "Tag",
+]

click_extended-1.0.1/click_extended/core/decorators/argument.py

@@ -0,0 +1,227 @@
+"""Class to support arguments in the command line interface."""
+
+# pylint: disable=too-many-arguments
+# pylint: disable=too-many-positional-arguments
+# pylint: disable=redefined-builtin
+
+from builtins import type as builtins_type
+from typing import Any, Type, cast
+
+from click_extended.core.nodes.argument_node import ArgumentNode
+from click_extended.core.other.context import Context
+from click_extended.types import Decorator
+from click_extended.utils.casing import Casing
+from click_extended.utils.humanize import humanize_type
+from click_extended.utils.naming import validate_name
+
+_MISSING = object()
+SUPPORTED_TYPES = (str, int, float, bool)
+
+
+class Argument(ArgumentNode):
+    """`ArgumentNode` that represents a Click argument."""
+
+    def __init__(
+        self,
+        name: str,
+        param: str | None = None,
+        nargs: int = 1,
+        type: Type[Any] | Any = None,
+        help: str | None = None,
+        required: bool = True,
+        default: Any = _MISSING,
+        tags: str | list[str] | None = None,
+        **kwargs: Any,
+    ):
+        """
+        Initialize a new `Argument` instance.
+
+        Args:
+            name (str):
+                The argument name in snake_case.
+                Examples: "filename", "input_file"
+            param (str, optional):
+                Custom parameter name for the function.
+                If not provided, uses the name directly.
+            nargs (int):
+                Number of arguments to accept. Use `-1` for unlimited.
+                Defaults to `1`.
+            type (Any, optional):
+                The type to convert the value to (`int`, `str`, `float`, etc.).
+            help (str, optional):
+                Help text for this argument.
+            required (bool):
+                Whether this argument is required. Defaults to `True` unless
+                `default` is provided, which makes it optional automatically.
+            default (Any):
+                Default value if not provided. When set, automatically makes
+                the argument optional (`required=False`). Defaults to `None`.
+            tags (str | list[str], optional):
+                Tag(s) to associate with this argument for grouping.
+            **kwargs (Any):
+                Additional keyword arguments.
+
+        Raises:
+            ValueError: If both `default` is provided and `required=True` is
+                explicitly set (detected via kwargs inspection in decorator).
+        """
+        validate_name(name, "argument name")
+
+        param_name = param if param is not None else name
+
+        validate_name(param_name, "parameter name")
+
+        if default is not _MISSING and required is True:
+            required = False
+
+        if default is _MISSING:
+            default = None
+
+        if type is None:
+            if default is not None:
+                type = cast(Type[Any], builtins_type(default))  # type: ignore
+            else:
+                type = str
+
+        if type not in SUPPORTED_TYPES:
+            types = humanize_type(
+                type.__name__ if hasattr(type, "__name__") else type
+            )
+            raise ValueError(
+                f"Argument '{name}' has unsupported type '{types}'. "
+                "Only basic primitives are supported: str, int, float, bool. "
+                "For complex types, use child decorators (e.g., @to_path, "
+                "@to_datetime, ..)."
+            )
+
+        super().__init__(
+            name=name,
+            param=param if param is not None else name,
+            nargs=nargs,
+            type=type,
+            help=help,
+            required=required,
+            default=default,
+            tags=tags,
+        )
+        self.extra_kwargs = kwargs
+
+    def get_display_name(self) -> str:
+        """
+        Get a formatted display name for error messages.
+
+        Returns:
+            str:
+                The argument name in SCREAMING_SNAKE_CASE.
+        """
+        return Casing.to_screaming_snake_case(self.name)
+
+    def load(
+        self,
+        value: str | int | float | bool | None,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        """
+        Load and return the CLI argument value.
+
+        Args:
+            value (str | int | float | bool | None):
+                The parsed CLI argument value from Click.
+            context (Context):
+                The current context instance.
+            *args (Any):
+                Optional positional arguments.
+            **kwargs (Any):
+                Optional keyword arguments.
+
+        Returns:
+            Any:
+                The argument value to inject into the function.
+        """
+        return value
+
+
+def argument(
+    name: str,
+    param: str | None = None,
+    nargs: int = 1,
+    type: Type[str | int | float | bool] | None = None,
+    help: str | None = None,
+    required: bool = True,
+    default: Any = _MISSING,
+    tags: str | list[str] | None = None,
+    **kwargs: Any,
+) -> Decorator:
+    """
+    A `ParentNode` decorator to create a Click argument with value injection.
+
+    Args:
+        name (str):
+            The argument name in snake_case.
+            Examples: "filename", "input_file"
+        param (str, optional):
+            Custom parameter name for the function.
+            If not provided, uses the name directly.
+        nargs (int):
+            Number of arguments to accept. Use `-1` for unlimited.
+            Defaults to `1`.
+        type (Type[str | int | float | bool] | None, optional):
+            The type to convert the value to.
+        help (str, optional):
+            Help text for this argument.
+        required (bool):
+            Whether this argument is required. Defaults to `True` unless
+            `default` is provided, which automatically makes it optional.
+        default (Any):
+            Default value if not provided. When set, automatically makes
+            the argument optional (`required=False`). Defaults to `None`.
+        tags (str | list[str], optional):
+            Tag(s) to associate with this argument for grouping.
+        **kwargs (Any):
+            Additional Click argument parameters.
+
+    Returns:
+        Decorator:
+            A decorator function that registers the argument parent node.
+
+    Examples:
+
+        ```python
+        @argument("filename")
+        def my_func(filename):
+            print(f"File: {filename}")
+        ```
+
+        ```python
+        @argument("files", nargs=-1, help="Files to process")
+        def my_func(files):
+            for file in files:
+                print(f"Processing: {file}")
+        ```
+
+        ```python
+        @argument("port", type=int, default=8080)
+        def my_func(port):
+            print(f"Port: {port}")
+        ```
+
+        ```python
+        # Custom parameter name
+        @argument("input_file", param="infile")
+        def my_func(infile):  # param: infile, CLI: INPUT_FILE
+            print(f"Input: {infile}")
+        ```
+    """
+    return Argument.as_decorator(
+        name=name,
+        param=param,
+        nargs=nargs,
+        type=type,
+        help=help,
+        required=required,
+        default=default,
+        tags=tags,
+        **kwargs,
+    )