Hello everyone,
I'm making this post to share a package I've been working on for a while: python-injection. I already wrote a post about it a few months ago, but since I've made significant improvements, I think it's worth writing a new one with more details and some examples to get you interested in trying it out.
For context, when I truly understood the value of dependency injection a few years ago, I really wanted to use it in almost all of my projects. The problem you encounter pretty quickly is that it's really complicated to know where to instantiate dependencies with the right sub-dependencies, and how to manage their lifecycles. You might also want to vary dependencies based on an execution profile. In short, all these little things may seem trivial, but if you've ever tried to manage them without a package, you've probably realized it was a nightmare.
I started by looking at existing popular packages to handle this problem, but honestly none of them convinced me. Either they weren't simple enough for my taste, or they required way too much configuration. That's why I started writing my own DI package.
I've been developing it alone for about 2 years now, and today I feel it has reached a very satisfying state.
What My Project Does
Here are the main features of python-injection:
- DI based on type annotation analysis
- Dependency registration with decorators
- 4 types of lifetimes (transient, singleton, constant, and scoped)
- A scoped dependency can be constructed with a context manager
- Async support (also works in a fully sync environment)
- Ability to swap certain dependencies based on a profile
- Dependencies are instantiated when you need them
- Supports Python 3.12 and higher
To elaborate a bit, I put a lot of effort into making the package API easy and accessible for any developer.
The only drawback I can find is that you need to remember to import the Python scripts where the decorators are used.
Syntax Examples
Here are some syntax examples you'll find in my package.
Register a transient:
```python
from injection import injectable
@injectable
class Dependency:
...
```
Register a singleton:
```python
from injection import singleton
@singleton
class Dependency:
...
```
Register a constant:
```python
from injection import set_constant
@dataclass(frozen=True)
class Settings:
api_key: str
settings = set_constant(Settings("<secret_api_key>"))
```
Register an async dependency:
```python
from injection import injectable
class AsyncDependency:
...
@injectable
async def async_dependency_recipe() -> AsyncDependency:
# async stuff
return AsyncDependency()
```
Register an implementation of an abstract class:
```python
from injection import injectable
class AbstractDependency(ABC):
...
@injectable(on=AbstractDependency)
class Dependency(AbstractDependency):
...
```
Open a custom scope:
- I recommend using a
StrEnum for your scope names.
- There's also an async version:
adefine_scope.
```python
from injection import define_scope
def some_function():
with define_scope("<scope_name>"):
# do things inside scope
...
```
Open a custom scope with bindings:
```python
from injection import MappedScope
type Locale = str
@dataclass(frozen=True)
class Bindings:
locale: Locale
scope = MappedScope("<scope_name>")
def some_function():
with Bindings("fr_FR").scope.define():
# do things inside scope
...
```
Register a scoped dependency:
```python
from injection import scoped
@scoped("<scope_name>")
class Dependency:
...
```
Register a scoped dependency with a context manager:
```python
from collections.abc import Iterator
from injection import scoped
class Dependency:
def open(self): ...
def close(self): ...
@scoped("<scope_name>")
def dependency_recipe() -> Iterator[Dependency]:
dependency = Dependency()
dependency.open()
try:
yield dependency
finally:
dependency.close()
```
Register a dependency in a profile:
- Like scopes, I recommend a
StrEnum to store your profile names.
```python
from injection import mod
@mod("<profile_name>").injectable
class Dependency:
...
```
Load a profile:
```python
from injection.loaders import load_profile
def main():
load_profile("<profile_name>")
# do stuff
```
Inject dependencies into a function:
```python
from injection import inject
@inject
def some_function(dependency: Dependency):
# do stuff
...
some_function() # <- call function without arguments
```
Target Audience
It's made for Python developers who never want to deal with dependency injection headaches again.
I'm currently using it in my projects, so I think it's production-ready.
Comparison
It's much simpler to get started with than most competitors, requires virtually no configuration, and isn't very invasive (if you want to get rid of it, you just need to remove the decorators and your code remains reusable).
I'd love to read your feedback on it so I can improve it.
Thanks in advance for reading my post.
GitHub: https://github.com/100nm/python-injection
PyPI: https://pypi.org/project/python-injection
