=========================================
jeni
injects annotated dependencies
jeni lets developers build applications and not e.g. web applications.
Overview
- Configure each dependency in the project (requirements.txt, config, ...).
- Write code with natural call signatures taking those dependencies as input.
- Implement a Provider for each dependency, register with an Injector.
jeni runs on Python 2.7, Python 3.2 through 3.4, and pypy.
Motivation
Write code as its meant to be written, without pegging function call signatures
to some monolithic object that only applies to a specific runtime. This is
about more than just testing. This is about composition.
jeni's design principle is to have all annotated callables usable in a context
that knows nothing about jeni. Any callable is as relevant to a fresh Python
REPL as it is to an injector.
Annotations
Annotations are implemented as decorators for Python2. In Python 3, either
decorators or function annotations can be used for injection.
Core API
annotate
Annotate a callable with a decorator to provide data for Injectors.
Intended use::
from jeni import annotate
@annotate('foo', 'bar')
def function(foo, bar):
return
An Injector
would then need to register providers for 'foo' and 'bar'
in order to apply this function; an injector with such providers can
apply the annotated function without any further information::
injector.apply(function)
To get a partially applied function, to call later::
fn = injector.partial(function)
fn()
Annotation does not alter the callable's default behavior.
Call it normally::
foo, bar = 'foo', 'bar'
function(foo, bar)
On Python 2, use decorators to annotate.
On Python 3, use either decorators or function annotations::
from jeni import annotate
@annotate
def function(foo: 'foo', bar: 'bar'):
return
Note that when using Python function annotations, all injected values
are provided as keyword arguments.
Since function annotations could be interpreted differently by
different packages, injectors do not use function.__annotations__
directly. Functions opt in by a simple @annotate
decoration. Functions with Python annotations which have not been
decorated are assumed to not be decorated for injection.
(For this reason, annotating a callable with a single note where the
note is a callable is not supported.)
Notes which are provided to annotate
(above 'foo' and 'bar') can be
any hashable object (i.e. object able to be used as a key in a dict)
and is not limited to strings. If tuples are used as notes, they must
be of length 2, and ('maybe', ...)
and ('partial', ...)
are
reserved.
Provider
Provide a single prepared dependency.
Provider.get(self, name=None)
Implement in subclass.
Annotations in the form of 'object:name'
will pass the name
value
to the get
method of the registered Provider
(in this case, the
provider registered with the Injector
to provide object
). This
get-by-name pattern is useful for providers which have a dependency
which supports lookups by key (e.g. HTTP headers or records in a
key-value store).
Provider.close(self)
By default, does nothing. Close objects as needed in subclass.
Provider close methods should not intentionally raise errors.
Specifically, if a dependency has transactions, the transaction should
be committed or rolled back before close is called, and not left as an
operation to be called during the close phase.
Provider close methods must not take an argument; an injector cannot
apply provided values on a close method since some providers may have
already been closed. If an injected value is needed for the close
method, annotate __init__
and access the value via self
.
Injector
Collects dependencies and reads annotations to inject them.
Injector.__init__(self, provide_self=False)
A subclass could take arguments, but should pass keywords to super.
An Injector subclass inherits the provider registry of its base
classes, but can override any provider by re-registering notes. When
organizing a project, create an Injector subclass to serve as the
object to register all providers. This allows for the project to have
its own namespace of registered dependencies. This registry can be
customized by further subclasses, either for injecting mocks in testing
or providing alternative dependencies in a different runtime::
from jeni import Injector as BaseInjector
class Injector(BaseInjector):
"Subclass provides namespace when registering providers."
By default, the injector does not provide itself, but will when asked::
injector = Injector(provide_self=True)
injector.get('injector')
This is useful in a context manager::
with Injector(provide_self=True) as injector:
injector.get('injector')
Annotate with note 'injector' to inject the injector.
Injector.sub(cls, *mixins_and_dicts, **values)
Create and instantiate a sub-injector.
Mixins and local value dicts can be passed in as arguments. Local
values can also be passed in as keyword arguments.
Injector.provider(cls, note, provider=None, name=False)
Register a provider, either a Provider class or a generator.
Provider class::
from jeni import Injector as BaseInjector
from jeni import Provider
class Injector(BaseInjector):
pass
@Injector.provider('hello')
class HelloProvider(Provider):
def get(self, name=None):
if name is None:
name = 'world'
return 'Hello, {}!'.format(name)
Simple generator::
@Injector.provider('answer')
def answer():
yield 42
If a generator supports get with a name argument::
@Injector.provider('spam', name=True)
def spam():
count_str = yield 'spam'
while True:
count_str = yield 'spam' * int(count_str)
Registration can be a decorator or a direct method call::
Injector.provider('hello', HelloProvider)
Injector.factory(cls, note, fn=None)
Register a function as a provider.
Function (name support is optional)::
from jeni import Injector as BaseInjector
from jeni import Provider
class Injector(BaseInjector):
pass
@Injector.factory('echo')
def echo(name=None):
return name
Registration can be a decorator or a direct method call::
Injector.factory('echo', echo)
Injector.value(cls, note, scalar)
Register a single value to be provided.
Supports base notes only, does not support get-by-name notes.
Injector.apply(self, fn, *a, **kw)
Fully apply annotated callable, returning callable's result.
Injector.partial(self, fn, *user_args, **user_kwargs)
Return function with closure to lazily inject annotated callable.
Repeat calls to the resulting function will reuse injections from the
first call.
Positional arguments are provided in this order:
- positional arguments provided by injector
- positional arguments provided in
partial_fn = partial(fn, *args)
- positional arguments provided in
partial_fn(*args)
Keyword arguments are resolved in this order (later override earlier):
- keyword arguments provided by injector
- keyword arguments provided in
partial_fn = partial(fn, **kwargs)
- keyword arguments provided in
partial_fn(**kargs)
Note that Python function annotations (in Python 3) are injected as
keyword arguments, as documented in annotate
, which affects the
argument order here.
annotate.partial
accepts arguments in same manner as this partial
.
Injector.eager_partial(self, fn, *a, **kw)
Partially apply annotated callable, returning a partial function.
By default, partial
is lazy so that injections only happen when they
are needed. Use eager_partial
in place of partial
when a guarantee
of injection is needed at the time the partially applied function is
created.
eager_partial
resolves arguments similarly to partial
but relies on
functools.partial
for argument resolution when calling the final
partial function.
Injector.apply_regardless(self, fn, *a, **kw)
Like apply
, but applies if callable is not annotated.
Injector.partial_regardless(self, fn, *a, **kw)
Like partial
, but applies if callable is not annotated.
Injector.eager_partial_regardless(self, fn, *a, **kw)
Like eager_partial
, but applies if callable is not annotated.
Injector.get(self, note)
Resolve a single note into an object.
Injector.close(self)
Close injector & injected Provider instances, including generators.
Providers are closed in the reverse order in which they were opened,
and each provider is only closed once. Providers are closed if accessed
by the injector, even if a dependency is not successfully provided. As
such, providers should determine whether or not anything needs to be
done in the close method.
Injector.enter(self)
Enter context-manager without with-block. See also: exit
.
Useful for before- and after-hooks which cannot use a with-block.
Injector.exit(self)
Exit context-manager without with-block. See also: enter
.
Additional API
annotate.wraps
Like functools.wraps
, with support for annotations.
annotate.maybe
Wrap a keyword note to record that its resolution is optional.
Normally all annotations require fulfilled dependencies, but if a
keyword argument is annotated as maybe
, then on apply, an injector
does not attempt to pass dependencies which are unset or not provided::
from jeni import annotate
@annotate('foo', bar=annotate.maybe('bar'))
def foobar(foo, bar=None):
return
annotate.partial
Wrap a note for injection of a partially applied function.
This allows for annotated functions to be injected for composition::
from jeni import annotate
@annotate('foo', bar=annotate.maybe('bar'))
def foobar(foo, bar=None):
return
@annotate('foo', annotate.partial(foobar))
def bazquux(foo, fn):
# fn: injector.partial(foobar)
return
Keyword arguments are treated as maybe
when using partial, in order
to allow partial application of only the notes which can be provided,
where the caller could then apply arguments known to be unavailable in
the injector. Note that with Python 3 function annotations, all
annotations are injected as keyword arguments.
Injections on the partial function are lazy and not applied until the
injected partial function is called. See eager_partial
to inject
eagerly.
annotate.eager_partial
Wrap a note for injection of an eagerly partially applied function.
Use this instead of partial
when eager injection is needed in place
of lazy injection.
InjectorProxy
Forwards getattr & getitem to enclosed injector.
If an injector has 'hello' registered::
from jeni import InjectorProxy
deps = InjectorProxy(injector)
deps.hello
Get by name can use dict-style access::
deps['hello:name']
License
Copyright 2013-2015 Ron DuPlain ron.duplain@gmail.com (see AUTHORS file).
Released under the BSD License (see LICENSE file).