injector 0.4.1

Provider

A means of providing an instance of a type. Built-in providers include ClassProvider (creates a new instance from a class), InstanceProvider (returns an existing instance directly) and CallableProvider (provides an instance by calling a function).

Scope

By default, providers are executed each time an instance is required. Scopes allow this behaviour to be customised. For example, SingletonScope (typically used through the class decorator singleton), can be used to always provide the same instance of a class.

Other examples of where scopes might be a threading scope, where instances are provided per-thread, or a request scope, where instances are provided per-HTTP-request.

The default scope is NoScope.

Binding Key

A binding key uniquely identifies a provider of a type. It is effectively a tuple of (type, annotation) where type is the type to be provided and annotation is additional, optional, uniquely identifying information for the type.

For example, the following are all unique binding keys for str:

(str, 'name')
(str, 'description')

For a generic type such as str, annotations are very useful for unique identification.

As an alternative convenience to using annotations, Key may be used to create unique types as necessary:

>>> from injector import Key
>>> Name = Key('name')
>>> Description = Key('description')

Which may then be used as binding keys, without annotations, as they already uniquely identify a particular provider:

(Name, None)
(Description, None)

Though of course, annotations may still be used with these types, like any other type.

Annotation

An annotation is additional unique information about a type to avoid binding key collisions. It creates a new unique binding key for an existing type.

Binding

A binding is the mapping of a unique binding key to a corresponding provider. For example:

>>> from injector import InstanceProvider
>>> bindings = {
...   (Name, None): InstanceProvider('Sherlock'),
...   (Description, None): InstanceProvider('A man of astounding insight')}
... }

Binder

The Binder is simply a convenient wrapper around the dictionary that maps types to providers. It provides methods that make declaring bindings easier.

Module

A Module configures bindings. It provides methods that simplify the process of binding a key to a provider. For example the above bindings would be created with:

>>> from injector import Module
>>> class MyModule(Module):
...     def configure(self, binder):
...         binder.bind(Name, to='Sherlock')
...         binder.bind(Description, to='A man of astounding insight')

For more complex instance construction, methods decorated with @provides will be called to resolve binding keys:

>>> from injector import provides
>>> class MyModule(Module):
...     def configure(self, binder):
...         binder.bind(Name, to='Sherlock')
...
...     @provides(Description)
...     def describe(self):
...         return 'A man of astounding insight (at %s)' % time.time()

Injection

Injection is the process of providing an instance of a type, to a method that uses that instance. It is achieved with the inject decorator. Keyword arguments to inject define which arguments in its decorated method should be injected, and with what.

Here is an example of injection on a module provider method, and on the constructor of a normal class:

>>> from injector import inject
>>> class User(object):
...     @inject(name=Name, description=Description)
...     def __init__(self, name, description):
...         self.name = name
...         self.description = description

>>> class UserModule(Module):
...     def configure(self, binder):
...        binder.bind(User)

>>> class UserAttributeModule(Module):
...     def configure(self, binder):
...         binder.bind(Name, to='Sherlock')
...
...     @provides(Description)
...     @inject(name=Name)
...     def describe(self, name):
...         return '%s is a man of astounding insight' % name

Injector

The Injector brings everything together. It takes a list of Module s, and configures them with a binder, effectively creating a dependency graph:

>>> from injector import Injector
>>> injector = Injector([UserModule(), UserAttributeModule()])

The injector can then be used to acquire instances of a type, either directly:

>>> injector.get(Name)
'Sherlock'
>>> injector.get(Description)
'Sherlock is a man of astounding insight'

Or transitively:

>>> user = injector.get(User)
>>> isinstance(user, User)
True
>>> user.name
'Sherlock'
>>> user.description
'Sherlock is a man of astounding insight'

Singletons

Singletons are declared by binding them in the SingletonScope. This can be done in three ways:

1. Decorating the class with @singleton.

2. Decorating a @provides(X) decorated Module method with @singleton.

3. Explicitly calling binder.bind(X, scope=singleton).

A (redunant) example showing all three methods:

>>> @singleton
... class Thing(object): pass
>>> class ThingModule(Module):
...   def configure(self, binder):
...     binder.bind(Thing, scope=singleton)
...   @singleton
...   @provides(Thing)
...   def provide_thing(self):
...     return Thing()

Implementing new Scopes

In the above description of scopes, we glossed over a lot of detail. In particular, how one would go about implementing our own scopes.

Basically, there are two steps. First, subclass Scope and implement Scope.get:

>>> from injector import Scope
>>> class CustomScope(Scope):
...   def get(self, key, provider):
...     return provider

Then create a global instance of ScopeDecorator to allow classes to be easily annotated with your scope:

>>> from injector import ScopeDecorator
>>> customscope = ScopeDecorator(CustomScope)

This can be used like so:

>>> @customscope
... class MyClass(object):
...   pass

Scopes are bound in modules with the Binder.bind_scope method:

>>> class MyModule(Module):
...   def configure(self, binder):
...     binder.bind_scope(CustomScope)

Scopes can be retrieved from the injector, as with any other instance. They are singletons across the life of the injector:

>>> injector = Injector([MyModule()])
>>> injector.get(CustomScope) is injector.get(CustomScope)
True

For scopes with a transient lifetime, such as those tied to HTTP requests, the usual solution is to use a thread or greenlet-local cache inside the scope. The scope is “entered” in some low-level code by calling a method on the scope instance that creates this cache. Once the request is complete, the scope is “left” and the cache cleared.