punq 0.4.1

Installation

Punq is available on the cheese shop.

pip install punq

Documentation is available on Read the docs.

Quick Start

Punq avoids global state, so you must explicitly create a container in the entrypoint of your application:

import punq

container = punq.Container()

Once you have a container, you can register your application’s dependencies. In the simplest case, we can register any arbitrary object with some key:

container.register("connection_string", "postgresql://...")

We can then request that object back from the container:

conn_str = container.resolve("connection_string")

Usually, though, we want to register some object that implements a useful service.:

class ConfigReader:
   def get_config(self):
      pass

class EnvironmentConfigReader(ConfigReader):
   def get_config(self):
      return {
         "logging": {
            "level": os.env.get("LOGGING_LEVEL", "debug")
         }
         "greeting": os.env.get("GREETING", "Hello world")
      }

container.register(ConfigReader, EnvironmentConfigReader)

Now we can resolve the ConfigReader service, and receive a concrete implementation:

config = container.resolve(ConfigReader).get_config()

If our application’s dependencies have their own dependencies, Punq will inject those, too:

class Greeter:
   def greet(self):
      pass


class ConsoleGreeter:
   def __init__(self, config_reader: ConfigReader):
      self.config = config_reader.get_config()

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


container.register(Greeter)
container.resolve(Greeter).greet()

If you just want to resolve an object without having any base class, that’s okay:

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

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

container.register(Greeter)
container.resolve(Greeter).greet()

And if you need to have a singleton object for some reason, we can tell punq to register a specific instance of an object:

class FileWritingGreeter:
   def __init__(self, path, greeting):
      self.path = path
      self.message = greeting
      self.file = open(self.path, 'w')

   def greet(self):
      self.file.write(self.message)


one_true_greeter = FileWritingGreeter("/tmp/greetings", "Hello world")
container.register(Greeter, instance=one_true_greeter)

You might not know all of your arguments at registration time, but you can provide them later:

container.register(Greeter, FileWritingGreeter)
greeter = container.resolve(Greeter, path="/tmp/foo", greeting="Hello world")

Conversely, you might want to provide arguments at registration time, without adding them to the container:

container.register(Greeter, FileWritingGreeter, path="/tmp/foo", greeting="Hello world")

Fuller documentation is available on Read the docs.

0.4.1 2020-02-01

The container now includes itself as a dependency. This makes some funky use-cases simple to implement, eg. dynamic dispatch to multiple implementations.

0.4.0 2020-02-01

Punq now supports registering implementations as singleton. Singleton instances are cached per-container, and instantiation is lazy, ie. we defer creation until we first resolve the service. Hat tip to jbcpollak

0.3.0 2019-07-13

Fixes

Punq only passes required arguments to nested dependencies. Previously, we would pass all the arguments in our context as kwargs, which caused unintuitive failures if constructors weren’t expecting them. Fixed by Thielen B

0.2.1 2019-05-22

Fixes

Punq will now prefer to use a provided resolution argument instead of creating it anew.

0.2.0 2019-02-12

Fixes

Added handling for typing.ForwardRef

Breaking Changes

Added explicit instance kwarg to register which replaces the previous behaviour where container.register(Service, someInstance) would register a concrete instance. This fixes https://github.com/bobthemighty/punq/issues/6

0.1.2-alpha 2019-02-11

Feature

First automatic Travis deploy

0.0.1

Basic resolution and registration works Punq is almost certainly slow as a dog, non thread-safe, and prone to weird behaviour in the edge cases.