rats-apps 0.1.2__py3-none-any.whl

rats/apps/__init__.py

@@ -0,0 +1,39 @@
+"""
+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 (
+    AnnotatedContainer,
+    config,
+    container,
+    fallback_config,
+    fallback_group,
+    fallback_service,
+    group,
+    service,
+)
+from ._container import Container, DuplicateServiceError, ServiceNotFoundError
+from ._ids import ConfigId, ServiceId
+from ._namespaces import ProviderNamespaces
+from ._scoping import autoscope
+
+__all__ = [
+    "AnnotatedContainer",
+    "ConfigId",
+    "Container",
+    "DuplicateServiceError",
+    "ProviderNamespaces",
+    "ServiceId",
+    "ServiceNotFoundError",
+    "autoscope",
+    "config",
+    "container",
+    "fallback_config",
+    "fallback_group",
+    "fallback_service",
+    "group",
+    "service",
+]

rats/apps/_annotations.py

@@ -0,0 +1,164 @@
+from collections import defaultdict
+from collections.abc import Callable, Iterator
+from functools import cache
+from typing import Any, cast
+
+from typing_extensions import NamedTuple
+
+from ._container import Container
+from ._ids import ConfigId, ServiceId, T_ConfigType, T_ServiceType
+from ._namespaces import ProviderNamespaces
+
+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)
+
+
+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[..., 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[..., T_ServiceType]]:
+    return fn_annotation_decorator(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)
+
+
+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_annotations_builder(fn: Any) -> FunctionAnnotationsBuilder:
+    if not hasattr(fn, "__rats_service_annotations__"):
+        fn.__rats_service_annotations__ = FunctionAnnotationsBuilder()
+
+    return cast(FunctionAnnotationsBuilder, fn.__rats_service_annotations__)

rats/apps/_composite_container.py

@@ -0,0 +1,19 @@
+from collections.abc import Iterator
+
+from ._container import Container
+from ._ids import ServiceId, T_ServiceType
+
+
+class CompositeContainer(Container):
+    _contailers: tuple[Container, ...]
+
+    def __init__(self, *containers: Container) -> None:
+        self._containers = containers
+
+    def get_namespaced_group(
+        self,
+        namespace: str,
+        group_id: ServiceId[T_ServiceType],
+    ) -> Iterator[T_ServiceType]:
+        for container in self._containers:
+            yield from container.get_namespaced_group(namespace, group_id)

rats/apps/_container.py

@@ -0,0 +1,89 @@
+from abc import abstractmethod
+from collections.abc import Iterator
+from typing import Generic, Protocol
+
+from ._ids import ServiceId, T_ServiceType, Tco_ConfigType, Tco_ServiceType
+from ._namespaces import ProviderNamespaces
+
+
+class ServiceProvider(Protocol[Tco_ServiceType]):
+    @abstractmethod
+    def __call__(self) -> Tco_ServiceType:
+        """Return the service instance."""
+
+
+class ConfigProvider(ServiceProvider[Tco_ConfigType], Protocol[Tco_ConfigType]):
+    @abstractmethod
+    def __call__(self) -> Tco_ConfigType:
+        """Return the config instance."""
+
+
+class Container(Protocol):
+    """Main interface for service containers."""
+
+    def has(self, service_id: ServiceId[T_ServiceType]) -> bool:
+        try:
+            return self.get(service_id) is not None
+        except ServiceNotFoundError:
+            return False
+
+    def has_group(self, group_id: ServiceId[T_ServiceType]) -> bool:
+        try:
+            return next(self.get_group(group_id)) is not None
+        except StopIteration:
+            return False
+
+    def has_namespace(self, namespace: str, group_id: ServiceId[T_ServiceType]) -> bool:
+        try:
+            return next(self.get_namespaced_group(namespace, group_id)) is not None
+        except StopIteration:
+            return False
+
+    def get(self, service_id: ServiceId[T_ServiceType]) -> T_ServiceType:
+        """Retrieve a service instance by its id."""
+        services = list(self.get_namespaced_group(ProviderNamespaces.SERVICES, service_id))
+        if len(services) == 0:
+            services.extend(
+                list(self.get_namespaced_group(ProviderNamespaces.FALLBACK_SERVICES, service_id)),
+            )
+
+        if len(services) > 1:
+            raise DuplicateServiceError(service_id)
+        elif len(services) == 0:
+            raise ServiceNotFoundError(service_id)
+        else:
+            return services[0]
+
+    def get_group(
+        self,
+        group_id: ServiceId[T_ServiceType],
+    ) -> Iterator[T_ServiceType]:
+        """Retrieve a service group by its id."""
+        if not self.has_namespace(ProviderNamespaces.GROUPS, group_id):
+            yield from self.get_namespaced_group(ProviderNamespaces.FALLBACK_GROUPS, group_id)
+
+        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."""
+
+
+class ServiceNotFoundError(RuntimeError, Generic[T_ServiceType]):
+    service_id: ServiceId[T_ServiceType]
+
+    def __init__(self, service_id: ServiceId[T_ServiceType]) -> None:
+        super().__init__(f"Service id not found: {service_id}")
+        self.service_id = service_id
+
+
+class DuplicateServiceError(RuntimeError, Generic[T_ServiceType]):
+    service_id: ServiceId[T_ServiceType]
+
+    def __init__(self, service_id: ServiceId[T_ServiceType]) -> None:
+        super().__init__(f"Service id provided multiple times: {service_id}")
+        self.service_id = service_id

rats/apps/_ids.py

@@ -0,0 +1,17 @@
+import typing
+from typing import Generic, TypeVar
+
+from typing_extensions import NamedTuple
+
+T_ServiceType = TypeVar("T_ServiceType")
+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/_namespaces.py

@@ -0,0 +1,6 @@
+class ProviderNamespaces:
+    SERVICES = "services"
+    GROUPS = "groups"
+    CONTAINERS = "containers"
+    FALLBACK_SERVICES = "fallback-services"
+    FALLBACK_GROUPS = "fallback-groups"

rats/apps/_plugin_container.py

@@ -0,0 +1,28 @@
+from collections.abc import Iterable, Iterator
+from functools import cache
+from importlib.metadata import entry_points
+
+from ._container import Container
+from ._ids import ServiceId, T_ServiceType
+
+
+class PluginContainers(Container):
+    _app: Container
+    _group: str
+
+    def __init__(self, app: Container, group: str) -> None:
+        self._app = app
+        self._group = group
+
+    def get_namespaced_group(
+        self,
+        namespace: str,
+        group_id: ServiceId[T_ServiceType],
+    ) -> Iterator[T_ServiceType]:
+        for container in self._load_containers():
+            yield from container.get_namespaced_group(namespace, group_id)
+
+    @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)

rats/apps/_scoping.py

@@ -0,0 +1,43 @@
+from collections.abc import Callable
+from types import FunctionType
+from typing import Any, ParamSpec, TypeVar, cast
+
+from ._ids import ServiceId
+
+T = TypeVar("T")
+P = ParamSpec("P")
+
+
+def autoscope(cls: type[T]) -> type[T]:
+    """
+    Decorator that replaces all ServiceId instances in the class with scoped ServiceId instances.
+
+    The scoped ServiceId instances have a prefix to eliminate the chance of conflicts across
+    packages.
+    """
+
+    def wrap(func: Callable[..., Any]) -> Callable[..., Any]:
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> ServiceId[Any]:
+            result = func(*args, **kwargs)
+            if not isinstance(result, ServiceId):
+                return result
+
+            return ServiceId[Any](f"{cls.__module__}:{cls.__name__}[{result.name}]")
+
+        return cast(FunctionType, wrapper)
+
+    props = [prop for prop in dir(cls) if not prop.startswith("_")]
+
+    for prop_name in props:
+        non_ns = getattr(cls, prop_name)
+
+        if isinstance(non_ns, FunctionType):
+            setattr(cls, prop_name, wrap(non_ns))
+        else:
+            if not isinstance(non_ns, ServiceId):
+                continue
+
+            prop = ServiceId[Any](f"{cls.__module__}:{cls.__name__}[{non_ns.name}]")
+            setattr(cls, prop_name, prop)
+
+    return cls

rats_apps-0.1.2.dist-info/METADATA

@@ -0,0 +1,21 @@
+Metadata-Version: 2.1
+Name: rats-apps
+Version: 0.1.2
+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
+Classifier: License :: OSI Approved :: MIT License
+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: typing_extensions
+Project-URL: Documentation, https://microsoft.github.io/rats/
+Project-URL: Repository, https://github.com/microsoft/rats/
+Description-Content-Type: text/markdown
+
+# rats-apps
+...
+

rats_apps-0.1.2.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.2.dist-info/METADATA,sha256=CwHSo9ZWpDzbbE60oLdJO4IG4aV9ub07NzfWoilk0xE,711
+rats_apps-0.1.2.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+rats_apps-0.1.2.dist-info/entry_points.txt,sha256=Vu1IgAPQvL4xMJzW_OG2JSPFac7HalCHyXiRr0-OfCI,86
+rats_apps-0.1.2.dist-info/RECORD,,

rats_apps-0.1.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 1.9.0
+Root-Is-Purelib: true
+Tag: py3-none-any

rats_apps-0.1.2.dist-info/entry_points.txt

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