feat: 📝 Enhanced documentation

Author: remimd

README.md

@@ -1,11 +1,10 @@
 # python-injection
 
 [![CI](https://github.com/100nm/python-injection/actions/workflows/ci.yml/badge.svg)](https://github.com/100nm/python-injection)
-[![PyPI](https://img.shields.io/pypi/v/python-injection.svg?color=blue)](https://pypi.org/project/python-injection)
+[![PyPI - Version](https://img.shields.io/pypi/v/python-injection.svg?color=blue)](https://pypi.org/project/python-injection)
+[![PyPI - Downloads](https://img.shields.io/pypi/dm/python-injection.svg?color=blue)](https://pypistats.org/packages/python-injection)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 
-Fast and easy dependency injection framework.
-
 ## Installation
 
 ⚠️ _Requires Python 3.12 or higher_
@@ -14,12 +13,21 @@ Fast and easy dependency injection framework.
 pip install python-injection
 ```
 
+## Features
+
+* Support for multiple dependency lifetimes: `transient`, `singleton`, and `scoped`.
+* Works seamlessly in both `async` and `sync` environments.
+* Separation of dependency sets using modules.
+* Runtime switching between different sets of dependencies.
+* Centralized setup logic using entrypoints.
+* Built-in type annotation for easy integration with [`FastAPI`](https://github.com/fastapi/fastapi).
+* Lazy dependency resolution for optimized performance.
+
 ## Motivations
 
 1. Easy to use
 2. No impact on class and function definitions
-3. Easily interchangeable dependencies _(depending on the runtime environment, for example)_
-4. No prerequisites
+3. No tedious configuration
 
 ## Quick start
 
@@ -64,5 +72,6 @@ if __name__ == "__main__":
 * [**Advanced usage**](https://github.com/100nm/python-injection/tree/prod/documentation/advanced-usage.md)
 * [**Loaders**](https://github.com/100nm/python-injection/tree/prod/documentation/loaders.md)
 * [**Entrypoint**](https://github.com/100nm/python-injection/tree/prod/documentation/entrypoint.md)
-* [**Integrations**](https://github.com/100nm/python-injection/tree/prod/documentation/integrations.md)
+* [**Integrations**](https://github.com/100nm/python-injection/tree/prod/documentation/integrations)
+  * [**FastAPI**](https://github.com/100nm/python-injection/tree/prod/documentation/integrations/fastapi.md)
 * [**Concrete example**](https://github.com/100nm/python-injection-example)

documentation/advanced-usage.md

@@ -41,6 +41,13 @@ def some_function(service_a: ServiceA, service_b: ServiceB):
 
 ### Module interconnections
 
+> [!IMPORTANT]
+> This section contains operations that can be performed between modules. In most cases, you don't need to worry about 
+> them. 
+> 
+> Instead, use [`ProfileLoader`](loaders.md#ProfileLoader) or [`load_profile`](loaders.md#load_profile), which are much 
+> simpler and easier to understand.
+
 > **Use a module**
 
 When a module is used by another module, the module's dependencies are replaced by those of the module used.

documentation/entrypoint.md

@@ -20,24 +20,54 @@ or `injectables`, because everything is not yet fully configured at this stage.
 
 **Instruction order matters**: each configuration step applies a decorator and returns a new `Entrypoint` instance.
 
+Here's all you can do with an entrypoint:
+
+_Take only what you need._
+
 ```python
 # src/entrypoint.py
 
+from enum import StrEnum, auto
+
 import uvloop
-from injection import adefine_scope
+from injection import adefine_scope, mod
 from injection.entrypoint import AsyncEntrypoint, Entrypoint, entrypointmaker
-from injection.loaders import PythonModuleLoader
+from injection.loaders import ProfileLoader, PythonModuleLoader
+from pydantic_settings import BaseSettings
+
+class Profile(StrEnum):
+    DEFAULT = mod().name
+    DEV = "dev"
+    STAGING = "staging"
+    PROD = "prod"
+    
+class SubProfile(StrEnum):
+    CONF = "conf"
+    
+class Scope(StrEnum):
+    LIFESPAN = auto()
 
-@entrypointmaker
-def entrypoint[**P, T](self: AsyncEntrypoint[P, T]) -> Entrypoint[P, T]:
+@mod(SubProfile.CONF).constant
+class Conf(BaseSettings):
+    profile: Profile = Profile.DEFAULT
+    
+@entrypointmaker(profile_loader=ProfileLoader({Profile.DEFAULT: [SubProfile.CONF]}))
+def entrypoint[**P, T](self: AsyncEntrypoint[P, T], conf: Conf) -> Entrypoint[P, T]:
     import src
 
-    loader = PythonModuleLoader.from_keywords("# Auto-import")
+    profile = conf.profile
+    keyword = "# auto-import"
+    keywords = {
+        f"{keyword}: {name}"
+        for name in self.profile_loader.required_module_names(profile)
+    }
+    module_loader = PythonModuleLoader.from_keywords(keyword, *keywords)
     return (
         self.inject()
-        .decorate(adefine_scope("lifespan", kind="shared"))
+        .decorate(adefine_scope(Scope.LIFESPAN, kind="shared"))
         .async_to_sync(uvloop.run)
-        .load_modules(loader, src)
+        .load_modules(module_loader, src)
+        .load_profile(profile)
     )
 ```
 

documentation/integrations/README.md

@@ -0,0 +1,3 @@
+# Integrations
+
+**Integrations make it easy to connect `python-injection` to other frameworks.**

documentation/integrations.md documentation/integrations/fastapi.mddocumentation/integrations.md renamed to documentation/integrations/fastapi.md

@@ -1,10 +1,6 @@
-# Integrations
+# [FastAPI](https://github.com/fastapi/fastapi)
 
-**Integrations make it easy to connect `python-injection` to other frameworks.**
-
-## [FastAPI](https://github.com/fastapi/fastapi)
-
-### Inject a dependency
+## Inject a dependency
 
 Here's how to inject an instance into a FastAPI endpoint.
 
@@ -16,13 +12,13 @@ async def my_endpoint(service: Inject[MyService]) -> None:
     ...
 ```
 
-### Useful scopes
+## 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)._
+_For a better understanding of the scopes, [here's the associated documentation](../scoped-dependencies.md)._
 
 Here's how to configure FastAPI:
 

documentation/loaders.md

@@ -38,7 +38,7 @@ PythonModuleLoader(predicate).load(package)
 Automatically imports modules whose Python script contains one of the keywords passed in parameter.
 
 ```python
-PythonModuleLoader.from_keywords("# Auto-import").load(package)
+PythonModuleLoader.from_keywords("# auto-import").load(package)
 ```
 
 * `startswith`

injection/__init__.pyi

@@ -115,7 +115,7 @@ class Module:
         parameter type annotations. If applied to a class, the dependencies resolved
         will be those of the `__init__` method.
 
-        With `threadsafe=True`, the injection logic is wrapped in a `threading.Lock`.
+        With `threadsafe=True`, the injection logic is wrapped in a `threading.RLock`.
         """
 
     def injectable[**P, T](
@@ -171,18 +171,18 @@ class Module:
         registered.
         """
 
-    def constant[T](
+    def constant[**P, T](
         self,
-        wrapped: type[T] = ...,
+        wrapped: _Recipe[P, T] = ...,
         /,
         *,
         on: _TypeInfo[T] = ...,
         mode: Mode | ModeStr = ...,
     ) -> Any:
         """
-        Decorator applicable to a class. It is used to indicate how the constant is
-        constructed. At injection time, the injected instance will always be the same.
-        Unlike `@singleton`, dependencies will not be resolved.
+        Decorator applicable to a class or function. It is used to indicate how the
+        constant is constructed. At injection time, the injected instance will always
+        be the same. Unlike `@singleton`, dependencies will not be resolved.
         """
 
     def set_constant[T](

injection/_core/module.py

@@ -503,15 +503,15 @@ def decorator(wp: type[T]) -> type[T]:
 
         return decorator(wrapped) if wrapped else decorator
 
-    def constant[T](
+    def constant[**P, T](
         self,
-        wrapped: type[T] | None = None,
+        wrapped: Recipe[P, T] | None = None,
         /,
         *,
         on: TypeInfo[T] = (),
         mode: Mode | ModeStr = Mode.get_default(),
     ) -> Any:
-        def decorator(wp: type[T]) -> type[T]:
+        def decorator(wp: Recipe[P, T]) -> Recipe[P, T]:
             lazy_instance = lazy(wp)
             self.injectable(
                 lambda: ~lazy_instance,
@@ -1087,7 +1087,7 @@ def decorator(wp: Callable[_P, _T]) -> Callable[_P, _T]:
         return decorator(wrapped) if wrapped else decorator
 
     @singledispatchmethod
-    def on_event(self, event: Event, /) -> ContextManager[None] | None:  # type: ignore[override]
+    def on_event(self, event: Event, /) -> ContextManager[None] | None:
         return None
 
     @on_event.register

injection/loaders.py

@@ -164,8 +164,11 @@ def init(self) -> Self:
 
     def load(self, name: str, /) -> LoadedProfile:
         self.init()
-        target_module = self.__init_subsets_for(mod(name))
-        self.module.use(target_module, priority=Priority.HIGH)
+
+        if not self.__is_default_module(name):
+            target_module = self.__init_subsets_for(mod(name))
+            self.module.use(target_module, priority=Priority.HIGH)
+
         return _UserLoadedProfile(self, name)
 
     def _unload(self, name: str, /) -> None:
@@ -182,6 +185,9 @@ def __init_subsets_for(self, module: Module) -> Module:
 
         return module
 
+    def __is_default_module(self, module_name: str) -> bool:
+        return module_name == self.module.name
+
     def __is_initialized(self, module: Module) -> bool:
         return module.name in self.__initialized_modules
 

pyproject.toml

@@ -15,6 +15,7 @@ dev = [
 ]
 doc = [
     "fastapi",
+    "pydantic-settings",
     "typer",
     "uvloop",
 ]
@@ -46,6 +47,8 @@ classifiers = [
     "Programming Language :: Python",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Operating System :: OS Independent",
     "Intended Audience :: Developers",
     "Natural Language :: English",