List provider (#251)

* Add List provider

* Add List provider example

* Add List provider unit tests

* Add docs

* Upstream changes from develop

* Update API docs

* Update unit tests

* Add support of positional context argument injections

* Update changelog

docs/main/changelog.rst

@@ -10,6 +10,9 @@ follows `Semantic versioning`_
 Development version
 -------------------
 
+- Add ``List`` provider
+  `issue #243 <https://github.com/ets-labs/python-dependency-injector/issues/243>`_,
+  `PR #251 <https://github.com/ets-labs/python-dependency-injector/pull/251>`_.
 - Fix a few typos in docs (thanks to `Bruno P. Kinoshita <https://github.com/kinow>`_,
   `issue #249 <https://github.com/ets-labs/python-dependency-injector/issues/249>`_,
   `PR #250 <https://github.com/ets-labs/python-dependency-injector/pull/250>`_).

docs/providers/index.rst

@@ -22,6 +22,7 @@ Providers package API docs - :py:mod:`dependency_injector.providers`
     callable
     coroutine
     object
+    list
     dependency
     overriding
     custom

docs/providers/list.rst

@@ -0,0 +1,34 @@
+List providers
+--------------
+
+.. currentmodule:: dependency_injector.providers
+
+:py:class:`List` provider provides a list of values.
+
+.. literalinclude:: ../../examples/providers/list.py
+   :language: python
+   :lines: 23-29
+   :linenos:
+
+:py:class:`List` provider is needed for injecting a list of dependencies. It handles
+positional argument injections the same way as :py:class:`Factory` provider:
+
++ All providers (instances of :py:class:`Provider`) are called every time
+  when injection needs to be done.
++ Providers could be injected "as is" (delegated), if it is defined explicitly. Check out
+  :ref:`factory_providers_delegation`.
++ All other values are injected *"as is"*.
++ Positional context arguments will be appended after :py:class:`List` positional injections.
+
+Full example:
+
+.. literalinclude:: ../../examples/providers/list.py
+   :language: python
+   :emphasize-lines: 23-29
+   :linenos:
+
+.. note::
+
+    Keyword argument injections are not supported.
+
+.. disqus::

examples/providers/list.py

@@ -0,0 +1,45 @@
+"""`List` provider example."""
+
+import dataclasses
+from typing import List
+
+from dependency_injector import providers
+
+
+@dataclasses.dataclass
+class Module:
+    """Example module."""
+
+    name: str
+
+
+@dataclasses.dataclass
+class Dispatcher:
+    """Example dispatcher."""
+
+    modules: List[Module]
+
+
+dispatcher_factory = providers.Factory(
+    Dispatcher,
+    modules=providers.List(
+        providers.Factory(Module, name='m1'),
+        providers.Factory(Module, name='m2'),
+    ),
+)
+
+if __name__ == '__main__':
+    dispatcher = dispatcher_factory()
+
+    assert isinstance(dispatcher.modules, list)
+    assert dispatcher.modules[0].name == 'm1'
+    assert dispatcher.modules[1].name == 'm2'
+
+    # Call of dispatcher_factory() is equivalent to:
+
+    dispatcher = Dispatcher(
+        modules=[
+            Module(name='m1'),
+            Module(name='m2'),
+        ],
+    )

src/dependency_injector/providers.pxd

@@ -75,6 +75,7 @@ cdef class CallableDelegate(Delegate):
 cdef class Coroutine(Callable):
     pass
 
+
 cdef class DelegatedCoroutine(Coroutine):
     pass
 
@@ -165,6 +166,15 @@ cdef class SingletonDelegate(Delegate):
     pass
 
 
+# Miscellaneous providers
+
+cdef class List(Provider):
+    cdef tuple __args
+    cdef int __args_len
+
+    cpdef object _provide(self, tuple args, dict kwargs)
+
+
 # Injections
 cdef class Injection(object):
     cdef object __value

src/dependency_injector/providers.pyx

@@ -1966,6 +1966,108 @@ cdef class SingletonDelegate(Delegate):
         super(SingletonDelegate, self).__init__(singleton)
 
 
+cdef class List(Provider):
+    """List provider provides a list of values.
+
+    :py:class:`List` provider is needed for injecting a list of dependencies. It handles
+    positional argument injections the same way as :py:class:`Factory` provider.
+
+    Keyword argument injections are not supported.
+
+    .. code-block:: python
+
+        dispatcher_factory = Factory(
+            Dispatcher,
+            modules=List(
+                Factory(ModuleA, dependency_a),
+                Factory(ModuleB, dependency_b),
+            ),
+        )
+
+        dispatcher = dispatcher_factory()
+
+        # is equivalent to:
+
+        dispatcher = Dispatcher(
+            modules=[
+                ModuleA(dependency_a),
+                ModuleB(dependency_b),
+            ],
+        )
+    """
+
+    def __init__(self, *args):
+        """Initializer."""
+        self.__args = tuple()
+        self.__args_len = 0
+        self.set_args(*args)
+        super(List, self).__init__()
+
+    def __deepcopy__(self, memo):
+        """Create and return full copy of provider."""
+        copied = memo.get(id(self))
+        if copied is not None:
+            return copied
+
+        copied = self.__class__(*deepcopy(self.args, memo))
+        self._copy_overridings(copied, memo)
+
+        return copied
+
+    def __str__(self):
+        """Return string representation of provider.
+
+        :rtype: str
+        """
+        return represent_provider(provider=self, provides=list(self.args))
+
+    @property
+    def args(self):
+        """Return positional argument injections."""
+        cdef int index
+        cdef PositionalInjection arg
+        cdef list args
+
+        args = list()
+        for index in range(self.__args_len):
+            arg = self.__args[index]
+            args.append(arg.__value)
+        return tuple(args)
+
+    def add_args(self, *args):
+        """Add positional argument injections.
+
+        :return: Reference ``self``
+        """
+        self.__args += parse_positional_injections(args)
+        self.__args_len = len(self.__args)
+        return self
+
+    def set_args(self, *args):
+        """Set positional argument injections.
+
+        Existing positional argument injections are dropped.
+
+        :return: Reference ``self``
+        """
+        self.__args = parse_positional_injections(args)
+        self.__args_len = len(self.__args)
+        return self
+
+    def clear_args(self):
+        """Drop positional argument injections.
+
+        :return: Reference ``self``
+        """
+        self.__args = tuple()
+        self.__args_len = len(self.__args)
+        return self
+
+    cpdef object _provide(self, tuple args, dict kwargs):
+        """Return result of provided callable's call."""
+        return list(__provide_positional_args(args, self.__args, self.__args_len))
+
+
 cdef class Injection(object):
     """Abstract injection class."""
 

tests/unit/providers/test_list_py2_py3.py

@@ -0,0 +1,136 @@
+"""Dependency injector list provider unit tests."""
+
+import sys
+
+import unittest2 as unittest
+
+from dependency_injector import providers
+
+
+class ListTests(unittest.TestCase):
+
+    def test_is_provider(self):
+        self.assertTrue(providers.is_provider(providers.List()))
+
+    def test_call_with_init_positional_args(self):
+        provider = providers.List('i1', 'i2')
+
+        list1 = provider()
+        list2 = provider()
+
+        self.assertEqual(list1, ['i1', 'i2'])
+        self.assertEqual(list2, ['i1', 'i2'])
+
+        self.assertIsNot(list1, list2)
+
+    def test_call_with_context_args(self):
+        provider = providers.List('i1', 'i2')
+
+        self.assertEqual(provider('i3', 'i4'), ['i1', 'i2', 'i3', 'i4'])
+
+    def test_fluent_interface(self):
+        provider = providers.List() \
+            .add_args(1, 2)
+
+        self.assertEqual(provider(), [1, 2])
+
+    def test_set_args(self):
+        provider = providers.List() \
+            .add_args(1, 2) \
+            .set_args(3, 4)
+        self.assertEqual(provider.args, tuple([3, 4]))
+
+    def test_clear_args(self):
+        provider = providers.List() \
+            .add_args(1, 2) \
+            .clear_args()
+        self.assertEqual(provider.args, tuple())
+
+    def test_call_overridden(self):
+        provider = providers.List(1, 2)
+        overriding_provider1 = providers.List(2, 3)
+        overriding_provider2 = providers.List(3, 4)
+
+        provider.override(overriding_provider1)
+        provider.override(overriding_provider2)
+
+        instance1 = provider()
+        instance2 = provider()
+
+        self.assertIsNot(instance1, instance2)
+        self.assertEqual(instance1, [3, 4])
+        self.assertEqual(instance2, [3, 4])
+
+    def test_deepcopy(self):
+        provider = providers.List(1, 2)
+
+        provider_copy = providers.deepcopy(provider)
+
+        self.assertIsNot(provider, provider_copy)
+        self.assertEqual(provider.args, provider_copy.args)
+        self.assertIsInstance(provider, providers.List)
+
+    def test_deepcopy_from_memo(self):
+        provider = providers.List(1, 2)
+        provider_copy_memo = providers.List(1, 2)
+
+        provider_copy = providers.deepcopy(
+            provider, memo={id(provider): provider_copy_memo})
+
+        self.assertIs(provider_copy, provider_copy_memo)
+
+    def test_deepcopy_args(self):
+        provider = providers.List()
+        dependent_provider1 = providers.Factory(list)
+        dependent_provider2 = providers.Factory(dict)
+
+        provider.add_args(dependent_provider1, dependent_provider2)
+
+        provider_copy = providers.deepcopy(provider)
+        dependent_provider_copy1 = provider_copy.args[0]
+        dependent_provider_copy2 = provider_copy.args[1]
+
+        self.assertNotEqual(provider.args, provider_copy.args)
+
+        self.assertIs(dependent_provider1.cls, dependent_provider_copy1.cls)
+        self.assertIsNot(dependent_provider1, dependent_provider_copy1)
+
+        self.assertIs(dependent_provider2.cls, dependent_provider_copy2.cls)
+        self.assertIsNot(dependent_provider2, dependent_provider_copy2)
+
+    def test_deepcopy_overridden(self):
+        provider = providers.List()
+        object_provider = providers.Object(object())
+
+        provider.override(object_provider)
+
+        provider_copy = providers.deepcopy(provider)
+        object_provider_copy = provider_copy.overridden[0]
+
+        self.assertIsNot(provider, provider_copy)
+        self.assertEqual(provider.args, provider_copy.args)
+        self.assertIsInstance(provider, providers.List)
+
+        self.assertIsNot(object_provider, object_provider_copy)
+        self.assertIsInstance(object_provider_copy, providers.Object)
+
+    def test_deepcopy_with_sys_streams(self):
+        provider = providers.List()
+        provider.add_args(sys.stdin, sys.stdout, sys.stderr)
+
+        provider_copy = providers.deepcopy(provider)
+
+        self.assertIsNot(provider, provider_copy)
+        self.assertIsInstance(provider_copy, providers.List)
+        self.assertIs(provider.args[0], sys.stdin)
+        self.assertIs(provider.args[1], sys.stdout)
+        self.assertIs(provider.args[2], sys.stderr)
+
+    def test_repr(self):
+        provider = providers.List(1, 2)
+
+        self.assertEqual(repr(provider),
+                         '<dependency_injector.providers.'
+                         'List({0}) at {1}>'.format(
+                             repr(list(provider.args)),
+                             hex(id(provider))))