feat: 📝 Update documentation

Author: remimd

README.md

@@ -55,6 +55,9 @@ if __name__ == "__main__":
 
 ## Resources
 
+> ⚠️ The package isn't threadsafe, for better performance in single-threaded applications and those using `asyncio`.
+> So remember to use `threading.Lock` if you're writing a multithreaded program.
+
 * [**Basic usage**](https://github.com/100nm/python-injection/tree/prod/documentation/basic-usage.md)
 * [**Scoped dependencies**](https://github.com/100nm/python-injection/tree/prod/documentation/scoped-dependencies.md)
 * [**Testing**](https://github.com/100nm/python-injection/tree/prod/documentation/testing.md)

documentation/basic-usage.md

@@ -79,6 +79,16 @@ class SomeDataClass:
     service_a: ServiceA = ...
 ```
 
+### Threadsafe injection
+
+With `threadsafe=True`, the injection logic is wrapped in a `threading.Lock`.
+
+```python
+@inject(threadsafe=True)
+def some_function(service_a: ServiceA):
+    """ function implementation """
+```
+
 ## Get an instance
 
 _Example with `get_instance` function:_

documentation/integrations.md

@@ -4,15 +4,70 @@
 
 ## [FastAPI](https://github.com/fastapi/fastapi)
 
-Exemple:
+### Inject a dependency
+
+Here's how to inject an instance into a FastAPI endpoint.
+
+> Import:
 
 ```python
-from fastapi import FastAPI
 from injection.integrations.fastapi import Inject
+```
 
-app = FastAPI()
+> With **Annotated**:
 
+```python
 @app.get("/")
-async def my_endpoint(service: MyService = Inject(MyService)):
+async def my_endpoint(
+    service: Annotated[MyService, Inject(MyService)],
+) -> None:
     ...
 ```
+
+> Without **Annotated**:
+
+```python
+@app.get("/")
+async def my_endpoint(
+    service: MyService = Inject(MyService),
+) -> None:
+    ...
+```
+
+### Useful scopes
+
+Two fairly common scopes in FastAPI:
+* **Application lifespan scope**: associate with application lifespan.
+* **Request scope**: associate with http request lifetime.
+
+_For a better understanding of the scopes, [here's the associated documentation](scoped-dependencies.md)._
+
+Here's how to configure FastAPI:
+
+```python
+from collections.abc import AsyncIterator, Awaitable, Callable
+from contextlib import asynccontextmanager
+from enum import StrEnum, auto
+
+from fastapi import FastAPI, Request, Response
+from injection import adefine_scope
+
+class InjectionScope(StrEnum):
+    LIFESPAN = auto()
+    REQUEST = auto()
+
+@asynccontextmanager
+async def lifespan(_: FastAPI) -> AsyncIterator[None]:
+    async with adefine_scope(InjectionScope.LIFESPAN, shared=True):
+        yield
+
+app = FastAPI(lifespan=lifespan)
+
+@app.middleware("http")
+async def define_request_scope_middleware(
+    request: Request,
+    handler: Callable[[Request], Awaitable[Response]],
+) -> Response:
+    async with adefine_scope(InjectionScope.REQUEST):
+        return await handler(request)
+```

documentation/scoped-dependencies.md

@@ -19,7 +19,7 @@ There are two kinds of scopes:
 
 First of all, the scope must be defined:
 
-*By default, the `shared` parameter is `False`.*
+_By default, the `shared` parameter is `False`._
 
 > Define an asynchronous scope:
 
@@ -47,7 +47,7 @@ def main() -> None:
 
 ### "contextmanager-like" recipes
 
-*Anything after the `yield` keyword will be executed when the scope is closed.*
+_Anything after the `yield` keyword will be executed when the scope is closed._
 
 > Asynchronous (asynchronous scope required):
 

injection/__init__.pyi

@@ -281,7 +281,7 @@ class Module:
         module: Module,
         *,
         priority: Priority | PriorityStr = ...,
-    ) -> Iterator[None]:
+    ) -> Iterator[Self]:
         """
         Context manager or decorator for temporary use of a module.
         """
@@ -305,7 +305,7 @@ class Module:
         """
 
     @contextmanager
-    def load_profile(self, *names: str) -> Iterator[None]: ...
+    def load_profile(self, *names: str) -> Iterator[Self]: ...
     async def all_ready(self) -> None: ...
     def add_logger(self, logger: Logger) -> Self: ...
     @classmethod

injection/_core/module.py

@@ -739,11 +739,11 @@ def use_temporarily(
         module: Module,
         *,
         priority: Priority | PriorityStr = Priority.get_default(),
-    ) -> Iterator[None]:
+    ) -> Iterator[Self]:
         self.use(module, priority=priority)
 
         try:
-            yield
+            yield self
         finally:
             self.stop_using(module)
 
@@ -762,7 +762,7 @@ def unlock(self) -> Self:
 
         return self
 
-    def load_profile(self, *names: str) -> ContextManager[None]:
+    def load_profile(self, *names: str) -> ContextManager[Self]:
         modules = tuple(self.from_name(name) for name in names)
 
         for module in modules:
@@ -773,8 +773,8 @@ def load_profile(self, *names: str) -> ContextManager[None]:
         del module, modules
 
         @contextmanager
-        def cleaner() -> Iterator[None]:
-            yield
+        def cleaner() -> Iterator[Self]:
+            yield self
             self.unlock().init_modules()
 
         return cleaner()

injection/_core/scope.py

@@ -121,11 +121,8 @@ def _bind_scope(name: str, scope: Scope, shared: bool) -> Iterator[None]:
             f"Scope `{name}` is already defined in the current context."
         )
 
-    strategy = (
-        state.bind_shared_scope(scope) if shared else state.bind_contextual_scope(scope)
-    )
-
-    with strategy:
+    strategy = state.bind_shared_scope if shared else state.bind_contextual_scope
+    with strategy(scope):
         yield
 
 

injection/testing/__init__.py

@@ -1,6 +1,6 @@
 from typing import ContextManager, Final
 
-from injection import mod
+from injection import Module, mod
 from injection.utils import load_profile
 
 __all__ = (
@@ -23,5 +23,5 @@
 test_singleton = mod(_TEST_PROFILE_NAME).singleton
 
 
-def load_test_profile(*names: str) -> ContextManager[None]:
+def load_test_profile(*names: str) -> ContextManager[Module]:
     return load_profile(_TEST_PROFILE_NAME, *names)

injection/testing/__init__.pyi

@@ -11,7 +11,7 @@ test_injectable = __MODULE.injectable
 test_scoped = __MODULE.scoped
 test_singleton = __MODULE.singleton
 
-def load_test_profile(*names: str) -> ContextManager[None]:
+def load_test_profile(*names: str) -> ContextManager[Module]:
     """
     Context manager or decorator for temporary use test module.
     """

injection/utils.py

@@ -5,13 +5,13 @@
 from types import ModuleType as PythonModule
 from typing import ContextManager
 
+from injection import Module, mod
 from injection import __name__ as injection_package_name
-from injection import mod
 
 __all__ = ("load_modules_with_keywords", "load_packages", "load_profile")
 
 
-def load_profile(*names: str) -> ContextManager[None]:
+def load_profile(*names: str) -> ContextManager[Module]:
     """
     Injection module initialization function based on profile name.
     A profile name is equivalent to an injection module name.