Resources (#312)

* Add prototype

* Add example

* Remove typing erros in Python 2.7 and 3.4

* Move resources example

* Draft resources docs

* Update resources docs

* Fix repr

* Rename dict provider test

* Add more tests

* Add tests + refactoring

* Add more tests

* Update tests to run only on 3.5+

* Update setup.py

* Add typing tests

* Update changelog

* Fix generator iteration

* Remove contextlib

* Hotfix aiohttp issue

* Move aiohttp fix to tox.ini

* Move aiohttp fix to a different place in tox

Author: rmk135

README.rst

@@ -57,17 +57,20 @@ It helps implementing the dependency injection principle.
 Key features of the ``Dependency Injector``:
 
 - **Providers**. Provides ``Factory``, ``Singleton``, ``Callable``, ``Coroutine``, ``Object``,
-  ``List``, ``Dict``, ``Configuration``, ``Dependency`` and ``Selector`` providers that help
-  assembling your objects.
+  ``List``, ``Dict``, ``Configuration``, ``Resource``, ``Dependency`` and ``Selector`` providers
+  that help assembling your objects.
   See `Providers <https://python-dependency-injector.ets-labs.org/providers/index.html>`_.
 - **Overriding**. Can override any provider by another provider on the fly. This helps in testing
   and configuring dev / stage environment to replace API clients with stubs etc. See
   `Provider overriding <https://python-dependency-injector.ets-labs.org/providers/overriding.html>`_.
-- **Configuration**. Read configuration from ``yaml`` & ``ini`` files, environment variables
+- **Configuration**. Reads configuration from ``yaml`` & ``ini`` files, environment variables
   and dictionaries.
   See `Configuration provider <https://python-dependency-injector.ets-labs.org/providers/configuration.html>`_.
 - **Containers**. Provides declarative and dynamic containers.
   See `Containers <https://python-dependency-injector.ets-labs.org/containers/index.html>`_.
+- **Resources**. Helps with initialization and configuring of logging, event loop, thread
+  or process pool, etc.
+  See `Resource provider <https://python-dependency-injector.ets-labs.org/providers/resource.html>`_.
 - **Wiring**. Injects dependencies into functions and methods. Helps integrating with
   other frameworks: Django, Flask, Aiohttp, etc.
   See `Wiring <https://python-dependency-injector.ets-labs.org/wiring.html>`_.

docs/index.rst

@@ -69,13 +69,15 @@ It helps implementing the dependency injection principle.
 Key features of the ``Dependency Injector``:
 
 - **Providers**. Provides ``Factory``, ``Singleton``, ``Callable``, ``Coroutine``, ``Object``,
-  ``List``, ``Dict``, ``Configuration``, ``Dependency`` and ``Selector`` providers that help
-  assembling your objects. See :ref:`providers`.
+  ``List``, ``Dict``, ``Configuration``, ``Resource``, ``Dependency`` and ``Selector`` providers
+  that help assembling your objects. See :ref:`providers`.
 - **Overriding**. Can override any provider by another provider on the fly. This helps in testing
   and configuring dev / stage environment to replace API clients with stubs etc. See
   :ref:`provider-overriding`.
-- **Configuration**. Read configuration from ``yaml`` & ``ini`` files, environment variables
+- **Configuration**. Reads configuration from ``yaml`` & ``ini`` files, environment variables
   and dictionaries. See :ref:`configuration-provider`.
+- **Resources**. Helps with initialization and configuring of logging, event loop, thread
+  or process pool, etc. See :ref:`resource-provider`.
 - **Containers**. Provides declarative and dynamic containers. See :ref:`containers`.
 - **Wiring**. Injects dependencies into functions and methods. Helps integrating with
   other frameworks: Django, Flask, Aiohttp, etc. See :ref:`wiring`.

docs/introduction/key_features.rst

@@ -11,13 +11,15 @@ Key features
 Key features of the ``Dependency Injector``:
 
 - **Providers**. Provides ``Factory``, ``Singleton``, ``Callable``, ``Coroutine``, ``Object``,
-  ``List``, ``Dict``, ``Configuration``, ``Dependency`` and ``Selector`` providers that help
-  assembling your objects. See :ref:`providers`.
+  ``List``, ``Dict``, ``Configuration``, ``Resource``, ``Dependency`` and ``Selector`` providers
+  that help assembling your objects. See :ref:`providers`.
 - **Overriding**. Can override any provider by another provider on the fly. This helps in testing
   and configuring dev / stage environment to replace API clients with stubs etc. See
   :ref:`provider-overriding`.
-- **Configuration**. Read configuration from ``yaml`` & ``ini`` files, environment variables
+- **Configuration**. Reads configuration from ``yaml`` & ``ini`` files, environment variables
   and dictionaries. See :ref:`configuration-provider`.
+- **Resources**. Helps with initialization and configuring of logging, event loop, thread
+  or process pool, etc. See :ref:`resource-provider`.
 - **Containers**. Provides declarative and dynamic containers. See :ref:`containers`.
 - **Wiring**. Injects dependencies into functions and methods. Helps integrating with
   other frameworks: Django, Flask, Aiohttp, etc. See :ref:`wiring`.

docs/main/changelog.rst

@@ -9,13 +9,15 @@ follows `Semantic versioning`_
 
 Develop
 -------
+- Add ``Resource`` provider.
 - Add ``Dict`` provider.
 - "Un-deprecate" ``@containers.override()`` and ``@containers.copy()`` decorators (
   see `Issue 301 <https://github.com/ets-labs/python-dependency-injector/issues/301>`_
   for more information).
 - Add favicon.
 - Remove redirects that occur while getting badge images to optimize docs load speed.
 - Update license year.
+- Update short description on PyPI.
 
 4.0.6
 -----

docs/providers/index.rst

@@ -45,6 +45,7 @@ Providers module API docs - :py:mod:`dependency_injector.providers`
     list
     dict
     configuration
+    resource
     selector
     dependency
     overriding

docs/providers/resource.rst

@@ -0,0 +1,206 @@
+.. _resource-provider:
+
+Resource provider
+=================
+
+.. meta::
+   :keywords: Python,DI,Dependency injection,IoC,Inversion of Control,Resource,Injection,
+              Logging,Event Loop,Thread Pool
+   :description: Resource provider provides a component with initialization and shutdown. It works
+                 well for configuring logging, event loop, thread or process pool, etc.
+                 This page demonstrates how to use resource provider.
+
+.. currentmodule:: dependency_injector.providers
+
+:py:class:`Resource` provider provides a component with initialization and shutdown.
+
+.. literalinclude:: ../../examples/providers/resource.py
+   :language: python
+   :lines: 3-
+
+Resource providers help to initialize and configure logging, event loop, thread or process pool, etc.
+
+Resource provider is similar to ``Singleton``. Resource initialization happens only once.
+You can do injections and use provided instance the same way like you do with any other provider.
+
+.. code-block:: python
+   :emphasize-lines: 12
+
+   class Container(containers.DeclarativeContainer):
+
+       config = providers.Configuration()
+
+       thread_pool = providers.Resource(
+           init_threat_pool,
+           max_workers=config.max_workers,
+       )
+
+       dispatcher = providers.Factory(
+           TaskDispatcher,
+           executor=thread_pool,
+       )
+
+Container has an interface to initialize and shutdown all resources:
+
+.. code-block:: python
+
+   container = Container()
+   container.init_resources()
+   container.shutdown_resources()
+
+You also can initialize and shutdown resources one-by-one using ``init()`` and
+``shutdown()`` methods of the provider:
+
+.. code-block:: python
+
+   container = Container()
+   container.thread_pool.init()
+   container.thread_pool.shutdown()
+
+Resource provider supports 3 types of initializers:
+
+- Function
+- Generator
+- Subclass of ``resources.Resource``
+
+Function initializer
+--------------------
+
+Function is the most common way to specify resource initialization:
+
+.. code-block:: python
+
+   def init_resource(argument1=..., argument2=...):
+       return SomeResource()
+
+
+   class Container(containers.DeclarativeContainer):
+
+       resource = providers.Resource(
+           init_resource,
+           argument1=...,
+           argument2=...,
+       )
+
+Function initializer may not return a value. This often happens when
+you configure global resource:
+
+.. code-block:: python
+
+   import logging.config
+
+
+   class Container(containers.DeclarativeContainer):
+
+       configure_logging = providers.Resource(
+           logging.config.fileConfig,
+           fname='logging.ini',
+       )
+
+Function initializer does not support shutdown.
+
+Generator initializer
+---------------------
+
+Resource provider can use 2-step generators:
+
+- First step of generator is an initialization phase
+- The second is step is a shutdown phase
+
+.. code-block:: python
+
+   def init_resource(argument1=..., argument2=...):
+       resource = SomeResource()  # initialization
+
+       yield resource
+
+       # shutdown
+       ...
+
+
+   class Container(containers.DeclarativeContainer):
+
+       resource = providers.Resource(
+           init_resource,
+           argument1=...,
+           argument2=...,
+       )
+
+Generator initialization phase ends on the first ``yield`` statement. You can return a
+resource object using ``yield resource`` like in the example above. Returning of the
+object is not mandatory. You can leave ``yield`` statement empty:
+
+.. code-block:: python
+
+   def init_resource(argument1=..., argument2=...):
+       # initialization
+       ...
+
+       yield
+
+       # shutdown
+       ...
+
+
+   class Container(containers.DeclarativeContainer):
+
+       resource = providers.Resource(
+           init_resource,
+           argument1=...,
+           argument2=...,
+       )
+
+Subclass initializer
+--------------------
+
+You can create resource initializer by implementing a subclass of the ``resources.Resource``:
+
+.. code-block:: python
+
+   from dependency_injector import resources
+
+
+   class MyResource(resources.Resource):
+
+       def init(self, argument1=..., argument2=...) -> SomeResource:
+           return SomeResource()
+
+       def shutdown(self, resource: SomeResource) -> None:
+           # shutdown
+           ...
+
+
+   class Container(containers.DeclarativeContainer):
+
+       resource = providers.Resource(
+           MyResource,
+           argument1=...,
+           argument2=...,
+       )
+
+Subclass must implement two methods: ``init()`` and ``shutdown()``.
+
+Method ``init()`` receives arguments specified in resource provider.
+It performs initialization and returns resource object. Returning of the object
+is not mandatory.
+
+Method ``shutdown()`` receives resource object returned from ``init()``. If ``init()``
+didn't return an object ``shutdown()`` method will be called anyway with ``None`` as a
+first argument.
+
+.. code-block:: python
+
+   from dependency_injector import resources
+
+
+   class MyResource(resources.Resource):
+
+       def init(self, argument1=..., argument2=...) -> None:
+           # initialization
+           ...
+
+       def shutdown(self, _: None) -> None:
+           # shutdown
+           ...
+
+.. disqus::

examples/providers/resource.py

@@ -0,0 +1,41 @@
+"""`Resource` provider example."""
+
+import sys
+import logging
+from concurrent.futures import ThreadPoolExecutor
+
+from dependency_injector import containers, providers
+
+
+def init_threat_pool(max_workers: int):
+    thread_pool = ThreadPoolExecutor(max_workers=max_workers)
+    yield thread_pool
+    thread_pool.shutdown(wait=True)
+
+
+class Container(containers.DeclarativeContainer):
+
+    config = providers.Configuration()
+
+    thread_pool = providers.Resource(
+        init_threat_pool,
+        max_workers=config.max_workers,
+    )
+
+    logging = providers.Resource(
+        logging.basicConfig,
+        level=logging.INFO,
+        stream=sys.stdout,
+    )
+
+
+if __name__ == '__main__':
+    container = Container(config={'max_workers': 4})
+
+    container.init_resources()
+
+    logging.info('Resources are initialized')
+    thread_pool = container.thread_pool()
+    thread_pool.map(print, range(10))
+
+    container.shutdown_resources()

setup.py

@@ -31,11 +31,11 @@
 
 setup(name='dependency-injector',
       version=version,
-      description='Dependency injection microframework for Python',
+      description='Dependency injection framework for Python',
       long_description=description,
       author='ETS Labs',
       author_email='rmogilatov@gmail.com',
-      maintainer='Roman Mogilatov',
+      maintainer='Roman Mogylatov',
       maintainer_email='rmogilatov@gmail.com',
       url='https://github.com/ets-labs/python-dependency-injector',
       download_url='https://pypi.python.org/pypi/dependency_injector',