click-extended 0.3.2__py3-none-any.whl → 1.0.0__py3-none-any.whl

click_extended/types.py

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

click_extended-1.0.0.dist-info/METADATA

@@ -0,0 +1,331 @@
+Metadata-Version: 2.4
+Name: click_extended
+Version: 1.0.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
+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"
+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"
+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)
+
+# 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.
+- **Short Flag Concatenation**: Automatically support concatenating short hand flags where `-r -f` is the same as `-rf`.
+
+## 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()
+```
+
+```bash
+$ python cli.py "Hello world"
+Hello world
+```
+
+```bash
+$ 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()
+```
+
+```bash
+$ python cli.py my_function "Hello world"
+Running initialization code...
+Hello world
+```
+
+```bash
+$ 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()
+```
+
+```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())
+```
+
+_Note: `pandas` is not installed in this library and must be installed manually due to size._
+
+### Pre-Built Children
+
+This library includes a vast number of pre-built children, everything from checking values to transforming values.
+
+```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 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
+
+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_string(
+        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()
+```
+
+```bash
+$ python cli.py my_function valid
+The value 'VALID' should be uppercase.
+```
+
+```bash
+$ 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-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+click_extended/__init__.py,sha256=wTarCHBxMz59fe0vCTyq8RiN0COooJ892C0N2OuPLLQ,640
+click_extended/classes.py,sha256=SdwglQ7O5ahjYeVnaM9_hCU14BYZBv8C0ZjWQIo7A_I,837
+click_extended/errors.py,sha256=tkvAXs4oUZ8SFgX37KhYrHAlsxmOGrSFLIezCH9NDQI,13897
+click_extended/types.py,sha256=0YT4QN269H-01RVxDGSpMT_hJm8cTcONonpX4_YxJlg,238
+click_extended-1.0.0.dist-info/licenses/AUTHORS.md,sha256=NkShPinjqtnRDQVRyVnfJuOGM56sejauE3WRoYCcbtw,132
+click_extended-1.0.0.dist-info/licenses/LICENSE,sha256=gjO8hzM4mFSBXFikktaXVSgmXGcre91_GPJ-E_yP56E,1075
+click_extended-1.0.0.dist-info/METADATA,sha256=l7TL-IV44rqCe0TzV7VHjjb7_dVtDxSdBBf9lsYmjes,10711
+click_extended-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+click_extended-1.0.0.dist-info/top_level.txt,sha256=2G3bm6tCNv80okRm773jKTk-_z1ElY-seaozZrn_TxA,15
+click_extended-1.0.0.dist-info/RECORD,,

click_extended-0.3.2.dist-info/METADATA

@@ -1,257 +0,0 @@
-Metadata-Version: 2.4
-Name: click_extended
-Version: 0.3.2
-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.2.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=9DGOs5x4CGwxlRLZe3zIacPtkWldZgix6hWQxcxJP_A,773
-click_extended-0.3.2.dist-info/licenses/AUTHORS.md,sha256=NkShPinjqtnRDQVRyVnfJuOGM56sejauE3WRoYCcbtw,132
-click_extended-0.3.2.dist-info/licenses/LICENSE,sha256=gjO8hzM4mFSBXFikktaXVSgmXGcre91_GPJ-E_yP56E,1075
-click_extended-0.3.2.dist-info/METADATA,sha256=_adGbk-vOJQKV-X0yTYfkmILjJDiAAGJbnkfp2ysY6g,8295
-click_extended-0.3.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-click_extended-0.3.2.dist-info/top_level.txt,sha256=2G3bm6tCNv80okRm773jKTk-_z1ElY-seaozZrn_TxA,15
-click_extended-0.3.2.dist-info/RECORD,,