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

README.rst

@@ -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
+designed to be unified, developer-friendly tool that helps to implement 
-of Python objects and their dependencies in formal, pretty way.
+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 
+`Dependency injection`_ is a software design pattern that implements 
-providers for definition of several IoC containers for some microservice 
+`Inversion of control`_ for resolving dependencies. Formally, if object **A** 
-system that consists from several business and platform services:
+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),
+        # example.main.main(uid=sys.argv[1],
-        #                   auth_service=example.services.Auth(db=database,
+        #                   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

docs/index.rst

@@ -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
+designed to be unified, developer-friendly tool that helps to implement 
-of Python objects and their dependencies in formal, pretty way.
+dependency injection pattern in formal, pretty, Pythonic way.
 
 *Dependency Injector* framework key features are:
 

examples/miniapps/services/README.rst

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

examples/miniapps/services/containers.py

@@ -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)
 

examples/miniapps/services/containers_alt_syntax_1.py

@@ -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)
 
 

examples/miniapps/services/containers_alt_syntax_2.py

@@ -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)
 
 

examples/miniapps/services/example/main.py

@@ -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')
+    user = users_service.get_user_by_id(uid)
-    auth_service.authenticate(user, 'secret')
+    auth_service.authenticate(user, password)
-    photos_service.upload_photo(user['id'], 'photo.jpg')
+    photos_service.upload_photo(user['uid'], photo)

examples/miniapps/services/example/services.py

@@ -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,
+        self.logger.debug('User %s has been found in database', uid)
-                'login': login,
+        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)

examples/miniapps/services/run.py

@@ -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),
+    # example.main.main(uid=sys.argv[1],
-    #                   auth_service=example.services.Auth(db=database,
+    #                   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