mirror of
https://github.com/ets-labs/python-dependency-injector.git
synced 2024-11-25 19:14:00 +03:00
346 lines
12 KiB
ReStructuredText
346 lines
12 KiB
ReStructuredText
Dependency Injector
|
|
===================
|
|
|
|
*Dependency Injector* is a Python dependency injection framework. 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*:
|
|
|
|
- Easy, smart, pythonic style.
|
|
- Obvious, clear structure.
|
|
- Memory efficiency.
|
|
- Thread safety.
|
|
- Semantic versioning.
|
|
|
|
Main idea of *Dependency Injector* is to keep dependencies under control.
|
|
|
|
Status
|
|
------
|
|
|
|
+---------------------------------------+---------------------------------------------------------------------------------+
|
|
| *PyPi* | .. image:: https://img.shields.io/pypi/v/dependency_injector.svg |
|
|
| | :target: https://pypi.python.org/pypi/dependency_injector/ |
|
|
| | :alt: Latest Version |
|
|
| | .. image:: https://img.shields.io/pypi/dm/dependency_injector.svg |
|
|
| | :target: https://pypi.python.org/pypi/dependency_injector/ |
|
|
| | :alt: Downloads |
|
|
| | .. image:: https://img.shields.io/pypi/l/dependency_injector.svg |
|
|
| | :target: https://pypi.python.org/pypi/dependency_injector/ |
|
|
| | :alt: License |
|
|
+---------------------------------------+---------------------------------------------------------------------------------+
|
|
| *Python versions and implementations* | .. image:: https://img.shields.io/pypi/pyversions/dependency_injector.svg |
|
|
| | :target: https://pypi.python.org/pypi/dependency_injector/ |
|
|
| | :alt: Supported Python versions |
|
|
| | .. image:: https://img.shields.io/pypi/implementation/dependency_injector.svg |
|
|
| | :target: https://pypi.python.org/pypi/dependency_injector/ |
|
|
| | :alt: Supported Python implementations |
|
|
+---------------------------------------+---------------------------------------------------------------------------------+
|
|
| *Builds and tests coverage* | .. image:: https://travis-ci.org/ets-labs/dependency_injector.svg?branch=master |
|
|
| | :target: https://travis-ci.org/ets-labs/dependency_injector |
|
|
| | :alt: Build Status |
|
|
| | .. image:: https://coveralls.io/repos/ets-labs/dependency_injector/badge.svg |
|
|
| | :target: https://coveralls.io/r/ets-labs/dependency_injector |
|
|
| | :alt: Coverage Status |
|
|
+---------------------------------------+---------------------------------------------------------------------------------+
|
|
|
|
Installation
|
|
------------
|
|
|
|
*Dependency Injector* library is available on PyPi_::
|
|
|
|
pip install dependency_injector
|
|
|
|
Documentation
|
|
-------------
|
|
|
|
*Dependency Injector* documentation is hosted on ReadTheDocs:
|
|
|
|
- `User's guide`_
|
|
- `API docs`_
|
|
|
|
Examples
|
|
--------
|
|
|
|
API client example:
|
|
|
|
.. code-block:: python
|
|
|
|
"""Pythonic way for Dependency Injection - API Client."""
|
|
|
|
from dependency_injector import providers
|
|
|
|
from mock import Mock
|
|
|
|
|
|
class ApiClient(object):
|
|
"""Some API client."""
|
|
|
|
def __init__(self, host, api_key):
|
|
"""Initializer."""
|
|
self.host = host
|
|
self.api_key = api_key
|
|
|
|
def call(self, operation, data):
|
|
"""Make some network operations."""
|
|
print 'API call [{0}:{1}], method - {2}, data - {3}'.format(
|
|
self.host, self.api_key, operation, repr(data))
|
|
|
|
|
|
class User(object):
|
|
"""User model."""
|
|
|
|
def __init__(self, id, api_client):
|
|
"""Initializer."""
|
|
self.id = id
|
|
self.api_client = api_client
|
|
|
|
def register(self):
|
|
"""Register user."""
|
|
self.api_client.call('register', {'id': self.id})
|
|
|
|
|
|
# Creating ApiClient and User providers:
|
|
api_client = providers.Singleton(ApiClient,
|
|
host='production.com',
|
|
api_key='PROD_API_KEY')
|
|
user_factory = providers.Factory(User,
|
|
api_client=api_client)
|
|
|
|
# Creating several users and register them:
|
|
user1 = user_factory(1)
|
|
user1.register()
|
|
# API call [production.com:PROD_API_KEY], method - register, data - {'id': 1}
|
|
|
|
user2 = user_factory(2)
|
|
user2.register()
|
|
# API call [production.com:PROD_API_KEY], method - register, data - {'id': 2}
|
|
|
|
# Mock ApiClient for testing:
|
|
with api_client.override(Mock(ApiClient)) as api_client_mock:
|
|
user = user_factory('test')
|
|
user.register()
|
|
api_client_mock().call.assert_called_with('register', {'id': 'test'})
|
|
|
|
|
|
# Overriding of ApiClient on dev environment:
|
|
api_client.override(providers.Singleton(ApiClient,
|
|
host='localhost',
|
|
api_key='DEV_API_KEY'))
|
|
|
|
user3 = user_factory(3)
|
|
user3.register()
|
|
# API call [localhost:DEV_API_KEY], method - register, data - {'id': 3}
|
|
|
|
Auth system example:
|
|
|
|
.. code-block:: python
|
|
|
|
"""Pythonic way for Dependency Injection - Auth System."""
|
|
|
|
from dependency_injector import providers
|
|
from dependency_injector import injections
|
|
|
|
|
|
@providers.DelegatedCallable
|
|
def get_user_info(user_id):
|
|
"""Return user info."""
|
|
raise NotImplementedError()
|
|
|
|
|
|
@providers.Factory
|
|
@injections.inject(get_user_info=get_user_info)
|
|
class AuthComponent(object):
|
|
"""Some authentication component."""
|
|
|
|
def __init__(self, get_user_info):
|
|
"""Initializer."""
|
|
self.get_user_info = get_user_info
|
|
|
|
def authenticate_user(self, token):
|
|
"""Authenticate user by token."""
|
|
user_info = self.get_user_info(user_id=token + '1')
|
|
return user_info
|
|
|
|
|
|
print AuthComponent
|
|
print get_user_info
|
|
|
|
|
|
@providers.override(get_user_info)
|
|
@providers.DelegatedCallable
|
|
def get_user_info(user_id):
|
|
"""Return user info."""
|
|
return {'user_id': user_id}
|
|
|
|
|
|
print AuthComponent().authenticate_user(token='abc')
|
|
# {'user_id': 'abc1'}
|
|
|
|
Service providers catalog example:
|
|
|
|
.. code-block:: python
|
|
|
|
"""Pythonic way for Dependency Injection - Service Providers Catalog."""
|
|
|
|
import sqlite3
|
|
|
|
from dependency_injector import catalogs
|
|
from dependency_injector import providers
|
|
from dependency_injector import injections
|
|
|
|
|
|
class UsersService(object):
|
|
"""Users service, that has dependency on database."""
|
|
|
|
def __init__(self, db):
|
|
"""Initializer."""
|
|
self.db = db
|
|
|
|
|
|
class AuthService(object):
|
|
"""Auth service, that has dependencies on users service and database."""
|
|
|
|
def __init__(self, db, users_service):
|
|
"""Initializer."""
|
|
self.db = db
|
|
self.users_service = users_service
|
|
|
|
|
|
class Services(catalogs.DeclarativeCatalog):
|
|
"""Catalog of service providers."""
|
|
|
|
database = providers.Singleton(sqlite3.connect, ':memory:')
|
|
""":type: providers.Provider -> sqlite3.Connection"""
|
|
|
|
users = providers.Factory(UsersService,
|
|
db=database)
|
|
""":type: providers.Provider -> UsersService"""
|
|
|
|
auth = providers.Factory(AuthService,
|
|
db=database,
|
|
users_service=users)
|
|
""":type: providers.Provider -> AuthService"""
|
|
|
|
|
|
# Retrieving catalog providers:
|
|
users_service = Services.users()
|
|
auth_service = Services.auth()
|
|
|
|
# Making some asserts:
|
|
assert users_service.db is auth_service.db is Services.database()
|
|
assert isinstance(auth_service.users_service, UsersService)
|
|
assert users_service is not Services.users()
|
|
assert auth_service is not Services.auth()
|
|
|
|
|
|
# Making some "inline" injections:
|
|
@injections.inject(users_service=Services.users)
|
|
@injections.inject(auth_service=Services.auth)
|
|
@injections.inject(database=Services.database)
|
|
def example(users_service, auth_service, database):
|
|
"""Example callback."""
|
|
assert users_service.db is auth_service.db
|
|
assert auth_service.db is database
|
|
assert database is Services.database()
|
|
|
|
|
|
# Making a call of decorated callback:
|
|
example()
|
|
|
|
Providing callbacks catalog example:
|
|
|
|
.. code-block:: python
|
|
|
|
"""Pythonic way for Dependency Injection - Providing Callbacks Catalog."""
|
|
|
|
import sqlite3
|
|
|
|
from dependency_injector import catalogs
|
|
from dependency_injector import providers
|
|
from dependency_injector import injections
|
|
|
|
|
|
class UsersService(object):
|
|
"""Users service, that has dependency on database."""
|
|
|
|
def __init__(self, db):
|
|
"""Initializer."""
|
|
self.db = db
|
|
|
|
|
|
class AuthService(object):
|
|
"""Auth service, that has dependencies on users service and database."""
|
|
|
|
def __init__(self, db, users_service):
|
|
"""Initializer."""
|
|
self.db = db
|
|
self.users_service = users_service
|
|
|
|
|
|
class Services(catalogs.DeclarativeCatalog):
|
|
"""Catalog of service providers."""
|
|
|
|
@providers.Singleton
|
|
def database():
|
|
"""Provide database connection.
|
|
|
|
:rtype: providers.Provider -> sqlite3.Connection
|
|
"""
|
|
return sqlite3.connect(':memory:')
|
|
|
|
@providers.Factory
|
|
@injections.inject(db=database)
|
|
def users(**kwargs):
|
|
"""Provide users service.
|
|
|
|
:rtype: providers.Provider -> UsersService
|
|
"""
|
|
return UsersService(**kwargs)
|
|
|
|
@providers.Factory
|
|
@injections.inject(db=database)
|
|
@injections.inject(users_service=users)
|
|
def auth(**kwargs):
|
|
"""Provide users service.
|
|
|
|
:rtype: providers.Provider -> AuthService
|
|
"""
|
|
return AuthService(**kwargs)
|
|
|
|
|
|
# Retrieving catalog providers:
|
|
users_service = Services.users()
|
|
auth_service = Services.auth()
|
|
|
|
# Making some asserts:
|
|
assert users_service.db is auth_service.db is Services.database()
|
|
assert isinstance(auth_service.users_service, UsersService)
|
|
assert users_service is not Services.users()
|
|
assert auth_service is not Services.auth()
|
|
|
|
You can get more *Dependency Injector* examples in ``/examples`` directory on
|
|
GitHub:
|
|
|
|
https://github.com/ets-labs/dependency_injector
|
|
|
|
|
|
Feedback
|
|
--------
|
|
|
|
Feel free to post questions, bugs, feature requests, proposals etc. on
|
|
*Dependency Injector* GitHub Issues:
|
|
|
|
https://github.com/ets-labs/dependency_injector/issues
|
|
|
|
Your feedback is quite important!
|
|
|
|
|
|
.. _PyPi: https://pypi.python.org/pypi/dependency_injector
|
|
.. _User's guide: http://dependency_injector.readthedocs.org/en/stable/
|
|
.. _API docs: http://dependency-injector.readthedocs.org/en/stable/api/
|
|
.. _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
|