90 lines
3.7 KiB
ReStructuredText
90 lines
3.7 KiB
ReStructuredText
.. Injector documentation master file, created by
|
||
sphinx-quickstart on Mon Sep 16 02:58:17 2013.
|
||
You can adapt this file completely to your liking, but it should at least
|
||
contain the root `toctree` directive.
|
||
|
||
Welcome to Injector's documentation!
|
||
====================================
|
||
|
||
.. image:: https://travis-ci.org/alecthomas/injector.png?branch=master
|
||
:alt: Build status
|
||
:target: https://travis-ci.org/alecthomas/injector
|
||
|
||
.. image:: https://coveralls.io/repos/github/alecthomas/injector/badge.svg?branch=master
|
||
:alt: Covergage status
|
||
:target: https://coveralls.io/github/alecthomas/injector?branch=master
|
||
|
||
GitHub (code repository, issues): https://github.com/alecthomas/injector
|
||
|
||
PyPI (installable, stable distributions): https://pypi.org/project/injector. You can install Injector using pip::
|
||
|
||
pip install injector
|
||
|
||
Injector works with CPython 3.5+ and PyPy 3 implementing Python 3.5+.
|
||
|
||
Introduction
|
||
------------
|
||
|
||
While dependency injection is easy to do in Python due to its support for keyword arguments, the ease with which objects can be mocked and its dynamic natura, a framework for assisting in this process can remove a lot of boiler-plate from larger applications. That's where Injector can help. It automatically and transitively provides dependencies for you. As an added benefit, Injector encourages nicely compartmentalised code through the use of :ref:`modules <module>`.
|
||
|
||
If you're not sure what dependency injection is or you'd like to learn more about it see:
|
||
|
||
* `The Clean Code Talks - Don't Look For Things! (a talk by Miško Hevery)
|
||
<https://www.youtube.com/watch?v=RlfLCWKxHJ0>`_
|
||
* `Inversion of Control Containers and the Dependency Injection pattern (an article by Martin Fowler)
|
||
<https://martinfowler.com/articles/injection.html>`_
|
||
|
||
The core values of Injector are:
|
||
|
||
* Simplicity - while being inspired by Guice, Injector does not slavishly replicate its API.
|
||
Providing a Pythonic API trumps faithfulness. Additionally some features are ommitted
|
||
because supporting them would be cumbersome and introduce a little bit too much "magic"
|
||
(member injection, method injection).
|
||
|
||
Connected to this, Injector tries to be as nonintrusive as possible. For example while you may
|
||
declare a class' constructor to expect some injectable parameters, the class' constructor
|
||
remains a standard constructor – you may instaniate the class just the same manually, if you want.
|
||
|
||
* No global state – you can have as many :class:`Injector` instances as you like, each with
|
||
a different configuration and each with different objects in different scopes. Code like this
|
||
won't work for this very reason::
|
||
|
||
class MyClass:
|
||
@inject
|
||
def __init__(t: SomeType):
|
||
# ...
|
||
|
||
MyClass()
|
||
|
||
This is simply because there's no global :class:`Injector` to use. You need to be explicit and use
|
||
:meth:`Injector.get <injector.Injector.get>`,
|
||
:meth:`Injector.create_object <injector.Injector.create_object>` or inject `MyClass` into the place
|
||
that needs it.
|
||
|
||
* Cooperation with static type checking infrastructure – the API provides as much static type safety
|
||
as possible and only breaks it where there's no other option. For example the
|
||
:meth:`Injector.get <injector.Injector.get>` method is typed such that `injector.get(SomeType)`
|
||
is statically declared to return an instance of `SomeType`, therefore making it possible for tools
|
||
such as `mypy <https://github.com/python/mypy>`_ to type-check correctly the code using it.
|
||
|
||
Quick start
|
||
-----------
|
||
|
||
See `the project's README <https://github.com/alecthomas/injector/blob/master/README.md>`_ for an
|
||
example of Injector use.
|
||
|
||
Contents
|
||
--------
|
||
|
||
.. toctree::
|
||
:maxdepth: 1
|
||
|
||
changelog
|
||
terminology
|
||
testing
|
||
scopes
|
||
logging
|
||
api
|
||
faq
|
||
practices
|