rats-apps 0.1.3.dev75__py3-none-any.whl → 0.1.3.dev20240624080525__py3-none-any.whl

rats/annotations/_functions.py

@@ -1,4 +1,3 @@
-# type: ignore
 from __future__ import annotations
 
 from collections import defaultdict
@@ -22,14 +21,14 @@ class GroupAnnotations(NamedTuple, Generic[T_GroupType]):
     groups: tuple[T_GroupType, ...]
 
 
-class AnnotationsContainer(NamedTuple):
+class AnnotationsContainer(tNamedTuple):
     """
-    Holds metadata about the annotated service provider.
+    Holds metadata about the annotated functions or class methods.
 
     Loosely inspired by: https://peps.python.org/pep-3107/.
     """
 
-    annotations: tuple[GroupAnnotations[...], ...]
+    annotations: tuple[GroupAnnotations[Any], ...]
 
     @staticmethod
     def empty() -> AnnotationsContainer:
@@ -38,7 +37,7 @@ class AnnotationsContainer(NamedTuple):
     def with_group(
         self,
         namespace: str,
-        group_id: T_GroupType,
+        group_id: NamedTuple,
     ) -> AnnotationsContainer:
         return AnnotationsContainer(
             annotations=tuple(
@@ -87,6 +86,13 @@ 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]
@@ -100,14 +106,22 @@ def annotation(
 
 @cache
 def get_class_annotations(cls: type) -> AnnotationsContainer:
-    tates = []
+    """
+    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
 
-        tates.extend(method.__rats_annotations__.make(method_name).annotations)
+        builder: AnnotationsBuilder = method.__rats_annotations__
+        tates.extend(builder.make(method_name).annotations)
 
     return AnnotationsContainer(annotations=tuple(tates))
 
@@ -116,6 +130,12 @@ 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__",

rats/apps/__init__.py

@@ -1,16 +1,14 @@
 """
-Provides a small set of libraries to help create new applications.
+Libraries to help create applications with a strong focus on composability and testability.
 
 Applications give you the ability to define a development experience to match your project's
 domain.
 """
 
 from ._annotations import (
-    AnnotatedContainer,
     autoid,
     autoid_service,
     config,
-    container,
     fallback_config,
     fallback_group,
     fallback_service,
@@ -19,23 +17,26 @@ from ._annotations import (
 )
 from ._composite_container import CompositeContainer
 from ._container import (
+    AnnotatedContainer,  # type: ignore[reportDeprecated]
     ConfigProvider,
     Container,
     DuplicateServiceError,
     ServiceNotFoundError,
     ServiceProvider,
+    container,
 )
-from ._executables import App, AppContainer, Executable
+from ._executables import App, Executable
 from ._ids import ConfigId, ServiceId
 from ._namespaces import ProviderNamespaces
 from ._plugin_container import PluginContainers
 from ._plugins import PluginRunner
+from ._runtimes import Runtime, T_ExecutableType
 from ._scoping import autoscope
+from ._simple_apps import AppServices, SimpleApplication, SimpleRuntime
 
 __all__ = [
     "AnnotatedContainer",
     "App",
-    "AppContainer",
     "CompositeContainer",
     "ConfigId",
     "Container",
@@ -58,4 +59,10 @@ __all__ = [
     "group",
     "autoid",
     "service",
+    "T_ExecutableType",
+    "Runtime",
+    "AppServices",
+    "SimpleRuntime",
+    "SimpleRuntime",
+    "SimpleApplication",
 ]

rats/apps/_annotations.py

@@ -1,157 +1,72 @@
-import abc
-from collections import defaultdict
-from collections.abc import Callable, Iterator
-from functools import cache
-from typing import Any, ParamSpec, cast
+from collections.abc import Callable
+from typing import Any, ParamSpec
 
-from typing_extensions import NamedTuple
+from rats import annotations
 
-from ._container import Container
 from ._ids import ConfigId, ServiceId, T_ConfigType, T_ServiceType
 from ._namespaces import ProviderNamespaces
 from ._scoping import scope_service_name
 
-DEFAULT_CONTAINER_GROUP = ServiceId[Container]("__default__")
-
-
-class GroupAnnotations(NamedTuple):
-    """
-    The list of service ids attached to a given function.
-
-    The `name` attribute is the name of the function, and the `namespace` attribute represents a
-    specific meaning for the group of services.
-    """
-
-    name: str
-    namespace: str
-    groups: tuple[ServiceId[Any], ...]
-
-
-class FunctionAnnotations(NamedTuple):
-    """
-    Holds metadata about the annotated service provider.
-
-    Loosely inspired by: https://peps.python.org/pep-3107/.
-    """
-
-    providers: tuple[GroupAnnotations, ...]
-
-    def group_in_namespace(
-        self,
-        namespace: str,
-        group_id: ServiceId[T_ServiceType],
-    ) -> tuple[GroupAnnotations, ...]:
-        return tuple([x for x in self.with_namespace(namespace) if group_id in x.groups])
-
-    def with_namespace(
-        self,
-        namespace: str,
-    ) -> tuple[GroupAnnotations, ...]:
-        return tuple([x for x in self.providers if x.namespace == namespace])
-
-
-class FunctionAnnotationsBuilder:
-    _service_ids: dict[str, list[ServiceId[Any]]]
-
-    def __init__(self) -> None:
-        self._service_ids = defaultdict(list)
-
-    def add(self, namespace: str, service_id: ServiceId[T_ServiceType]) -> None:
-        self._service_ids[namespace].append(service_id)
-
-    def get_service_names(self, namespace: str) -> tuple[str, ...]:
-        return tuple(s.name for s in self._service_ids.get(namespace, []))
-
-    def make(self, name: str) -> tuple[GroupAnnotations, ...]:
-        return tuple(
-            [
-                GroupAnnotations(name=name, namespace=namespace, groups=tuple(services))
-                for namespace, services in self._service_ids.items()
-            ]
-        )
-
-
-class AnnotatedContainer(Container, abc.ABC):
-    def get_namespaced_group(
-        self,
-        namespace: str,
-        group_id: ServiceId[T_ServiceType],
-    ) -> Iterator[T_ServiceType]:
-        annotations = _extract_class_annotations(type(self))
-        containers = annotations.with_namespace(ProviderNamespaces.CONTAINERS)
-        groups = annotations.group_in_namespace(namespace, group_id)
-
-        for annotation in groups:
-            yield getattr(self, annotation.name)()
-
-        for container in containers:
-            c = getattr(self, container.name)()
-            yield from c.get_namespaced_group(namespace, group_id)
-
-
 P = ParamSpec("P")
 
 
 def service(
     service_id: ServiceId[T_ServiceType],
 ) -> Callable[[Callable[P, T_ServiceType]], Callable[P, T_ServiceType]]:
-    return fn_annotation_decorator(ProviderNamespaces.SERVICES, service_id)
+    """A service is anything you would create instances of?"""
+    return annotations.annotation(ProviderNamespaces.SERVICES, service_id)
 
 
 def autoid_service(fn: Callable[P, T_ServiceType]) -> Callable[P, T_ServiceType]:
     _service_id = autoid(fn)
-    _add_annotation(ProviderNamespaces.SERVICES, fn, _service_id)
-    cached_fn = cache(fn)
-    return cast(Callable[P, T_ServiceType], cached_fn)
+    return annotations.annotation(ProviderNamespaces.SERVICES, _service_id)(fn)
 
 
 def group(
     group_id: ServiceId[T_ServiceType],
 ) -> Callable[[Callable[P, T_ServiceType]], Callable[P, T_ServiceType]]:
-    return fn_annotation_decorator(ProviderNamespaces.GROUPS, group_id)
+    """A group is a collection of services."""
+    return annotations.annotation(ProviderNamespaces.GROUPS, group_id)
 
 
 def config(
     config_id: ConfigId[T_ConfigType],
 ) -> Callable[[Callable[P, T_ConfigType]], Callable[P, T_ConfigType]]:
-    return fn_annotation_decorator(ProviderNamespaces.SERVICES, config_id)
+    """A service that provides simple data-structures."""
+    return annotations.annotation(
+        ProviderNamespaces.SERVICES,
+        config_id,
+    )
 
 
 def fallback_service(
     service_id: ServiceId[T_ServiceType],
 ) -> Callable[[Callable[P, T_ServiceType]], Callable[P, T_ServiceType]]:
-    return fn_annotation_decorator(ProviderNamespaces.FALLBACK_SERVICES, service_id)
+    """A fallback service gets used if no service is defined."""
+    return annotations.annotation(
+        ProviderNamespaces.FALLBACK_SERVICES,
+        service_id,
+    )
 
 
 def fallback_group(
     group_id: ServiceId[T_ServiceType],
 ) -> Callable[[Callable[P, T_ServiceType]], Callable[P, T_ServiceType]]:
-    return fn_annotation_decorator(ProviderNamespaces.FALLBACK_GROUPS, group_id)
+    """A fallback group gets used if no group is defined."""
+    return annotations.annotation(
+        ProviderNamespaces.FALLBACK_GROUPS,
+        group_id,
+    )
 
 
 def fallback_config(
     config_id: ConfigId[T_ConfigType],
 ) -> Callable[[Callable[P, T_ConfigType]], Callable[P, T_ConfigType]]:
-    return fn_annotation_decorator(ProviderNamespaces.FALLBACK_SERVICES, config_id)
-
-
-def container(
-    group_id: ServiceId[T_ServiceType] = DEFAULT_CONTAINER_GROUP,
-) -> Callable[[Callable[P, T_ServiceType]], Callable[P, T_ServiceType]]:
-    return fn_annotation_decorator(ProviderNamespaces.CONTAINERS, group_id)
-
-
-def _get_method_service_id_name(method: Callable[..., Any]) -> str:
-    existing_names = _get_annotations_builder(method).get_service_names(
-        ProviderNamespaces.SERVICES
+    """A fallback config gets used if no config is defined."""
+    return annotations.annotation(
+        ProviderNamespaces.FALLBACK_SERVICES,
+        config_id,
     )
-    if existing_names:
-        return existing_names[0]
-    else:
-        module_name = method.__module__
-        class_name, method_name = method.__qualname__.rsplit(".", 1)
-        service_name = scope_service_name(module_name, class_name, method_name)
-        return service_name
 
 
 def autoid(method: Callable[..., T_ServiceType]) -> ServiceId[T_ServiceType]:
@@ -168,43 +83,12 @@ def autoid(method: Callable[..., T_ServiceType]) -> ServiceId[T_ServiceType]:
     return ServiceId[T_ServiceType](service_name)
 
 
-def fn_annotation_decorator(
-    namespace: str,
-    service_id: ServiceId[T_ServiceType],
-) -> Callable[[Callable[P, T_ServiceType]], Callable[P, T_ServiceType]]:
-    def wrapper(
-        fn: Callable[P, T_ServiceType],
-    ) -> Callable[P, T_ServiceType]:
-        _service_id = service_id
-        _add_annotation(namespace, fn, _service_id)
-        cached_fn = cache(fn)
-        # The static type of cached_fn should be correct, but it does not maintain the param-spec,
-        # so we need to cast.
-        return cast(Callable[P, T_ServiceType], cached_fn)
-
-    return wrapper
-
-
-@cache
-def _extract_class_annotations(cls: Any) -> FunctionAnnotations:
-    function_annotations: list[GroupAnnotations] = []
-    for method_name in dir(cls):
-        if method_name.startswith("_"):
-            continue
-
-        builder = _get_annotations_builder(getattr(cls, method_name))
-        function_annotations.extend(list(builder.make(method_name)))
-
-    return FunctionAnnotations(tuple(function_annotations))
-
-
-def _add_annotation(namespace: str, fn: Any, service_id: ServiceId[T_ServiceType]) -> None:
-    builder = _get_annotations_builder(fn)
-    builder.add(namespace, service_id)
-
+def _get_method_service_id_name(method: Callable[..., Any]) -> str:
+    tates = annotations.get_annotations(method).with_namespace(ProviderNamespaces.SERVICES)
 
-def _get_annotations_builder(fn: Any) -> FunctionAnnotationsBuilder:
-    if not hasattr(fn, "__rats_service_annotations__"):
-        fn.__rats_service_annotations__ = FunctionAnnotationsBuilder()
+    for a in tates.annotations:
+        return a.groups[0].name
 
-    return cast(FunctionAnnotationsBuilder, fn.__rats_service_annotations__)
+    module_name = method.__module__
+    class_name, method_name = method.__qualname__.rsplit(".", 1)
+    return scope_service_name(module_name, class_name, method_name)

rats/apps/_container.py

@@ -1,10 +1,18 @@
+import abc
+import logging
 from abc import abstractmethod
-from collections.abc import Iterator
-from typing import Generic, Protocol
+from collections.abc import Callable, Iterator
+from typing import Generic, ParamSpec, Protocol
+
+from typing_extensions import deprecated
+
+from rats import annotations
 
 from ._ids import ServiceId, T_ServiceType, Tco_ConfigType, Tco_ServiceType
 from ._namespaces import ProviderNamespaces
 
+logger = logging.getLogger(__name__)
+
 
 class ServiceProvider(Protocol[Tco_ServiceType]):
     @abstractmethod
@@ -19,15 +27,55 @@ class ConfigProvider(ServiceProvider[Tco_ConfigType], Protocol[Tco_ConfigType]):
 
 
 class Container(Protocol):
-    """Main interface for service containers."""
+    """
+    Main interface for service containers.
+
+    The default methods in this protocol  attempt to find service providers that have been
+    annotated.
+
+    Example:
+        .. code-block:: python
+
+            from rats import apps
+
+
+            class MyStorageClient:
+                def save(self, data: str) -> None:
+                    print(f"Saving data: {data}")
+
+
+            class MyPluginServices:
+                STORAGE_CLIENT = ServiceId[MyStorageClient]("storage-client")
+
+
+            class MyPluginContainer(apps.Container):
+                @apps.service(MyPluginServices.STORAGE_CLIENT)
+                def _storage_client() -> MyStorageClient:
+                    return MyStorageClient()
+
+
+            container = MyPluginContainer()
+            storage_client = container.get(MyPluginServices.STORAGE_CLIENT)
+            storage_client.save("Hello, world!")
+    """
 
     def has(self, service_id: ServiceId[T_ServiceType]) -> bool:
+        """
+        Check if a service is provided by this container.
+
+        Example:
+            .. code-block:: python
+
+                if not container.has(MyPluginServices.STORAGE_CLIENT):
+                    print("Did you forget to configure a storage client?")
+        """
         try:
             return self.get(service_id) is not None
         except ServiceNotFoundError:
             return False
 
     def has_group(self, group_id: ServiceId[T_ServiceType]) -> bool:
+        """Check if a service group has at least one provider in the container."""
         try:
             return next(self.get_group(group_id)) is not None
         except StopIteration:
@@ -64,13 +112,61 @@ class Container(Protocol):
 
         yield from self.get_namespaced_group(ProviderNamespaces.GROUPS, group_id)
 
-    @abstractmethod
     def get_namespaced_group(
         self,
         namespace: str,
         group_id: ServiceId[T_ServiceType],
     ) -> Iterator[T_ServiceType]:
         """Retrieve a service group by its id, within a given service namespace."""
+        tates = annotations.get_class_annotations(type(self))
+        containers = tates.with_namespace(ProviderNamespaces.CONTAINERS)
+        groups = tates.with_group(namespace, group_id)
+
+        for annotation in groups.annotations:
+            if not hasattr(self, f"__rats_cache_{annotation.name}"):
+                setattr(self, f"__rats_cache_{annotation.name}", getattr(self, annotation.name)())
+
+            yield getattr(self, f"__rats_cache_{annotation.name}")
+
+        for annotation in containers.annotations:
+            if not hasattr(self, f"__rats_container_cache_{annotation.name}"):
+                setattr(
+                    self,
+                    f"__rats_container_cache_{annotation.name}",
+                    getattr(self, annotation.name)(),
+                )
+
+            c = getattr(self, f"__rats_container_cache_{annotation.name}")
+            yield from c.get_namespaced_group(namespace, group_id)
+
+
+@deprecated(
+    " ".join(
+        [
+            "AnnotatedContainer is deprecated and will be removed in the next major release.",
+            "The functionality has been moved into the apps.Container protocol.",
+            "Please extend apps.Container directly.",
+        ]
+    ),
+    stacklevel=2,
+)
+class AnnotatedContainer(Container, abc.ABC):
+    """
+    A Container implementation that extracts providers from its annotated methods.
+
+    .. deprecated:: 0.1.3
+    The behavior of this class has been made the default within ``Container``.
+    """
+
+
+DEFAULT_CONTAINER_GROUP = ServiceId[Container]("__default__")
+P = ParamSpec("P")
+
+
+def container(
+    group_id: ServiceId[T_ServiceType] = DEFAULT_CONTAINER_GROUP,
+) -> Callable[[Callable[P, T_ServiceType]], Callable[P, T_ServiceType]]:
+    return annotations.annotation(ProviderNamespaces.CONTAINERS, group_id)
 
 
 class ServiceNotFoundError(RuntimeError, Generic[T_ServiceType]):

rats/apps/_executables.py

@@ -1,19 +1,30 @@
 from abc import abstractmethod
-from collections.abc import Callable, Iterator
-from functools import cache
+from collections.abc import Callable
 from typing import Protocol
 
-from ._container import Container, ServiceId
-from ._ids import T_ServiceType
-
 
 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:
@@ -23,19 +34,19 @@ class App(Executable):
         self._callback()
 
 
-class AppContainer(Container):
-    _container: Callable[[Container], Container]
-
-    def __init__(self, container: Callable[[Container], Container]) -> None:
-        self._container = container
-
-    def get_namespaced_group(
-        self,
-        namespace: str,
-        group_id: ServiceId[T_ServiceType],
-    ) -> Iterator[T_ServiceType]:
-        yield from self._load_container().get_namespaced_group(namespace, group_id)
-
-    @cache  # noqa: B019
-    def _load_container(self) -> Container:
-        return self._container(self)
+# class AppContainer(Container):
+#     _container: Callable[[Container], Container]
+#
+#     def __init__(self, container: Callable[[Container], Container]) -> None:
+#         self._container = container
+#
+#     def get_namespaced_group(
+#         self,
+#         namespace: str,
+#         group_id: ServiceId[T_ServiceType],
+#     ) -> Iterator[T_ServiceType]:
+#         yield from self._load_container().get_namespaced_group(namespace, group_id)
+#
+#     @cache
+#     def _load_container(self) -> Container:
+#         return self._container(self)

rats/apps/_plugin_container.py

@@ -9,10 +9,12 @@ from ._ids import ServiceId, T_ServiceType
 class PluginContainers(Container):
     _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 +27,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

@@ -1,3 +1,4 @@
+import warnings
 from collections.abc import Callable, Iterator
 from typing import Generic, TypeVar
 
@@ -13,5 +14,10 @@ class PluginRunner(Generic[T_PluginType]):
         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,32 @@
+from abc import abstractmethod
+from collections.abc import Callable
+from typing import Protocol, TypeVar
+
+from ._executables import Executable
+from ._ids import ServiceId
+
+T_ExecutableType = TypeVar("T_ExecutableType", bound=Executable)
+
+
+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.
+        """

rats/apps/_scoping.py

@@ -8,10 +8,6 @@ T = TypeVar("T")
 P = ParamSpec("P")
 
 
-def scope_service_name(module_name: str, cls_name: str, name: str) -> str:
-    return f"{module_name}:{cls_name}[{name}]"
-
-
 def autoscope(cls: type[T]) -> type[T]:
     """
     Decorator that replaces all ServiceId instances in the class with scoped ServiceId instances.
@@ -45,3 +41,7 @@ def autoscope(cls: type[T]) -> type[T]:
             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,144 @@
+from collections.abc import Callable, Iterable, Iterator
+from contextlib import contextmanager
+from typing import final
+
+from ._annotations import fallback_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")
+    CONTAINER = ServiceId[Container]("app-container")
+    CALLABLE_EXE_CTX = ServiceId[ExecutableCallableContext]("callable-exe-ctx")
+    CALLABLE_EXE = ServiceId[Executable]("callable-exe")
+
+
+@final
+class SimpleRuntime(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]
+
+    def __init__(self, *plugin_groups: str) -> None:
+        self._plugin_groups = plugin_groups
+
+    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 is an instance of SimpleRuntime.
+
+        Define a non-fallback service to override this default implementation.
+        """
+        return SimpleRuntime(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:
+        return CompositeContainer(
+            *[PluginContainers(self, group) for group in self._plugin_groups],
+        )

rats/cli/__init__.py

@@ -1,14 +1,17 @@
-"""Uses `rats.annotations` to streamline the creation of CLI commands written with Click."""
+"""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",

rats/cli/_plugin.py

@@ -0,0 +1,69 @@
+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]:
+        # autowrapped!
+        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/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,60 @@
+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",
+                        }
+                    },
+                    "root": {"level": "INFO", "handlers": ["console"]},
+                }
+            )
+        )

{rats_apps-0.1.3.dev75.dist-info → rats_apps-0.1.3.dev20240624080525.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: rats-apps
-Version: 0.1.3.dev75
+Version: 0.1.3.dev20240624080525
 Summary: research analysis tools for building applications
 Home-page: https://github.com/microsoft/rats/
 License: MIT
@@ -12,6 +12,7 @@ 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/

rats_apps-0.1.3.dev20240624080525.dist-info/RECORD

@@ -0,0 +1,29 @@
+rats/annotations/__init__.py,sha256=wsGhRQzZrV2oJTnBAX0aGgpyT1kYT235jkP3Wb8BTRY,498
+rats/annotations/_functions.py,sha256=ziAZOqS1lojfjDjZW7qPYNJUAFuLBWtVAoPsmJqxqpE,4356
+rats/annotations/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rats/apps/__init__.py,sha256=yvwCwhSZrPre0_SNESf0asSrabZrru9P_JteKcljemU,1611
+rats/apps/_annotations.py,sha256=2dvq0ZXDUMC9LK4athRzHrVlx23rGYtw4Gn0aNA9aSk,3063
+rats/apps/_composite_container.py,sha256=wSWVQWPin2xxIlEoSgk_D1rlc3N2gpTxQ2y9UFdqXy0,553
+rats/apps/_container.py,sha256=tIpU4o1nK5tQaOKZHh35qGBw6TV4uuU0k5vDY6NwS3Y,6280
+rats/apps/_executables.py,sha256=acwOXlWpGmLuSFr30dPzg2LU6-ae1yfOtbDRTIXLEjc,1520
+rats/apps/_ids.py,sha256=dxWCPMpMA_vpaTDJEKNByIBJaX97Db203XqWLhaOezo,457
+rats/apps/_namespaces.py,sha256=THUV_Xj5PtweC23Ob-zsSpk8exC4fT-qRwjpQ6IDm0U,188
+rats/apps/_plugin_container.py,sha256=Vhh1IdCzpUVwRdh301sALX7DQKny7Hru-yF_GwdxVqc,1075
+rats/apps/_plugins.py,sha256=mvSYQPi11wTGZpM4umoyD37Rc8CQX8nt5eAJbmLrBFM,688
+rats/apps/_runtimes.py,sha256=r6aRoI4rAkUh0uv3IKn-rNuwEu2MmB724rHsJpHDO74,1138
+rats/apps/_scoping.py,sha256=EIUopw3b38CEV57kCmSKQTAnQQMcXHZ_vwtk9t0K__g,1453
+rats/apps/_simple_apps.py,sha256=wjrPUt2_GLnp065gKSfIgG_3aLAU9ixi9rRt2d9mIJw,4742
+rats/apps/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rats/cli/__init__.py,sha256=dMrubxMJocbl8QoI_3fKI0Dt0QHYAM5Mxh5Vj8OaX-w,664
+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/_plugin.py,sha256=iUf2-ScR8o5p3g-0M1qNTAb3l9Q-FIBVjT_HEskISJY,2301
+rats/cli/_plugins.py,sha256=H3-QdaICPJhCC5FkLHdXpwqe7Z0mpvsenakhNiPllC8,2739
+rats/cli/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rats/logs/__init__.py,sha256=fCn4pfpYiAcTtt5CsnUZX68CjOB3KJHxMSiYxsma4qE,183
+rats/logs/_plugin.py,sha256=j3hLJDcdF4DvxeZ84zdMGP4EHgfMEzZc0wBGQjvrzGc,2039
+rats_apps-0.1.3.dev20240624080525.dist-info/METADATA,sha256=Vy9kUx6YxdnFpwc9rhhw6toJ3F6LiVfDR5_oH3_QcT4,774
+rats_apps-0.1.3.dev20240624080525.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+rats_apps-0.1.3.dev20240624080525.dist-info/entry_points.txt,sha256=9oOvf2loQr5ACWQgvuu9Q3KZIVIxKE5Aa-rLuUII5WQ,91
+rats_apps-0.1.3.dev20240624080525.dist-info/RECORD,,

rats_apps-0.1.3.dev20240624080525.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[rats.apps.plugins]
+rats.cli=rats.cli:PluginContainer
+rats.logs=rats.logs:PluginContainer
+

rats_apps-0.1.3.dev75.dist-info/RECORD

@@ -1,23 +0,0 @@
-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.dev75.dist-info/METADATA,sha256=LLwWeGo0LQUWWTvwzATROfpAPux4cSLOydQcLHcYK8o,738
-rats_apps-0.1.3.dev75.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
-rats_apps-0.1.3.dev75.dist-info/RECORD,,