rats-apps 0.6.0.dev20250218170831__py3-none-any.whl → 0.6.0.dev20250310152143__py3-none-any.whl

rats/app_context/__init__.py

@@ -0,0 +1,19 @@
+"""Application context package to help share [apps.Container][] state across machines."""
+
+from ._collection import (
+    Collection,
+    dumps,
+    loads,
+)
+from ._container import GroupContainer, ServiceContainer
+from ._context import Context, T_ContextType
+
+__all__ = [
+    "Collection",
+    "Context",
+    "GroupContainer",
+    "ServiceContainer",
+    "T_ContextType",
+    "dumps",
+    "loads",
+]

rats/app_context/_collection.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass
+from typing import Any, Generic, final
+
+import dataclass_wizard
+
+from rats import apps
+
+from ._context import Context, ContextValue, T_ContextType
+
+logger = logging.getLogger(__name__)
+
+
+@final
+@dataclass(frozen=True)
+class Collection(Generic[T_ContextType]):
+    """
+    Collection of context objects linking service ids to serializable data structures.
+
+    It is up to the user of this class to provide the correct mapping between services and the
+    constructor for those services.
+    """
+
+    items: tuple[Context[T_ContextType], ...]
+
+    @staticmethod
+    def merge(*collections: Collection[T_ContextType]) -> Collection[T_ContextType]:
+        return Collection[T_ContextType].make(
+            *[ctx for collection in collections for ctx in collection.items]
+        )
+
+    @staticmethod
+    def empty() -> Collection[T_ContextType]:
+        """Useful when wanting to define a simple default value for a context collection."""
+        return Collection(items=())
+
+    @staticmethod
+    def make(*items: Context[T_ContextType]) -> Collection[T_ContextType]:
+        # just a handy shortcut to remove a nested tuple from the end-user code.
+        return Collection(items=items)
+
+    def service_ids(self) -> set[apps.ServiceId[T_ContextType]]:
+        return {item.service_id for item in self.items}
+
+    def decoded_values(
+        self,
+        cls: type[T_ContextType],
+        service_id: apps.ServiceId[T_ContextType],
+    ) -> tuple[T_ContextType, ...]:
+        return tuple(dataclass_wizard.fromlist(cls, list(self.values(service_id))))
+
+    def values(self, service_id: apps.ServiceId[T_ContextType]) -> tuple[ContextValue, ...]:
+        results: list[ContextValue] = []
+        for item in self.with_id(service_id).items:
+            for value in item.values:
+                results.append(value)
+
+        return tuple(results)
+
+    def add(self, *items: Context[T_ContextType]) -> Collection[T_ContextType]:
+        """Creates a new Collection with the provided items added to the current ones."""
+        return Collection[T_ContextType].make(
+            *self.items,
+            *items,
+        )
+
+    def with_id(self, *service_ids: apps.ServiceId[T_ContextType]) -> Collection[T_ContextType]:
+        """Filter out context items not matching the provided service ids and return a new Collection."""
+        return Collection[T_ContextType](
+            items=tuple(item for item in self.items if item.service_id in service_ids),
+        )
+
+
+def loads(context: str) -> Collection[Any]:
+    """
+    Transforms a json string into a [rats.app_context.Collection][] instance.
+
+    This function does not attempt to validate the mapping between services and their values.
+
+    Args:
+        context: json string containing an `items` key of `service_id`, `values` mappings.
+    """
+    data = json.loads(context)
+    return Collection[Any](
+        items=tuple(
+            [
+                Context(
+                    service_id=apps.ServiceId(*x["serviceId"]),
+                    values=tuple(x["values"]),
+                )
+                for x in data["items"]
+            ]
+        ),
+    )
+
+
+def dumps(collection: Collection[Any]) -> str:
+    """
+    Serializes a [rats.app_context.Collection][] instance to a json string.
+
+    Args:
+        collection: collection of serializable services wanting to be shared between machines.
+
+    Returns: a string that can easily be shared between machines.
+
+    """
+    return json.dumps(dataclass_wizard.asdict(collection))  # type: ignore

rats/app_context/_container.py

@@ -0,0 +1,92 @@
+import logging
+from collections.abc import Iterator
+from functools import partial
+from typing import Generic, final
+
+from rats import apps
+
+from ._collection import Collection
+from ._context import T_ContextType
+
+logger = logging.getLogger(__name__)
+
+
+@final
+class ServiceContainer(apps.Container, Generic[T_ContextType]):
+    """A [rats.apps.Container][] that provides services from a [rats.app_context.Collection][]."""
+
+    _cls: type[T_ContextType]
+    _namespace: str
+    _collection: Collection[T_ContextType]
+
+    def __init__(
+        self,
+        cls: type[T_ContextType],
+        namespace: str,
+        collection: Collection[T_ContextType],
+    ) -> None:
+        self._cls = cls
+        self._namespace = namespace
+        self._collection = collection
+
+    @apps.container()
+    def _contexts(self) -> apps.Container:
+        containers: list[apps.Container] = []
+
+        def _provider(_service_id: apps.ServiceId[T_ContextType]) -> T_ContextType:
+            contexts = self._collection.decoded_values(self._cls, _service_id)
+            if len(contexts) > 1:
+                raise apps.DuplicateServiceError(_service_id)
+            if len(contexts) == 0:
+                raise apps.ServiceNotFoundError(_service_id)
+
+            return contexts[0]
+
+        for service_id in self._collection.service_ids():
+            containers.append(
+                apps.StaticContainer(
+                    apps.StaticProvider[T_ContextType](
+                        namespace=apps.ProviderNamespaces.SERVICES,
+                        service_id=service_id,
+                        call=partial(_provider, service_id),
+                    ),
+                )
+            )
+
+        return apps.CompositeContainer(*containers)
+
+
+@final
+class GroupContainer(apps.Container, Generic[T_ContextType]):
+    """A [rats.apps.Container][] that provides services from a [rats.app_context.Collection][]."""
+
+    _cls: type[T_ContextType]
+    _collection: Collection[T_ContextType]
+
+    def __init__(
+        self,
+        cls: type[T_ContextType],
+        collection: Collection[T_ContextType],
+    ) -> None:
+        self._cls = cls
+        self._collection = collection
+
+    @apps.container()
+    def _contexts(self) -> apps.Container:
+        containers: list[apps.Container] = []
+
+        def _group_provider(_service_id: apps.ServiceId[T_ContextType]) -> Iterator[T_ContextType]:
+            yield from self._collection.decoded_values(self._cls, _service_id)
+
+        for service_id in self._collection.service_ids():
+            containers.append(
+                apps.StaticContainer(
+                    apps.StaticProvider[T_ContextType](
+                        namespace=apps.ProviderNamespaces.GROUPS,
+                        service_id=service_id,
+                        provider=partial(_group_provider, service_id),  # type: ignore
+                    ),
+                )
+            )
+
+        return apps.CompositeContainer(*containers)

rats/app_context/_context.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Any, Generic, TypeVar, final
+
+import dataclass_wizard
+
+from rats import apps
+
+logger = logging.getLogger(__name__)
+T_ContextType = TypeVar("T_ContextType")  # TODO: figure out how to bind this to dataclasses :(
+ContextValue = dict[str, Any]
+
+
+@final
+@dataclass(frozen=True)
+class Context(dataclass_wizard.JSONSerializable, Generic[T_ContextType]):
+    """
+    An easily serializable class to hold one or more values tied to a service id.
+
+    We can use these instances to share simple value types across a cluster of machines, and
+    integrate them with [rats.apps.Container][] to make the business logic unaware of any
+    complexity in here.
+    """
+
+    service_id: apps.ServiceId[T_ContextType]
+    values: tuple[ContextValue, ...]
+
+    @staticmethod
+    def make(
+        service_id: apps.ServiceId[T_ContextType],
+        *contexts: T_ContextType,
+    ) -> Context[T_ContextType]:
+        """
+        Convert a dataclass into a context object tied to the provided service id.
+
+        ```python
+        from dataclass import dataclass
+
+
+        class MySimpleData:
+            blob_path: Tuple[str, str, str]
+            offset: int
+
+
+        ctx = app_context.Context[MySimpleData].make(
+            MySimpleData(
+                blob_path=("accountname", "containername", "/some/blob/path"),
+            )
+        )
+        ```
+        """
+        return Context(
+            service_id,
+            tuple([dataclass_wizard.asdict(ctx) for ctx in contexts]),  # type: ignore
+        )

rats/apps/__init__.py

@@ -23,7 +23,7 @@ from ._app_containers import (
     ContainerPlugin,
     PluginMixin,
 )
-from ._composite_container import CompositeContainer
+from ._composite_container import EMPTY_CONTAINER, CompositeContainer
 from ._container import (
     Container,
     DuplicateServiceError,
@@ -42,6 +42,7 @@ from ._scoping import autoscope
 from ._static_container import StaticContainer, StaticProvider, static_group, static_service
 
 __all__ = [
+    "EMPTY_CONTAINER",
     "App",
     "AppBundle",
     "AppContainer",

rats/apps/_composite_container.py

@@ -19,3 +19,7 @@ class CompositeContainer(Container):
     ) -> Iterator[T_ServiceType]:
         for container in self._containers:
             yield from container.get_namespaced_group(namespace, group_id)
+
+
+EMPTY_CONTAINER = CompositeContainer()
+"""Convenience [rats.apps.Container][] instance with no services."""

rats/apps/_runtimes.py

@@ -10,6 +10,16 @@ logger = logging.getLogger(__name__)
 
 
 class Runtime(Protocol):
+    """
+    Classes that run services that implement the [rats.apps.Executable][] interface.
+
+    Many of the lower level interfaces use [rats.apps.Executable][] to provide the user with a
+    class that has an [rats.apps.Executable.execute][] method; most notably, [rats.apps.App][] and
+    [rats.apps.AppContainer][]. These classes typically represent the main entry points to an
+    application, and runtime implementations provide a way to execute these applications in
+    threads, processes, and remote environments.
+    """
+
     @abstractmethod
     def execute(self, *exe_ids: ServiceId[T_ExecutableType]) -> None:
         """Execute a list of executables sequentially."""

{rats_apps-0.6.0.dev20250218170831.dist-info → rats_apps-0.6.0.dev20250310152143.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: rats-apps
-Version: 0.6.0.dev20250218170831
+Version: 0.6.0.dev20250310152143
 Summary: research analysis tools for building applications
 License: MIT
 Keywords: pipelines,machine learning,research
@@ -13,6 +13,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Dist: click
 Requires-Dist: colorlog
+Requires-Dist: dataclass-wizard
 Requires-Dist: typing_extensions
 Project-URL: Documentation, https://microsoft.github.io/rats/
 Project-URL: Repository, https://github.com/microsoft/rats/

{rats_apps-0.6.0.dev20250218170831.dist-info → rats_apps-0.6.0.dev20250310152143.dist-info}/RECORD

@@ -2,17 +2,22 @@ rats/annotations/__init__.py,sha256=YmydaopUSlpoX6MvQ-3p18sgEC_DB_y683wVICD-jnU,
 rats/annotations/__main__.py,sha256=vlzQOM9y82P0OL5tYcmSM_4jTg0s8jayAcvEoi9cBvI,1065
 rats/annotations/_functions.py,sha256=UkHh3zdBivluE7dBeGQ17zoIfGdyIokMAkFmpWaIlDc,4284
 rats/annotations/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-rats/apps/__init__.py,sha256=uTPk2ipOy7MgLoV0s9l22U1Qyo8aL2yKVwDukOY9WGw,1934
+rats/app_context/__init__.py,sha256=UoTUhj1VvefMsD_k0rruTuQxauXUEk9N8qcqgyyPXS0,401
+rats/app_context/_collection.py,sha256=hOfKF5OExsuuDhdj8urNWoYRLchAMWq2gwyc72J_9i0,3607
+rats/app_context/_container.py,sha256=YkNG25jngfN_064jv8fZmKW1FSuL6RRJAp9F_hm2NZg,2954
+rats/app_context/_context.py,sha256=VUm-cg2WKtFU2VvIJI8OmTdRRoDLXeWPBYu_ynpUjlY,1599
+rats/app_context/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rats/apps/__init__.py,sha256=4dzcE7MZTtZD5NA-pnzQbElABUxUsepf3GknBbXjfwc,1974
 rats/apps/_annotations.py,sha256=6M_M7K8haNVda0Tx02EpFf3s9EjnWYacNMjTIkNEdRU,4617
 rats/apps/_app_containers.py,sha256=ygZL0NM-fSRSemFddBsVMwcmSQw07sbb7bIqWTr-_yU,6147
-rats/apps/_composite_container.py,sha256=s_of6NyyrjFVYWGVehyEHe9WJIPRCnbB-tyWyNF8zyc,585
+rats/apps/_composite_container.py,sha256=FdpmH_xIly6LxNZrA_nZCznukptjVLXttXTMtf_tnv8,695
 rats/apps/_container.py,sha256=sYISCG-qVzl-bsBwX_CAWEP9gtXCnG-Jls3l8IKb4DQ,7208
 rats/apps/_executables.py,sha256=hXExNmAnuPU1KJXihNw1jEDAQpMlQ9E9_aPV8tpGbOY,1347
 rats/apps/_ids.py,sha256=T8Onrj79t8NPfBMQBk0xI6fIWDKF0m2JfFNrdtXAbWg,353
 rats/apps/_mains.py,sha256=2Q97mNk1cBzYROc_pJcm57EEeHmwRbXOWpfYXH37qcA,995
 rats/apps/_namespaces.py,sha256=THUV_Xj5PtweC23Ob-zsSpk8exC4fT-qRwjpQ6IDm0U,188
 rats/apps/_plugin_container.py,sha256=cad9Xm1YsJrPkKfMb3xvegIxaL3HVL5JYreHKqooy1A,1543
-rats/apps/_runtimes.py,sha256=l5Z26jZVHk4CvT8VyKUK5tpcCAKt2N1DWipd4gX_Bls,2060
+rats/apps/_runtimes.py,sha256=yzWPVbY0I-orRRN23on-iEX8Bo0BqoRiYeR3dwcBlGg,2592
 rats/apps/_scoping.py,sha256=6C2-ID22cCPR9Cbexf3CvCF3o9F_7ieURbwqkf6DI68,1360
 rats/apps/_static_container.py,sha256=KH4AwRMX5QPIwYrD9W_HayIpQIrbVn7clEMx44LFAGc,2113
 rats/apps/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -35,6 +40,6 @@ rats_e2e/apps/inputs/_app.py,sha256=FiaLgOZc-d1ryKSwKnL5XBNGcOP1bHbxxeMJqoU_RJg,
 rats_e2e/apps/minimal/__init__.py,sha256=bUR6Oexx6Jsouxor0cL9emXoVha4cm3WqyhU1pgchsI,521
 rats_e2e/apps/minimal/__main__.py,sha256=Mf-a2iQKTTgh9hMd6AeuzmU9araMIyf1AtdWkh_L07E,117
 rats_e2e/apps/minimal/_app.py,sha256=CQ09LVTNRarz7Pb1wiSuNHrZ_2KGcgH8nUqy4BjxMUY,849
-rats_apps-0.6.0.dev20250218170831.dist-info/METADATA,sha256=RoQiYMoEdygZ7Q3hVavblFvkcjEvz3YEG_5wfanxYpU,779
-rats_apps-0.6.0.dev20250218170831.dist-info/WHEEL,sha256=XbeZDeTWKc1w7CSIyre5aMDU_-PohRwTQceYnisIYYY,88
-rats_apps-0.6.0.dev20250218170831.dist-info/RECORD,,
+rats_apps-0.6.0.dev20250310152143.dist-info/METADATA,sha256=qyliU36pf-1mlVwt4xDDdtLaDIKpEchKRynXbqBZVvo,811
+rats_apps-0.6.0.dev20250310152143.dist-info/WHEEL,sha256=XbeZDeTWKc1w7CSIyre5aMDU_-PohRwTQceYnisIYYY,88
+rats_apps-0.6.0.dev20250310152143.dist-info/RECORD,,