punq

Punq is an unintrusive dependency injection library that avoids global state, decorators, and special syntax on arguments.

To use Punq, you must explicitly create a punq.Container at your application's entrypoint. You then register dependencies (either specific instances or classes) with the container and use resolve() to retrieve them. Punq automatically handles recursive dependency injection: if a requested class has dependencies in its __init__ method, Punq will resolve and inject those dependencies automatically.

import punq

# 1. Create the container
container = punq.Container()

# 2. Register dependencies
container.register(BaseService, ConcreteService)

# 3. Resolve dependencies
service = container.resolve(BaseService)

To ensure the container returns the exact same object every time (a singleton pattern), register a specific instance using the instance keyword argument.

class FileWritingGreeter:
    def __init__(self, path: str, greeting: str) -> None:
        self.path = path
        self.message = greeting

# Create the single instance manually
one_true_greeter = FileWritingGreeter("/tmp/greetings", "Hello world")

# Register that specific instance
container.register(FileWritingGreeter, instance=one_true_greeter)

You can provide arguments to a dependency at two different stages:

1. At Resolution: If you don't know the arguments at registration time, pass them to resolve().
2. At Registration: If you want to bake specific arguments into the dependency definition, pass them to register().

# Option 1: Provide arguments at resolution time
container.register(Greeter, FileWritingGreeter)
greeter = container.resolve(Greeter, path="/tmp/foo", greeting="Hello world")

# Option 2: Provide arguments at registration time
container.register(Greeter, FileWritingGreeter, path="/tmp/foo", greeting="Hello world")

Install the punq library using pip to use it in your Python projects.

pip install punq

You can register arbitrary objects using a string key or register classes to map an interface (base class) to a concrete implementation.

import punq

container = punq.Container()

# Registering an object with a string key
container.register("connection_string", instance="postgresql://...")
conn_str = container.resolve("connection_string")

# Registering a concrete implementation for an interface/base class
class ConfigReader:
    def get_config(self) -> dict[str, str]: pass

class EnvironmentConfigReader(ConfigReader):
    def get_config(self) -> dict[str, str]: return {"greeting": "Hello"}

container.register(ConfigReader, EnvironmentConfigReader)
config = container.resolve(ConfigReader).get_config()

If a service uses a string type annotation (a forward reference) in its constructor, Punq may fail to resolve it with an InvalidForwardReferenceError.

To resolve this, you can:

1. Register the dependency type in the container before registering the service that depends on it.
2. Register the dependency using the exact string name as the service key.

from dataclasses import dataclass
from punq import Container

@dataclass
class Client:
    dep: 'Dependency'  # Forward reference

container = Container()

# Option 1: Register the type first
class Dependency: pass
container.register(Dependency)
container.register(Client)

# Option 2: Register using the string key
class AlternativeDependency: pass
container.register('Dependency', AlternativeDependency)
container.register(Client)

instance = container.resolve(Client)

Punq uses the Scope enum to control the lifetime of resolved objects:

• Scope.transient (default): A fresh instance is created every time the service is resolved.
• Scope.singleton: The same instance is created once and re-used for every subsequent resolve call.

from punq import Container, Scope

container = Container()

# This will always return a new instance
container.register(MyService, scope=Scope.transient)

# This will always return the same instance
container.register(MyService, scope=Scope.singleton)

Punq automatically inspects the __init__ method of registered classes to inject required dependencies.

import punq

class ConfigReader:
    def get_config(self) -> dict[str, str]: return {"greeting": "Hello world"}

class Greeter:
    def __init__(self, config_reader: ConfigReader) -> None:
        self.config = config_reader.get_config()

    def greet(self) -> None: 
        print(self.config['greeting'])

container = punq.Container()
container.register(ConfigReader)
container.register(Greeter)

# Punq injects ConfigReader into Greeter automatically
container.resolve(Greeter).greet()

If you want to create an instance of a class that has not been explicitly registered in the container, but you still want Punq to resolve its dependencies, use Container.instantiate(service_key, **kwargs). This treats the class as a transient service for that specific call.

from punq import Container

class BirthdayNotification:
    def __init__(self, sender: EmailSender) -> None:
        self.sender = sender

container = Container()
# ... register EmailSender ...

# Instantiate without explicit registration
instance = container.instantiate(BirthdayNotification)

If you have registered multiple implementations for the same service key, use Container.resolve_all(service_type, **kwargs) to retrieve all of them as a list. This is useful for patterns like plugin systems or middleware chains where multiple authenticators or handlers need to be processed.

from punq import Container

class Authenticator:
    def matches(self, req): return False
    def authenticate(self, req): return False

class BasicAuthenticator(Authenticator): ...
class TokenAuthenticator(Authenticator): ...

container = Container()
container.register(Authenticator, BasicAuthenticator)
container.register(Authenticator, TokenAuthenticator)

def authenticate_request(container, req):
    # Returns all registered Authenticator instances
    for authn in container.resolve_all(Authenticator):
        if authn.matches(req):
            return authn.authenticate(req)