Metadata-Version: 1.1
Name: jeni
Version: 0.3.4
Summary: jeni injects annotated dependencies
Home-page: https://github.com/rduplain/jeni-python
Author: Ron DuPlain
Author-email: ron.duplain@gmail.com
License: BSD
Description: 
        =========================================
         ``jeni`` injects annotated dependencies
        =========================================
        
        **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
        
        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)``
        ---------------------------
        
        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, *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:
        
        1. positional arguments provided by injector
        2. positional arguments provided in `partial_fn = partial(fn, *args)`
        3. positional arguments provided in `partial_fn(*args)`
        
        Keyword arguments are resolved in this order (later override earlier):
        
        1. keyword arguments provided by injector
        2. keyword arguments provided in `partial_fn = partial(fn, **kwargs)`
        3. 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 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.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
        
        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-2014 Ron DuPlain <ron.duplain@gmail.com> (see AUTHORS file).
        
        Released under the BSD License (see LICENSE file).
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.2
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Utilities
Classifier: Topic :: Software Development :: Libraries :: Python Modules
