rats-apps 0.1.3__py3-none-any.whl → 0.1.3.dev8__py3-none-any.whl

rats/annotations/_functions.py

@@ -1,145 +0,0 @@
-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(tNamedTuple):
-    """
-    Holds metadata about the annotated functions or class methods.
-
-    Loosely inspired by: https://peps.python.org/pep-3107/.
-    """
-
-    annotations: tuple[GroupAnnotations[Any], ...]
-
-    @staticmethod
-    def empty() -> AnnotationsContainer:
-        return AnnotationsContainer(annotations=())
-
-    def with_group(
-        self,
-        namespace: str,
-        group_id: NamedTuple,
-    ) -> 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]:
-    """
-    Decorator to add an annotation to a function.
-
-    Typically used to create domain-specific annotation functions for things like DI Containers.
-    For examples, see the rats.apps annotations, like service() and group().
-    """
-
-    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:
-    """
-    Get all annotations for a class.
-
-    Traverses the class methods looking for any annotated with "__rats_annotations__" and returns
-    an instance of AnnotationsContainer. This function tries to cache the results to avoid any
-    expensive parsing of the class methods.
-    """
-    tates: list[GroupAnnotations[Any]] = []
-
-    for method_name in dir(cls):
-        method = getattr(cls, method_name)
-        if not hasattr(method, "__rats_annotations__"):
-            continue
-
-        builder: AnnotationsBuilder = method.__rats_annotations__
-        tates.extend(builder.make(method_name).annotations)
-
-    return AnnotationsContainer(annotations=tuple(tates))
-
-
-P = ParamSpec("P")
-
-
-def get_annotations(fn: Callable[..., Any]) -> AnnotationsContainer:
-    """
-    Get all annotations for a function or class method.
-
-    Builds an instance of AnnotationsContainer from the annotations found in the object's
-    "__rats_annotations__" attribute.
-    """
-    builder: AnnotationsBuilder = getattr(
-        fn,
-        "__rats_annotations__",
-        AnnotationsBuilder(),
-    )
-
-    return builder.make(fn.__name__)

rats/apps/_executables.py

@@ -1,34 +0,0 @@
-from abc import abstractmethod
-from collections.abc import Callable
-from typing import Protocol
-
-
-class Executable(Protocol):
-    """
-    An interface for an executable object.
-
-    One of the lowest level abstractions in the rats-apps library, executables are meant to be
-    easy to run from anywhere, with limited knowledge of the implementation details of the object,
-    by ensuring that the object has an `execute` method with no arguments.
-    """
-
-    @abstractmethod
-    def execute(self) -> None:
-        """Execute the application."""
-
-
-class App(Executable):
-    """
-    Wraps a plain callable objects as an executable.
-
-    This simple object allows for turning any callable object into an executable that is recognized
-    by the rest of the rats application.
-    """
-
-    _callback: Callable[[], None]
-
-    def __init__(self, callback: Callable[[], None]) -> None:
-        self._callback = callback
-
-    def execute(self) -> None:
-        self._callback()

rats/apps/_plugins.py

@@ -1,23 +0,0 @@
-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

@@ -1,41 +0,0 @@
-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/_simple_apps.py

@@ -1,163 +0,0 @@
-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

@@ -1,22 +0,0 @@
-"""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

@@ -1,40 +0,0 @@
-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

@@ -1,38 +0,0 @@
-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

@@ -1,23 +0,0 @@
-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

@@ -1,68 +0,0 @@
-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

@@ -1,81 +0,0 @@
-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,
-                    )
-                )