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

rats/annotations/__init__.py

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

rats/annotations/_functions.py

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

@@ -1,39 +1,62 @@
 """
-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,
-    config,
-    container,
-    fallback_config,
+    autoid,
+    autoid_service,
     fallback_group,
     fallback_service,
     group,
     service,
 )
-from ._container import Container, DuplicateServiceError, ServiceNotFoundError
-from ._ids import ConfigId, ServiceId
+from ._composite_container import CompositeContainer
+from ._container import (
+    AnnotatedContainer,  # type: ignore[reportDeprecated]
+    Container,
+    DuplicateServiceError,
+    ServiceNotFoundError,
+    ServiceProvider,
+    container,
+)
+from ._executables import App, Executable
+from ._ids import ServiceId, T_ExecutableType
 from ._namespaces import ProviderNamespaces
+from ._plugin_container import PluginContainers
+from ._plugins import PluginRunner
+from ._runtimes import NullRuntime, Runtime
 from ._scoping import autoscope
+from ._simple_apps import AppServices, SimpleApplication, StandardRuntime
 
 __all__ = [
     "AnnotatedContainer",
-    "ConfigId",
+    "App",
+    "CompositeContainer",
     "Container",
     "DuplicateServiceError",
+    "Executable",
+    "PluginContainers",
     "ProviderNamespaces",
+    "ServiceProvider",
     "ServiceId",
     "ServiceNotFoundError",
+    "autoid_service",
     "autoscope",
-    "config",
     "container",
-    "fallback_config",
+    "PluginRunner",
     "fallback_group",
     "fallback_service",
     "group",
+    "autoid",
     "service",
+    "T_ExecutableType",
+    "Runtime",
+    "NullRuntime",
+    "AppServices",
+    "StandardRuntime",
+    "StandardRuntime",
+    "SimpleApplication",
 ]

rats/apps/_annotations.py

@@ -1,164 +1,74 @@
-from collections import defaultdict
-from collections.abc import Callable, Iterator
-from functools import cache
-from typing import Any, 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 ._ids import ServiceId, 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 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):
-    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[..., T_ServiceType]]:
-    return fn_annotation_decorator(ProviderNamespaces.SERVICES, service_id)
+) -> Callable[[Callable[P, T_ServiceType]], Callable[P, T_ServiceType]]:
+    """A service is anything you would create instances of?"""
+    return annotations.annotation(ProviderNamespaces.SERVICES, service_id)
 
 
-def group(
-    group_id: ServiceId[T_ServiceType],
-) -> Callable[..., Callable[..., T_ServiceType]]:
-    return fn_annotation_decorator(ProviderNamespaces.GROUPS, group_id)
+def autoid_service(fn: Callable[P, T_ServiceType]) -> Callable[P, T_ServiceType]:
+    _service_id = autoid(fn)
+    return annotations.annotation(ProviderNamespaces.SERVICES, _service_id)(fn)
 
 
-def config(
-    config_id: ConfigId[T_ConfigType],
-) -> Callable[..., Callable[..., T_ConfigType]]:
-    return fn_annotation_decorator(ProviderNamespaces.SERVICES, config_id)
+def group(
+    group_id: ServiceId[T_ServiceType],
+) -> Callable[[Callable[P, T_ServiceType]], Callable[P, T_ServiceType]]:
+    """A group is a collection of services."""
+    return annotations.annotation(ProviderNamespaces.GROUPS, group_id)
 
 
 def fallback_service(
     service_id: ServiceId[T_ServiceType],
-) -> Callable[..., Callable[..., T_ServiceType]]:
-    return fn_annotation_decorator(ProviderNamespaces.FALLBACK_SERVICES, service_id)
+) -> Callable[[Callable[P, T_ServiceType]], Callable[P, T_ServiceType]]:
+    """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[..., T_ServiceType]]:
-    return fn_annotation_decorator(ProviderNamespaces.FALLBACK_GROUPS, group_id)
-
-
-def fallback_config(
-    config_id: ConfigId[T_ConfigType],
-) -> Callable[..., Callable[..., T_ConfigType]]:
-    return fn_annotation_decorator(ProviderNamespaces.FALLBACK_SERVICES, config_id)
+) -> Callable[[Callable[P, T_ServiceType]], Callable[P, T_ServiceType]]:
+    """A fallback group gets used if no group is defined."""
+    return annotations.annotation(
+        ProviderNamespaces.FALLBACK_GROUPS,
+        group_id,
+    )
 
 
-def container(
-    group_id: ServiceId[T_ServiceType] = DEFAULT_CONTAINER_GROUP,
-) -> Callable[..., Callable[..., T_ServiceType]]:
-    return fn_annotation_decorator(ProviderNamespaces.CONTAINERS, group_id)
-
-
-def fn_annotation_decorator(
-    namespace: str,
-    service_id: ServiceId[T_ServiceType],
-) -> Callable[..., Callable[..., T_ServiceType]]:
-    def wrapper(
-        fn: Callable[..., T_ServiceType],
-    ) -> Callable[..., T_ServiceType]:
-        _add_annotation(namespace, fn, service_id)
-        return cache(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)))
+def autoid(method: Callable[..., T_ServiceType]) -> ServiceId[T_ServiceType]:
+    """
+    Get a service id for a method.
 
-    return FunctionAnnotations(tuple(function_annotations))
+    The service id is constructed from the module, class and method name.  It should be identical
+    regardless of whether the method is bound or not, and regardless of the instance it is bound
+    to.
 
+    The service type is the return type of the method.
+    """
+    service_name = _get_method_service_id_name(method)
+    return ServiceId[T_ServiceType](service_name)
 
-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/_composite_container.py

@@ -1,11 +1,13 @@
 from collections.abc import Iterator
+from typing import final
 
 from ._container import Container
 from ._ids import ServiceId, T_ServiceType
 
 
+@final
 class CompositeContainer(Container):
-    _contailers: tuple[Container, ...]
+    _containers: tuple[Container, ...]
 
     def __init__(self, *containers: Container) -> None:
         self._containers = containers

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 ._ids import ServiceId, T_ServiceType, Tco_ConfigType, Tco_ServiceType
+from typing_extensions import deprecated
+
+from rats import annotations
+
+from ._ids import ServiceId, T_ServiceType, Tco_ServiceType
 from ._namespaces import ProviderNamespaces
 
+logger = logging.getLogger(__name__)
+
 
 class ServiceProvider(Protocol[Tco_ServiceType]):
     @abstractmethod
@@ -12,22 +20,62 @@ class ServiceProvider(Protocol[Tco_ServiceType]):
         """Return the service instance."""
 
 
-class ConfigProvider(ServiceProvider[Tco_ConfigType], Protocol[Tco_ConfigType]):
+class GroupProvider(Protocol[Tco_ServiceType]):
     @abstractmethod
-    def __call__(self) -> Tco_ConfigType:
-        """Return the config instance."""
+    def __call__(self) -> Iterator[Tco_ServiceType]:
+        """Return the group instances."""
 
 
 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

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

@@ -1,17 +1,13 @@
-import typing
 from typing import Generic, TypeVar
 
 from typing_extensions import NamedTuple
 
+from ._executables import Executable
+
 T_ServiceType = TypeVar("T_ServiceType")
-T_ConfigType = TypeVar("T_ConfigType", bound=typing.NamedTuple)
+T_ExecutableType = TypeVar("T_ExecutableType", bound=Executable)
 Tco_ServiceType = TypeVar("Tco_ServiceType", covariant=True)
-Tco_ConfigType = TypeVar("Tco_ConfigType", bound=NamedTuple, covariant=True)
 
 
 class ServiceId(NamedTuple, Generic[T_ServiceType]):
     name: str
-
-
-class ConfigId(ServiceId[T_ConfigType]):
-    pass