click-compose 2026.9.8__py3-none-any.whl

click_compose/__init__.py

@@ -0,0 +1,106 @@
+"""
+Composable Click callback utilities for building flexible CLI
+applications.
+"""
+
+from collections.abc import Callable, Sequence
+from typing import TypeVar
+
+import click
+from beartype import beartype
+
+T = TypeVar("T")
+U = TypeVar("U")
+
+
+@beartype
+def sequence_validator(
+    *,
+    validator: Callable[[click.Context | None, click.Parameter | None, T], U],
+) -> Callable[
+    [click.Context | None, click.Parameter | None, Sequence[T] | None],
+    Sequence[U] | None,
+]:
+    """Wrap a single-value validator to apply it to a sequence of values.
+
+    This function takes a Click callback that validates a single value and
+    returns a new callback that applies the same validation to each element
+    in a sequence. The validator can transform the type of each element.
+
+    Args:
+        validator: A Click callback that validates a single value.
+
+    Returns:
+        A Click callback that validates a sequence of values.
+    """
+
+    def callback(
+        ctx: click.Context | None,
+        param: click.Parameter | None,
+        value: Sequence[T] | None,
+    ) -> Sequence[U] | None:
+        """Apply the validator to each element in the sequence."""
+        if value is None:
+            return None
+        return_values: list[U] = []
+        for item in value:
+            returned_value = validator(ctx, param, item)
+            return_values.append(returned_value)
+        return return_values
+
+    return callback
+
+
+@beartype
+def deduplicate(
+    ctx: click.Context | None,
+    param: click.Parameter | None,
+    sequence: Sequence[T] | None,
+) -> Sequence[T] | None:
+    """
+    Return the sequence with duplicates removed while preserving
+    order.
+    """
+    # We "use" the parameters to silence unused-argument tooling.
+    del ctx
+    del param
+
+    if sequence is None:
+        return None
+
+    return tuple(dict.fromkeys(sequence).keys())
+
+
+@beartype
+def multi_callback(
+    *,
+    callbacks: Sequence[Callable[..., T]],
+) -> Callable[[click.Context | None, click.Parameter | None, T], T]:
+    """Create a Click-compatible callback that applies multiple callbacks
+    in
+    sequence.
+
+    This function takes a sequence of Click callbacks and returns a new
+    callback that applies each callback in order, threading the value through
+    each one. Each callback can transform the type, allowing for flexible
+    pipelines of transformations and validations.
+
+    Args:
+        callbacks: A sequence of Click callbacks to apply in order.
+
+    Returns:
+        A Click callback that applies all the given callbacks in sequence.
+    """
+
+    def callback(
+        ctx: click.Context | None,
+        param: click.Parameter | None,
+        value: T,
+    ) -> T:
+        """Apply each callback in sequence to the value."""
+        result = value
+        for cb in callbacks:
+            result = cb(ctx, param, result)
+        return result
+
+    return callback

click_compose-2026.9.8.dist-info/METADATA

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: click-compose
+Version: 2026.9.8
+Summary: Composable Click callback utilities for building flexible CLI applications.
+Author-email: Adam Dangoor <adamdangoor@gmail.com>
+License-Expression: MIT
+Project-URL: Source, https://github.com/adamtheturtle/click-compose
+Keywords: callbacks,cli,click,validation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+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
+Requires-Python: >=3.11
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: beartype>=0.22.9
+Requires-Dist: click>=8.3.1
+Dynamic: license-file
+
+click-compose
+=============
+
+|Build Status| |PyPI|
+
+Composable Click callback utilities for building flexible CLI applications.
+
+.. |Build Status| image:: https://github.com/adamtheturtle/click-compose/actions/workflows/ci.yml/badge.svg?branch=main
+   :target: https://github.com/adamtheturtle/click-compose/actions/workflows/ci.yml
+.. |PyPI| image:: https://badge.fury.io/py/click-compose.svg
+   :target: https://badge.fury.io/py/click-compose
+
+.. contents::
+   :local:
+
+Installation
+------------
+
+.. code-block:: shell
+
+   $ pip install click-compose
+
+Or with ``uv``:
+
+.. code-block:: shell
+
+   $ uv add click-compose
+
+Quick Start
+-----------
+
+``click-compose`` provides utilities for composing Click callbacks:
+
+multi_callback
+~~~~~~~~~~~~~~
+
+Combine multiple callbacks into a single callback that applies them in sequence:
+
+.. code-block:: python
+
+   """Example of using multi_callback to combine validators."""
+
+   import click
+
+   from click_compose import multi_callback
+
+
+   def validate_positive(
+       _ctx: click.Context,
+       _param: click.Parameter,
+       value: int,
+   ) -> int:
+       """Validate that value is positive."""
+       if value <= 0:
+           msg = "Must be positive"
+           raise click.BadParameter(message=msg)
+       return value
+
+
+   MAX_VALUE = 100
+
+
+   def validate_max_100(
+       _ctx: click.Context,
+       _param: click.Parameter,
+       value: int,
+   ) -> int:
+       """Validate that value is at most 100."""
+       if value > MAX_VALUE:
+           msg = "Must be <= 100"
+           raise click.BadParameter(message=msg)
+       return value
+
+
+   @click.command()
+   @click.option(
+       "--count",
+       type=int,
+       callback=multi_callback(callbacks=[validate_positive, validate_max_100]),
+   )
+   def cmd(count: int) -> None:
+       """Example command with multiple validators."""
+       click.echo(message=f"Count: {count}")
+
+sequence_validator
+~~~~~~~~~~~~~~~~~~
+
+Apply a validator to each element in a sequence (useful with ``multiple=True``):
+
+.. code-block:: python
+
+   """Example of using sequence_validator with multiple values."""
+
+   import click
+
+   from click_compose import sequence_validator
+
+
+   def validate_positive(
+       _ctx: click.Context | None,
+       _param: click.Parameter | None,
+       value: int,
+   ) -> int:
+       """Validate that value is positive."""
+       if value <= 0:
+           msg = "Must be positive"
+           raise click.BadParameter(message=msg)
+       return value
+
+
+   @click.command()
+   @click.option(
+       "--numbers",
+       multiple=True,
+       type=int,
+       callback=sequence_validator(validator=validate_positive),
+   )
+   def cmd(numbers: tuple[int, ...]) -> None:
+       """Example command with sequence validation."""
+       click.echo(message=f"Sum: {sum(numbers)}")
+
+deduplicate
+~~~~~~~~~~~
+
+Remove duplicates from a sequence while preserving order (useful with ``multiple=True``):
+
+.. code-block:: python
+
+   """Example of using ``deduplicate`` to remove duplicate values."""
+
+   import click
+
+   from click_compose import deduplicate
+
+
+   @click.command()
+   @click.option(
+       "--tags",
+       multiple=True,
+       type=str,
+       callback=deduplicate,
+   )
+   def cmd(tags: tuple[str, ...]) -> None:
+       """Example command that removes duplicate tags."""
+       click.echo(message=f"Unique tags: {', '.join(tags)}")
+
+Documentation
+-------------
+
+See the `full documentation <https://adamtheturtle.github.io/click-compose/>`__.

click_compose-2026.9.8.dist-info/RECORD

@@ -0,0 +1,7 @@
+click_compose/__init__.py,sha256=oBDHYOys7KbmkY0qj492Agnb36j_7rR60iDkw5VeqhQ,2881
+click_compose/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+click_compose-2026.9.8.dist-info/licenses/LICENSE,sha256=N3qm7laipxyuXkWpYllj89AObvPbtWgoABmaKfhQYL4,1069
+click_compose-2026.9.8.dist-info/METADATA,sha256=GeTU2l4MZIjhZv93J49iobth61KEKtRHysGZkBs0Lr0,4426
+click_compose-2026.9.8.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+click_compose-2026.9.8.dist-info/top_level.txt,sha256=D6w2GKY-8Qwmbiv3G8DyrtwEjiu-yd7I6n6IpPIUauU,14
+click_compose-2026.9.8.dist-info/RECORD,,

click_compose-2026.9.8.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

click_compose-2026.9.8.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Adam Dangoor
+
+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.

click_compose-2026.9.8.dist-info/top_level.txt

@@ -0,0 +1 @@
+click_compose