mirror of
https://github.com/ets-labs/python-dependency-injector.git
synced 2024-11-25 19:14:00 +03:00
112 lines
4.4 KiB
ReStructuredText
112 lines
4.4 KiB
ReStructuredText
Introduction
|
|
============
|
|
|
|
Before you have started with *Dependency Injector* framework and dependecy
|
|
injection, there are a couple of introduction notes that might be useful.
|
|
|
|
What is DI and why is it needed?
|
|
--------------------------------
|
|
|
|
Python ecosystem consists of a big amount of various libraries that contain
|
|
different classes and functions that could be used for applications
|
|
development. Each of them has its own role.
|
|
|
|
Modern Python applications are mostly the composition of well-known open
|
|
source systems / frameworks / libraries and some turnkey functionality.
|
|
|
|
When application goes bigger, its complexity and SLOC_ are also increased.
|
|
Being driven by SOLID_ (for example), developers often start to split
|
|
application's sources into not so big classes, functions and modules, that are
|
|
less complex, could be reused several times and so on... It always helps, but
|
|
there is another problem on the horizon.
|
|
|
|
The name of this problem is - "Dependency hell!". It sounds like "I have so
|
|
many classes and functions! They are great, now I can understand each of them,
|
|
but it is so hard to see the whole picture! How are they linked with each
|
|
other? What dependencies does this class have?". And this is a key question:
|
|
"What dependencies does certain class / function have?". To resolve this issues
|
|
developers have to go inside with IoC_ principles and implementation patterns.
|
|
|
|
One of such IoC_ implementation patterns is called `dependency injection`_.
|
|
|
|
Dependency injection in Python
|
|
------------------------------
|
|
|
|
Interesting but, dependency injection is not very popular topic in Python.
|
|
The things are so because Python is an awesome language. Your eyes are opened
|
|
and your hands are free while you are using Python. In practice this means that
|
|
you can do dependency injection in Python in quite an easy way because language
|
|
itself helps you to do this. At the same time, even the thins are so, you still
|
|
have to do some work. Another one 'minor' problem is that there are several
|
|
ways to do dependency injection container.
|
|
|
|
Key features
|
|
------------
|
|
|
|
*Dependency Injector* is a dependency injection framework for Python projects.
|
|
It was designed to be unified, developer's friendly tool for managing any kind
|
|
of Python objects and their dependencies in formal, pretty way.
|
|
|
|
Below is a list of some key features and points of *Dependency Injector*
|
|
framework:
|
|
|
|
- Easy, smart, pythonic style.
|
|
- Obvious, clear structure.
|
|
- Memory efficiency.
|
|
- Semantic versioning.
|
|
|
|
Main idea of *Dependency Injector* is to keep dependencies under control.
|
|
|
|
Shortcuts
|
|
---------
|
|
|
|
*Dependency Injector* recommends to use such kind of import shortcut:
|
|
|
|
.. code-block:: python
|
|
|
|
import dependency_injector as di
|
|
|
|
- All *Dependency Injector* entities could be used just from top-level package
|
|
(like ``di.Factory``, ``di.inject``, ``di.AbstractCatalog`` and so on).
|
|
- Another one way is to use second level packages (like
|
|
``di.providers.Factory``, ``di.injections.inject``,
|
|
``di.catalog.AbstractCatalog`` and so on). It might be useful for improving
|
|
of readability in some cases.
|
|
|
|
.. note::
|
|
|
|
``import dependency_injector as di`` shortcut is used among current
|
|
documentation, images and examples.
|
|
|
|
Main entities
|
|
-------------
|
|
|
|
Current section describes *Dependency Injector* main entities and their
|
|
interaction with each other.
|
|
|
|
.. image:: /images/internals.png
|
|
:width: 100%
|
|
:align: center
|
|
|
|
There are 3 main entities:
|
|
|
|
- Providers. Providers are strategies of accesing objects. For example,
|
|
``di.providers.Factory`` creates new instance of provided
|
|
class every time it is called. ``di.providers.Singleton`` creates
|
|
provided instance once and returns it on every next call. Providers
|
|
could be overridden by another providers. Base class is -
|
|
``di.providers.Provider``.
|
|
- Injections. Injections are instructions for making dependency injections
|
|
(there are several ways how they could be done). Injections are used mostly
|
|
by ``di.providers.Factory`` and ``di.providers.Singleton`` providers, but
|
|
these are not only cases. Base class is - ``di.injections.Injection``.
|
|
- Catalogs. Catalogs are collections of providers. They are used for grouping
|
|
of providers by some principles. Base class is -
|
|
``di.catalog.AbstractCatalog``.
|
|
|
|
|
|
.. _SLOC: http://en.wikipedia.org/wiki/Source_lines_of_code
|
|
.. _SOLID: http://en.wikipedia.org/wiki/SOLID_%28object-oriented_design%29
|
|
.. _IoC: http://en.wikipedia.org/wiki/Inversion_of_control
|
|
.. _dependency injection: http://en.wikipedia.org/wiki/Dependency_injection
|