python-inject Documentation

If you bind a class or a function to a context manager (using bind_to_provider or bind), python-inject will use the object as-is. If the object is a context manager, it will be managed by the caller's lifecycle (e.g., when used in an @inject.autoparams function), ensuring resources like connections or files are properly destroyed.

import contextlib
import inject

@contextlib.contextmanager
def get_file_sync():
    obj = MockFile()
    yield obj
    obj.destroy()

def config(binder):
    # Binding a provider that returns a context manager
    binder.bind_to_provider(MockFile, get_file_sync)

inject.configure(config)

@inject.autoparams()
def example(file: MockFile):
    # 'file' will be automatically destroyed when 'example' exits
    pass

Use pip to install the latest version of inject.

pip install inject

When using python-inject in environments like Django where modules might be loaded multiple times, use once=True to ensure configuration only runs if the injector is absent.

To create composable configurations (e.g., for testing), use binder.install(base_config) to reuse existing bindings, and set allow_override=True in inject.configure to permit overriding previously registered dependencies.

# Django usage
inject.configure(my_config, once=True)

# Composable/Override usage
def base_config(binder):
    binder.bind(Validator, RealValidator())

def tests_config(binder):
    binder.install(base_config)
    binder.bind(Validator, TestValidator()) # Overrides RealValidator

inject.configure(tests_config, allow_override=True, clear=True)

In unit tests, it is best practice to create a fresh injector for each test using inject.configure(callable, clear=True) in the setUp method, and clean up the injector in the tearDown method using inject.clear().

import unittest
import inject

class MyTest(unittest.TestCase):
    def setUp(self):
        # Create a new injector for this test
        inject.configure(lambda binder:
            binder.bind(Cache, MockCache()),
            clear=True)
    
    def tearDown(self):
        # Clean up after the test
        inject.clear()

By default, python-inject uses runtime binding to implicitly instantiate classes that haven't been explicitly bound. To prevent unexpected behavior and ensure that only explicitly configured dependencies are injected, pass bind_in_runtime=False to inject.configure. This will cause inject to raise an InjectorException if an unbound instance is requested.

inject.configure(my_config, bind_in_runtime=False)

To use python-inject, you must first configure a shared injector. This is typically done by defining a configuration function that accepts a Binder object and then calling inject.configure(your_config_func).

Once configured, the injector is thread-safe and can be reused across multiple threads.

def my_config(binder):
    binder.bind(Cache, RedisCache('localhost:1234'))
    binder.bind_to_provider(CurrentUser, get_current_user)

import inject
inject.configure(my_config)

When writing tests, you often need a clean state for each test case. Use inject.clear_and_configure(config_func) to wipe the existing injector and set up a new one, or inject.clear() to remove the injector entirely during teardown.

import inject

def test_my_feature():
    # Setup a fresh injector for this test
    inject.clear_and_configure(my_test_config)
    
    try:
        # ... run test ...
        pass
    finally:
        # Clean up after the test
        inject.clear()

The @inject.autoparams decorator automatically injects arguments into a function based on their type annotations. This requires Python >= 3.5.

To avoid attempting to inject every argument, you can specify exactly which arguments should be injected by passing their names as strings to the decorator.

You can also use the empty parentheses notation @inject.autoparams() for non-parameterized decorations.

@inject.autoparams
def refresh_cache(cache: RedisCache, db: DbInterface):
    pass

# Specify specific arguments to inject
@inject.autoparams('cache', 'db')
def sign_up(name, email, cache: RedisCache, db: DbInterface):
    pass

# Non-parameterized usage
@inject.autoparams()
def example(conn: MockConnection, file: MockFile):
    pass

The @inject.autoparams decorator automatically injects arguments into a function based on their type hints.

• Full injection: Use @inject.autoparams to inject all hinted arguments.
• Selective injection: Use @inject.autoparams('arg1', 'arg2') to only attempt to inject specific arguments by name, even if others are hinted.

Note: It unwraps Union types (e.g., Union[A, None] becomes A) to find the underlying type for injection.

import inject

@inject.autoparams
def refresh_cache(cache: RedisCache, db: DbInterface):
    cache.refresh()
    db.sync()

@inject.autoparams('cache')
def sign_up(name: str, email: str, cache: RedisCache):
    # Only 'cache' is injected; 'name' and 'email' must be provided by the caller
    cache.save(name)