Merge branch 'release/3.10.0' into master

Author: rmk135

docs/examples/index.rst

@@ -18,3 +18,4 @@ and powered by *Dependency Injector* framework.
     movie_lister
     services_miniapp
     bundles_miniapp
+    use_cases_miniapp

docs/examples/use_cases_miniapp.rst

@@ -0,0 +1,57 @@
+Use cases mini application example
+----------------------------------
+
+.. currentmodule:: dependency_injector.providers
+
+"Use cases" miniapp demonstrate usage of :py:class:`DependenciesContainer` 
+provider.
+
+Example application
+~~~~~~~~~~~~~~~~~~~
+
+"Use cases" mini application has next structure:
+
+.. code-block:: bash
+
+    use_cases/
+        example/               <-- Example package
+            __init__.py
+            adapters.py
+            use_cases.py
+        containers.py          <-- Dependency injection containers
+        run.py                 <-- Entrypoint
+
+
+IoC containers
+~~~~~~~~~~~~~~
+
+Listing of ``use_cases/containers.py``:
+
+.. literalinclude:: ../../examples/miniapps/use_cases/containers.py
+   :language: python
+   :linenos:
+
+Run application
+~~~~~~~~~~~~~~~
+
+Listing of ``run.py``:
+
+.. literalinclude:: ../../examples/miniapps/use_cases/run.py
+   :language: python
+   :linenos:
+
+Instructions for running:
+
+.. code-block:: bash
+
+    python run.py prod [email protected]  # Running in "production" environment
+    python run.py test [email protected]  # Running in "testing" environment
+
+Links
+~~~~~
+
++ `Dependency Injector <https://github.com/ets-labs/python-dependency-injector/>`_
++ `Full example sources <https://github.com/ets-labs/python-dependency-injector/tree/master/examples/miniapps/use_cases>`_
+
+
+.. disqus::

docs/main/changelog.rst

@@ -7,6 +7,15 @@ that were made in every particular version.
 From version 0.7.6 *Dependency Injector* framework strictly 
 follows `Semantic versioning`_
 
+
+3.10.0
+------
+- Add ``DependenciesContainer`` provider.
+- Add "use_cases" example miniapp.
+- Update documentation requirements to use fixed version of 
+  ``sphinxcontrib-disqus``.
+
+
 3.9.1
 -----
 - Fix docs build problem (``sphinx`` is frozen on ``1.5.6`` version because of

examples/miniapps/movie_lister/movies/__init__.py

@@ -23,10 +23,10 @@
 class MoviesModule(containers.DeclarativeContainer):
     """IoC container of movies module component providers."""
 
-    models_factory = providers.Factory(movies.models.Movie)
+    movie = providers.Factory(movies.models.Movie)
 
     finder = providers.AbstractFactory(movies.finders.MovieFinder,
-                                       movie_model=models_factory.delegate())
+                                       movie_model=movie.provider)
 
     lister = providers.Factory(movies.listers.MovieLister,
                                movie_finder=finder)

examples/miniapps/use_cases/README.rst

@@ -0,0 +1,9 @@
+Dependency Injector Use Cases example
+=====================================
+
+Instructions for running
+
+.. code-block:: bash
+
+    python run.py prod [email protected]  # Running in "production" environment
+    python run.py test [email protected]  # Running in "testing" environment

examples/miniapps/use_cases/containers.py

@@ -0,0 +1,30 @@
+"""Dependency injection containers for 'Use Cases' example application."""
+
+from dependency_injector import containers, providers
+
+from example.adapters import SmtpEmailSender, EchoEmailSender
+from example.use_cases import SignupUseCase
+
+
+class Adapters(containers.DeclarativeContainer):
+    """Adapters container."""
+
+    email_sender = providers.Singleton(SmtpEmailSender)
+
+
+class TestAdapters(containers.DeclarativeContainer):
+    """Adapters container.
+
+    This container is used for testing purposes.
+    """
+
+    email_sender = providers.Singleton(EchoEmailSender)
+
+
+class UseCases(containers.DeclarativeContainer):
+    """Use cases container."""
+
+    adapters = providers.DependenciesContainer()
+
+    signup = providers.Factory(SignupUseCase,
+                               email_sender=adapters.email_sender)

examples/miniapps/use_cases/example/__init__.py

@@ -0,0 +1 @@
+"""Example top-level package."""

examples/miniapps/use_cases/example/adapters.py

@@ -0,0 +1,25 @@
+"""Example adapters package."""
+
+
+class EmailSender(object):
+    """Abstract email sender."""
+
+    def send(self, to, body):
+        """Send email to specified email."""
+        raise NotImplementedError()
+
+
+class SmtpEmailSender(object):
+    """SMTP email sender uses SMTP protocol for sending emails."""
+
+    def send(self, to, body):
+        """Send email to specified email."""
+        # Send email via SMTP
+
+
+class EchoEmailSender(object):
+    """Echo email sender prints emails to stdout."""
+
+    def send(self, to, body):
+        """Send email to specified email."""
+        print('Sending email to "{0}", body = "{1}"'.format(to, body))

examples/miniapps/use_cases/example/use_cases.py

@@ -0,0 +1,22 @@
+"""Example use cases package."""
+
+
+class UseCase(object):
+    """Abstract use case."""
+
+    def execute(self):
+        """Execute use case handling."""
+        raise NotImplementedError()
+
+
+class SignupUseCase(object):
+    """Sign up use cases registers users."""
+
+    def __init__(self, email_sender):
+        """Initializer."""
+        self.email_sender = email_sender
+
+    def execute(self, email):
+        """Execute use case handling."""
+        print('Sign up user {0}'.format(email))
+        self.email_sender.send(email, 'Welcome, "{}"'.format(email))

examples/miniapps/use_cases/run.py

@@ -0,0 +1,19 @@
+"""Run 'Use Cases' example application."""
+
+import sys
+
+from containers import Adapters, TestAdapters, UseCases
+
+
+if __name__ == '__main__':
+    environment, email = sys.argv[1:]
+
+    if environment == 'prod':
+        adapters = Adapters()
+    elif environment == 'test':
+        adapters = TestAdapters()
+
+    use_cases = UseCases(adapters=adapters)
+
+    use_case = use_cases.signup()
+    use_case.execute(email)