andi


Nameandi JSON
Version 0.6.0 PyPI version JSON
download
home_pagehttps://github.com/scrapinghub/andi
SummaryLibrary for annotation-based dependency injection
upload_time2023-12-26 12:47:25
maintainer
docs_urlNone
authorMikhail Korobov
requires_python>=3.8.1
license
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage
            ====
andi
====

.. image:: https://img.shields.io/pypi/v/andi.svg
   :target: https://pypi.python.org/pypi/andi
   :alt: PyPI Version

.. image:: https://img.shields.io/pypi/pyversions/andi.svg
   :target: https://pypi.python.org/pypi/andi
   :alt: Supported Python Versions

.. image:: https://github.com/scrapinghub/andi/workflows/tox/badge.svg
   :target: https://github.com/scrapinghub/andi/actions
   :alt: Build Status

.. image:: https://codecov.io/github/scrapinghub/andi/coverage.svg?branch=master
   :target: https://codecov.io/gh/scrapinghub/andi
   :alt: Coverage report

``andi`` makes easy implementing custom dependency injection mechanisms
where dependencies are expressed using type annotations.

``andi`` is useful as a building block for frameworks, or as a library
which helps to implement dependency injection (thus the name -
ANnotation-based Dependency Injection).

License is BSD 3-clause.

Installation
============

::

    pip install andi

andi requires Python >= 3.8.1.

Goal
====

See the following classes that represents parts of a car
(and the car itself):

.. code-block:: python

    class Valves:
        pass

    class Engine:
        def __init__(self, valves):
            self.valves = valves

    class Wheels:
        pass

    class Car:
        def __init__(self, engine, wheels):
            self.engine = engine
            self.wheels = wheels

The following would be the usual way of build a ``Car`` instance:

.. code-block:: python

    valves = Valves()
    engine = Engine(valves)
    wheels = Wheels()
    car = Car(engine, wheels)

There are some dependencies between the classes: A car requires
and engine and wheels to be built, as well as the engine requires
valves. These are the car dependencies and sub-dependencies.

The question is, could we have an automatic way of building instances?
For example, could we have a ``build`` function that
given the ``Car`` class or any other class would return an instance
even if the class itself has some other dependencies?

.. code-block:: python

    car = build(Car)  # Andi helps creating this generic build function

``andi`` inspect the dependency tree and creates a plan making easy creating
such a ``build`` function.

This is how this plan for the ``Car`` class would looks like:

1. Invoke ``Valves`` with empty arguments
2. Invoke ``Engine`` using the instance created in 1 as the argument ``valves``
3. Invoke ``Wheels`` with empty arguments
4. Invoke ``Cars`` with the instance created in 2 as the ``engine`` argument and with
   the instance created in 3 as the ``wheels`` argument

Type annotations
----------------

But there is a missing piece in the Car example before. How can
``andi`` know that the class ``Valves`` is required to build the
argument ``valves``? A first idea would be to use the argument
name as a hint for the class name
(as `pinject <https://pypi.org/project/pinject/>`_ does),
but ``andi`` opts to rely on arguments' type annotations instead.

The classes for ``Car`` should then be rewritten as:

.. code-block:: python

    class Valves:
        pass

    class Engine:
        def __init__(self, valves: Valves):
            self.valves = valves

    class Wheels:
        pass

    class Car:
        def __init__(self, engine: Engine, wheels: Wheels):
            self.engine = engine
            self.wheels = wheels

Note how now there is a explicit annotation stating that the
``valves`` argument is of type ``Valves``
(same for ``engine`` and ``wheels``).

The ``andi.plan`` function can now create a plan to build the
``Car`` class (ignore the ``is_injectable`` parameter by now):

.. code-block:: python

    plan = andi.plan(Car, is_injectable={Engine, Wheels, Valves})


This is what the ``plan`` variable contains:

.. code-block:: python

    [(Valves, {}),
     (Engine, {'valves': Valves}),
     (Wheels, {}),
     (Car,    {'engine': Engine,
               'wheels': Wheels})]

Note how this plan correspond exactly to the 4-steps plan described
in the previous section.

Building from the plan
----------------------

Creating a generic function to build the instances from
a plan generated by ``andi`` is then very easy:

.. code-block:: python

    def build(plan):
        instances = {}
        for fn_or_cls, kwargs_spec in plan:
            instances[fn_or_cls] = fn_or_cls(**kwargs_spec.kwargs(instances))
        return instances

So let's see putting all the pieces together. The following code
creates an instance of ``Car`` using ``andi``:

.. code-block:: python

    plan = andi.plan(Car, is_injectable={Engine, Wheels, Valves})
    instances = build(plan)
    car = instances[Car]

is_injectable
-------------

It is not always desired for ``andi`` to manage every single annotation found.
Instead is usually better to explicitly declare which types
can be handled by ``andi``. The argument ``is_injectable``
allows to customize this feature.

``andi`` will raise an error on the presence of a dependency that cannot be resolved
because it is not injectable.

Usually is desirable to declare injectabilty by
creating a base class to inherit from. For example,
we could create a base class ``Injectable`` as base
class for the car components:

.. code-block:: python

    class Injectable(ABC):
        pass

    class Valves(Injectable):
        pass

    class Engine(Injectable):
        def __init__(self, valves: Valves):
            self.valves = valves

    class Wheels(Injectable):
        pass

The call to ``andi.plan`` would then be:

.. code-block:: python

    is_injectable = lambda cls: issubclass(cls, Injectable)
    plan = andi.plan(Car, is_injectable=is_injectable)

Functions and methods
---------------------

Dependency injection is also very useful when applied to functions.
Imagine that you have a function ``drive`` that drives the ``Car``
through the ``Road``:

.. code-block:: python

    class Road(Injectable):
        ...

    def drive(car: Car, road: Road, speed):
        ... # Drive the car through the road

The dependencies has to be resolved before invoking
the ``drive`` function:

.. code-block:: python

    plan = andi.plan(drive, is_injectable=is_injectable)
    instances = build(plan.dependencies)

Now the ``drive`` function can be invoked:

.. code-block:: python

    drive(instances[Car], instances[Road], 100)

Note that ``speed`` argument was not annotated. The resultant plan just won't include it
because the ``andi.plan`` ``full_final_kwargs`` parameter is ``False``
by default. Otherwise, an exception would have been raised (see ``full_final_kwargs`` argument
documentation for more information).

An alternative and more generic way to invoke the drive function
would be:

.. code-block:: python

    drive(speed=100, **plan.final_kwargs(instances))

dataclasses and attrs
---------------------

``andi`` supports classes defined using `attrs <https://www.attrs.org/>`_
and also `dataclasses <https://docs.python.org/3/library/dataclasses.html>`_.
For example the ``Car`` class could have been defined as:

.. code-block:: python

    # attrs class example
    @attr.s(auto_attribs=True)
    class Car:
        engine: Engine
        wheels: Wheels

    # dataclass example
    @dataclass
    class Car(Injectable):
        engine: Engine
        wheels: Wheels

Using ``attrs`` or ``dataclass`` is handy because they avoid
some boilerplate.

Externally provided dependencies
--------------------------------

Retaining the control over object instantiation
could be desired in some cases. For example creating
a database connection could require accessing some
credentials registry or getting the connection from a pool
so you might want to control building
such instances outside of the regular
dependency injection mechanism.

``andi.plan`` allows to specify which types would be
externally provided. Let's see an example:

.. code-block:: python

    class DBConnection(ABC):

        @abstractmethod
        def getConn():
            pass

    @dataclass
    class UsersDAO:
        conn: DBConnection

        def getUsers():
           return self.conn.query("SELECT * FROM USERS")

``UsersDAO`` requires a database connection to run queries.
But the connection will be provided externally from a pool, so we
call then ``andi.plan`` using also the ``externally_provided``
parameter:

.. code-block:: python

    plan = andi.plan(UsersDAO, is_injectable=is_injectable,
                     externally_provided={DBConnection})

The build method should then be modified slightly to be able
to inject externally provided instances:

.. code-block:: python

    def build(plan, instances_stock=None):
        instances_stock = instances_stock or {}
        instances = {}
        for fn_or_cls, kwargs_spec in plan:
            if fn_or_cls in instances_stock:
                instances[fn_or_cls] = instances_stock[fn_or_cls]
            else:
                instances[fn_or_cls] = fn_or_cls(**kwargs_spec.kwargs(instances))
        return instances

Now we are ready to create ``UserDAO`` instances with ``andi``:

.. code-block:: python

    plan = andi.plan(UsersDAO, is_injectable=is_injectable,
                     externally_provided={DBConnection})
    dbconnection = DBPool.get_connection()
    instances = build(plan.dependencies, {DBConnection: dbconnection})
    users_dao = instances[UsersDAO]
    users = user_dao.getUsers()

Note that being injectable is not required for externally provided
dependencies.

Optional
--------

``Optional`` type annotations can be used in case of
dependencies that can be optional. For example:

.. code-block:: python

    @dataclass
    class Dashboard:
        conn: Optional[DBConnection]

        def showPage():
            if self.conn:
                self.conn.query("INSERT INTO VISITS ...")
            ...  # renders a HTML page

In this example, the ``Dashboard`` class generates a HTML page to be served, and
also stores the number of visits into a database. Database
could be absent in some environments, but you might want
the dashboard to work even if it cannot log the visits.

When a database connection is possible the plan call would be:

.. code-block:: python

    plan = andi.plan(UsersDAO, is_injectable=is_injectable,
                     externally_provided={DBConnection})


And the following when the connection is absent:

.. code-block:: python

    plan = andi.plan(UsersDAO, is_injectable=is_injectable,
                     externally_provided={})

It is also required to register the type of ``None``
as injectable. Otherwise ``andi.plan`` with raise an exception
saying that "NoneType is not injectable".

.. code-block:: python

    Injectable.register(type(None))

Union
-----

``Union`` can also be used to express alternatives. For example:

.. code-block:: python

    @dataclass
    class UsersDAO:
        conn: Union[ProductionDBConnection, DevelopmentDBConnection]

``DevelopmentDBConnection`` will be injected in the absence of
``ProductionDBConnection``.

Annotated
---------

On Python 3.9+ ``Annotated`` type annotations can be used to attach arbitrary
metadata that will be preserved in the plan. Occurrences of the same type
annotated with different metadata will not be considered duplicates. For
example:

.. code-block:: python

    @dataclass
    class Dashboard:
        conn_main: Annotated[DBConnection, "main DB"]
        conn_stats: Annotated[DBConnection, "stats DB"]

The plan will contain both dependencies.

Custom builders
---------------

Sometimes a dependency can't be created directly but needs some additional code
to be built. And that code can also have its own dependencies:

.. code-block:: python

    class Wheels:
        pass

    def wheel_factory(wheel_builder: WheelBuilder) -> Wheels:
        return wheel_builder.get_wheels()

As by default ``andi`` can't know how to create a ``Wheels`` instance or that
the plan needs to create a ``WheelBuilder`` instance first, it needs to be told
this with a ``custom_builder_fn`` argument:

.. code-block:: python

    custom_builders = {
        Wheels: wheel_factory,
    }

    plan = andi.plan(Car, is_injectable={Engine, Wheels, Valves},
                     custom_builder_fn=custom_builders.get,
                     )

``custom_builder_fn`` should be a function that takes a type and returns a factory
for that type.

The build code also needs to know how to build ``Wheels`` instances. A plan step
for an object built with a custom builder uses an instance of the ``andi.CustomBuilder``
wrapper that contains the type to be built in the ``result_class_or_fn`` attribute and
the callable for building it in the ``factory`` attribute:

.. code-block:: python

    from andi import CustomBuilder

    def build(plan):
        instances = {}
        for fn_or_cls, kwargs_spec in plan:
            if isinstance(fn_or_cls, CustomBuilder):
                instances[fn_or_cls.result_class_or_fn] = fn_or_cls.factory(**kwargs_spec.kwargs(instances))
            else:
                instances[fn_or_cls] = fn_or_cls(**kwargs_spec.kwargs(instances))
        return instances

Full final kwargs mode
-------------------------

By default ``andi.plan`` won't fail if it is not able to provide
some of the direct dependencies for the given input (see the
``speed`` argument in one of the examples above).

This behaviour is desired when inspecting functions
for which is already known that some arguments won't be
injectable but they will be provided by other means
(like the ``drive`` function above).

But in other cases is better to be sure that all dependencies
are fulfilled and otherwise fail. Such is the case for classes.
So it is recommended to set ``full_final_kwargs=True`` when invoking
``andi.plan`` for classes.

Overrides
---------

Let's go back to the ``Car`` example. Imagine you want to build a car again.
But this time you want to replace the ``Engine`` because this is
going to be an electric car!. And of course, an electric engine contains a battery
and have no valves at all. This could be the new ``Engine``:

.. code-block:: python

    class Battery:
        pass

    class ElectricEngine(Engine):

        def __init__(self, battery: Battery):
            self.battery = valves

Andi offers the possibility to replace dependencies when planning,
and this is what is required to build the electric car: we need
to replace any dependency on ``Engine`` by a dependency on ``ElectricEngine``.
This is exactly what overrides offers. Let's see how ``plan`` should
be invoked in this case:

.. code-block:: python

    plan = andi.plan(Car, is_injectable=is_injectable,
                     overrides={Engine: ElectricEngine}.get)

Note that Andi will unroll the new dependencies properly. That is,
``Valves`` and ``Engine`` won't be in the resultant plan but
``ElectricEngine`` and ``Battery`` will.

In summary, overrides offers a way to override the default
dependencies anywhere in the tree, changing them with an
alternative one.

By default overrides are not recursive: overrides aren't applied
over the children of an already overridden dependency. There
is flag to turn recursion on if this is what is desired.
Check ``andi.plan`` documentation for more information.

Why type annotations?
---------------------

``andi`` uses type annotations to declare dependencies (inputs).
It has several advantages, and some limitations as well.

Advantages:

1. Built-in language feature.
2. You're not lying when specifying a type - these
   annotations still work as usual type annotations.
3. In many projects you'd annotate arguments anyways, so ``andi`` support
   is "for free".

Limitations:

1. Callable can't have two arguments of the same type.
2. This feature could possibly conflict with regular type annotation usages.

If your callable has two arguments of the same type, consider making them
different types. For example, a callable may receive url and html of
a web page:

.. code-block:: python

    def parse(html: str, url: str):
        # ...

To make it play well with ``andi``, you may define separate types for url
and for html:

.. code-block:: python

    class HTML(str):
        pass

    class URL(str):
        pass

    def parse(html: HTML, url: URL):
        # ...

This is more boilerplate though.

Why doesn't andi handle creation of objects?
--------------------------------------------

Currently ``andi`` just inspects callable and chooses best concrete types
a framework needs to create and pass to a callable, without prescribing how
to create them. This makes ``andi`` useful in various contexts - e.g.

* creation of some objects may require asynchronous functions, and it
  may depend on libraries used (asyncio, twisted, etc.)
* in streaming architectures (e.g. based on Kafka) inspection may happen
  on one machine, while creation of objects may happen on different nodes
  in a distributed system, and then actually running a callable may happen on
  yet another machine.

It is hard to design API with enough flexibility for all such use cases.
That said, ``andi`` may provide more helpers in future,
once patterns emerge, even if they're useful only in certain contexts.

Examples: callback based frameworks
-----------------------------------

Spider example
**************

Nothing better than a example to understand how ``andi`` can be useful.
Let's imagine you want to implemented a callback based framework
for writing spiders to crawl web pages.

The basic idea is that there is framework in which the user
can write spiders. Each spider is a collection of callbacks
that can process data from a page, emit extracted data or request new
pages. Then, there is an engine that takes care of downloading
the web pages
and invoking the user defined callbacks, chaining requests
with its corresponding callback.

Let's see an example of an spider to download recipes
from a cooking page:

.. code-block:: python

    class MySpider(Spider):
        start_url = "htttp://a_page_with_a_list_of_recipes"

        def parse(self, response):
            for url in recipes_urls_from_page(response)
                yield Request(url, callback=parse_recipe)

        def parse_recipe(self, response):
            yield extract_recipe(response)


It would be handy if the user can define some requirements
just by annotating parameters in the callbacks. And ``andi`` make it
possible.

For example, a particular callback could require access to the cookies:

.. code-block:: python

    def parse(self, response: Response, cookies: CookieJar):
        # ... Do something with the response and the cookies

In this case, the engine can use ``andi`` to inspect the ``parse`` method, and
detect that ``Response`` and ``CookieJar`` are required.
Then the framework will build them and will invoke the callback.

This functionality would serve to inject into the users callbacks
some components only when they are required.

It could also serve to encapsulate better the user code. For
example, we could just decouple the recipe extraction into
it's own class:

.. code-block:: python

    @dataclass
    class RecipeExtractor:
        response: Response

        def to_item():
            return extract_recipe(self.response)

The callback could then be defined as:

.. code-block:: python

        def parse_recipe(extractor: RecipeExtractor):
            yield extractor.to_item()

Note how handy is that with ``andi`` the engine can create
an instance of ``RecipesExtractor`` feeding it with the
declared ``Response`` dependency.

In definitive, using ``andi`` in such a framework
can provide great flexibility to the user
and reduce boilerplate.

Web server example
******************

``andi`` can be useful also for implementing a new
web framework.

Let's imagine a framework where you can declare your sever in a
class like the following:

.. code-block:: python

    class MyWeb(Server):

        @route("/products")
        def productspage(self, request: Request):
            ... # return the composed page

        @route("/sales")
        def salespage(self, request: Request):
            ... # return the composed page

The former case is composed of two endpoints, one for serving
a page with a summary of sales, and a second one to serve
the products list.

Connection to the database can be required
to sever these pages. This logic could be encapsulated
in some classes:

.. code-block:: python

    @dataclass
    class Products:
        conn: DBConnection

        def get_products()
            return self.conn.query("SELECT ...")

    @dataclass
    class Sales:
        conn: DBConnection

        def get_sales()
            return self.conn.query("SELECT ...")

Now ``productspage`` and ``salespage`` methods can just declare
that they require these objects:

.. code-block:: python

    class MyWeb(Server):

        @route("/products")
        def productspage(self, request: Request, products: Products):
            ... # return the composed page

        @route("/sales")
        def salespage(self, request: Request, sales: Sales):
            ... # return the composed page

And the framework can then be responsible to fulfill these
dependencies. The flexibility offered would be a great advantage.
As an example, if would be very easy to create a page that requires
both sales and products:

.. code-block:: python

        @route("/overview")
        def productspage(self, request: Request,
                         products: Products, sales: Sales):
            ... # return the composed overview page


Contributing
============

* Source code: https://github.com/scrapinghub/andi
* Issue tracker: https://github.com/scrapinghub/andi/issues

Use tox_ to run tests with different Python versions::

    tox

The command above also runs type checks; we use mypy.

.. _tox: https://tox.readthedocs.io


Changes
=======

0.6.0 (2023-12-26)
------------------

* Drop support for Python 3.5-3.7.
* Add support for dependencies that need to be built using custom callables.

0.5.0 (2023-12-12)
------------------

* Add support for dependency metadata via ``typing.Annotated`` (requires
  Python 3.9+).
* Add docs for overrides.
* Add support for Python 3.10-3.12.
* CI improvements.

0.4.1 (2021-02-11)
------------------

* Overrides support in ``andi.plan``

0.4.0 (2020-04-23)
------------------

* ``andi.inspect`` can handle classes now (their ``__init__`` method
  is inspected)
* ``andi.plan`` and ``andi.inspect`` can handle objects which are
  callable via ``__call__`` method.

0.3.0 (2020-04-03)
------------------

* ``andi.plan`` function replacing ``andi.to_provide``.
* Rewrite README explaining the new approach based in ``plan`` method.
* ``andi.inspect`` return non annotated arguments also.

0.2.0 (2020-02-14)
------------------

* Better attrs support (workaround issue with string type annotations).
* Declare Python 3.8 support.
* More tests; ensure dataclasses support.

0.1 (2019-08-28)
----------------

Initial release.

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/scrapinghub/andi",
    "name": "andi",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.8.1",
    "maintainer_email": "",
    "keywords": "",
    "author": "Mikhail Korobov",
    "author_email": "kmike84@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/0b/91/15758f49c921b11e03e5e0da15392ef156f942e7aec3e010d4bf3c9b9366/andi-0.6.0.tar.gz",
    "platform": null,
    "description": "====\nandi\n====\n\n.. image:: https://img.shields.io/pypi/v/andi.svg\n   :target: https://pypi.python.org/pypi/andi\n   :alt: PyPI Version\n\n.. image:: https://img.shields.io/pypi/pyversions/andi.svg\n   :target: https://pypi.python.org/pypi/andi\n   :alt: Supported Python Versions\n\n.. image:: https://github.com/scrapinghub/andi/workflows/tox/badge.svg\n   :target: https://github.com/scrapinghub/andi/actions\n   :alt: Build Status\n\n.. image:: https://codecov.io/github/scrapinghub/andi/coverage.svg?branch=master\n   :target: https://codecov.io/gh/scrapinghub/andi\n   :alt: Coverage report\n\n``andi`` makes easy implementing custom dependency injection mechanisms\nwhere dependencies are expressed using type annotations.\n\n``andi`` is useful as a building block for frameworks, or as a library\nwhich helps to implement dependency injection (thus the name -\nANnotation-based Dependency Injection).\n\nLicense is BSD 3-clause.\n\nInstallation\n============\n\n::\n\n    pip install andi\n\nandi requires Python >= 3.8.1.\n\nGoal\n====\n\nSee the following classes that represents parts of a car\n(and the car itself):\n\n.. code-block:: python\n\n    class Valves:\n        pass\n\n    class Engine:\n        def __init__(self, valves):\n            self.valves = valves\n\n    class Wheels:\n        pass\n\n    class Car:\n        def __init__(self, engine, wheels):\n            self.engine = engine\n            self.wheels = wheels\n\nThe following would be the usual way of build a ``Car`` instance:\n\n.. code-block:: python\n\n    valves = Valves()\n    engine = Engine(valves)\n    wheels = Wheels()\n    car = Car(engine, wheels)\n\nThere are some dependencies between the classes: A car requires\nand engine and wheels to be built, as well as the engine requires\nvalves. These are the car dependencies and sub-dependencies.\n\nThe question is, could we have an automatic way of building instances?\nFor example, could we have a ``build`` function that\ngiven the ``Car`` class or any other class would return an instance\neven if the class itself has some other dependencies?\n\n.. code-block:: python\n\n    car = build(Car)  # Andi helps creating this generic build function\n\n``andi`` inspect the dependency tree and creates a plan making easy creating\nsuch a ``build`` function.\n\nThis is how this plan for the ``Car`` class would looks like:\n\n1. Invoke ``Valves`` with empty arguments\n2. Invoke ``Engine`` using the instance created in 1 as the argument ``valves``\n3. Invoke ``Wheels`` with empty arguments\n4. Invoke ``Cars`` with the instance created in 2 as the ``engine`` argument and with\n   the instance created in 3 as the ``wheels`` argument\n\nType annotations\n----------------\n\nBut there is a missing piece in the Car example before. How can\n``andi`` know that the class ``Valves`` is required to build the\nargument ``valves``? A first idea would be to use the argument\nname as a hint for the class name\n(as `pinject <https://pypi.org/project/pinject/>`_ does),\nbut ``andi`` opts to rely on arguments' type annotations instead.\n\nThe classes for ``Car`` should then be rewritten as:\n\n.. code-block:: python\n\n    class Valves:\n        pass\n\n    class Engine:\n        def __init__(self, valves: Valves):\n            self.valves = valves\n\n    class Wheels:\n        pass\n\n    class Car:\n        def __init__(self, engine: Engine, wheels: Wheels):\n            self.engine = engine\n            self.wheels = wheels\n\nNote how now there is a explicit annotation stating that the\n``valves`` argument is of type ``Valves``\n(same for ``engine`` and ``wheels``).\n\nThe ``andi.plan`` function can now create a plan to build the\n``Car`` class (ignore the ``is_injectable`` parameter by now):\n\n.. code-block:: python\n\n    plan = andi.plan(Car, is_injectable={Engine, Wheels, Valves})\n\n\nThis is what the ``plan`` variable contains:\n\n.. code-block:: python\n\n    [(Valves, {}),\n     (Engine, {'valves': Valves}),\n     (Wheels, {}),\n     (Car,    {'engine': Engine,\n               'wheels': Wheels})]\n\nNote how this plan correspond exactly to the 4-steps plan described\nin the previous section.\n\nBuilding from the plan\n----------------------\n\nCreating a generic function to build the instances from\na plan generated by ``andi`` is then very easy:\n\n.. code-block:: python\n\n    def build(plan):\n        instances = {}\n        for fn_or_cls, kwargs_spec in plan:\n            instances[fn_or_cls] = fn_or_cls(**kwargs_spec.kwargs(instances))\n        return instances\n\nSo let's see putting all the pieces together. The following code\ncreates an instance of ``Car`` using ``andi``:\n\n.. code-block:: python\n\n    plan = andi.plan(Car, is_injectable={Engine, Wheels, Valves})\n    instances = build(plan)\n    car = instances[Car]\n\nis_injectable\n-------------\n\nIt is not always desired for ``andi`` to manage every single annotation found.\nInstead is usually better to explicitly declare which types\ncan be handled by ``andi``. The argument ``is_injectable``\nallows to customize this feature.\n\n``andi`` will raise an error on the presence of a dependency that cannot be resolved\nbecause it is not injectable.\n\nUsually is desirable to declare injectabilty by\ncreating a base class to inherit from. For example,\nwe could create a base class ``Injectable`` as base\nclass for the car components:\n\n.. code-block:: python\n\n    class Injectable(ABC):\n        pass\n\n    class Valves(Injectable):\n        pass\n\n    class Engine(Injectable):\n        def __init__(self, valves: Valves):\n            self.valves = valves\n\n    class Wheels(Injectable):\n        pass\n\nThe call to ``andi.plan`` would then be:\n\n.. code-block:: python\n\n    is_injectable = lambda cls: issubclass(cls, Injectable)\n    plan = andi.plan(Car, is_injectable=is_injectable)\n\nFunctions and methods\n---------------------\n\nDependency injection is also very useful when applied to functions.\nImagine that you have a function ``drive`` that drives the ``Car``\nthrough the ``Road``:\n\n.. code-block:: python\n\n    class Road(Injectable):\n        ...\n\n    def drive(car: Car, road: Road, speed):\n        ... # Drive the car through the road\n\nThe dependencies has to be resolved before invoking\nthe ``drive`` function:\n\n.. code-block:: python\n\n    plan = andi.plan(drive, is_injectable=is_injectable)\n    instances = build(plan.dependencies)\n\nNow the ``drive`` function can be invoked:\n\n.. code-block:: python\n\n    drive(instances[Car], instances[Road], 100)\n\nNote that ``speed`` argument was not annotated. The resultant plan just won't include it\nbecause the ``andi.plan`` ``full_final_kwargs`` parameter is ``False``\nby default. Otherwise, an exception would have been raised (see ``full_final_kwargs`` argument\ndocumentation for more information).\n\nAn alternative and more generic way to invoke the drive function\nwould be:\n\n.. code-block:: python\n\n    drive(speed=100, **plan.final_kwargs(instances))\n\ndataclasses and attrs\n---------------------\n\n``andi`` supports classes defined using `attrs <https://www.attrs.org/>`_\nand also `dataclasses <https://docs.python.org/3/library/dataclasses.html>`_.\nFor example the ``Car`` class could have been defined as:\n\n.. code-block:: python\n\n    # attrs class example\n    @attr.s(auto_attribs=True)\n    class Car:\n        engine: Engine\n        wheels: Wheels\n\n    # dataclass example\n    @dataclass\n    class Car(Injectable):\n        engine: Engine\n        wheels: Wheels\n\nUsing ``attrs`` or ``dataclass`` is handy because they avoid\nsome boilerplate.\n\nExternally provided dependencies\n--------------------------------\n\nRetaining the control over object instantiation\ncould be desired in some cases. For example creating\na database connection could require accessing some\ncredentials registry or getting the connection from a pool\nso you might want to control building\nsuch instances outside of the regular\ndependency injection mechanism.\n\n``andi.plan`` allows to specify which types would be\nexternally provided. Let's see an example:\n\n.. code-block:: python\n\n    class DBConnection(ABC):\n\n        @abstractmethod\n        def getConn():\n            pass\n\n    @dataclass\n    class UsersDAO:\n        conn: DBConnection\n\n        def getUsers():\n           return self.conn.query(\"SELECT * FROM USERS\")\n\n``UsersDAO`` requires a database connection to run queries.\nBut the connection will be provided externally from a pool, so we\ncall then ``andi.plan`` using also the ``externally_provided``\nparameter:\n\n.. code-block:: python\n\n    plan = andi.plan(UsersDAO, is_injectable=is_injectable,\n                     externally_provided={DBConnection})\n\nThe build method should then be modified slightly to be able\nto inject externally provided instances:\n\n.. code-block:: python\n\n    def build(plan, instances_stock=None):\n        instances_stock = instances_stock or {}\n        instances = {}\n        for fn_or_cls, kwargs_spec in plan:\n            if fn_or_cls in instances_stock:\n                instances[fn_or_cls] = instances_stock[fn_or_cls]\n            else:\n                instances[fn_or_cls] = fn_or_cls(**kwargs_spec.kwargs(instances))\n        return instances\n\nNow we are ready to create ``UserDAO`` instances with ``andi``:\n\n.. code-block:: python\n\n    plan = andi.plan(UsersDAO, is_injectable=is_injectable,\n                     externally_provided={DBConnection})\n    dbconnection = DBPool.get_connection()\n    instances = build(plan.dependencies, {DBConnection: dbconnection})\n    users_dao = instances[UsersDAO]\n    users = user_dao.getUsers()\n\nNote that being injectable is not required for externally provided\ndependencies.\n\nOptional\n--------\n\n``Optional`` type annotations can be used in case of\ndependencies that can be optional. For example:\n\n.. code-block:: python\n\n    @dataclass\n    class Dashboard:\n        conn: Optional[DBConnection]\n\n        def showPage():\n            if self.conn:\n                self.conn.query(\"INSERT INTO VISITS ...\")\n            ...  # renders a HTML page\n\nIn this example, the ``Dashboard`` class generates a HTML page to be served, and\nalso stores the number of visits into a database. Database\ncould be absent in some environments, but you might want\nthe dashboard to work even if it cannot log the visits.\n\nWhen a database connection is possible the plan call would be:\n\n.. code-block:: python\n\n    plan = andi.plan(UsersDAO, is_injectable=is_injectable,\n                     externally_provided={DBConnection})\n\n\nAnd the following when the connection is absent:\n\n.. code-block:: python\n\n    plan = andi.plan(UsersDAO, is_injectable=is_injectable,\n                     externally_provided={})\n\nIt is also required to register the type of ``None``\nas injectable. Otherwise ``andi.plan`` with raise an exception\nsaying that \"NoneType is not injectable\".\n\n.. code-block:: python\n\n    Injectable.register(type(None))\n\nUnion\n-----\n\n``Union`` can also be used to express alternatives. For example:\n\n.. code-block:: python\n\n    @dataclass\n    class UsersDAO:\n        conn: Union[ProductionDBConnection, DevelopmentDBConnection]\n\n``DevelopmentDBConnection`` will be injected in the absence of\n``ProductionDBConnection``.\n\nAnnotated\n---------\n\nOn Python 3.9+ ``Annotated`` type annotations can be used to attach arbitrary\nmetadata that will be preserved in the plan. Occurrences of the same type\nannotated with different metadata will not be considered duplicates. For\nexample:\n\n.. code-block:: python\n\n    @dataclass\n    class Dashboard:\n        conn_main: Annotated[DBConnection, \"main DB\"]\n        conn_stats: Annotated[DBConnection, \"stats DB\"]\n\nThe plan will contain both dependencies.\n\nCustom builders\n---------------\n\nSometimes a dependency can't be created directly but needs some additional code\nto be built. And that code can also have its own dependencies:\n\n.. code-block:: python\n\n    class Wheels:\n        pass\n\n    def wheel_factory(wheel_builder: WheelBuilder) -> Wheels:\n        return wheel_builder.get_wheels()\n\nAs by default ``andi`` can't know how to create a ``Wheels`` instance or that\nthe plan needs to create a ``WheelBuilder`` instance first, it needs to be told\nthis with a ``custom_builder_fn`` argument:\n\n.. code-block:: python\n\n    custom_builders = {\n        Wheels: wheel_factory,\n    }\n\n    plan = andi.plan(Car, is_injectable={Engine, Wheels, Valves},\n                     custom_builder_fn=custom_builders.get,\n                     )\n\n``custom_builder_fn`` should be a function that takes a type and returns a factory\nfor that type.\n\nThe build code also needs to know how to build ``Wheels`` instances. A plan step\nfor an object built with a custom builder uses an instance of the ``andi.CustomBuilder``\nwrapper that contains the type to be built in the ``result_class_or_fn`` attribute and\nthe callable for building it in the ``factory`` attribute:\n\n.. code-block:: python\n\n    from andi import CustomBuilder\n\n    def build(plan):\n        instances = {}\n        for fn_or_cls, kwargs_spec in plan:\n            if isinstance(fn_or_cls, CustomBuilder):\n                instances[fn_or_cls.result_class_or_fn] = fn_or_cls.factory(**kwargs_spec.kwargs(instances))\n            else:\n                instances[fn_or_cls] = fn_or_cls(**kwargs_spec.kwargs(instances))\n        return instances\n\nFull final kwargs mode\n-------------------------\n\nBy default ``andi.plan`` won't fail if it is not able to provide\nsome of the direct dependencies for the given input (see the\n``speed`` argument in one of the examples above).\n\nThis behaviour is desired when inspecting functions\nfor which is already known that some arguments won't be\ninjectable but they will be provided by other means\n(like the ``drive`` function above).\n\nBut in other cases is better to be sure that all dependencies\nare fulfilled and otherwise fail. Such is the case for classes.\nSo it is recommended to set ``full_final_kwargs=True`` when invoking\n``andi.plan`` for classes.\n\nOverrides\n---------\n\nLet's go back to the ``Car`` example. Imagine you want to build a car again.\nBut this time you want to replace the ``Engine`` because this is\ngoing to be an electric car!. And of course, an electric engine contains a battery\nand have no valves at all. This could be the new ``Engine``:\n\n.. code-block:: python\n\n    class Battery:\n        pass\n\n    class ElectricEngine(Engine):\n\n        def __init__(self, battery: Battery):\n            self.battery = valves\n\nAndi offers the possibility to replace dependencies when planning,\nand this is what is required to build the electric car: we need\nto replace any dependency on ``Engine`` by a dependency on ``ElectricEngine``.\nThis is exactly what overrides offers. Let's see how ``plan`` should\nbe invoked in this case:\n\n.. code-block:: python\n\n    plan = andi.plan(Car, is_injectable=is_injectable,\n                     overrides={Engine: ElectricEngine}.get)\n\nNote that Andi will unroll the new dependencies properly. That is,\n``Valves`` and ``Engine`` won't be in the resultant plan but\n``ElectricEngine`` and ``Battery`` will.\n\nIn summary, overrides offers a way to override the default\ndependencies anywhere in the tree, changing them with an\nalternative one.\n\nBy default overrides are not recursive: overrides aren't applied\nover the children of an already overridden dependency. There\nis flag to turn recursion on if this is what is desired.\nCheck ``andi.plan`` documentation for more information.\n\nWhy type annotations?\n---------------------\n\n``andi`` uses type annotations to declare dependencies (inputs).\nIt has several advantages, and some limitations as well.\n\nAdvantages:\n\n1. Built-in language feature.\n2. You're not lying when specifying a type - these\n   annotations still work as usual type annotations.\n3. In many projects you'd annotate arguments anyways, so ``andi`` support\n   is \"for free\".\n\nLimitations:\n\n1. Callable can't have two arguments of the same type.\n2. This feature could possibly conflict with regular type annotation usages.\n\nIf your callable has two arguments of the same type, consider making them\ndifferent types. For example, a callable may receive url and html of\na web page:\n\n.. code-block:: python\n\n    def parse(html: str, url: str):\n        # ...\n\nTo make it play well with ``andi``, you may define separate types for url\nand for html:\n\n.. code-block:: python\n\n    class HTML(str):\n        pass\n\n    class URL(str):\n        pass\n\n    def parse(html: HTML, url: URL):\n        # ...\n\nThis is more boilerplate though.\n\nWhy doesn't andi handle creation of objects?\n--------------------------------------------\n\nCurrently ``andi`` just inspects callable and chooses best concrete types\na framework needs to create and pass to a callable, without prescribing how\nto create them. This makes ``andi`` useful in various contexts - e.g.\n\n* creation of some objects may require asynchronous functions, and it\n  may depend on libraries used (asyncio, twisted, etc.)\n* in streaming architectures (e.g. based on Kafka) inspection may happen\n  on one machine, while creation of objects may happen on different nodes\n  in a distributed system, and then actually running a callable may happen on\n  yet another machine.\n\nIt is hard to design API with enough flexibility for all such use cases.\nThat said, ``andi`` may provide more helpers in future,\nonce patterns emerge, even if they're useful only in certain contexts.\n\nExamples: callback based frameworks\n-----------------------------------\n\nSpider example\n**************\n\nNothing better than a example to understand how ``andi`` can be useful.\nLet's imagine you want to implemented a callback based framework\nfor writing spiders to crawl web pages.\n\nThe basic idea is that there is framework in which the user\ncan write spiders. Each spider is a collection of callbacks\nthat can process data from a page, emit extracted data or request new\npages. Then, there is an engine that takes care of downloading\nthe web pages\nand invoking the user defined callbacks, chaining requests\nwith its corresponding callback.\n\nLet's see an example of an spider to download recipes\nfrom a cooking page:\n\n.. code-block:: python\n\n    class MySpider(Spider):\n        start_url = \"htttp://a_page_with_a_list_of_recipes\"\n\n        def parse(self, response):\n            for url in recipes_urls_from_page(response)\n                yield Request(url, callback=parse_recipe)\n\n        def parse_recipe(self, response):\n            yield extract_recipe(response)\n\n\nIt would be handy if the user can define some requirements\njust by annotating parameters in the callbacks. And ``andi`` make it\npossible.\n\nFor example, a particular callback could require access to the cookies:\n\n.. code-block:: python\n\n    def parse(self, response: Response, cookies: CookieJar):\n        # ... Do something with the response and the cookies\n\nIn this case, the engine can use ``andi`` to inspect the ``parse`` method, and\ndetect that ``Response`` and ``CookieJar`` are required.\nThen the framework will build them and will invoke the callback.\n\nThis functionality would serve to inject into the users callbacks\nsome components only when they are required.\n\nIt could also serve to encapsulate better the user code. For\nexample, we could just decouple the recipe extraction into\nit's own class:\n\n.. code-block:: python\n\n    @dataclass\n    class RecipeExtractor:\n        response: Response\n\n        def to_item():\n            return extract_recipe(self.response)\n\nThe callback could then be defined as:\n\n.. code-block:: python\n\n        def parse_recipe(extractor: RecipeExtractor):\n            yield extractor.to_item()\n\nNote how handy is that with ``andi`` the engine can create\nan instance of ``RecipesExtractor`` feeding it with the\ndeclared ``Response`` dependency.\n\nIn definitive, using ``andi`` in such a framework\ncan provide great flexibility to the user\nand reduce boilerplate.\n\nWeb server example\n******************\n\n``andi`` can be useful also for implementing a new\nweb framework.\n\nLet's imagine a framework where you can declare your sever in a\nclass like the following:\n\n.. code-block:: python\n\n    class MyWeb(Server):\n\n        @route(\"/products\")\n        def productspage(self, request: Request):\n            ... # return the composed page\n\n        @route(\"/sales\")\n        def salespage(self, request: Request):\n            ... # return the composed page\n\nThe former case is composed of two endpoints, one for serving\na page with a summary of sales, and a second one to serve\nthe products list.\n\nConnection to the database can be required\nto sever these pages. This logic could be encapsulated\nin some classes:\n\n.. code-block:: python\n\n    @dataclass\n    class Products:\n        conn: DBConnection\n\n        def get_products()\n            return self.conn.query(\"SELECT ...\")\n\n    @dataclass\n    class Sales:\n        conn: DBConnection\n\n        def get_sales()\n            return self.conn.query(\"SELECT ...\")\n\nNow ``productspage`` and ``salespage`` methods can just declare\nthat they require these objects:\n\n.. code-block:: python\n\n    class MyWeb(Server):\n\n        @route(\"/products\")\n        def productspage(self, request: Request, products: Products):\n            ... # return the composed page\n\n        @route(\"/sales\")\n        def salespage(self, request: Request, sales: Sales):\n            ... # return the composed page\n\nAnd the framework can then be responsible to fulfill these\ndependencies. The flexibility offered would be a great advantage.\nAs an example, if would be very easy to create a page that requires\nboth sales and products:\n\n.. code-block:: python\n\n        @route(\"/overview\")\n        def productspage(self, request: Request,\n                         products: Products, sales: Sales):\n            ... # return the composed overview page\n\n\nContributing\n============\n\n* Source code: https://github.com/scrapinghub/andi\n* Issue tracker: https://github.com/scrapinghub/andi/issues\n\nUse tox_ to run tests with different Python versions::\n\n    tox\n\nThe command above also runs type checks; we use mypy.\n\n.. _tox: https://tox.readthedocs.io\n\n\nChanges\n=======\n\n0.6.0 (2023-12-26)\n------------------\n\n* Drop support for Python 3.5-3.7.\n* Add support for dependencies that need to be built using custom callables.\n\n0.5.0 (2023-12-12)\n------------------\n\n* Add support for dependency metadata via ``typing.Annotated`` (requires\n  Python 3.9+).\n* Add docs for overrides.\n* Add support for Python 3.10-3.12.\n* CI improvements.\n\n0.4.1 (2021-02-11)\n------------------\n\n* Overrides support in ``andi.plan``\n\n0.4.0 (2020-04-23)\n------------------\n\n* ``andi.inspect`` can handle classes now (their ``__init__`` method\n  is inspected)\n* ``andi.plan`` and ``andi.inspect`` can handle objects which are\n  callable via ``__call__`` method.\n\n0.3.0 (2020-04-03)\n------------------\n\n* ``andi.plan`` function replacing ``andi.to_provide``.\n* Rewrite README explaining the new approach based in ``plan`` method.\n* ``andi.inspect`` return non annotated arguments also.\n\n0.2.0 (2020-02-14)\n------------------\n\n* Better attrs support (workaround issue with string type annotations).\n* Declare Python 3.8 support.\n* More tests; ensure dataclasses support.\n\n0.1 (2019-08-28)\n----------------\n\nInitial release.\n",
    "bugtrack_url": null,
    "license": "",
    "summary": "Library for annotation-based dependency injection",
    "version": "0.6.0",
    "project_urls": {
        "Homepage": "https://github.com/scrapinghub/andi"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "3928bd6b8be8f73eecaa064700f4f06b2387ecfda11324108a8591296bf7aab7",
                "md5": "6b1d6bb445c312288a102cdb180f6bd4",
                "sha256": "e83dac54852cabe2da2cebe9bddb77da10a3636bfee4a40ebab4c09b64c3beb1"
            },
            "downloads": -1,
            "filename": "andi-0.6.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "6b1d6bb445c312288a102cdb180f6bd4",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8.1",
            "size": 18580,
            "upload_time": "2023-12-26T12:47:24",
            "upload_time_iso_8601": "2023-12-26T12:47:24.068932Z",
            "url": "https://files.pythonhosted.org/packages/39/28/bd6b8be8f73eecaa064700f4f06b2387ecfda11324108a8591296bf7aab7/andi-0.6.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "0b9115758f49c921b11e03e5e0da15392ef156f942e7aec3e010d4bf3c9b9366",
                "md5": "6d6fecd7bdc75d29fd6264388e34208a",
                "sha256": "4e4a5f20ab1d2b7c35c31617adcd2e36023e1cc428cfdfccf722ab0c94179c4c"
            },
            "downloads": -1,
            "filename": "andi-0.6.0.tar.gz",
            "has_sig": false,
            "md5_digest": "6d6fecd7bdc75d29fd6264388e34208a",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8.1",
            "size": 30638,
            "upload_time": "2023-12-26T12:47:25",
            "upload_time_iso_8601": "2023-12-26T12:47:25.981454Z",
            "url": "https://files.pythonhosted.org/packages/0b/91/15758f49c921b11e03e5e0da15392ef156f942e7aec3e010d4bf3c9b9366/andi-0.6.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2023-12-26 12:47:25",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "scrapinghub",
    "github_project": "andi",
    "travis_ci": false,
    "coveralls": true,
    "github_actions": true,
    "tox": true,
    "lcname": "andi"
}
        
Elapsed time: 0.20282s