Skip to main content

jeni injects annotated dependencies

Project description

jeni lets developers build applications and not e.g. web applications.

Overview

  1. Configure each dependency in the project (requirements.txt, config, …).

  2. Write code with natural call signatures taking those dependencies as input.

  3. 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

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.

Injector

Collects dependencies and reads annotations to inject them.

Injector.__init__(self)

An Injector could take arguments to init, but this base does not.

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."

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, *a, **kw)

Partially apply annotated callable, returning a partial function.

Injector.apply_regardless(self, fn, *a, **kw)

Like apply, but applies even if callable is not annotated.

Injector.partial_regardless(self, fn, *a, **kw)

Like partial, but applies even 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.

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.

Providers are closed in the reverse order in which they were opened, and each provider is only closed once. Providers are only closed if they have successfully provided a dependency via get.

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.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 an injector does not pass unset dependencies on apply:

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

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-2014 Ron DuPlain <ron.duplain@gmail.com> (see AUTHORS file).

Released under the BSD License (see LICENSE file).

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

jeni-0.3.1.zip (24.0 kB view hashes)

Uploaded Source

jeni-0.3.1.tar.bz2 (13.5 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page