ets-labs/python-dependency-injector
1
1
Fork 0
mirror of https://github.com/ets-labs/python-dependency-injector.git synced 2024-11-26 03:23:58 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/docs-n-examples-improvements'

Browse Source
This commit is contained in:
Roman Mogilatov 2016-10-07 16:52:24 +03:00
commit e64366ab09
9 changed files with 234 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

169
README.rst
View File

@ -3,8 +3,8 @@ Dependency Injector - Python dependency injection framework
===========================================================
*Dependency Injector* is a Python dependency injection framework. It was
designed to be unified, developer-friendly tool for managing any kind
of Python objects and their dependencies in formal, pretty way.
designed to be unified, developer-friendly tool that helps to implement
dependency injection pattern in formal, pretty, Pythonic way.
*Dependency Injector* framework key features are:
@ -45,22 +45,109 @@ Status
Installation
------------
*Dependency Injector* library is available on PyPi_::
*Dependency Injector* library is available on `PyPi`_::
pip install dependency_injector
Example
-------
Dependency Injection
--------------------
Brief example below demonstrates usage of *Dependency Injector* containers and
providers for definition of several IoC containers for some microservice
system that consists from several business and platform services:
`Dependency injection`_ is a software design pattern that implements
`Inversion of control`_ for resolving dependencies. Formally, if object **A**
depends on object **B**, object **A** must not create or import object **B**,
but provide a way for injecting object **B** (object **B** could be injected
into object **A** in several ways: by passing it as ``__init__`` argument, by
setting it as attribute's value or by passing it as method's argument).
Dependency injection pattern has few strict rules that should be followed:
+ Object **A** (the client) delegates to external code (the dependency
injector) the responsibility of providing its dependencies - object **B**
(the service).
+ The client doesn't know how to create the service, it knows only interface
of service.
+ The service doesn't know that it is used by the client.
+ The dependency injector knows how to create the client.
+ The dependency injector knows how to create the service.
+ The dependency injector knows that the client depends on the service.
+ The dependency injector knows how to inject the service into the client.
+ The client knows nothing about the dependency injector.
+ The service knows nothing about the dependency injector.
Next two examples demonstrate refactoring of a small piece of code to
dependency injection pattern:
.. code-block:: python
"""Example of several Dependency Injector IoC containers."""
"""Car & Engine example."""
class Engine(object):
"""Example engine."""
class Car(object):
"""Example car."""
def __init__(self):
"""Initializer."""
self.engine = Engine() # Engine is a "hardcoded" dependency
if __name__ == '__main__':
car = Car() # Application creates Car's instance
``Car`` **creates** an ``Engine`` during its creation. Really? Does it make
more sense than creating an ``Engine`` separately and then
**inject it into** ``Car`` when ``Car`` is being created? Looks more
realistic, right?
.. code-block:: python
"""Refactored Car & Engine example that demonstrates dependency injection."""
class Engine(object):
"""Example engine."""
class Car(object):
"""Example car."""
def __init__(self, engine):
"""Initializer."""
self.engine = engine # Engine is an "injected" dependency
if __name__ == '__main__':
engine = Engine() # Application creates Engine's instance
car = Car(engine) # and inject it into the Car's instance
Advantages of dependency injection
----------------------------------
Dependency injection pattern provides next advantages:
+ Control on application structure.
+ Decreased coupling between application components.
+ Increased code reusability.
+ Increased testability.
+ Increased maintainability.
+ Reconfiguration of system without rebuilding.
Example of dependency injection
-------------------------------
Brief example below demonstrates usage of *Dependency Injector* for creating
several IoC containers for some microservice system:
.. code-block:: python
"""Example of dependency injection in Python."""
import logging
import sqlite3
import boto.s3.connection
import example.main
@ -73,6 +160,8 @@ system that consists from several business and platform services:
class Platform(containers.DeclarativeContainer):
"""IoC container of platform service providers."""
logger = providers.Singleton(logging.Logger, name='example')
database = providers.Singleton(sqlite3.connect, ':memory:')
s3 = providers.Singleton(boto.s3.connection.S3Connection,
@ -84,13 +173,16 @@ system that consists from several business and platform services:
"""IoC container of business service providers."""
users = providers.Factory(example.services.Users,
logger=Platform.logger,
db=Platform.database)
auth = providers.Factory(example.services.Auth,
logger=Platform.logger,
db=Platform.database,
token_ttl=3600)
photos = providers.Factory(example.services.Photos,
logger=Platform.logger,
db=Platform.database,
s3=Platform.s3)
@ -103,32 +195,60 @@ system that consists from several business and platform services:
auth_service=Services.auth,
photos_service=Services.photos)
Next example demonstrates usage of IoC containers & providers defined above:
Next example demonstrates run of dependency injection example application
defined above:
.. code-block:: python
"""Run example application."""
"""Run dependency injection example application.
import containers
Instructions for running:
python run.py 1 secret photo.jpg
"""
import sys
import logging
from containers import Platform, Application
if __name__ == '__main__':
containers.Application.main()
# Configure platform logger:
Platform.logger().addHandler(logging.StreamHandler(sys.stdout))
# Run application:
Application.main(uid=sys.argv[1],
password=sys.argv[2],
photo=sys.argv[3])
# Previous call is an equivalent of next operations:
#
# logger = logging.Logger(name='example')
# database = sqlite3.connect(':memory:')
# s3 = boto.s3.connection.S3Connection(aws_access_key_id='KEY',
# aws_secret_access_key='SECRET')
#
# example.main.main(users_service=example.services.Users(db=database),
# auth_service=example.services.Auth(db=database,
# example.main.main(uid=sys.argv[1],
# password=sys.argv[2],
# photo=sys.argv[3],
# users_service=example.services.Users(logger=logger,
# db=database),
# auth_service=example.services.Auth(logger=logger,
# db=database,
# token_ttl=3600),
# photos_service=example.services.Photos(db=database,
# photos_service=example.services.Photos(logger=logger,
# db=database,
# s3=s3))
#
# Output:
#
# User 1 has been found in database
# User 1 has been successfully authenticated
# Photo photo.jpg has been successfully uploaded by user 1
Alternative definition styles
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Alternative definition styles of providers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*Dependecy Injector* supports few other styles of dependency injections
definition.
@ -140,6 +260,9 @@ IoC containers from previous example could look like these:
class Platform(containers.DeclarativeContainer):
"""IoC container of platform service providers."""
logger = providers.Singleton(logging.Logger) \
.add_kwargs(name='example')
database = providers.Singleton(sqlite3.connect) \
.add_args(':memory:')
@ -154,6 +277,9 @@ or like this these:
class Platform(containers.DeclarativeContainer):
"""IoC container of platform service providers."""
logger = providers.Singleton(logging.Logger)
logger.add_kwargs(name='example')
database = providers.Singleton(sqlite3.connect)
database.add_args(':memory:')
@ -161,6 +287,7 @@ or like this these:
s3.add_kwargs(aws_access_key_id='KEY',
aws_secret_access_key='SECRET')
You can get more *Dependency Injector* examples in ``/examples`` directory on
GitHub:
@ -185,10 +312,8 @@ Feel free to post questions, bugs, feature requests, proposals etc. on
Your feedback is quite important!
.. _Dependency injection: http://en.wikipedia.org/wiki/Dependency_injection
.. _Inversion of control: https://en.wikipedia.org/wiki/Inversion_of_control
.. _PyPi: https://pypi.python.org/pypi/dependency_injector
.. _User's guide: http://python-dependency-injector.ets-labs.org/en/stable/
.. _API docs: http://python-dependency-injector.ets-labs.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

5
docs/index.rst
View File

@ -1,3 +1,4 @@
=============================================================
Dependency Injector --- Python dependency injection framework
=============================================================
@ -10,8 +11,8 @@ Dependency Injector --- Python dependency injection framework
their dependencies in formal, pretty way.
*Dependency Injector* is a Python dependency injection framework. It was
designed to be unified, developer-friendly tool for managing any kind
of Python objects and their dependencies in formal, pretty way.
designed to be unified, developer-friendly tool that helps to implement
dependency injection pattern in formal, pretty, Pythonic way.
*Dependency Injector* framework key features are:

2
examples/miniapps/services/README.rst
View File

@ -5,4 +5,4 @@ Instructions for running
.. code-block:: bash
python run.py
python run.py 1 secret photo.jpg

9
examples/miniapps/services/containers.py
View File

@ -1,6 +1,8 @@
"""Example of several Dependency Injector IoC containers."""
"""Example of dependency injection in Python."""
import logging
import sqlite3
import boto.s3.connection
import example.main
@ -13,6 +15,8 @@ import dependency_injector.providers as providers
class Platform(containers.DeclarativeContainer):
"""IoC container of platform service providers."""
logger = providers.Singleton(logging.Logger, name='example')
database = providers.Singleton(sqlite3.connect, ':memory:')
s3 = providers.Singleton(boto.s3.connection.S3Connection,
@ -24,13 +28,16 @@ class Services(containers.DeclarativeContainer):
"""IoC container of business service providers."""
users = providers.Factory(example.services.Users,
logger=Platform.logger,
db=Platform.database)
auth = providers.Factory(example.services.Auth,
logger=Platform.logger,
db=Platform.database,
token_ttl=3600)
photos = providers.Factory(example.services.Photos,
logger=Platform.logger,
db=Platform.database,
s3=Platform.s3)

16
examples/miniapps/services/containers_alt_syntax_1.py
View File

@ -1,9 +1,11 @@
"""Example of several Dependency Injector IoC containers.
"""Example of dependency injection in Python.
Alternative injections definition style #1.
"""
import logging
import sqlite3
import boto.s3.connection
import example.main
@ -16,6 +18,9 @@ import dependency_injector.providers as providers
class Platform(containers.DeclarativeContainer):
"""IoC container of platform service providers."""
logger = providers.Singleton(logging.Logger) \
.add_kwargs(name='example')
database = providers.Singleton(sqlite3.connect) \
.add_args(':memory:')
@ -28,14 +33,17 @@ class Services(containers.DeclarativeContainer):
"""IoC container of business service providers."""
users = providers.Factory(example.services.Users) \
.add_kwargs(db=Platform.database)
.add_kwargs(logger=Platform.logger,
db=Platform.database)
auth = providers.Factory(example.services.Auth) \
.add_kwargs(db=Platform.database,
.add_kwargs(logger=Platform.logger,
db=Platform.database,
token_ttl=3600)
photos = providers.Factory(example.services.Photos) \
.add_kwargs(db=Platform.database,
.add_kwargs(logger=Platform.logger,
db=Platform.database,
s3=Platform.s3)

16
examples/miniapps/services/containers_alt_syntax_2.py
View File

@ -1,9 +1,11 @@
"""Example of several Dependency Injector IoC containers.
"""Example of dependency injection in Python.
Alternative injections definition style #2.
"""
import logging
import sqlite3
import boto.s3.connection
import example.main
@ -16,6 +18,9 @@ import dependency_injector.providers as providers
class Platform(containers.DeclarativeContainer):
"""IoC container of platform service providers."""
logger = providers.Singleton(logging.Logger)
logger.add_kwargs(name='example')
database = providers.Singleton(sqlite3.connect)
database.add_args(':memory:')
@ -28,14 +33,17 @@ class Services(containers.DeclarativeContainer):
"""IoC container of business service providers."""
users = providers.Factory(example.services.Users)
users.add_kwargs(db=Platform.database)
users.add_kwargs(logger=Platform.logger,
db=Platform.database)
auth = providers.Factory(example.services.Auth)
auth.add_kwargs(db=Platform.database,
auth.add_kwargs(logger=Platform.logger,
db=Platform.database,
token_ttl=3600)
photos = providers.Factory(example.services.Photos)
photos.add_kwargs(db=Platform.database,
photos.add_kwargs(logger=Platform.logger,
db=Platform.database,
s3=Platform.s3)

8
examples/miniapps/services/example/main.py
View File

@ -1,8 +1,8 @@
"""Example main module."""
def main(users_service, auth_service, photos_service):
def main(uid, password, photo, users_service, auth_service, photos_service):
"""Example main function."""
user = users_service.get_user('user')
auth_service.authenticate(user, 'secret')
photos_service.upload_photo(user['id'], 'photo.jpg')
user = users_service.get_user_by_id(uid)
auth_service.authenticate(user, password)
photos_service.upload_photo(user['uid'], photo)

21
examples/miniapps/services/example/services.py
View File

@ -4,37 +4,44 @@
class Users(object):
"""Users service."""
def __init__(self, db):
def __init__(self, logger, db):
"""Initializer."""
self.logger = logger
self.db = db
def get_user(self, login):
def get_user_by_id(self, uid):
"""Return user's information by login."""
return {'id': 1,
'login': login,
self.logger.debug('User %s has been found in database', uid)
return {'uid': uid,
'password_hash': 'secret_hash'}
class Auth(object):
"""Auth service."""
def __init__(self, db, token_ttl):
def __init__(self, logger, db, token_ttl):
"""Initializer."""
self.logger = logger
self.db = db
self.token_ttl = token_ttl
def authenticate(self, user, password):
"""Authenticate user."""
assert user['password_hash'] == '_'.join((password, 'hash'))
self.logger.debug('User %s has been successfully authenticated',
user['uid'])
class Photos(object):
"""Photos service."""
def __init__(self, db, s3):
def __init__(self, logger, db, s3):
"""Initializer."""
self.logger = logger
self.db = db
self.s3 = s3
def upload_photo(self, user_id, photo_path):
def upload_photo(self, uid, photo_path):
"""Upload user photo."""
self.logger.debug('Photo %s has been successfully uploaded by user %s',
photo_path, uid)

39
examples/miniapps/services/run.py
View File

@ -1,19 +1,46 @@
"""Run example application."""
"""Run dependency injection example application.
import containers
Instructions for running:
python run.py 1 secret photo.jpg
"""
import sys
import logging
from containers import Platform, Application
if __name__ == '__main__':
containers.Application.main()
# Configure platform logger:
Platform.logger().addHandler(logging.StreamHandler(sys.stdout))
# Run application:
Application.main(uid=sys.argv[1],
password=sys.argv[2],
photo=sys.argv[3])
# Previous call is an equivalent of next operations:
#
# logger = logging.Logger(name='example')
# database = sqlite3.connect(':memory:')
# s3 = boto.s3.connection.S3Connection(aws_access_key_id='KEY',
# aws_secret_access_key='SECRET')
#
# example.main.main(users_service=example.services.Users(db=database),
# auth_service=example.services.Auth(db=database,
# example.main.main(uid=sys.argv[1],
# password=sys.argv[2],
# photo=sys.argv[3],
# users_service=example.services.Users(logger=logger,
# db=database),
# auth_service=example.services.Auth(logger=logger,
# db=database,
# token_ttl=3600),
# photos_service=example.services.Photos(db=database,
# photos_service=example.services.Photos(logger=logger,
# db=database,
# s3=s3))
#
# Output:
#
# User 1 has been found in database
# User 1 has been successfully authenticated
# Photo photo.jpg has been successfully uploaded by user 1