Merge pull request #301 from python-ellar/feat/global-tag-registry-and-testing

feat: Add InjectByTag support and global TagRegistry for testing

Author: eadwinCode

docs/basics/testing.md

@@ -221,5 +221,11 @@ class AModule(ModuleBase):
 
 In the above example, we are tagging `Foo` as `first_foo` and `FooB` as `second_foo`. By doing this, we can resolve both services using their tag names, thus providing the possibility of resolving services by tag name or type.
 
-Also, services can be injected as a dependency by using tags. To achieve this, the `InjectByTag` decorator is used as a `**constructor**` argument.
+Also, services can be injected as a dependency by using tags. To achieve this, `InjectByTag` is used as a `**constructor**` argument.
 This allows for more flexibility in managing dependencies and resolving services based on tags.
+
+`InjectByTag` supports two syntaxes:
+- **Callable syntax**: `InjectByTag('tag_name')` 
+- **Generic syntax**: `InjectByTag[T("tag_name")]` where T is from `ellar.common.types.T`
+
+Both syntaxes work identically and can be used interchangeably based on your preference.

docs/overview/providers.md

@@ -1,3 +1,3 @@
 """Ellar - Python ASGI web framework for building fast, efficient, and scalable RESTful APIs and server-side applications."""
 
-__version__ = "0.9.0"
+__version__ = "0.9.2"

ellar/__init__.py

@@ -279,7 +279,7 @@ async def add_authentication_schemes(
 
     def get_module_loaders(self) -> t.Generator[ModuleTemplating, None, None]:
         for loader in self._injector.get_templating_modules().values():
-            yield loader
+            yield t.cast(ModuleTemplating, loader)
 
     def _create_jinja_environment(self) -> Environment:
         # TODO: rename to `create_jinja_environment`

ellar/app/main.py

@@ -99,7 +99,13 @@
 from .serializer import Serializer, serialize_object
 from .templating import TemplateResponse, render_template, render_template_string
 
+
+def T(tag: str) -> str:
+    return tag
+
+
 __all__ = [
+    "T",
     "AnonymousIdentity",
     "ControllerBase",
     "serialize_object",

ellar/common/__init__.py

@@ -147,17 +147,17 @@ def exports(self) -> t.List[t.Type]:
         return list(reflect.get_metadata(MODULE_METADATA.EXPORTS, self.module) or [])
 
     @cached_property
-    def providers(self) -> t.Dict[t.Type, t.Type]:
+    def providers(self) -> t.Dict[t.Type, ProviderConfig]:
         _providers = list(
             reflect.get_metadata(MODULE_METADATA.PROVIDERS, self.module) or []
         )
-        res = {}
+        res: t.Dict[t.Type, ProviderConfig] = {}
         for item in _providers:
             if isinstance(item, ProviderConfig):
-                res.update({item: item.get_type()})
+                res.update({item.get_type(): item})
             else:
-                res.update({item: item})
-        return res  # type:ignore[return-value]
+                res.update({item: ProviderConfig(item)})
+        return res
 
     @property
     def is_ready(self) -> bool:

ellar/core/modules/config.py

@@ -1,6 +1,5 @@
 import typing as t
 from abc import ABC, abstractmethod
-from functools import cached_property
 from typing import Type
 
 from ellar.auth.constants import POLICY_KEYS
@@ -66,16 +65,21 @@ def __init__(
         self._routers: t.List[t.Union[BaseRoute]] = []
         self._exports: t.List[t.Type] = []
         self._providers: t.Dict[t.Type, ProviderConfig] = {}
+        self._module_execution_context: t.Optional[ModuleExecutionContext] = None
 
     def __repr__(self) -> str:
         return f"<{self.__class__.__name__} name={self.name} module={self.module}>"
 
     def __hash__(self) -> int:
         return hash(self.module)
 
-    @cached_property
+    @property
     def module_context(self) -> ModuleExecutionContext:
-        return ModuleExecutionContext(container=self.container, module=self.module)
+        if self._module_execution_context is None:
+            self._module_execution_context = ModuleExecutionContext(
+                container=self.container, module=self.module
+            )
+        return self._module_execution_context
 
     @property
     def tree_manager(self) -> ModuleTreeManager:

ellar/core/modules/ref/base.py

@@ -33,7 +33,6 @@ class Container(InjectorBinder):
         "injector",
         "_auto_bind",
         "_bindings",
-        "_bindings_by_tag",
         "parent",
         "_aliases",
         "_exact_aliases",
@@ -43,7 +42,6 @@ class Container(InjectorBinder):
 
     def __init__(self, *args: t.Any, **kwargs: t.Any) -> None:
         super().__init__(*args, **kwargs)
-        self._bindings_by_tag: t.Dict[str, t.Type[t.Any]] = {}
 
     @t.no_type_check
     def create_binding(
@@ -58,22 +56,13 @@ def create_binding(
             scope = scope.scope
         return Binding(interface, provider, scope)
 
-    def get_interface_by_tag(self, tag: str) -> t.Type[t.Any]:
-        interface = self._bindings_by_tag.get(tag)
-        if interface:
-            return interface
-        if isinstance(self.parent, Container):
-            return self.parent.get_interface_by_tag(tag)
-
-        raise UnsatisfiedRequirement(None, t.cast(t.Any, tag))
-
     def register_binding(
         self, interface: t.Type, binding: Binding, tag: t.Optional[str] = None
     ) -> None:
         self._bindings[interface] = binding
 
         if tag:
-            self._bindings_by_tag[tag] = interface
+            self.injector.tag_registry.register(tag, interface)
 
     @t.no_type_check
     def register(

ellar/di/injector/container.py

@@ -1,22 +1,26 @@
+from __future__ import annotations
+
 import sys
 import typing as t
 from functools import cached_property
 
 from ellar.di.constants import MODULE_REF_TYPES, Tag, request_context_var
 from ellar.di.injector.tree_manager import ModuleTreeManager
 from ellar.di.logger import log
+from ellar.di.providers import InstanceProvider, Provider
+from ellar.di.types import T
 from injector import Injector, Scope, ScopeDecorator
 from typing_extensions import Annotated
 
-from ..providers import InstanceProvider, Provider
-from ..types import T
 from .container import Container
+from .tag_registry import TagRegistry
 
 if t.TYPE_CHECKING:  # pragma: no cover
     from ellar.core.modules import (
         ModuleBase,
+        ModuleForwardRef,
         ModuleRefBase,
-        ModuleTemplateRef,
+        ModuleSetup,
     )
 
 
@@ -62,6 +66,9 @@ class EllarInjector(Injector):
         "owner",
     )
 
+    # Global tag registry shared across all injector instances
+    tag_registry: t.ClassVar[TagRegistry] = TagRegistry()
+
     def __init__(
         self,
         auto_bind: bool = True,
@@ -101,9 +108,11 @@ def get_module(self, module: t.Type) -> t.Optional["ModuleRefBase"]:
 
     def get_templating_modules(
         self,
-    ) -> t.Dict[t.Type["ModuleBase"], "ModuleTemplateRef"]:
+    ) -> dict[
+        type[ModuleBase] | type, ModuleRefBase | "ModuleSetup" | ModuleForwardRef
+    ]:
         return {
-            item.value.module: item.value  # type:ignore[misc]
+            item.value.module: item.value
             for item in self.tree_manager.get_by_ref_type(MODULE_REF_TYPES.TEMPLATE)
         }
 
@@ -115,7 +124,7 @@ def get(
     ) -> T:
         data = _tag_info_interface(interface)
         if data and data.supertype is Tag:
-            interface = self.container.get_interface_by_tag(data.tag)
+            interface = self.tag_registry.get_interface(data.tag)
 
         binding, binder = self.container.get_binding(interface)
         scope = binding.scope

ellar/di/injector/ellar_injector.py

@@ -0,0 +1,62 @@
+"""
+Tag Registry for managing global tag-to-interface mappings
+"""
+
+import typing as t
+
+from ellar.di.exceptions import UnsatisfiedRequirement
+
+
+class TagRegistry:
+    """
+    Centralized registry for managing tag-to-interface mappings.
+
+    This ensures that all tagged providers are registered globally and accessible
+    across the entire injector hierarchy, rather than being scoped to individual containers.
+    """
+
+    def __init__(self) -> None:
+        self._bindings_by_tag: t.Dict[str, t.Type[t.Any]] = {}
+
+    def register(self, tag: str, interface: t.Type[t.Any]) -> None:
+        """
+        Register a tag-to-interface mapping.
+
+        :param tag: The tag string
+        :param interface: The interface/type associated with this tag
+        """
+        self._bindings_by_tag[tag] = interface
+
+    def get_interface(self, tag: str) -> t.Type[t.Any]:
+        """
+        Get the interface associated with a tag.
+
+        :param tag: The tag string to lookup
+        :return: The interface/type associated with the tag
+        :raises UnsatisfiedRequirement: If the tag is not registered
+        """
+        interface = self._bindings_by_tag.get(tag)
+        if interface:
+            return interface
+
+        raise UnsatisfiedRequirement(None, t.cast(t.Any, tag))
+
+    def has_tag(self, tag: str) -> bool:
+        """
+        Check if a tag is registered.
+
+        :param tag: The tag string to check
+        :return: True if the tag is registered, False otherwise
+        """
+        return tag in self._bindings_by_tag
+
+    def clear(self) -> None:
+        """Clear all tag registrations. Useful for testing."""
+        self._bindings_by_tag.clear()
+
+    def get_all_tags(self) -> t.Dict[str, t.Type[t.Any]]:
+        """Get a copy of all tag-to-interface mappings."""
+        return self._bindings_by_tag.copy()
+
+    def __repr__(self) -> str:
+        return f"TagRegistry(tags={list(self._bindings_by_tag.keys())})"