-name:Install Dependencies

shell:bash

run:uv sync

run:uv sync --no-group bench

steps:

-name:Run checkout

uses:actions/checkout@v5

uses:actions/checkout@v6

-name:Set up environment

uses:./.github/actions/environment

steps:

-name:Run checkout

uses:actions/checkout@v5

uses:actions/checkout@v6

-name:Set up environment

uses:./.github/actions/environment

name:GitHub Pages

on:

push:

branches:

-prod

jobs:

delivery:

name:Delivery

runs-on:ubuntu-latest

permissions:

contents:write

steps:

-name:Run checkout

uses:actions/checkout@v6

-name:Configure Git

run:|

-name:Set up environment

uses:./.github/actions/environment

-name:Deploy MkDocs

shell:bash

run:uv run mkdocs gh-deploy --force

pytest:

uv run pytest

mkdocs:

uv run mkdocs serve

[](https://pypistats.org/packages/python-injection)

[](https://github.com/astral-sh/ruff)

Documentation:https://python-injection.remimd.dev

⚠️_Requires Python 3.12 or higher_

pip install python-injection

* Automatic dependency resolution based on type hints.

* Support for multiple dependency lifetimes:`transient`,`singleton`,`constant`, 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.

1. Easy to use

2. No impact on class and function definitions

3. No tedious configuration

Simply apply the decorators and the package takes care of the rest.

from injectionimport injectable, inject, singleton

if__name__=="__main__":

main()

*[**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)

*[**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)

*[**FastAPI**](https://github.com/100nm/python-injection/tree/prod/documentation/integrations/fastapi.md)

*[**What if my framework isn't listed?**](https://github.com/100nm/python-injection/tree/prod/documentation/integrations/unlisted-framework.md)

*[**Concrete example**](https://github.com/100nm/python-injection-example)

python-injection.remimd.dev

When using decorators to register dependencies, some implementations may never be explicitly imported in your project. This creates a problem: if a module is never imported, its decorators never execute, and the dependencies are never registered.

For example, if you register an implementation with`@injectable(on=AbstractDependency)` but never import that implementation module, the dependency won't be available for injection even though it's decorated.

To solve this,`python-injection` provides two solutions for automatically importing modules in a package.

!!! tip

Call auto-import functions early in your application startup,**before loading your profile** and before any dependency resolution occurs.

The`load_packages` function imports all modules from the specified packages. Packages can be passed as module objects or as strings:

from injection.loadersimport load_packages

from srcimport adapters, services

load_packages(adapters, services)

load_packages("src.adapters","src.services")

This is the simplest approach and works well when you want to import everything from specific packages.

For more control over which modules get imported, use`PythonModuleLoader` with a custom predicate function. Like`load_packages`, it accepts both module objects and strings:

from injection.loadersimport PythonModuleLoader

from srcimport adapters, services

defpredicate(module_name:str) ->bool:

return"impl"in module_name

PythonModuleLoader(predicate).load(adapters, services)

The predicate function receives the full module name (e.g.,`"src.adapters.dependency_impl"`) and returns`True` if the module should be imported.

`PythonModuleLoader` provides three convenient factory methods for common filtering patterns:

**Filter by prefix:**

PythonModuleLoader.startswith("impl_").load(adapters, services)

**Filter by suffix:**

PythonModuleLoader.endswith("_impl").load(adapters, services)

**Filter by keyword marker:**

PythonModuleLoader.from_keywords("# auto-import").load(adapters, services)

This last approach is particularly useful for explicitly marking which modules should be auto-imported:

@injectable(on=AbstractDependency)

classDependency(AbstractDependency):

As we've seen throughout this guide, there can be quite a bit of setup around a main function: loading modules, defining scopes, injecting dependencies, loading profiles, etc. This becomes repetitive when you have multiple entry points in your project (CLI commands, etc.).

To solve this,`python-injection` provides**entrypoints**, a way to create custom decorators that encapsulate all your setup logic using a builder pattern.

Use the`@entrypointmaker` decorator to define your setup logic once:

from injectionimport adefine_scope

from injection.entrypointimport AsyncEntrypoint, Entrypoint, entrypointmaker

from injection.loadersimport PythonModuleLoader

def entrypoint[**P, T](self: AsyncEntrypoint[P, T])-> Entrypoint[P, T]:

import src

module_loader= PythonModuleLoader.endswith("_impl")

return (

self.inject()

.decorate(adefine_scope("lifespan",kind="shared"))

.async_to_sync()

.load_modules(module_loader, src)

)

Now you can use your custom`@entrypoint` decorator on any function:

asyncdefmain(dependency: Dependency):

if__name__=="__main__":

main()

!!! info "Builder execution order"

The builder instructions execute in**reverse order**. Each method call re-decorates the main function, so the last instruction in the chain is call first. In the example above, modules are loaded first, then the function is converted to sync, then the scope is defined, and finally dependencies are injected.

The entrypoint decorator accepts an optional`autocall` parameter. When set to`True`, the decorated function is automatically called:

@entrypoint(autocall=True)

asyncdefmain(dependency: Dependency):

This is particularly convenient for scripts and CLI commands where you want the entry point to execute immediately.

If you're using a[`ProfileLoader`](profiles.md#profileloader) in your project, pass it to`@entrypointmaker` using the`profile_loader` parameter:

from injection.entrypointimport Entrypoint, entrypointmaker

from injection.loadersimport ProfileLoader, PythonModuleLoader

profile_loader= ProfileLoader(...)

@entrypointmaker(profile_loader=profile_loader)

def entrypoint[**P, T](self: Entrypoint[P, T])-> Entrypoint[P, T]:

import src

module_loader= PythonModuleLoader.endswith("_impl")

return (

self.inject()

.load_profile(Profile.DEV)# Load a specific profile

.load_modules(module_loader, src)

)

The`load_profile` method accepts a profile name and loads it before the main function executes.

You can resolve dependencies from the setup function parameters. These dependencies must be registered in the default module (not in a profile-specific module) and should preferably be transient or constant. This is particularly useful for resolving configuration to determine which profile to load:

from dataclassesimport dataclass

from injectionimport constant

from injection.entrypointimport Entrypoint, entrypointmaker

from injection.loadersimport PythonModuleLoader

from osimport getenv

classConfig:

profile: Profile

def_config_factory() -> Config:

profile= Profile(getenv("PROFILE","development"))

return Config(profile)

@entrypointmaker(profile_loader=profile_loader)

def entrypoint[**P, T](self: Entrypoint[P, T], config: Config)-> Entrypoint[P, T]:

import src

profile= config.profile# Use config to determine profile

suffixes=self.profile_loader.required_module_names(profile)

module_loader= PythonModuleLoader.endswith(*suffixes)

return (

self.inject()

.load_profile(profile)

.load_modules(module_loader, src)

)

In this example,`config` is resolved from the default module and used to dynamically load the appropriate profile.

!!! warning

Dependencies resolved in the entrypoint setup function must be registered in the default module (not in a profile-specific module) and should be transient or constant to avoid state issues.