rats-apps 0.11.1.dev20250527164753__py3-none-any.whl → 0.11.1.dev20250528185313__py3-none-any.whl

rats/apps/_container.py

@@ -108,7 +108,6 @@ class Container(Protocol):
         """Retrieve a service group by its id."""
         if not self.has_namespace(ProviderNamespaces.GROUPS, group_id):
             # groups are expected to return iterable services
-            # TODO: we need to clean up the meaning of groups and services somehow
             for i in self.get_namespaced_group(ProviderNamespaces.FALLBACK_GROUPS, group_id):
                 yield from cast(Iterator[T_ServiceType], i)
 
@@ -151,7 +150,14 @@ def _get_cached_services_for_group(
 
     for provider in info_cache[(namespace, group_id)]:
         if provider not in provider_cache:
-            provider_cache[provider] = getattr(c, provider.attr)()
+            if namespace in [
+                ProviderNamespaces.CONTAINERS,
+                ProviderNamespaces.SERVICES,
+                ProviderNamespaces.FALLBACK_SERVICES,
+            ]:
+                provider_cache[provider] = getattr(c, provider.attr)()
+            else:
+                provider_cache[provider] = list(getattr(c, provider.attr)())
 
         yield provider_cache[provider]
 

rats_apps-0.11.1.dev20250528185313.dist-info/METADATA

@@ -0,0 +1,238 @@
+Metadata-Version: 2.3
+Name: rats-apps
+Version: 0.11.1.dev20250528185313
+Summary: research analysis tools for building applications
+License: MIT
+Keywords: pipelines,machine learning,research
+Author: Elon Portugaly
+Author-email: elonp@microsoft.com
+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
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: click
+Requires-Dist: colorlog
+Requires-Dist: dataclass-wizard
+Requires-Dist: pyyaml
+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
+
+---
+title: introduction
+---
+
+The `rats-apps` package helps create applications; a small set of modules that eliminate the most
+common boilerplate code when creating applications of any kind. We do this mainly by providing a
+set of libraries to define service containers, and using the service containers to hide the
+complexity of creating services–like authentication, storage, or database clients–from other parts
+of the system, allowing developers to focus on the business logic of the application. Often referred
+to as [Dependency Injection](https://en.wikipedia.org/wiki/Dependency_injection), we use our
+service containers to separate the concerns of constructing objects and using them.
+
+## Installation
+
+Use `pip` or your favorite packaging tool to install the package from PyPI.
+
+```bash
+pip install rats-apps
+```
+
+## What is an application?
+
+Let's start with a standard python script, and slowly migrate it to be a rats application in order
+to explain a few main details. Creating a `__main__.py` file in a package makes it executable.
+After the common python boilerplate code is added, this is typically what we find in the wild:
+
+=== ":material-language-python: ~/code/src/foo/\_\_main\_\_.py"
+    ```python
+    def main() -> None:
+        print("hello, world")
+
+
+    if __name__ == "__main__":
+        main()
+    ```
+
+=== ":material-console: ~/code"
+    ```bash
+    python -m foo
+    ```
+
+Using this pattern, we can define our application with a small modification, turning our `main()`
+function into a runnable rats application, and then running it:
+
+=== ":material-language-python: ~/code/src/foo/\_\_main\_\_.py"
+    ```python
+    from rats import apps
+
+
+    def main() -> None:
+        print("hello, world")
+
+
+    if __name__ == "__main__":
+        apps.run(apps.App(main))
+    ```
+
+!!! info
+    The [rats.apps.App][] class is used to quickly turn a script entry point–`Callable[[], None]`
+    –into an object with an `execute()` method, defined by our [rats.apps.Executable][]
+    interface.
+
+## Application Containers & Plugins
+
+We can start to leverage [rats.apps][] to make our application easy to extend. Let's replace our use
+of the [rats.apps.App][] wrapper and move our `main()` function into a class. Using the
+[rats.apps.AppContainer][] and [rats.apps.PluginMixin][] classes, we finish adapting our example
+to be a rats application.
+
+=== ":material-language-python: ~/code/src/foo/\_\_main\_\_.py"
+
+    ```python
+        from rats import apps
+
+
+        class Application(apps.AppContainer, apps.PluginMixin):
+            def execute() -> None:
+                print("hello, world")
+
+
+        if __name__ == "__main__":
+            apps.run_plugin(Application)
+    ```
+
+!!! info
+    If you're making these changes to an existing code base, you should be able to run things to
+    validate that everything still works as it did before. Your `main()` function is now in
+    the `execute()` method of your new `Application` class, but none of the behavior of your
+    application should have been affected.
+
+Now that we have a fully defined rats application; we can use [rats.apps.Container][] instances to
+make services available to our application while remaining decoupled from the details of how these
+services are initialized. A common use case for this is to give our team access to the azure
+storage clients without needing to specify the authentication details; allowing us to ensure our
+application is functional in many compute environments.
+
+=== ":material-language-python: ~/code/src/foo/\_\_init\_\_.py"
+
+    ```python
+        from ._plugin import PluginContainer
+
+        __all__ = ["PluginContainer"]
+    ```
+
+=== ":material-language-python: ~/code/src/foo/\_\_main\_\_.py"
+
+    ```python
+        from rats import apps
+        import foo
+
+
+        class Application(apps.AppContainer, apps.PluginMixin):
+
+            def execute() -> None:
+                blob_client = self._app.get(foo.BLOB_SERVICE_ID)
+                print(f"hello, world. loaded blob client: {blob_client}")
+
+            @apps.container()
+            def _plugins(self) -> apps.Container:
+                return foo.PluginContainer(self._app)
+
+
+        if __name__ == "__main__":
+            apps.run_plugin(Application)
+    ```
+
+=== ":material-language-python: ~/code/src/foo/_plugin.py"
+
+    ```python
+        from rats import apps
+        from azure.storage.blob import BlobServiceClient
+
+        BLOB_SERVICE_ID = apps.ServiceId[BlobServiceClient]("blob-client")
+
+
+        class PluginContainer(apps.Container, apps.PluginMixin):
+
+            @apps.service(BLOB_SERVICE_ID)
+            def _blob_client(self) -> BlobServiceClient:
+                credential = DefaultAzureCredential()
+                return BlobServiceClient(
+                    account_url=f"https://example.blob.core.windows.net/",
+                    credential=credential,
+                )
+    ```
+
+!!! success
+    Following these patterns, we can make services available to others with plugin containers; and
+    we can combine these containers to create applications. The [rats.apps][] module has additional
+    libraries to help define different types of applications, designed to help your solutions
+    evolve as ideas mature. Our first runnable example was a single instance of the
+    [rats.apps.AppContainer][] interface with an `execute()` method; but a larger project might
+    have a few modules providing different aspects of the application's needs by sharing a set of
+    service ids and a plugin container.
+
+## Installable Plugins
+
+We use the standard [Entry Points](https://packaging.python.org/en/latest/specifications/entry-points/)
+mechanism to allow authors to make their application extensible. These plugins are instances of
+[rats.apps.Container][] and loaded into applications like our previous examples.
+
+=== ":material-file-settings: ~/code/pyproject.toml"
+    ```toml
+    [tool.poetry.plugins."foo.plugins"]
+    "foo" = "foo:PluginContainer"
+    ```
+
+=== ":material-language-python: ~/code/src/foo/\_\_main\_\_.py"
+    ```python
+        from rats import apps
+        import foo
+
+
+        class Application(apps.AppContainer, apps.PluginMixin):
+
+            def execute() -> None:
+                blob_client = self._app.get(foo.BLOB_SERVICE_ID)
+                print(f"hello, world. loaded blob client: {blob_client}")
+
+            @apps.container()
+            def _plugins(self) -> apps.Container:
+                return apps.PythonEntryPointContainer("foo.plugins")
+
+
+        if __name__ == "__main__":
+            apps.run_plugin(Application)
+    ```
+
+!!! success
+    We used [rats.app] to define an application, and used a service provided by a plugin container
+    that is loaded through a python entry point. You can create a script entry in your
+    `pyproject.toml` file to expose your application through a terminal command:
+
+    === ":material-language-python: ~/code/src/foo/\_\_init\_\_.py"
+        ```python
+            from ._app import Application, main
+            from ._plugin import PluginContainer
+
+
+            __all__ = [
+                "Application",
+                "main",
+                "PluginContainer",
+            ]
+        ```
+    === ":material-file-settings: ~/code/pyproject.toml"
+        ```toml
+            [tool.poetry.plugins."foo.plugins"]
+            "foo" = "foo:PluginContainer"
+
+            [tool.poetry.scripts]
+            foo = "foo:main"
+        ```
+

{rats_apps-0.11.1.dev20250527164753.dist-info → rats_apps-0.11.1.dev20250528185313.dist-info}/RECORD

@@ -11,7 +11,7 @@ rats/apps/__init__.py,sha256=6B5qQvzx1xlRrNRY4QJi6GEywuQ1MoW454kC4nO2Yqg,2084
 rats/apps/_annotations.py,sha256=6M_M7K8haNVda0Tx02EpFf3s9EjnWYacNMjTIkNEdRU,4617
 rats/apps/_app_containers.py,sha256=1rtq92rOGvCbroQmDgOM24jxxcNNFQHy65fBLO5LIXo,6920
 rats/apps/_composite_container.py,sha256=FdpmH_xIly6LxNZrA_nZCznukptjVLXttXTMtf_tnv8,695
-rats/apps/_container.py,sha256=sYISCG-qVzl-bsBwX_CAWEP9gtXCnG-Jls3l8IKb4DQ,7208
+rats/apps/_container.py,sha256=N8qR0oBLi03xZvPfc8SxaSci0oVYfX_rftzfaBkTSfQ,7415
 rats/apps/_executables.py,sha256=hXExNmAnuPU1KJXihNw1jEDAQpMlQ9E9_aPV8tpGbOY,1347
 rats/apps/_ids.py,sha256=T8Onrj79t8NPfBMQBk0xI6fIWDKF0m2JfFNrdtXAbWg,353
 rats/apps/_mains.py,sha256=2Q97mNk1cBzYROc_pJcm57EEeHmwRbXOWpfYXH37qcA,995
@@ -55,7 +55,7 @@ rats_e2e/runtime/_data.py,sha256=3d1F_JO2gEOPUjBp_KYMP3TefyneiG_ktlJjdIIYUy8,125
 rats_e2e/runtime/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 rats_resources/runtime/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 rats_resources/runtime/example-context.yaml,sha256=eiLsNFquFfkIpUhxUCQLzLigH21QF2F00fzA_e_aOKk,215
-rats_apps-0.11.1.dev20250527164753.dist-info/METADATA,sha256=kgJQUzcaMgofZndS9ETn14z0uY0ZE50-Y1Yh8pqVqYA,889
-rats_apps-0.11.1.dev20250527164753.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-rats_apps-0.11.1.dev20250527164753.dist-info/entry_points.txt,sha256=Gf6bPwxIVjWd3Xx71upZo7eDJA5cujniLew6fxJMgA4,117
-rats_apps-0.11.1.dev20250527164753.dist-info/RECORD,,
+rats_apps-0.11.1.dev20250528185313.dist-info/METADATA,sha256=5ywdh1LvrSfuQ9ZP5oKGfYMxR98PRsvQCS-RIDstGvE,8292
+rats_apps-0.11.1.dev20250528185313.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+rats_apps-0.11.1.dev20250528185313.dist-info/entry_points.txt,sha256=Gf6bPwxIVjWd3Xx71upZo7eDJA5cujniLew6fxJMgA4,117
+rats_apps-0.11.1.dev20250528185313.dist-info/RECORD,,

rats_apps-0.11.1.dev20250527164753.dist-info/METADATA

@@ -1,27 +0,0 @@
-Metadata-Version: 2.3
-Name: rats-apps
-Version: 0.11.1.dev20250527164753
-Summary: research analysis tools for building applications
-License: MIT
-Keywords: pipelines,machine learning,research
-Author: Elon Portugaly
-Author-email: elonp@microsoft.com
-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
-Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: click
-Requires-Dist: colorlog
-Requires-Dist: dataclass-wizard
-Requires-Dist: pyyaml
-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
-...
-