rats-apps 0.1.2.dev14__py3-none-any.whl → 0.1.3__py3-none-any.whl

rats/apps/_plugin_container.py

@@ -7,12 +7,24 @@ from ._ids import ServiceId, T_ServiceType
 
 
 class PluginContainers(Container):
+    """
+    A container that loads plugins using importlib.metadata.entry_points.
+
+    When looking for groups, the container loads the specified entry_points and defers the lookups
+    to the plugins. Plugin containers are expected to be Callable[[Container], Container] objects,
+    where the input container is typically the root application container.
+
+    TODO: How do we better specify the API for plugins without relying on documentation?
+    """
+
     _app: Container
     _group: str
+    _names: tuple[str, ...]
 
-    def __init__(self, app: Container, group: str) -> None:
+    def __init__(self, app: Container, group: str, *names: str) -> None:
         self._app = app
         self._group = group
+        self._names = names
 
     def get_namespaced_group(
         self,
@@ -25,4 +37,7 @@ class PluginContainers(Container):
     @cache  # noqa: B019
     def _load_containers(self) -> Iterable[Container]:
         entries = entry_points(group=self._group)
-        return tuple(entry.load()(self._app) for entry in entries)
+        return tuple(entry.load()(self._app) for entry in entries if self._is_enabled(entry.name))
+
+    def _is_enabled(self, plugin_name: str) -> bool:
+        return len(self._names) == 0 or plugin_name in self._names

rats/apps/_plugins.py

@@ -0,0 +1,23 @@
+import warnings
+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:
+        warnings.warn(
+            "PluginRunner is deprecated. Use PluginContainer instances instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        for plugin in self._plugins:
+            handler(plugin)

rats/apps/_runtimes.py

@@ -0,0 +1,41 @@
+from abc import abstractmethod
+from collections.abc import Callable
+from typing import Protocol, final
+
+from ._ids import ServiceId, T_ExecutableType
+
+
+class Runtime(Protocol):
+    @abstractmethod
+    def execute(self, *exe_ids: ServiceId[T_ExecutableType]) -> None:
+        """Execute a list of executables sequentially."""
+
+    @abstractmethod
+    def execute_group(self, *exe_group_ids: ServiceId[T_ExecutableType]) -> None:
+        """
+        Execute one or more groups of executables sequentially.
+
+        Although each group is expected to be executed sequentially, the groups themselves are not
+        executed in a deterministic order. Runtime implementations are free to execute groups in
+        parallel or in any order that is convenient.
+        """
+
+    @abstractmethod
+    def execute_callable(self, *callables: Callable[[], None]) -> None:
+        """
+        Execute provided callables by automatically turning them into apps.Executable objects.
+
+        The used ServiceId is determined by the Runtime implementation.
+        """
+
+
+@final
+class NullRuntime(Runtime):
+    def execute(self, *exe_ids: ServiceId[T_ExecutableType]) -> None:
+        raise NotImplementedError("NullRuntime does not support execution.")
+
+    def execute_group(self, *exe_group_ids: ServiceId[T_ExecutableType]) -> None:
+        raise NotImplementedError("NullRuntime does not support execution.")
+
+    def execute_callable(self, *callables: Callable[[], None]) -> None:
+        raise NotImplementedError("NullRuntime does not support execution.")

rats/apps/_scoping.py

@@ -22,7 +22,7 @@ def autoscope(cls: type[T]) -> type[T]:
             if not isinstance(result, ServiceId):
                 return result
 
-            return ServiceId[Any](f"{cls.__module__}:{cls.__name__}[{result.name}]")
+            return ServiceId[Any](scope_service_name(cls.__module__, cls.__name__, result.name))
 
         return cast(FunctionType, wrapper)
 
@@ -37,7 +37,11 @@ def autoscope(cls: type[T]) -> type[T]:
             if not isinstance(non_ns, ServiceId):
                 continue
 
-            prop = ServiceId[Any](f"{cls.__module__}:{cls.__name__}[{non_ns.name}]")
+            prop = ServiceId[Any](scope_service_name(cls.__module__, cls.__name__, non_ns.name))
             setattr(cls, prop_name, prop)
 
     return cls
+
+
+def scope_service_name(module_name: str, cls_name: str, name: str) -> str:
+    return f"{module_name}:{cls_name}[{name}]"

rats/apps/_simple_apps.py

@@ -0,0 +1,163 @@
+from collections.abc import Callable, Iterable, Iterator
+from contextlib import contextmanager
+from typing import final
+
+from ._annotations import fallback_service, service
+from ._composite_container import CompositeContainer
+from ._container import Container, container
+from ._executables import App, Executable
+from ._ids import ServiceId
+from ._plugin_container import PluginContainers
+from ._runtimes import Runtime, T_ExecutableType
+from ._scoping import autoscope
+
+
+class ExecutableCallableContext(Executable):
+    """
+    An executable that can be set dynamically with a callable.
+
+    We use this class to support the use of `rats.apps` with a plain callable, like is expected of
+    standard python scripts. We give this class a service id, and set the callable before using
+    `apps.Runtime` to execute the chosen service id.
+    """
+
+    _exe_id: ServiceId[Executable]
+    _callables: list[Callable[[], None]]
+
+    def __init__(self, exe_id: ServiceId[Executable]) -> None:
+        self._exe_id = exe_id
+        self._callables = []
+
+    def execute(self) -> None:
+        if len(self._callables) == 0:
+            raise RuntimeError("No active executable found.")
+
+        self._callables[-1]()
+
+    @contextmanager
+    def open_callable(
+        self,
+        callable: Callable[[], None],
+    ) -> Iterator[Executable]:
+        self._callables.append(callable)
+        try:
+            yield App(callable)
+        finally:
+            self._callables.pop()
+
+
+@autoscope
+class AppServices:
+    """
+    Services used by simple apps that can generally be used anywhere.
+
+    Owners of applications can decide not to use or not to make these services available to plugin
+    authors.
+    """
+
+    RUNTIME = ServiceId[Runtime]("app-runtime")
+    STANDARD_RUNTIME = ServiceId[Runtime]("standard-runtime")
+    CONTAINER = ServiceId[Container]("app-container")
+    CALLABLE_EXE_CTX = ServiceId[ExecutableCallableContext]("callable-exe-ctx")
+    CALLABLE_EXE = ServiceId[Executable]("callable-exe")
+
+
+@final
+class StandardRuntime(Runtime):
+    """A simple runtime that executes sequentially and in a single thread."""
+
+    _app: Container
+
+    def __init__(self, app: Container) -> None:
+        self._app = app
+
+    def execute(self, *exe_ids: ServiceId[T_ExecutableType]) -> None:
+        for exe_id in exe_ids:
+            self._app.get(exe_id).execute()
+
+    def execute_group(self, *exe_group_ids: ServiceId[T_ExecutableType]) -> None:
+        for exe_group_id in exe_group_ids:
+            for exe in self._app.get_group(exe_group_id):
+                exe.execute()
+
+    def execute_callable(self, *callables: Callable[[], None]) -> None:
+        ctx: ExecutableCallableContext = self._app.get(AppServices.CALLABLE_EXE_CTX)
+        for cb in callables:
+            with ctx.open_callable(cb) as exe:
+                exe.execute()
+
+
+@final
+class SimpleApplication(Runtime, Container):
+    """An application without anything fancy."""
+
+    _plugin_groups: Iterable[str]
+    _runtime_plugin: Callable[[Container], Container] | None
+
+    def __init__(
+        self,
+        *plugin_groups: str,
+        runtime_plugin: Callable[[Container], Container] | None = None,
+    ) -> None:
+        self._plugin_groups = plugin_groups
+        self._runtime_plugin = runtime_plugin
+
+    def execute(self, *exe_ids: ServiceId[T_ExecutableType]) -> None:
+        self._runtime().execute(*exe_ids)
+
+    def execute_group(self, *exe_group_ids: ServiceId[T_ExecutableType]) -> None:
+        self._runtime().execute_group(*exe_group_ids)
+
+    def execute_callable(self, *callables: Callable[[], None]) -> None:
+        for cb in callables:
+            self._runtime().execute_callable(cb)
+
+    @fallback_service(AppServices.RUNTIME)
+    def _runtime(self) -> Runtime:
+        """
+        The default runtime defers to AppServices.STANDARD_RUNTIME.
+
+        Define a non-fallback service to override this default implementation.
+        """
+        return self.get(AppServices.STANDARD_RUNTIME)
+
+    @service(AppServices.STANDARD_RUNTIME)
+    def _std_runtime(self) -> Runtime:
+        """
+        The standard locally executed runtime.
+
+        Regardless of the configured AppServices.RUNTIME provider, everyone has access to this
+        class for plugin development.
+        """
+        return StandardRuntime(self)
+
+    @fallback_service(AppServices.CALLABLE_EXE)
+    def _callable_exe(self) -> Executable:
+        """We use the callable exe ctx here, so we can treat it like any other app downstream."""
+        return self.get(AppServices.CALLABLE_EXE_CTX)
+
+    @fallback_service(AppServices.CALLABLE_EXE_CTX)
+    def _callable_exe_ctx(self) -> ExecutableCallableContext:
+        """
+        The default executable context client for executing raw callables.
+
+        Define a non-fallback service to override this default implementation.
+        """
+        return ExecutableCallableContext(AppServices.CALLABLE_EXE)
+
+    @fallback_service(AppServices.CONTAINER)
+    def _container(self) -> Container:
+        """
+        The default container is the root application instance.
+
+        Define a non-fallback service to override this default implementation.
+        """
+        return self
+
+    @container()
+    def _plugins(self) -> Container:
+        plugins: list[Container] = [PluginContainers(self, group) for group in self._plugin_groups]
+        if self._runtime_plugin:
+            plugins.append(self._runtime_plugin(self))
+
+        return CompositeContainer(*plugins)

rats/cli/__init__.py

@@ -0,0 +1,22 @@
+"""Uses `rats.cli` 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 ._plugin import PluginContainer, PluginServices
+from ._plugins import AttachClickCommands, AttachClickGroup, ClickGroupPlugin, CommandContainer
+
+__all__ = [
+    "CommandId",
+    "PluginContainer",
+    "command",
+    "group",
+    "PluginServices",
+    "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/_plugin.py

@@ -0,0 +1,68 @@
+from typing import cast, final
+
+import click
+
+from rats import apps
+
+
+@apps.autoscope
+class _PluginEvents:
+    @staticmethod
+    def command_open(cmd_id: apps.ServiceId[apps.Executable]) -> apps.ServiceId[apps.Executable]:
+        return apps.ServiceId(f"command-open[{cmd_id.name}]")
+
+    @staticmethod
+    def command_execute(
+        cmd_id: apps.ServiceId[apps.Executable],
+    ) -> apps.ServiceId[apps.Executable]:
+        return apps.ServiceId(f"command-execute[{cmd_id.name}]")
+
+    @staticmethod
+    def command_close(cmd_id: apps.ServiceId[apps.Executable]) -> apps.ServiceId[apps.Executable]:
+        return apps.ServiceId(f"command-close[{cmd_id.name}]")
+
+
+@apps.autoscope
+class PluginServices:
+    ROOT_COMMAND = apps.ServiceId[apps.Executable]("root-command")
+    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)
+
+
+@final
+class PluginContainer(apps.Container):
+    _app: apps.Container
+
+    def __init__(self, app: apps.Container) -> None:
+        self._app = app
+
+    @apps.service(PluginServices.ROOT_COMMAND)
+    def _root_command(self) -> apps.Executable:
+        def run() -> None:
+            runtime = self._app.get(apps.AppServices.RUNTIME)
+            runtime.execute_group(
+                PluginServices.EVENTS.command_open(PluginServices.ROOT_COMMAND),
+                PluginServices.EVENTS.command_execute(PluginServices.ROOT_COMMAND),
+                PluginServices.EVENTS.command_close(PluginServices.ROOT_COMMAND),
+            )
+
+        return apps.App(run)
+
+    @apps.fallback_group(PluginServices.EVENTS.command_execute(PluginServices.ROOT_COMMAND))
+    def _default_command(self) -> apps.Executable:
+        group = self._app.get(PluginServices.click_command(PluginServices.ROOT_COMMAND))
+        return apps.App(lambda: group())
+
+    @apps.service(PluginServices.click_command(PluginServices.ROOT_COMMAND))
+    def _root_click_command(self) -> click.Group:
+        return click.Group("groot")

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/logs/__init__.py

@@ -0,0 +1,8 @@
+"""Small package to help configure logging for rats applications."""
+
+from ._plugin import PluginContainer, PluginServices
+
+__all__ = [
+    "PluginServices",
+    "PluginContainer",
+]

rats/logs/_plugin.py

@@ -0,0 +1,63 @@
+import logging.config
+
+from rats import apps
+
+logger = logging.getLogger(__name__)
+
+
+@apps.autoscope
+class _PluginEvents:
+    CONFIGURE_LOGGING = apps.ServiceId[apps.Executable]("configure-logging")
+
+
+@apps.autoscope
+class PluginServices:
+    EVENTS = _PluginEvents
+
+
+class PluginContainer(apps.Container):
+    _app: apps.Container
+
+    def __init__(self, app: apps.Container) -> None:
+        self._app = app
+
+    @apps.group(PluginServices.EVENTS.CONFIGURE_LOGGING)
+    def _configure_logging(self) -> apps.Executable:
+        # in the future, we can use this plugin to make logging easily configurable
+        return apps.App(
+            lambda: logging.config.dictConfig(
+                {
+                    "version": 1,
+                    "disable_existing_loggers": False,
+                    "formatters": {
+                        "colored": {
+                            "()": "colorlog.ColoredFormatter",
+                            "format": (
+                                "%(log_color)s%(asctime)s %(levelname)-8s [%(name)s][%(lineno)d]: "
+                                "%(message)s%(reset)s"
+                            ),
+                            "datefmt": "%Y-%m-%d %H:%M:%S",
+                            "log_colors": {
+                                "DEBUG": "white",
+                                "INFO": "green",
+                                "WARNING": "yellow",
+                                "ERROR": "red,",
+                                "CRITICAL": "bold_red",
+                            },
+                        }
+                    },
+                    "handlers": {
+                        "console": {
+                            "class": "logging.StreamHandler",
+                            "level": "DEBUG",
+                            "formatter": "colored",
+                            "stream": "ext://sys.stderr",
+                        }
+                    },
+                    "loggers": {
+                        "": {"level": "INFO", "handlers": ["console"]},
+                        "azure": {"level": "WARNING", "handlers": ["console"]},
+                    },
+                }
+            )
+        )

{rats_apps-0.1.2.dev14.dist-info → rats_apps-0.1.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: rats-apps
-Version: 0.1.2.dev14
+Version: 0.1.3
 Summary: research analysis tools for building applications
 Home-page: https://github.com/microsoft/rats/
 License: MIT
@@ -11,6 +11,8 @@ 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: colorlog
 Requires-Dist: typing_extensions
 Project-URL: Documentation, https://microsoft.github.io/rats/
 Project-URL: Repository, https://github.com/microsoft/rats/