rats-apps 0.5.1.dev20250206185646__py3-none-any.whl → 0.6.0.dev20250207152453__py3-none-any.whl

rats/apps/_app_containers.py

@@ -63,10 +63,11 @@ be used easily in functions that need to defer the construction of an applicatio
 
 class PluginMixin:
     """
-    Mix into your [Container][] classes to add our default constructor.
+    Mix into your [rats.apps.Container][] classes to add our default constructor.
 
     This mixin adds a common constructor to a `Container` in order to quickly create types that
-    are compatible with functions asking for `AppPlugin` and `ContainerPlugin` arguments.
+    are compatible with functions asking for [rats.apps.AppPlugin][] and
+    [rats.apps.ContainerPlugin][] arguments.
 
     !!! warning
         Avoid using mixins as an input type to your functions, because we don't want to restrict

rats/cli/__init__.py

@@ -1,16 +1,23 @@
-"""Uses `rats.cli` to streamline the creation of CLI commands written with Click."""
+"""Use `rats.cli` to streamline the creation of CLI commands written with Click."""
 
-from ._annotations import CommandId, command, get_class_commands, get_class_groups, group
+from ._annotations import (
+    AUTO_COMMAND,
+    CommandId,
+    command,
+    get_class_commands,
+    get_class_groups,
+    group,
+)
 from ._app import ClickApp
 from ._container import CompositeContainer, Container
-from ._plugin import PluginServices, attach, create_group
+from ._plugin import attach, create_group
 
 __all__ = [
+    "AUTO_COMMAND",
     "ClickApp",
     "CommandId",
     "CompositeContainer",
     "Container",
-    "PluginServices",
     "attach",
     "command",
     "create_group",

rats/cli/_annotations.py

@@ -8,14 +8,47 @@ from rats import apps
 
 
 class CommandId(NamedTuple):
+    """
+    A small wrapper around the string name of a [click.Command][].
+
+    Used when wanting to specify a custom name for a command within a [rats.cli.Container][] class.
+    See [rats.cli.command][] for more details.
+    """
+
     name: str
 
 
 AUTO_COMMAND = CommandId("__auto__")
+"""
+Causes command names to be generated from the method names in [rats.cli.Container][]'s.
+
+This is the default option for [rats.cli.command][] and [rats.cli.group][] and typically does not
+need to be used directly.
+"""
 T = TypeVar("T", bound=Callable[[Any], Any])
 
 
 def command(command_id: CommandId = AUTO_COMMAND) -> Callable[..., apps.Executable]:
+    """
+    Mark a method in [rats.cli.Container][] instances as a [click.Command][].
+
+    By default, the name of the method is used to generate a dash-separated command name. You can
+    provide a [rats.cli.CommandId][] argument to specify a custom name, for example, if the desired
+    command contains characters that are invalid in method names, like periods.
+
+    ```python
+    from rats import cli
+
+    class Example(cli.Container):
+        @cli.command(cli.CommandId("some.example-command")
+        def _any_method_name(self) -> None:
+            print("this cli command is called some.example-command")
+    ```
+
+    Args:
+        command_id: An optional [rats.cli.CommandId][] to specify the command name.
+    """
+
     def decorator(fn: T) -> T:
         if command_id == AUTO_COMMAND:
             cmd_name = fn.__name__.replace("_", "-").strip("-")
@@ -26,17 +59,31 @@ def command(command_id: CommandId = AUTO_COMMAND) -> Callable[..., apps.Executab
 
 
 def group(command_id: CommandId = AUTO_COMMAND) -> Callable[..., apps.Executable]:
+    """
+    Mark a method in [rats.cli.Container][] instances as a [click.Group][].
+
+    !!! warning
+        It's unclear if this API is useful as-is and will most likely change soon.
+
+    See [rats.cli.command][] for more details.
+
+    Args:
+        command_id: An optional [rats.cli.CommandId][] to specify the group name.
+    """
+
     def decorator(fn: T) -> T:
         if command_id == AUTO_COMMAND:
             return anns.annotation("command-groups", CommandId(fn.__name__.replace("_", "-")))(fn)
-        return anns.annotation("commands", command_id)(fn)
+        return anns.annotation("command-groups", command_id)(fn)
 
     return decorator  # type: ignore[reportReturnType]
 
 
 def get_class_commands(cls: type) -> anns.AnnotationsContainer:
+    """Extracts class methods decorated with [rats.cli.command][]."""
     return anns.get_class_annotations(cls).with_namespace("commands")
 
 
 def get_class_groups(cls: type) -> anns.AnnotationsContainer:
+    """Extracts class methods decorated with [rats.cli.group][]."""
     return anns.get_class_annotations(cls).with_namespace("command-groups")

rats/cli/_app.py

@@ -9,7 +9,13 @@ from ._container import Container
 
 @final
 class ClickApp(apps.Executable):
-    """..."""
+    """
+    A wrapper to configure and run a [click.Group][] as a [rats.apps.Executable][].
+
+    The [rats.cli.Container][] is attached to the provided [click.Group][] when the
+    [rats.cli.ClickApp.execute][] is called, allowing some simple forms of lazy-loading to keep
+    commands snappy.
+    """
 
     _group: click.Group
     _commands: Container
@@ -19,11 +25,24 @@ class ClickApp(apps.Executable):
         group: click.Group,
         commands: Container,
     ) -> None:
-        """Not sure this is the right interface."""
+        """
+        Provide the [rats.cli.Container][] instance that makes up the wanted cli commands.
+
+        Args:
+            group: group that will be executed by this application.
+            commands: container that will be attached before executing the above group.
+        """
         self._group = group
         self._commands = commands
 
     def execute(self) -> None:
-        """This app executes a click application after letting rats plugins attach commands."""
+        """
+        Attach any commands provided by the [rats.cli.Container][] and then execute the group.
+
+        !!! note
+            Currently, this method runs [click.BaseCommand.main][] without arguments, causing Click
+            to pull the command arguments from [sys.argv][]. If you are needing to change this,
+            skip using this class and implement the custom logic yourself.
+        """
         self._commands.attach(self._group)
         self._group.main()

rats/cli/_container.py

@@ -11,10 +11,34 @@ logger = logging.getLogger(__name__)
 
 
 class Container(Protocol):
-    """A container that can attach click commands to a click group."""
+    """
+    A container that can attach click commands to a click group.
+
+    !!! example
+        The default protocol implementation detects any methods in the class decorated with the
+        [rats.cli.command][] annotation. Apart from marking the method as a cli command, you can
+        add [click.argument][] and [click.option][] decorators as defined by the click docs.
+
+        ```python
+        from rats import cli
+
+
+        class ExampleCli(cli.Container):
+            @cli.command()
+            @click.argument("something")
+            def my_cmd(self, something: str) -> None:
+                print("this command is automatically detected and attached as my-cmd")
+                print("add a docstring to the method to be used as the --help text")
+        ```
+    """
 
     def attach(self, group: click.Group) -> None:
-        """..."""
+        """
+        Attach this container's provided cli commands to the provided [click.Group][].
+
+        Args:
+            group: The [click.Group][] we are attaching our commands to.
+        """
 
         def cb(_method: Callable[..., None], *args: Any, **kwargs: Any) -> None:
             """
@@ -50,11 +74,25 @@ class Container(Protocol):
 
 @final
 class CompositeContainer(Container):
+    """Take any number of [rats.cli.Container][] instances and expose them as if they were one."""
+
     _containers: tuple[Container, ...]
 
     def __init__(self, *containers: Container) -> None:
+        """
+        Zero or more instances can be provided.
+
+        Args:
+            *containers: Any number of container instances wanting to be merged.
+        """
         self._containers = containers
 
     def attach(self, group: click.Group) -> None:
+        """
+        Attach the cli commands from all [rats.cli.Container][] instances to the [click.Group][].
+
+        Args:
+            group: The [click.Group][] we are attaching our commands to.
+        """
         for container in self._containers:
             container.attach(group)

rats/cli/_plugin.py

@@ -1,13 +1,31 @@
-from typing import cast
-
 import click
 
-from rats import apps
-
 from ._container import Container
 
 
 def create_group(group: click.Group, container: Container) -> click.Group:
+    """
+    A simple shortcut to create a [click.Group][] with commands provided by `rats.cli.Container`'s.
+
+    ```python
+    import click
+    from rats import cli
+
+
+    class Example(cli.Container):
+        @cli.command()
+        def my_command(self) -> None:
+            print("hello, world. run me with `my-cli my-command`.")
+
+
+    if __name__ == "__main__":
+        cli.create_group(click.Group("my-cli"), Example()).main()
+    ```
+
+    Args:
+        group: The [click.Group][] commands will be added to.
+        container: The [rats.cli.Container][] instance to attach commands from
+    """
     container.attach(group)
     return group
 
@@ -17,27 +35,27 @@ def attach(
     command: click.Command | click.Group,
     *commands: click.Command | click.Group,
 ) -> None:
+    """
+    Convenience function to attach multiple [click.Command]'s to a [click.Group].
+
+    ```python
+    import click
+    from rats import cli
+
+    cli.attach(
+        click.Group("my-cli"),
+        click.Command("command-1"),
+        click.Command("command-2"),
+    )
+    ```
+
+    Args:
+        group: The [click.Group] we want to build.
+        command: A [click.Command] to attach to the provided group.
+        *commands: Any number of additional [click.Command]'s to attach.
+
+    Returns: The input [click.Group][] with all of the commands attached.
+    """
     group.add_command(command)
     for c in commands:
         group.add_command(c)
-
-
-@apps.autoscope
-class _PluginEvents:
-    pass
-
-
-@apps.autoscope
-class PluginServices:
-    EVENTS = _PluginEvents
-
-    @staticmethod
-    def sub_command(
-        parent: apps.ServiceId[apps.Executable],
-        name: str,
-    ) -> apps.ServiceId[apps.Executable]:
-        return apps.ServiceId(f"{parent.name}[{name}]")
-
-    @staticmethod
-    def click_command(cmd_id: apps.ServiceId[apps.Executable]) -> apps.ServiceId[click.Group]:
-        return cast(apps.ServiceId[click.Group], cmd_id)

{rats_apps-0.5.1.dev20250206185646.dist-info → rats_apps-0.6.0.dev20250207152453.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: rats-apps
-Version: 0.5.1.dev20250206185646
+Version: 0.6.0.dev20250207152453
 Summary: research analysis tools for building applications
 License: MIT
 Keywords: pipelines,machine learning,research

{rats_apps-0.5.1.dev20250206185646.dist-info → rats_apps-0.6.0.dev20250207152453.dist-info}/RECORD

@@ -4,7 +4,7 @@ rats/annotations/_functions.py,sha256=UkHh3zdBivluE7dBeGQ17zoIfGdyIokMAkFmpWaIlD
 rats/annotations/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 rats/apps/__init__.py,sha256=uTPk2ipOy7MgLoV0s9l22U1Qyo8aL2yKVwDukOY9WGw,1934
 rats/apps/_annotations.py,sha256=6M_M7K8haNVda0Tx02EpFf3s9EjnWYacNMjTIkNEdRU,4617
-rats/apps/_app_containers.py,sha256=Ym2NrRljmZVE7EXK2G8KgDHAGreYsuFlvu1QYTkhOsE,6109
+rats/apps/_app_containers.py,sha256=ygZL0NM-fSRSemFddBsVMwcmSQw07sbb7bIqWTr-_yU,6147
 rats/apps/_composite_container.py,sha256=s_of6NyyrjFVYWGVehyEHe9WJIPRCnbB-tyWyNF8zyc,585
 rats/apps/_container.py,sha256=sYISCG-qVzl-bsBwX_CAWEP9gtXCnG-Jls3l8IKb4DQ,7208
 rats/apps/_executables.py,sha256=hXExNmAnuPU1KJXihNw1jEDAQpMlQ9E9_aPV8tpGbOY,1347
@@ -16,12 +16,12 @@ rats/apps/_runtimes.py,sha256=l5Z26jZVHk4CvT8VyKUK5tpcCAKt2N1DWipd4gX_Bls,2060
 rats/apps/_scoping.py,sha256=6C2-ID22cCPR9Cbexf3CvCF3o9F_7ieURbwqkf6DI68,1360
 rats/apps/_static_container.py,sha256=KH4AwRMX5QPIwYrD9W_HayIpQIrbVn7clEMx44LFAGc,2113
 rats/apps/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-rats/cli/__init__.py,sha256=PFwnpWtiAkHyV_wyQRNslKHKAOI659HpU5KBfswq8RQ,540
+rats/cli/__init__.py,sha256=0VDmmNP4JOW-hNjufYwO-e38kLpquWb_fo95geuNv5w,564
 rats/cli/__main__.py,sha256=WeldAKjA3Kmz9ZRnZVd3G8Ud66Y_gSRDLIPNE1JyhV0,1418
-rats/cli/_annotations.py,sha256=5voM1pNm7iybZpgQTSVpaq3rMIMz33jr4eUyoEmxWJ4,1359
-rats/cli/_app.py,sha256=EmLIJe1LTLob5u5gP8gpgxk3kFlALTvrpYlwxlILu0k,620
-rats/cli/_container.py,sha256=q3L6On6RS3PfUFZ67t6eUvKUQIK4Qxomz5ob86aNcR4,2143
-rats/cli/_plugin.py,sha256=IknKt0yLNpk2ZYH2yRiADC74jO5DowAGmoWOEvR6l4g,928
+rats/cli/_annotations.py,sha256=TCjs2b7o6kUSseFwrHm63o9QurwGDO7YsK56ZNMQPGg,3014
+rats/cli/_app.py,sha256=4z2jiRHafCAN7S-cbMhfQJhLGwl6ljFS3r6P1COgR00,1454
+rats/cli/_container.py,sha256=FIQBqi9PTNpE2P52qkfGET51BczdD-JvcWXLTjCNPDI,3512
+rats/cli/_plugin.py,sha256=BNmgWVquQUEqJAYsed_l8vLnlLP7u3XC1TDyEFI1AiU,1552
 rats/cli/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 rats/logs/__init__.py,sha256=sizLa6JbqekhJGKDyRZUUQvTuqiJx6yxwA5jT-tDQck,152
 rats/logs/_app.py,sha256=TF6rfQXQfaHd3AFW2anAoAGaxzU31kqJMoKkjuBtbF0,1617
@@ -35,6 +35,6 @@ rats_e2e/apps/inputs/_app.py,sha256=FiaLgOZc-d1ryKSwKnL5XBNGcOP1bHbxxeMJqoU_RJg,
 rats_e2e/apps/minimal/__init__.py,sha256=bUR6Oexx6Jsouxor0cL9emXoVha4cm3WqyhU1pgchsI,521
 rats_e2e/apps/minimal/__main__.py,sha256=Mf-a2iQKTTgh9hMd6AeuzmU9araMIyf1AtdWkh_L07E,117
 rats_e2e/apps/minimal/_app.py,sha256=CQ09LVTNRarz7Pb1wiSuNHrZ_2KGcgH8nUqy4BjxMUY,849
-rats_apps-0.5.1.dev20250206185646.dist-info/METADATA,sha256=wONNll9olXOhYo3oMYUDXG0ZB1ySa0j96yyu1m_uEs0,779
-rats_apps-0.5.1.dev20250206185646.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
-rats_apps-0.5.1.dev20250206185646.dist-info/RECORD,,
+rats_apps-0.6.0.dev20250207152453.dist-info/METADATA,sha256=NSS2NJbeZ1O-du3MXAgRdb68VYaRZ-O5mdHdAn9vqt0,779
+rats_apps-0.6.0.dev20250207152453.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
+rats_apps-0.6.0.dev20250207152453.dist-info/RECORD,,