rats-apps 0.4.0.dev20241217004929__py3-none-any.whl → 0.5.0__py3-none-any.whl

rats/annotations/__init__.py

@@ -15,11 +15,11 @@ from ._functions import (
 )
 
 __all__ = [
-    "annotation",
-    "DecoratorType",
     "AnnotationsContainer",
-    "get_annotations",
-    "get_class_annotations",
+    "DecoratorType",
     "GroupAnnotations",
     "T_GroupType",
+    "annotation",
+    "get_annotations",
+    "get_class_annotations",
 ]

rats/apps/__init__.py

@@ -15,6 +15,14 @@ from ._annotations import (
     group,
     service,
 )
+from ._app_containers import (
+    AppBundle,
+    AppContainer,
+    AppPlugin,
+    CompositePlugin,
+    ContainerPlugin,
+    PluginMixin,
+)
 from ._composite_container import CompositeContainer
 from ._container import (
     Container,
@@ -22,51 +30,54 @@ from ._container import (
     GroupProvider,
     Provider,
     ServiceNotFoundError,
-    ServiceProvider,
     container,
 )
 from ._executables import App, Executable
 from ._ids import ServiceId, T_ExecutableType, T_ServiceType
+from ._mains import run, run_plugin
 from ._namespaces import ProviderNamespaces
-from ._plugin_container import PluginContainers
-from ._plugins import PluginRunner
-from ._runtimes import NullRuntime, Runtime
+from ._plugin_container import PythonEntryPointContainer
+from ._runtimes import NullRuntime, Runtime, StandardRuntime
 from ._scoping import autoscope
-from ._simple_apps import AppServices, SimpleApplication, StandardRuntime
-from ._static_container import StaticContainer, StaticProvider
+from ._static_container import StaticContainer, StaticProvider, static_group, static_service
 
 __all__ = [
     "App",
+    "AppBundle",
+    "AppContainer",
+    "AppPlugin",
     "CompositeContainer",
+    "CompositePlugin",
     "Container",
-    "StaticContainer",
-    "StaticProvider",
+    "ContainerPlugin",
     "DuplicateServiceError",
     "Executable",
-    "PluginContainers",
-    "ProviderNamespaces",
-    "ServiceProvider",
-    "Provider",
     "GroupProvider",
+    "NullRuntime",
+    "PluginMixin",
+    "Provider",
+    "ProviderNamespaces",
+    "PythonEntryPointContainer",
+    "Runtime",
     "ServiceId",
     "ServiceNotFoundError",
+    "StandardRuntime",
+    "StaticContainer",
+    "StaticProvider",
+    "T_ExecutableType",
+    "T_ServiceType",
+    "autoid",
+    "autoid_factory_service",
     "autoid_service",
     "autoscope",
     "container",
-    "PluginRunner",
+    "factory_service",
     "fallback_group",
     "fallback_service",
     "group",
-    "autoid",
+    "run",
+    "run_plugin",
     "service",
-    "T_ExecutableType",
-    "T_ServiceType",
-    "Runtime",
-    "NullRuntime",
-    "AppServices",
-    "StandardRuntime",
-    "StandardRuntime",
-    "SimpleApplication",
-    "factory_service",
-    "autoid_factory_service",
+    "static_group",
+    "static_service",
 ]

rats/apps/_app_containers.py

@@ -0,0 +1,199 @@
+from __future__ import annotations
+
+import logging
+from abc import abstractmethod
+from collections.abc import Callable
+from functools import cache
+from typing import Protocol, final
+
+from ._composite_container import CompositeContainer
+from ._container import Container, container
+from ._executables import Executable
+
+logger = logging.getLogger(__name__)
+EMPTY_CONTEXT = CompositeContainer()
+
+
+def _empty_plugin(app: Container) -> Container:
+    return CompositeContainer()
+
+
+EMPTY_PLUGIN = _empty_plugin
+
+
+class AppContainer(Container, Executable, Protocol):
+    """The combination of a [rats.apps.Container][] an [rats.apps.Executable][]."""
+
+    def execute(self) -> None:
+        """The main application entry point."""
+        logger.warning(f"empty execute method in application: {self.__class__}")
+
+
+class _AppPluginType(Protocol):
+    @abstractmethod
+    def __call__(self, app: Container) -> AppContainer:
+        pass
+
+
+class _ContainerPluginType(Protocol):
+    @abstractmethod
+    def __call__(self, app: Container) -> Container:
+        pass
+
+
+AppPlugin = _AppPluginType | Callable[[Container], AppContainer]
+"""
+Main interface for a function that returns an [rats.apps.AppContainer][] instance.
+
+Functions that act as runners or application factories often take this as their input type in
+order to manage the top most [rats.apps.Container][] instance, allowing most containers to use the
+[rats.apps.PluginMixin][] mixin and rely on the top most container being managed automatically.
+This is the companion type to [rats.apps.ContainerPlugin][].
+"""
+
+ContainerPlugin = _ContainerPluginType | Callable[[Container], Container]
+"""
+Main interface for a function that returns an [rats.apps.Container][] instance.
+
+Containers that implement this type—for example, by using the [rats.apps.PluginMixin][] mixin—can
+be used easily in functions that need to defer the construction of an application container. See
+[rats.apps.AppBundle][] for additional examples.
+"""
+
+
+class PluginMixin:
+    """
+    Mix into your [Container][] classes to add our default constructor.
+
+    This mixin adds a common constructor to a `Container` in order to quickly create types that
+    are compatible with functions asking for `AppPlugin` and `ContainerPlugin` arguments.
+
+    !!! warning
+        Avoid using mixins as an input type to your functions, because we don't want to restrict
+        others to containers with a private `_app` property. Instead, use this as a shortcut to
+        some commonly used implementation details.
+
+    Example:
+        ```python
+         from rats import apps
+
+         class ExampleApplication(apps.AppContainer, apps.PluginMixin):
+
+            def execute() -> None:
+                print("hello, world!")
+
+
+        if __name__ == "__main__":
+            apps.run_plugin(ExampleApplication)
+        ```
+    """
+
+    _app: Container
+
+    def __init__(self, app: Container) -> None:
+        self._app = app
+
+
+class CompositePlugin:
+    """
+    Similar to [rats.apps.CompositeContainer][] but takes a list of plugin container types.
+
+    Example:
+        ```python
+        from rats import apps
+        from rats_e2e.apps import inputs
+
+
+        class ExamplePlugin1(apps.Container, apps.PluginMixin):
+            pass
+
+
+        class ExamplePlugin2(apps.Container, apps.PluginMixin):
+            pass
+
+
+        apps.run(
+            apps.AppBundle(
+                app_plugin=inputs.Application,
+                container_plugin=apps.CompositePlugin(
+                    ExamplePlugin1,
+                    ExamplePlugin2,
+                ),
+            )
+        )
+        ```
+    """
+
+    _plugins: tuple[ContainerPlugin, ...]
+
+    def __init__(self, *plugins: ContainerPlugin) -> None:
+        self._plugins = plugins
+
+    def __call__(self, app: Container) -> Container:
+        return CompositeContainer(*[plugin(app) for plugin in self._plugins])
+
+
+@final
+class AppBundle(AppContainer):
+    """
+    Brings together different types of containers to construct an executable application.
+
+    Use this class to defer the creation of an [rats.apps.AppContainer][] instance in order to
+    combine services with additional [rats.apps.ContainerPlugin][] classes.
+    """
+
+    _app_plugin: AppPlugin
+    _container_plugin: ContainerPlugin
+    _context: Container
+
+    def __init__(
+        self,
+        *,
+        app_plugin: AppPlugin,
+        container_plugin: ContainerPlugin = EMPTY_PLUGIN,
+        context: Container = EMPTY_CONTEXT,
+    ):
+        """
+        Create an instance by providing the [rats.apps.AppPlugin] type and any additional context.
+
+        Example:
+            ```python
+            from rats import apps
+
+
+            class ExamplePlugin(apps.Container, apps.PluginMixin):
+                @apps.service(apps.ServiceId[str]("some-value"))
+                def _some_value() -> str:
+                    return "hello, world!"
+
+
+            class ExampleApplication(apps.AppContainer, apps.PluginMixin):
+                def execute() -> None:
+                    print(self._app.get(apps.ServiceId[str]("some-value")))
+
+
+            if __name__ == "__main__":
+                apps.run(apps.AppBundle(ExampleApplication, ExamplePlugin))
+            ```
+
+        Args:
+            app_plugin: the class reference to the application container.
+            container_plugin: the class reference to an additional plugin container.
+            context: an optional plugin container to make part of the container tree.
+        """
+        self._app_plugin = app_plugin
+        self._container_plugin = container_plugin
+        self._context = context
+
+    def execute(self) -> None:
+        """Initializes a new [rats.apps.AppContainer] with the provided nodes before executing it."""
+        app, _ = self._get_or_create_containers()
+        app.execute()
+
+    @container()
+    def _plugins(self) -> Container:
+        return CompositeContainer(*self._get_or_create_containers(), self._context)
+
+    @cache  # noqa: B019
+    def _get_or_create_containers(self) -> tuple[AppContainer, Container]:
+        return self._app_plugin(self), self._container_plugin(self)

rats/apps/_container.py

@@ -19,10 +19,6 @@ class Provider(Protocol[Tco_ServiceType]):
         """Return the service instance."""
 
 
-# temporary alias for backwards compatibility
-ServiceProvider = Provider
-
-
 class GroupProvider(Protocol[Tco_ServiceType]):
     @abstractmethod
     def __call__(self) -> Iterator[Tco_ServiceType]:

rats/apps/_executables.py

@@ -19,16 +19,30 @@ class Executable(Protocol):
 
 class App(Executable):
     """
-    Wraps a plain callable objects as an executable.
+    Wraps a plain callable objects as a [rats.apps.Executable][].
 
     This simple object allows for turning any callable object into an executable that is recognized
     by the rest of the rats application.
+
+    Example:
+        ```python
+        from rats import apps
+
+        apps.App(lambda: print("hello, world")).execute()
+        ```
     """
 
     _callback: Callable[[], None]
 
     def __init__(self, callback: Callable[[], None]) -> None:
+        """
+        Created by providing a reference to a `Callable[[], None]` function.
+
+        Args:
+            callback: called when the application instance is executed.
+        """
         self._callback = callback
 
     def execute(self) -> None:
+        """Runs the provided callback."""
         self._callback()

rats/apps/_mains.py

@@ -0,0 +1,42 @@
+import logging
+
+from ._app_containers import AppBundle, AppPlugin
+from ._executables import Executable
+
+logger = logging.getLogger(__name__)
+
+
+def run(*apps: Executable) -> None:
+    """Shortcut for running a list of apps."""
+    for app in apps:
+        app.execute()
+
+
+def run_plugin(*app_plugins: AppPlugin) -> None:
+    """
+    Shortcut to create and execute instances of `apps.AppPlugin`.
+
+    This function is most commonly used in a `console_script` function `main()` entry point.
+
+    Example:
+        ```python
+        from rats import apps
+
+
+        class Application(apps.AppContainer, apps.AppPlugin):
+            def execute(self) -> None:
+                print("hello, world")
+
+
+        def main() -> None:
+            apps.run_plugin(Application)
+
+
+        if __name__ == "__main__":
+            main()
+        ```
+
+    Args:
+        *app_plugins: one or more class types to be instantiated and executed.
+    """
+    run(*[AppBundle(app_plugin=plugin) for plugin in app_plugins])

rats/apps/_plugin_container.py

@@ -6,9 +6,9 @@ from ._container import Container
 from ._ids import ServiceId, T_ServiceType
 
 
-class PluginContainers(Container):
+class PythonEntryPointContainer(Container):
     """
-    A container that loads plugins using importlib.metadata.entry_points.
+    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,

rats/apps/_runtimes.py

@@ -3,6 +3,7 @@ from abc import abstractmethod
 from collections.abc import Callable
 from typing import Protocol, final
 
+from ._container import Container
 from ._ids import ServiceId, T_ExecutableType
 
 logger = logging.getLogger(__name__)
@@ -23,14 +24,6 @@ class Runtime(Protocol):
         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):
@@ -48,3 +41,22 @@ class NullRuntime(Runtime):
 
     def execute_callable(self, *callables: Callable[[], None]) -> None:
         raise NotImplementedError(f"NullRuntime cannot execute callables: {callables}")
+
+
+@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()

rats/apps/_static_container.py

@@ -1,16 +1,17 @@
-from collections.abc import Callable, Iterator
+from collections.abc import Iterator
+from dataclasses import dataclass
 from typing import Any, Generic
 
-from typing_extensions import NamedTuple as ExtNamedTuple
-
-from ._container import Container
+from ._container import Container, Provider
 from ._ids import ServiceId, T_ServiceType
+from ._namespaces import ProviderNamespaces
 
 
-class StaticProvider(ExtNamedTuple, Generic[T_ServiceType]):
+@dataclass(frozen=True)
+class StaticProvider(Generic[T_ServiceType]):
     namespace: str
     service_id: ServiceId[T_ServiceType]
-    provider: Callable[[], T_ServiceType]
+    call: Provider[T_ServiceType]
 
 
 class StaticContainer(Container):
@@ -26,4 +27,40 @@ class StaticContainer(Container):
     ) -> Iterator[T_ServiceType]:
         for provider in self._providers:
             if provider.namespace == namespace and provider.service_id == group_id:
-                yield provider.provider()
+                yield provider.call()
+
+
+def static_service(
+    service_id: ServiceId[T_ServiceType],
+    provider: Provider[T_ServiceType],
+) -> StaticProvider[T_ServiceType]:
+    """
+    Factory function for a `StaticProvider` instance for `ProviderNamespaces.SERVICES`.
+
+    Args:
+        service_id: the identifier for the provided service.
+        provider: a callable that returns an instance of T_ServiceType.
+
+    Returns: StaticProvider instance for the provided service_id.
+    """
+    return StaticProvider(ProviderNamespaces.SERVICES, service_id, provider)
+
+
+def static_group(
+    group_id: ServiceId[T_ServiceType],
+    provider: Provider[T_ServiceType],
+) -> StaticProvider[T_ServiceType]:
+    """
+    Factory function for a `StaticProvider` instance for `ProviderNamespaces.GROUPS`.
+
+    !!! warning
+        Unlike group providers in a container, the provider function argument here should return
+        a single instance of the service group.
+
+    Args:
+        group_id: the identifier for the provided service group.
+        provider: a callable that returns an instance of T_ServiceType.
+
+    Returns: StaticProvider instance for the provided group_id.
+    """
+    return StaticProvider(ProviderNamespaces.GROUPS, group_id, provider)

rats/cli/__init__.py

@@ -3,19 +3,18 @@
 from ._annotations import CommandId, command, get_class_commands, get_class_groups, group
 from ._app import ClickApp
 from ._container import CompositeContainer, Container
-from ._plugin import PluginContainer, PluginServices, attach, create_group
+from ._plugin import PluginServices, attach, create_group
 
 __all__ = [
-    "PluginContainer",
+    "ClickApp",
+    "CommandId",
+    "CompositeContainer",
+    "Container",
+    "PluginServices",
+    "attach",
     "command",
+    "create_group",
     "get_class_commands",
     "get_class_groups",
-    "create_group",
-    "attach",
     "group",
-    "ClickApp",
-    "PluginServices",
-    "CommandId",
-    "Container",
-    "CompositeContainer",
 ]

rats/cli/__main__.py

@@ -41,24 +41,16 @@ class ExampleServices:
     MAIN = apps.ServiceId[apps.Executable]("main")
 
 
-class ExampleContainer(apps.Container):
+class ExampleContainer(apps.Container, apps.PluginMixin):
     """An example container of services."""
 
-    _app: apps.Container
-
-    def __init__(self, app: apps.Container) -> None:
-        """The root container allows us to access services in other plugins."""
-        self._app = app
-
-    @apps.service(ExampleServices.MAIN)
-    def _main(self) -> apps.Executable:
-        return cli.ClickApp(
+    def execute(self) -> None:
+        """Run our ExampleCommands click group."""
+        cli.create_group(
             group=click.Group("example", help="An example application."),
-            commands=ExampleCommands(),
-        )
+            container=ExampleCommands(),
+        )()
 
 
 if __name__ == "__main__":
-    apps.SimpleApplication(runtime_plugin=ExampleContainer).execute(
-        ExampleServices.MAIN,
-    )
+    apps.run_plugin(ExampleContainer)

rats/cli/_plugin.py

@@ -1,4 +1,4 @@
-from typing import cast, final
+from typing import cast
 
 import click
 
@@ -41,11 +41,3 @@ class PluginServices:
     @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

rats/logs/__init__.py

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

rats/logs/_app.py

@@ -0,0 +1,45 @@
+import logging.config
+
+from rats import apps
+
+logger = logging.getLogger(__name__)
+
+
+class ConfigureApplication(apps.AppContainer, apps.PluginMixin):
+    def execute(self) -> None:
+        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"]},
+                },
+            }
+        )
+        logger.debug("done configuring logging")

{rats_apps-0.4.0.dev20241217004929.dist-info → rats_apps-0.5.0.dist-info}/METADATA

@@ -1,8 +1,7 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: rats-apps
-Version: 0.4.0.dev20241217004929
+Version: 0.5.0
 Summary: research analysis tools for building applications
-Home-page: https://github.com/microsoft/rats/
 License: MIT
 Keywords: pipelines,machine learning,research
 Requires-Python: >=3.10,<4.0