rats-apps 0.1.3.dev50__py3-none-any.whl → 0.1.3.dev58__py3-none-any.whl

rats/annotations/__init__.py

@@ -0,0 +1,25 @@
+"""
+General purpose library to attach annotations to functions.
+
+Annotations are typically, but not exclusively, attached using decorators.
+"""
+
+from ._functions import (
+    AnnotationsContainer,
+    DecoratorType,
+    GroupAnnotations,
+    T_GroupType,
+    annotation,
+    get_annotations,
+    get_class_annotations,
+)
+
+__all__ = [
+    "annotation",
+    "DecoratorType",
+    "AnnotationsContainer",
+    "get_annotations",
+    "get_class_annotations",
+    "GroupAnnotations",
+    "T_GroupType",
+]

rats/annotations/_functions.py

@@ -0,0 +1,125 @@
+# type: ignore
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Callable
+from functools import cache
+from typing import Any, Generic, ParamSpec, TypeVar
+from typing import NamedTuple as tNamedTuple
+
+from typing_extensions import NamedTuple
+
+T_GroupType = TypeVar("T_GroupType", bound=NamedTuple)
+
+
+class GroupAnnotations(NamedTuple, Generic[T_GroupType]):
+    """The list of T_GroupType objects identified by a given name in a namespace."""
+
+    name: str
+    """The name of the annotation, typically the name of the function in a class"""
+    namespace: str
+    """All the groups in a namespace are expected to be of the same T_GroupType."""
+    groups: tuple[T_GroupType, ...]
+
+
+class AnnotationsContainer(NamedTuple):
+    """
+    Holds metadata about the annotated service provider.
+
+    Loosely inspired by: https://peps.python.org/pep-3107/.
+    """
+
+    annotations: tuple[GroupAnnotations[...], ...]
+
+    @staticmethod
+    def empty() -> AnnotationsContainer:
+        return AnnotationsContainer(annotations=())
+
+    def with_group(
+        self,
+        namespace: str,
+        group_id: T_GroupType,
+    ) -> AnnotationsContainer:
+        return AnnotationsContainer(
+            annotations=tuple(
+                [
+                    annotation_group
+                    for x in self.with_namespace(namespace)
+                    for annotation_group in x
+                    if group_id in annotation_group.groups
+                ]
+            ),
+        )
+
+    def with_namespace(
+        self,
+        namespace: str,
+    ) -> AnnotationsContainer:
+        return AnnotationsContainer(
+            annotations=tuple([x for x in self.annotations if x.namespace == namespace]),
+        )
+
+
+class AnnotationsBuilder:
+    _group_ids: dict[str, set[Any]]
+
+    def __init__(self) -> None:
+        self._group_ids = defaultdict(set)
+
+    def add(self, namespace: str, group_id: NamedTuple | tNamedTuple) -> None:
+        self._group_ids[namespace].add(group_id)
+
+    def make(self, name: str) -> AnnotationsContainer:
+        return AnnotationsContainer(
+            annotations=tuple(
+                [
+                    GroupAnnotations[Any](name=name, namespace=namespace, groups=tuple(groups))
+                    for namespace, groups in self._group_ids.items()
+                ]
+            ),
+        )
+
+
+DecoratorType = TypeVar("DecoratorType", bound=Callable[..., Any])
+
+
+def annotation(
+    namespace: str,
+    group_id: NamedTuple | tNamedTuple,
+) -> Callable[[DecoratorType], DecoratorType]:
+    def decorator(fn: DecoratorType) -> DecoratorType:
+        if not hasattr(fn, "__rats_annotations__"):
+            fn.__rats_annotations__ = AnnotationsBuilder()  # type: ignore[reportFunctionMemberAccess]
+
+        fn.__rats_annotations__.add(namespace, group_id)  # type: ignore[reportFunctionMemberAccess]
+
+        return fn
+
+    return decorator
+
+
+@cache
+def get_class_annotations(cls: type) -> AnnotationsContainer:
+    tates = []
+
+    for method_name in dir(cls):
+        method = getattr(cls, method_name)
+        if not hasattr(method, "__rats_annotations__"):
+            continue
+
+        tates.extend(method.__rats_annotations__.make(method_name).annotations)
+
+    return AnnotationsContainer(annotations=tuple(tates))
+
+
+P = ParamSpec("P")
+
+
+def get_annotations(fn: Callable[..., Any]) -> AnnotationsContainer:
+    builder: AnnotationsBuilder = getattr(
+        fn,
+        "__rats_annotations__",
+        AnnotationsBuilder(),
+    )
+
+    return builder.make(fn.__name__)

rats/apps/__init__.py

@@ -18,11 +18,18 @@ from ._annotations import (
     service,
 )
 from ._composite_container import CompositeContainer
-from ._container import Container, DuplicateServiceError, ServiceNotFoundError
+from ._container import (
+    ConfigProvider,
+    Container,
+    DuplicateServiceError,
+    ServiceNotFoundError,
+    ServiceProvider,
+)
 from ._executables import App, AppContainer, Executable
 from ._ids import ConfigId, ServiceId
 from ._namespaces import ProviderNamespaces
 from ._plugin_container import PluginContainers
+from ._plugins import PluginRunner
 from ._scoping import autoscope
 
 __all__ = [
@@ -36,12 +43,15 @@ __all__ = [
     "Executable",
     "PluginContainers",
     "ProviderNamespaces",
+    "ConfigProvider",
+    "ServiceProvider",
     "ServiceId",
     "ServiceNotFoundError",
     "autoid_service",
     "autoscope",
     "config",
     "container",
+    "PluginRunner",
     "fallback_config",
     "fallback_group",
     "fallback_service",

rats/apps/_annotations.py

@@ -1,3 +1,4 @@
+import abc
 from collections import defaultdict
 from collections.abc import Callable, Iterator
 from functools import cache
@@ -70,7 +71,7 @@ class FunctionAnnotationsBuilder:
         )
 
 
-class AnnotatedContainer(Container):
+class AnnotatedContainer(Container, abc.ABC):
     def get_namespaced_group(
         self,
         namespace: str,

rats/apps/_plugins.py

@@ -0,0 +1,17 @@
+from collections.abc import Callable, Iterator
+from typing import Generic, TypeVar
+
+T_PluginType = TypeVar("T_PluginType")
+
+
+class PluginRunner(Generic[T_PluginType]):
+    """Client to apply a function to a list of plugins."""
+
+    _plugins: Iterator[T_PluginType]
+
+    def __init__(self, plugins: Iterator[T_PluginType]) -> None:
+        self._plugins = plugins
+
+    def apply(self, handler: Callable[[T_PluginType], None]) -> None:
+        for plugin in self._plugins:
+            handler(plugin)

rats/cli/__init__.py

@@ -0,0 +1,19 @@
+"""Uses `rats.annotations` to streamline the creation of CLI commands written with Click."""
+
+from ._annotations import CommandId, command, group
+from ._click import ClickCommandGroup, ClickCommandMapper
+from ._executable import ClickExecutable
+from ._plugins import AttachClickCommands, AttachClickGroup, ClickGroupPlugin, CommandContainer
+
+__all__ = [
+    "CommandId",
+    "command",
+    "group",
+    "ClickCommandMapper",
+    "ClickExecutable",
+    "ClickGroupPlugin",
+    "ClickCommandGroup",
+    "AttachClickCommands",
+    "AttachClickGroup",
+    "CommandContainer",
+]

rats/cli/_annotations.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, NamedTuple, TypeVar
+
+from rats import annotations as anns
+
+
+class CommandId(NamedTuple):
+    name: str
+
+    # does this api make it impossible to reference a given command that was auto generated?
+    @staticmethod
+    def auto() -> CommandId:
+        return CommandId(name=f"{__name__}:auto")
+
+
+T = TypeVar("T", bound=Callable[[Any], Any])
+
+
+def command(command_id: CommandId) -> Callable[[T], T]:
+    def decorator(fn: T) -> T:
+        if command_id == CommandId.auto():
+            return anns.annotation("commands", CommandId(fn.__name__.replace("_", "-")))(fn)
+        return anns.annotation("commands", command_id)(fn)
+
+    return decorator
+
+
+def group(command_id: CommandId) -> Callable[[T], T]:
+    def decorator(fn: T) -> T:
+        if command_id == CommandId.auto():
+            return anns.annotation("command-groups", CommandId(fn.__name__.replace("_", "-")))(fn)
+        return anns.annotation("commands", command_id)(fn)
+
+    return decorator
+
+
+def get_class_commands(cls: type) -> anns.AnnotationsContainer:
+    return anns.get_class_annotations(cls).with_namespace("commands")

rats/cli/_click.py

@@ -0,0 +1,38 @@
+from collections.abc import Callable, Mapping
+from typing import final
+
+import click
+
+
+class ClickCommandMapper:
+    _commands: Mapping[str, Callable[[], click.Command]]
+
+    def __init__(
+        self,
+        commands: Mapping[str, Callable[[], click.Command]],
+    ) -> None:
+        self._commands = commands
+
+    def names(self) -> frozenset[str]:
+        return frozenset(self._commands.keys())
+
+    def get(self, name: str) -> click.Command:
+        if name not in self._commands:
+            raise ValueError(f"Command {name} not found")
+
+        return self._commands[name]()
+
+
+@final
+class ClickCommandGroup(click.Group):
+    _mapper: ClickCommandMapper
+
+    def __init__(self, name: str, mapper: ClickCommandMapper) -> None:
+        super().__init__(name=name)
+        self._mapper = mapper
+
+    def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command | None:
+        return self._mapper.get(cmd_name)
+
+    def list_commands(self, ctx: click.Context) -> list[str]:
+        return list(self._mapper.names())

rats/cli/_executable.py

@@ -0,0 +1,23 @@
+import click
+
+from rats import apps
+
+from ._plugins import ClickGroupPlugin
+
+
+class ClickExecutable(apps.Executable):
+    _command: apps.ServiceProvider[click.Group]
+    _plugins: apps.PluginRunner[ClickGroupPlugin]
+
+    def __init__(
+        self,
+        command: apps.ServiceProvider[click.Group],
+        plugins: apps.PluginRunner[ClickGroupPlugin],
+    ) -> None:
+        self._command = command
+        self._plugins = plugins
+
+    def execute(self) -> None:
+        cmd = self._command()
+        self._plugins.apply(lambda plugin: plugin.on_group_open(cmd))
+        cmd()

rats/cli/_plugins.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from abc import abstractmethod
+from collections.abc import Callable, Iterator
+from functools import partial
+from typing import Any, Protocol
+
+import click
+
+from rats import apps
+
+from ._annotations import get_class_commands
+
+
+class ClickGroupPlugin(Protocol):
+    @abstractmethod
+    def on_group_open(self, group: click.Group) -> None:
+        pass
+
+
+class AttachClickCommands(ClickGroupPlugin):
+    """When a group is opened, attach a set of commands to it."""
+
+    _commands: Iterator[click.Command]
+
+    def __init__(self, commands: Iterator[click.Command]) -> None:
+        self._commands = commands
+
+    def on_group_open(self, group: click.Group) -> None:
+        for command in self._commands:
+            group.add_command(command)
+
+
+class AttachClickGroup(ClickGroupPlugin):
+    _group: apps.ServiceProvider[click.Group]
+    _plugins: apps.PluginRunner[ClickGroupPlugin]
+
+    def __init__(
+        self,
+        group: apps.ServiceProvider[click.Group],
+        plugins: apps.PluginRunner[ClickGroupPlugin],
+    ) -> None:
+        self._group = group
+        self._plugins = plugins
+
+    def on_group_open(self, group: click.Group) -> None:
+        cmd = self._group()
+        self._plugins.apply(lambda plugin: plugin.on_group_open(cmd))
+        group.add_command(cmd)
+
+
+class CommandContainer(ClickGroupPlugin):
+    def on_group_open(self, group: click.Group) -> None:
+        def cb(_method: Callable[[Any], Any], *args: Any, **kwargs: Any) -> None:
+            """
+            Callback handed to `click.Command`. Calls the method with matching name on this class.
+
+            When the command is decorated with `@click.params` and `@click.option`, `click` will
+            call this callback with the parameters in the order they were defined. This callback
+            then calls the method with the same name on this class, passing the parameters in
+            reverse order. This is because the method is defined with the parameters in the
+            reverse order to the decorator, so we need to reverse them again to get the correct
+            order.
+            """
+            _method(*args, **kwargs)
+
+        commands = get_class_commands(type(self))
+        tates = commands.annotations
+
+        for tate in tates:
+            method = getattr(self, tate.name)
+            params = list(reversed(getattr(method, "__click_params__", [])))
+            for command in tate.groups:
+                group.add_command(
+                    click.Command(
+                        name=command.name,
+                        callback=partial(cb, method),
+                        short_help=method.__doc__,
+                        params=params,
+                    )
+                )

{rats_apps-0.1.3.dev50.dist-info → rats_apps-0.1.3.dev58.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: rats-apps
-Version: 0.1.3.dev50
+Version: 0.1.3.dev58
 Summary: research analysis tools for building applications
 Home-page: https://github.com/microsoft/rats/
 License: MIT
@@ -11,6 +11,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: click
 Requires-Dist: typing_extensions
 Project-URL: Documentation, https://microsoft.github.io/rats/
 Project-URL: Repository, https://github.com/microsoft/rats/

rats_apps-0.1.3.dev58.dist-info/RECORD

@@ -0,0 +1,23 @@
+rats/annotations/__init__.py,sha256=wsGhRQzZrV2oJTnBAX0aGgpyT1kYT235jkP3Wb8BTRY,498
+rats/annotations/_functions.py,sha256=r4Y-9fOZ9M0lDpcIv8nMuggEffc2bgZLeubWRj8uj-o,3552
+rats/annotations/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rats/apps/__init__.py,sha256=e9RQPGGgm3IG1XZgaK4e2u18-jQ4D9Seo7vpGgwuD0k,1340
+rats/apps/_annotations.py,sha256=LOuVckzeUmbDWko8tB2HpACc_xdLoldeNJpAgvclf-s,6991
+rats/apps/_composite_container.py,sha256=wSWVQWPin2xxIlEoSgk_D1rlc3N2gpTxQ2y9UFdqXy0,553
+rats/apps/_container.py,sha256=5uiCyxN6HS2z97XcTOFP-t72cNoB1U1sJMkMcfSfDps,3129
+rats/apps/_executables.py,sha256=8ITn__pjTLHo7FEb-3C6ZQrs1mow0gZn6d-24XGBSu8,1079
+rats/apps/_ids.py,sha256=dxWCPMpMA_vpaTDJEKNByIBJaX97Db203XqWLhaOezo,457
+rats/apps/_namespaces.py,sha256=THUV_Xj5PtweC23Ob-zsSpk8exC4fT-qRwjpQ6IDm0U,188
+rats/apps/_plugin_container.py,sha256=W_xQD2btc0N2dEb3c5tXM-ZZ4A4diMpkCjbOZdlXYuI,853
+rats/apps/_plugins.py,sha256=i1K5dCRC9cRA5QLiIdVUDJNM2rG935fdvqSTAK49h38,499
+rats/apps/_scoping.py,sha256=plSVEq3rJ8JFAu2epVg2NQpuTbpSTA3a0Tha_DwJL_Y,1453
+rats/apps/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rats/cli/__init__.py,sha256=LJe3zGI4IH2Siti4kQjqHOrxygv03g3hDE7jwpfYS9E,574
+rats/cli/_annotations.py,sha256=0dI8hu_y754Y53Pka1-mGEgHjjVcnIOGd8l1SFx8OBY,1190
+rats/cli/_click.py,sha256=7-ClnYSW4poFr_B-Q6NT45DnMF1XL7ntUgwQqQ7q_eo,1036
+rats/cli/_executable.py,sha256=kAQ9hImv3hBaScu6e19o_BMvl7tdYJql38E76S3FjSk,580
+rats/cli/_plugins.py,sha256=H3-QdaICPJhCC5FkLHdXpwqe7Z0mpvsenakhNiPllC8,2739
+rats/cli/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rats_apps-0.1.3.dev58.dist-info/METADATA,sha256=5Jtm7M9adH9QwyM7lEb_CsSMSQV1sgydmD3X89iT6dE,738
+rats_apps-0.1.3.dev58.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+rats_apps-0.1.3.dev58.dist-info/RECORD,,

rats_apps-0.1.3.dev50.dist-info/RECORD

@@ -1,13 +0,0 @@
-rats/apps/__init__.py,sha256=C2AHnjIf0Bf4gnrS4sO0QSEknIQXfn3X9qzknY7t9PE,1182
-rats/apps/_annotations.py,sha256=MMYqJ0F6MzynwOT3ZWKiIkXwQsaD4rvkpkURP4EzZDE,6971
-rats/apps/_composite_container.py,sha256=wSWVQWPin2xxIlEoSgk_D1rlc3N2gpTxQ2y9UFdqXy0,553
-rats/apps/_container.py,sha256=5uiCyxN6HS2z97XcTOFP-t72cNoB1U1sJMkMcfSfDps,3129
-rats/apps/_executables.py,sha256=8ITn__pjTLHo7FEb-3C6ZQrs1mow0gZn6d-24XGBSu8,1079
-rats/apps/_ids.py,sha256=dxWCPMpMA_vpaTDJEKNByIBJaX97Db203XqWLhaOezo,457
-rats/apps/_namespaces.py,sha256=THUV_Xj5PtweC23Ob-zsSpk8exC4fT-qRwjpQ6IDm0U,188
-rats/apps/_plugin_container.py,sha256=W_xQD2btc0N2dEb3c5tXM-ZZ4A4diMpkCjbOZdlXYuI,853
-rats/apps/_scoping.py,sha256=plSVEq3rJ8JFAu2epVg2NQpuTbpSTA3a0Tha_DwJL_Y,1453
-rats/apps/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-rats_apps-0.1.3.dev50.dist-info/METADATA,sha256=u0iyVLDioMUseN9RcFdzffdxCGNpnZ9EltaWmoVhNc0,717
-rats_apps-0.1.3.dev50.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
-rats_apps-0.1.3.dev50.dist-info/RECORD,,