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

rats/apps/__init__.py

@@ -1,62 +1,39 @@
 """
-Libraries to help create applications with a strong focus on composability and testability.
+Provides a small set of libraries to help create new applications.
 
 Applications give you the ability to define a development experience to match your project's
 domain.
 """
 
 from ._annotations import (
-    autoid,
-    autoid_service,
+    AnnotatedContainer,
+    config,
+    container,
+    fallback_config,
     fallback_group,
     fallback_service,
     group,
     service,
 )
-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 ._container import Container, DuplicateServiceError, ServiceNotFoundError
+from ._ids import ConfigId, ServiceId
 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",
-    "App",
-    "CompositeContainer",
+    "ConfigId",
     "Container",
     "DuplicateServiceError",
-    "Executable",
-    "PluginContainers",
     "ProviderNamespaces",
-    "ServiceProvider",
     "ServiceId",
     "ServiceNotFoundError",
-    "autoid_service",
     "autoscope",
+    "config",
     "container",
-    "PluginRunner",
+    "fallback_config",
     "fallback_group",
     "fallback_service",
     "group",
-    "autoid",
     "service",
-    "T_ExecutableType",
-    "Runtime",
-    "NullRuntime",
-    "AppServices",
-    "StandardRuntime",
-    "StandardRuntime",
-    "SimpleApplication",
 ]

rats/apps/_annotations.py

@@ -1,74 +1,164 @@
-from collections.abc import Callable
-from typing import Any, ParamSpec
+from collections import defaultdict
+from collections.abc import Callable, Iterator
+from functools import cache
+from typing import Any, cast
 
-from rats import annotations
+from typing_extensions import NamedTuple
 
-from ._ids import ServiceId, T_ServiceType
+from ._container import Container
+from ._ids import ConfigId, ServiceId, T_ConfigType, T_ServiceType
 from ._namespaces import ProviderNamespaces
-from ._scoping import scope_service_name
 
-P = ParamSpec("P")
+DEFAULT_CONTAINER_GROUP = ServiceId[Container]("__default__")
 
 
-def service(
-    service_id: ServiceId[T_ServiceType],
-) -> 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)
+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()
+            ]
+        )
 
 
-def autoid_service(fn: Callable[P, T_ServiceType]) -> Callable[P, T_ServiceType]:
-    _service_id = autoid(fn)
-    return annotations.annotation(ProviderNamespaces.SERVICES, _service_id)(fn)
+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)
+
+
+def service(
+    service_id: ServiceId[T_ServiceType],
+) -> Callable[..., Callable[..., T_ServiceType]]:
+    return fn_annotation_decorator(ProviderNamespaces.SERVICES, service_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)
+) -> Callable[..., Callable[..., T_ServiceType]]:
+    return fn_annotation_decorator(ProviderNamespaces.GROUPS, group_id)
+
+
+def config(
+    config_id: ConfigId[T_ConfigType],
+) -> Callable[..., Callable[..., T_ConfigType]]:
+    return fn_annotation_decorator(ProviderNamespaces.SERVICES, config_id)
 
 
 def fallback_service(
     service_id: ServiceId[T_ServiceType],
-) -> 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,
-    )
+) -> Callable[..., Callable[..., T_ServiceType]]:
+    return fn_annotation_decorator(ProviderNamespaces.FALLBACK_SERVICES, service_id)
 
 
 def fallback_group(
     group_id: ServiceId[T_ServiceType],
-) -> 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,
-    )
+) -> Callable[..., Callable[..., T_ServiceType]]:
+    return fn_annotation_decorator(ProviderNamespaces.FALLBACK_GROUPS, group_id)
 
 
-def autoid(method: Callable[..., T_ServiceType]) -> ServiceId[T_ServiceType]:
-    """
-    Get a service id for a method.
+def fallback_config(
+    config_id: ConfigId[T_ConfigType],
+) -> Callable[..., Callable[..., T_ConfigType]]:
+    return fn_annotation_decorator(ProviderNamespaces.FALLBACK_SERVICES, config_id)
 
-    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 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)))
+
+    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)
 
-    for a in tates.annotations:
-        return a.groups[0].name
+def _get_annotations_builder(fn: Any) -> FunctionAnnotationsBuilder:
+    if not hasattr(fn, "__rats_service_annotations__"):
+        fn.__rats_service_annotations__ = FunctionAnnotationsBuilder()
 
-    module_name = method.__module__
-    class_name, method_name = method.__qualname__.rsplit(".", 1)
-    return scope_service_name(module_name, class_name, method_name)
+    return cast(FunctionAnnotationsBuilder, fn.__rats_service_annotations__)

rats/apps/_composite_container.py

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

rats/apps/_container.py

@@ -1,18 +1,10 @@
-import abc
-import logging
 from abc import abstractmethod
-from collections.abc import Callable, Iterator
-from typing import Generic, ParamSpec, Protocol
+from collections.abc import Iterator
+from typing import Generic, Protocol
 
-from typing_extensions import deprecated
-
-from rats import annotations
-
-from ._ids import ServiceId, T_ServiceType, Tco_ServiceType
+from ._ids import ServiceId, T_ServiceType, Tco_ConfigType, Tco_ServiceType
 from ._namespaces import ProviderNamespaces
 
-logger = logging.getLogger(__name__)
-
 
 class ServiceProvider(Protocol[Tco_ServiceType]):
     @abstractmethod
@@ -20,62 +12,22 @@ class ServiceProvider(Protocol[Tco_ServiceType]):
         """Return the service instance."""
 
 
-class GroupProvider(Protocol[Tco_ServiceType]):
+class ConfigProvider(ServiceProvider[Tco_ConfigType], Protocol[Tco_ConfigType]):
     @abstractmethod
-    def __call__(self) -> Iterator[Tco_ServiceType]:
-        """Return the group instances."""
+    def __call__(self) -> Tco_ConfigType:
+        """Return the config instance."""
 
 
 class Container(Protocol):
-    """
-    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!")
-    """
+    """Main interface for service containers."""
 
     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:
@@ -112,61 +64,13 @@ 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/_ids.py

@@ -1,13 +1,17 @@
+import typing
 from typing import Generic, TypeVar
 
 from typing_extensions import NamedTuple
 
-from ._executables import Executable
-
 T_ServiceType = TypeVar("T_ServiceType")
-T_ExecutableType = TypeVar("T_ExecutableType", bound=Executable)
+T_ConfigType = TypeVar("T_ConfigType", bound=typing.NamedTuple)
 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

rats/apps/_plugin_container.py

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

rats/apps/_scoping.py

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

{rats_apps-0.1.3.dist-info → rats_apps-0.1.3.dev8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: rats-apps
-Version: 0.1.3
+Version: 0.1.3.dev8
 Summary: research analysis tools for building applications
 Home-page: https://github.com/microsoft/rats/
 License: MIT
@@ -11,8 +11,6 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Requires-Dist: click
-Requires-Dist: colorlog
 Requires-Dist: typing_extensions
 Project-URL: Documentation, https://microsoft.github.io/rats/
 Project-URL: Repository, https://github.com/microsoft/rats/

rats_apps-0.1.3.dev8.dist-info/RECORD

@@ -0,0 +1,13 @@
+rats/apps/__init__.py,sha256=JYVss3L2R4uxdOp4Ozfg_cHWgRvCWq79OyVZefFw9wY,858
+rats/apps/_annotations.py,sha256=NGCw1JMZdPMoK_pE61iXgjeI1Xn7P5WXLt7t8zWligg,5125
+rats/apps/_composite_container.py,sha256=wSWVQWPin2xxIlEoSgk_D1rlc3N2gpTxQ2y9UFdqXy0,553
+rats/apps/_container.py,sha256=5uiCyxN6HS2z97XcTOFP-t72cNoB1U1sJMkMcfSfDps,3129
+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/_scoping.py,sha256=lRV1DDq-U4mr4WOQhvFjTiCQe2dKY95LNn6b0RXRjFA,1305
+rats/apps/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rats_apps-0.1.3.dev8.dist-info/METADATA,sha256=mZp5dVow8ScTYqG5JaKsEPzABPF-b3r55srRYgJJ9y8,716
+rats_apps-0.1.3.dev8.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+rats_apps-0.1.3.dev8.dist-info/entry_points.txt,sha256=Vu1IgAPQvL4xMJzW_OG2JSPFac7HalCHyXiRr0-OfCI,86
+rats_apps-0.1.3.dev8.dist-info/RECORD,,

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

@@ -0,0 +1,3 @@
+[rats-apps.test-plugins]
+example-storage=rats_test.apps.example:ExampleStoragePlugin
+

rats/annotations/__init__.py

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