antidote 0.5.0

Transparent dependency injection.

Antidotes is a declarative dependency injection micro-framework for Python 3.5+ which tries to do the following :

• Injection can be added anywhere easily, no need to use anything else than decorators except for advanced features.

• It should be easy to find where dependencies are instantiated from any point in the code where they’re injected.

• Easily extendable to support any kind of dependencies.

• Testing injected objects must be easy.

• Catch as much errors as it can.

• Limit performance impact of injection.

Why ?

In short antidote avoids you the hassle of instantiating and managing your services. You declare them at their definition, and inject them wherever needed with simple decorators, which do not change how you interact with your objects. Unit testing is not impacted as one can override any injection and control the available dependencies easily.

For the longer version: https://antidote.readthedocs.io/en/stable/why.html

Features Highlight

• Services, factories, resources (configuration typically), tags, auto-wiring…

• Dependencies bound through type hints and optionally from variable names and/or mapping.

• Integrates well with any code, injected functions can be called as usual with all their arguments.

• Thread-safe and limited performance impact (see injection benchmark).

• Dependency cycle detection.

• Easily extendable to support any kind of dependencies.

• Integration with the attrs package through the antidote_attrs package.

Installation

To install Antidote, simply run this command:

pip install antidote

In order to install the cython version, you’ll need to install the following first (This should be better in the near future):

pip install cython fastrlock

Quick Start

Let’s suppose you have database class from an external library and you wrap it with a custom class for easier usage. Antidote can do all the wiring for you:

import antidote


class Database:
    """
    Class from an external library.
    """
    def __init__(self, *args, **kwargs):
        """ Initializes the database. """

# Usage of constants for configuration makes refactoring easier and is
# less error-prone. Moreover Conf will only be instantiated if necessary.
class Conf(metaclass=antidote.LazyConfigurationMeta):
    DB_HOST = 'db.host'
    DB_USER = 'db.user'
    DB_PORT = 'db.port'
    DB_PASSWORD = 'db.password'

    def __init__(self):
        # Load configuration from somewhere
        self._raw_conf = {
            'db.host': 'host',
            'db.user': 'user',
            'db.port': 5432,
            'db.password': 'password'
        }

    def __call__(self, key):
        return self._raw_conf[key]


# Declare a factory which should be called to instantiate Database.
# The order of the arguments is here used to map the dependencies.
# A dictionary mapping arguments name to their dependency could also
# have been used.
@antidote.factory(dependencies=(Conf.DB_HOST, Conf.DB_PORT,
                                Conf.DB_USER, Conf.DB_PASSWORD))
def database_factory(host: str, port: int, user: str, password: str) -> Database:
    """
    Configure your database.
    """
    return Database(host=host, port=port, user=user, password=password)

# Declare DatabaseWrapper as a service to be injected.
@antidote.register
class DatabaseWrapper:
    """
    Your class to manage the database.
    """

    # Dependencies of __init__() are injected by default when
    # registering a service.
    def __init__(self, db: Database):
        self.db = db


@antidote.inject
def f(db: DatabaseWrapper):
    """ Do something with your database. """

# Can be called without arguments now.
f()

# You can still explicitly pass the arguments to override
# injection.
conf = Conf()
f(DatabaseWrapper(database_factory(
    host=conf.DB_HOST,  # equivalent to conf._raw_conf['db.host']
    port=conf._raw_conf['db.port'],
    user=conf._raw_conf['db.user'],
    password=conf._raw_conf['db.password']
)))

Documentation

The documentation is available at https://antidote.readthedocs.io/en/stable.

Injection benchmark is available at injection benchmarks.

Bug Reports / Feature Requests

Any feedback is always welcome, feel free to submit issues and enhancement requests ! :) For any questions, open an issue on Github.

How to Contribute

1. Check for open issues or open a fresh issue to start a discussion around a feature or a bug.

2. Fork the repo on GitHub. Run the tests to confirm they all pass on your machine. If you cannot find why it fails, open an issue.

3. Start making your changes to the master branch.

4. Writes tests which shows that your code is working as intended. (This also means 100% coverage.)

5. Send a pull request.

Be sure to merge the latest from “upstream” before making a pull request!

Pull requests should avoid to:

• make it harder to integrate Antidote into existing code.

• break backwards compatibility.

• create features difficult to understand for an IDE, such as converting a string dependency id to a non singleton object somehow. An user may do this, but antidote shouldn’t.

Pull requests will not be accepted if:

• classes and non trivial functions have not docstrings documenting their behavior.

• tests do not cover all of code changes.

Do not hesitate to send a pull request, even if incomplete, to get early feedback ! :)