Add abstract providers

docs/main/changelog.rst

@@ -13,6 +13,9 @@ Development version
 
 3.4.0
 -----
+- Add ``AbstractCallable`` provider.
+- Add ``AbstractFactory`` provider.
+- Add ``AbstractSingleton`` provider.
 - Optimize calling of overridden providers (~15% faster).
 
 3.3.7

src/dependency_injector/providers.pxd

@@ -50,6 +50,10 @@ cdef class DelegatedCallable(Callable):
     pass
 
 
+cdef class AbstractCallable(Callable):
+    cpdef object _provide(self, tuple args, dict kwargs)
+
+
 # Configuration providers
 cdef class Configuration(Provider):
     cdef str __name
@@ -76,6 +80,10 @@ cdef class DelegatedFactory(Factory):
     pass
 
 
+cdef class AbstractFactory(Factory):
+    cpdef object _provide(self, tuple args, dict kwargs)
+
+
 # Singleton providers
 cdef class BaseSingleton(Provider):
     cdef Factory __instantiator
@@ -112,6 +120,10 @@ cdef class DelegatedThreadLocalSingleton(ThreadLocalSingleton):
     pass
 
 
+cdef class AbstractSingleton(BaseSingleton):
+    pass
+
+
 # Injections
 cdef class Injection(object):
     cdef object __value

src/dependency_injector/providers.pyx

@@ -593,6 +593,47 @@ cdef class DelegatedCallable(Callable):
     __IS_DELEGATED__ = True
 
 
+cdef class AbstractCallable(Callable):
+    """Abstract callable provider.
+
+    :py:class:`AbstractCallable` is a :py:class:`Callable` provider that must
+    be explicitly overridden before calling.
+
+    Overriding of :py:class:`AbstractCallable` is possible only by another
+    :py:class:`Callable` provider.
+    """
+
+    def __call__(self, *args, **kwargs):
+        """Return provided object.
+
+        Callable interface implementation.
+        """
+        if self.__last_overriding is None:
+            raise Error('{0} must be overridden before calling'.format(self))
+        return self.__last_overriding._provide(args, kwargs)
+
+    def override(self, provider):
+        """Override provider with another provider.
+
+        :param provider: Overriding provider.
+        :type provider: :py:class:`Provider`
+
+        :raise: :py:exc:`dependency_injector.errors.Error`
+
+        :return: Overriding context.
+        :rtype: :py:class:`OverridingContext`
+        """
+        if not isinstance(provider, Callable):
+            raise Error('{0} must be overridden only by '
+                        '{1} providers'.format(self, Callable))
+        return super(AbstractCallable, self).override(provider)
+
+    cpdef object _provide(self, tuple args, dict kwargs):
+        """Return result of provided callable's call."""
+        raise NotImplementedError('Abstract provider forward providing logic '
+                                  'to overriding provider')
+
+
 cdef class Configuration(Provider):
     """Configuration provider.
 
@@ -967,6 +1008,46 @@ cdef class DelegatedFactory(Factory):
     __IS_DELEGATED__ = True
 
 
+cdef class AbstractFactory(Factory):
+    """Abstract factory provider.
+
+    :py:class:`AbstractFactory` is a :py:class:`Factory` provider that must
+    be explicitly overridden before calling.
+
+    Overriding of :py:class:`AbstractFactory` is possible only by another
+    :py:class:`Factory` provider.
+    """
+
+    def __call__(self, *args, **kwargs):
+        """Return provided object.
+
+        Callable interface implementation.
+        """
+        if self.__last_overriding is None:
+            raise Error('{0} must be overridden before calling'.format(self))
+        return self.__last_overriding._provide(args, kwargs)
+
+    def override(self, provider):
+        """Override provider with another provider.
+
+        :param provider: Overriding provider.
+        :type provider: :py:class:`Provider`
+
+        :raise: :py:exc:`dependency_injector.errors.Error`
+
+        :return: Overriding context.
+        :rtype: :py:class:`OverridingContext`
+        """
+        if not isinstance(provider, Factory):
+            raise Error('{0} must be overridden only by '
+                        '{1} providers'.format(self, Factory))
+        return super(AbstractFactory, self).override(provider)
+
+    cpdef object _provide(self, tuple args, dict kwargs):
+        """Return result of provided callable's call."""
+        raise NotImplementedError('Abstract provider forward providing logic '
+                                  'to overriding provider')
+
 cdef class BaseSingleton(Provider):
     """Base class of singleton providers."""
 
@@ -1353,6 +1434,51 @@ cdef class DelegatedThreadLocalSingleton(ThreadLocalSingleton):
     __IS_DELEGATED__ = True
 
 
+cdef class AbstractSingleton(BaseSingleton):
+    """Abstract singleton provider.
+
+    :py:class:`AbstractSingleton` is a :py:class:`Singleton` provider that must
+    be explicitly overridden before calling.
+
+    Overriding of :py:class:`AbstractSingleton` is possible only by another
+    :py:class:`BaseSingleton` provider.
+    """
+
+    def __call__(self, *args, **kwargs):
+        """Return provided object.
+
+        Callable interface implementation.
+        """
+        if self.__last_overriding is None:
+            raise Error('{0} must be overridden before calling'.format(self))
+        return self.__last_overriding._provide(args, kwargs)
+
+    def override(self, provider):
+        """Override provider with another provider.
+
+        :param provider: Overriding provider.
+        :type provider: :py:class:`Provider`
+
+        :raise: :py:exc:`dependency_injector.errors.Error`
+
+        :return: Overriding context.
+        :rtype: :py:class:`OverridingContext`
+        """
+        if not isinstance(provider, BaseSingleton):
+            raise Error('{0} must be overridden only by '
+                        '{1} providers'.format(self, BaseSingleton))
+        return super(AbstractSingleton, self).override(provider)
+
+    def reset(self):
+        """Reset cached instance, if any.
+
+        :rtype: None
+        """
+        if self.__last_overriding is None:
+            raise Error('{0} must be overridden before calling'.format(self))
+        return self.__last_overriding.reset()
+
+
 cdef class Injection(object):
     """Abstract injection class."""
 

tests/performance/test.py

@@ -117,7 +117,7 @@ class Tester(object):
         for x in xrange(int(5000000 * self.duration_factor)):
             test_factory()
 
-    def test_overridden_factory_3_factory_kw_injections(self, providers):
+    def test_abstract_factory_3_factory_kw_injections(self, providers):
         """Test factory with 3 keyword argument injections via factories."""
         class A(object):
             pass
@@ -135,7 +135,7 @@ class Tester(object):
         a_factory = providers.Factory(A)
         b_factory = providers.Factory(B)
         c_factory = providers.Factory(C)
-        test_factory = providers.Factory(object)
+        test_factory = providers.AbstractFactory(object)
         test_factory.override(providers.Factory(Test,
                                                 a=a_factory,
                                                 b=b_factory,

tests/unit/providers/test_callables.py

@@ -8,13 +8,14 @@ from dependency_injector import (
 )
 
 
+def _example(arg1, arg2, arg3, arg4):
+    return arg1, arg2, arg3, arg4
+
+
 class CallableTests(unittest.TestCase):
 
-    def example(self, arg1, arg2, arg3, arg4):
-        return arg1, arg2, arg3, arg4
-
     def test_init_with_callable(self):
-        self.assertTrue(providers.Callable(self.example))
+        self.assertTrue(providers.Callable(_example))
 
     def test_init_with_not_callable(self):
         self.assertRaises(errors.Error, providers.Callable, 123)
@@ -24,66 +25,66 @@ class CallableTests(unittest.TestCase):
         self.assertTrue(provider())
 
     def test_call_with_positional_args(self):
-        provider = providers.Callable(self.example,
+        provider = providers.Callable(_example,
                                       1, 2, 3, 4)
         self.assertTupleEqual(provider(), (1, 2, 3, 4))
 
     def test_call_with_keyword_args(self):
-        provider = providers.Callable(self.example,
+        provider = providers.Callable(_example,
                                       arg1=1, arg2=2, arg3=3, arg4=4)
         self.assertTupleEqual(provider(), (1, 2, 3, 4))
 
     def test_call_with_positional_and_keyword_args(self):
-        provider = providers.Callable(self.example,
+        provider = providers.Callable(_example,
                                       1, 2,
                                       arg3=3, arg4=4)
         self.assertTupleEqual(provider(), (1, 2, 3, 4))
 
     def test_call_with_context_args(self):
-        provider = providers.Callable(self.example, 1, 2)
+        provider = providers.Callable(_example, 1, 2)
         self.assertTupleEqual(provider(3, 4), (1, 2, 3, 4))
 
     def test_call_with_context_kwargs(self):
-        provider = providers.Callable(self.example, arg1=1)
+        provider = providers.Callable(_example, arg1=1)
         self.assertTupleEqual(provider(arg2=2, arg3=3, arg4=4), (1, 2, 3, 4))
 
     def test_call_with_context_args_and_kwargs(self):
-        provider = providers.Callable(self.example, 1)
+        provider = providers.Callable(_example, 1)
         self.assertTupleEqual(provider(2, arg3=3, arg4=4), (1, 2, 3, 4))
 
     def test_fluent_interface(self):
-        provider = providers.Singleton(self.example) \
+        provider = providers.Singleton(_example) \
             .add_args(1, 2) \
             .add_kwargs(arg3=3, arg4=4)
 
         self.assertTupleEqual(provider(), (1, 2, 3, 4))
 
     def test_set_args(self):
-        provider = providers.Callable(self.example) \
+        provider = providers.Callable(_example) \
             .add_args(1, 2) \
             .set_args(3, 4)
         self.assertEqual(provider.args, tuple([3, 4]))
 
     def test_set_kwargs(self):
-        provider = providers.Callable(self.example) \
+        provider = providers.Callable(_example) \
             .add_kwargs(init_arg3=3, init_arg4=4) \
             .set_kwargs(init_arg3=4, init_arg4=5)
         self.assertEqual(provider.kwargs, dict(init_arg3=4, init_arg4=5))
 
     def test_clear_args(self):
-        provider = providers.Callable(self.example) \
+        provider = providers.Callable(_example) \
             .add_args(1, 2) \
             .clear_args()
         self.assertEqual(provider.args, tuple())
 
     def test_clear_kwargs(self):
-        provider = providers.Callable(self.example) \
+        provider = providers.Callable(_example) \
             .add_kwargs(init_arg3=3, init_arg4=4) \
             .clear_kwargs()
         self.assertEqual(provider.kwargs, dict())
 
     def test_call_overridden(self):
-        provider = providers.Callable(self.example)
+        provider = providers.Callable(_example)
 
         provider.override(providers.Object((4, 3, 2, 1)))
         provider.override(providers.Object((1, 2, 3, 4)))
@@ -91,7 +92,7 @@ class CallableTests(unittest.TestCase):
         self.assertTupleEqual(provider(), (1, 2, 3, 4))
 
     def test_deepcopy(self):
-        provider = providers.Callable(self.example)
+        provider = providers.Callable(_example)
 
         provider_copy = providers.deepcopy(provider)
 
@@ -100,8 +101,8 @@ class CallableTests(unittest.TestCase):
         self.assertIsInstance(provider, providers.Callable)
 
     def test_deepcopy_from_memo(self):
-        provider = providers.Callable(self.example)
+        provider = providers.Callable(_example)
-        provider_copy_memo = providers.Callable(self.example)
+        provider_copy_memo = providers.Callable(_example)
 
         provider_copy = providers.deepcopy(
             provider, memo={id(provider): provider_copy_memo})
@@ -109,7 +110,7 @@ class CallableTests(unittest.TestCase):
         self.assertIs(provider_copy, provider_copy_memo)
 
     def test_deepcopy_args(self):
-        provider = providers.Callable(self.example)
+        provider = providers.Callable(_example)
         dependent_provider1 = providers.Callable(list)
         dependent_provider2 = providers.Callable(dict)
 
@@ -130,7 +131,7 @@ class CallableTests(unittest.TestCase):
         self.assertIsNot(dependent_provider2, dependent_provider_copy2)
 
     def test_deepcopy_kwargs(self):
-        provider = providers.Callable(self.example)
+        provider = providers.Callable(_example)
         dependent_provider1 = providers.Callable(list)
         dependent_provider2 = providers.Callable(dict)
 
@@ -151,7 +152,7 @@ class CallableTests(unittest.TestCase):
         self.assertIsNot(dependent_provider2, dependent_provider_copy2)
 
     def test_deepcopy_overridden(self):
-        provider = providers.Callable(self.example)
+        provider = providers.Callable(_example)
         object_provider = providers.Object(object())
 
         provider.override(object_provider)
@@ -167,34 +168,86 @@ class CallableTests(unittest.TestCase):
         self.assertIsInstance(object_provider_copy, providers.Object)
 
     def test_repr(self):
-        provider = providers.Callable(self.example)
+        provider = providers.Callable(_example)
 
         self.assertEqual(repr(provider),
                          '<dependency_injector.providers.'
                          'Callable({0}) at {1}>'.format(
-                             repr(self.example),
+                             repr(_example),
                              hex(id(provider))))
 
 
 class DelegatedCallableTests(unittest.TestCase):
 
     def test_inheritance(self):
-        self.assertIsInstance(providers.DelegatedCallable(len),
+        self.assertIsInstance(providers.DelegatedCallable(_example),
                               providers.Callable)
 
     def test_is_provider(self):
         self.assertTrue(
-            providers.is_provider(providers.DelegatedCallable(len)))
+            providers.is_provider(providers.DelegatedCallable(_example)))
 
     def test_is_delegated_provider(self):
-        provider = providers.DelegatedCallable(len)
+        provider = providers.DelegatedCallable(_example)
         self.assertTrue(providers.is_delegated(provider))
 
     def test_repr(self):
-        provider = providers.DelegatedCallable(len)
+        provider = providers.DelegatedCallable(_example)
 
         self.assertEqual(repr(provider),
                          '<dependency_injector.providers.'
                          'DelegatedCallable({0}) at {1}>'.format(
-                             repr(len),
+                             repr(_example),
+                             hex(id(provider))))
+
+
+class AbstractCallableTests(unittest.TestCase):
+
+    def test_inheritance(self):
+        self.assertIsInstance(providers.AbstractCallable(_example),
+                              providers.Callable)
+
+    def test_call_overridden_by_callable(self):
+        def _abstract_example():
+            pass
+
+        provider = providers.AbstractCallable(_abstract_example)
+        provider.override(providers.Callable(_example))
+
+        self.assertTrue(provider(1, 2, 3, 4), (1, 2, 3, 4))
+
+    def test_call_overridden_by_delegated_callable(self):
+        def _abstract_example():
+            pass
+
+        provider = providers.AbstractCallable(_abstract_example)
+        provider.override(providers.DelegatedCallable(_example))
+
+        self.assertTrue(provider(1, 2, 3, 4), (1, 2, 3, 4))
+
+    def test_call_not_overridden(self):
+        provider = providers.AbstractCallable(_example)
+
+        with self.assertRaises(errors.Error):
+            provider(1, 2, 3, 4)
+
+    def test_override_by_not_callable(self):
+        provider = providers.AbstractCallable(_example)
+
+        with self.assertRaises(errors.Error):
+            provider.override(providers.Factory(object))
+
+    def test_provide_not_implemented(self):
+        provider = providers.AbstractCallable(_example)
+
+        with self.assertRaises(NotImplementedError):
+            provider._provide((1, 2, 3, 4), dict())
+
+    def test_repr(self):
+        provider = providers.AbstractCallable(_example)
+
+        self.assertEqual(repr(provider),
+                         '<dependency_injector.providers.'
+                         'AbstractCallable({0}) at {1}>'.format(
+                             repr(_example),
                              hex(id(provider))))

tests/unit/providers/test_factories.py

@@ -353,3 +353,49 @@ class DelegatedFactoryTests(unittest.TestCase):
                          'DelegatedFactory({0}) at {1}>'.format(
                              repr(Example),
                              hex(id(provider))))
+
+
+class AbstractFactoryTests(unittest.TestCase):
+
+    def test_inheritance(self):
+        self.assertIsInstance(providers.AbstractFactory(Example),
+                              providers.Factory)
+
+    def test_call_overridden_by_factory(self):
+        provider = providers.AbstractFactory(object)
+        provider.override(providers.Factory(Example))
+
+        self.assertIsInstance(provider(), Example)
+
+    def test_call_overridden_by_delegated_factory(self):
+        provider = providers.AbstractFactory(object)
+        provider.override(providers.DelegatedFactory(Example))
+
+        self.assertIsInstance(provider(), Example)
+
+    def test_call_not_overridden(self):
+        provider = providers.AbstractFactory(object)
+
+        with self.assertRaises(errors.Error):
+            provider()
+
+    def test_override_by_not_factory(self):
+        provider = providers.AbstractFactory(object)
+
+        with self.assertRaises(errors.Error):
+            provider.override(providers.Callable(object))
+
+    def test_provide_not_implemented(self):
+        provider = providers.AbstractFactory(Example)
+
+        with self.assertRaises(NotImplementedError):
+            provider._provide(tuple(), dict())
+
+    def test_repr(self):
+        provider = providers.AbstractFactory(Example)
+
+        self.assertEqual(repr(provider),
+                         '<dependency_injector.providers.'
+                         'AbstractFactory({0}) at {1}>'.format(
+                             repr(Example),
+                             hex(id(provider))))

tests/unit/providers/test_singletons.py

@@ -432,3 +432,63 @@ class DelegatedThreadSafeSingletonTests(_BaseSingletonTestCase,
                          'DelegatedThreadSafeSingleton({0}) at {1}>'.format(
                              repr(Example),
                              hex(id(provider))))
+
+
+class AbstractSingletonTests(unittest.TestCase):
+
+    def test_inheritance(self):
+        self.assertIsInstance(providers.AbstractSingleton(Example),
+                              providers.BaseSingleton)
+
+    def test_call_overridden_by_singleton(self):
+        provider = providers.AbstractSingleton(object)
+        provider.override(providers.Singleton(Example))
+
+        self.assertIsInstance(provider(), Example)
+
+    def test_call_overridden_by_delegated_singleton(self):
+        provider = providers.AbstractSingleton(object)
+        provider.override(providers.DelegatedSingleton(Example))
+
+        self.assertIsInstance(provider(), Example)
+
+    def test_call_not_overridden(self):
+        provider = providers.AbstractSingleton(object)
+
+        with self.assertRaises(errors.Error):
+            provider()
+
+    def test_reset_overridden(self):
+        provider = providers.AbstractSingleton(object)
+        provider.override(providers.Singleton(Example))
+
+        instance1 = provider()
+
+        provider.reset()
+
+        instance2 = provider()
+
+        self.assertIsNot(instance1, instance2)
+        self.assertIsInstance(instance1, Example)
+        self.assertIsInstance(instance2, Example)
+
+    def test_reset_not_overridden(self):
+        provider = providers.AbstractSingleton(object)
+
+        with self.assertRaises(errors.Error):
+            provider.reset()
+
+    def test_override_by_not_singleton(self):
+        provider = providers.AbstractSingleton(object)
+
+        with self.assertRaises(errors.Error):
+            provider.override(providers.Factory(object))
+
+    def test_repr(self):
+        provider = providers.AbstractSingleton(Example)
+
+        self.assertEqual(repr(provider),
+                         '<dependency_injector.providers.'
+                         'AbstractSingleton({0}) at {1}>'.format(
+                             repr(Example),
+                             hex(id(provider))))