diff --git a/docs/images/providers/singleton.png b/docs/images/providers/singleton.png index 3cc3f598..06e8996f 100644 Binary files a/docs/images/providers/singleton.png and b/docs/images/providers/singleton.png differ diff --git a/docs/providers/factory.rst b/docs/providers/factory.rst index 24609098..46c61ebf 100644 --- a/docs/providers/factory.rst +++ b/docs/providers/factory.rst @@ -29,7 +29,7 @@ Injections are done according to the next rules: + 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 obviously. - Check out `Factory providers delegation`_. + Check out :ref:`factory_providers_delegation`. + All other injectable values are provided *"as is"*. + Positional context arguments will be appended after :py:class:`Factory` positional injections. @@ -50,6 +50,8 @@ injectable values are also provided by another factories: :language: python :linenos: +.. _factory_providers_delegation: + Factory providers delegation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -89,6 +91,8 @@ Example: :language: python :linenos: +.. _factory_providers_specialization: + Factory providers specialization ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/providers/singleton.rst b/docs/providers/singleton.rst index bd00b79e..292ec093 100644 --- a/docs/providers/singleton.rst +++ b/docs/providers/singleton.rst @@ -16,6 +16,20 @@ Example: :language: python :linenos: +Singleton providers resetting +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Created and memorized by :py:class:`Singleton` instance can be reset. Reset of +:py:class:`Singleton`'s memorized instance is done by clearing reference to +it. Further lifecycle of memorized instance is out of :py:class:`Singleton` +provider's control and dependes on garbage collection strategy. + +Example: + +.. literalinclude:: ../../examples/providers/singleton_reseting.py + :language: python + :linenos: + Singleton providers and injections ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -42,47 +56,17 @@ provider. . It makes possible to inject providers *as is*. Please check out `Singleton providers delegation`_ section. -Singleton providers resetting -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Created and memorized by :py:class:`Singleton` instance can be reset. Reset of -:py:class:`Singleton`'s memorized instance is done by clearing reference to -it. Further lifecycle of memorized instance is out of :py:class:`Singleton` -provider's control. - -Example: - -.. literalinclude:: ../../examples/providers/singleton_reseting.py - :language: python - :linenos: - Singleton providers delegation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :py:class:`Singleton` provider could be delegated to any other provider via -any kind of injection. Delegation of :py:class:`Singleton` providers is the -same as :py:class:`Factory` providers delegation, please follow *Factory -providers delegation* section for example. +any kind of injection. -:py:class:`Singleton` delegate could be created obviously using -``Delegate(Singleton(...))`` or by calling ``Singleton(...).delegate()`` -method. - -Example: - -.. literalinclude:: ../../examples/providers/singleton_delegation.py - :language: python - :linenos: - -Alternative way of doing :py:class:`Singleton` delegation is an usage of -:py:class:`DelegatedSingleton`. :py:class:`DelegatedSingleton` is a -:py:class:`Singleton` that is always injected "as is". - -Example: - -.. literalinclude:: ../../examples/providers/delegated_singleton.py - :language: python - :linenos: +Delegation of :py:class:`Singleton` providers is the same as +:py:class:`Factory` providers delegation, please follow +:ref:`factory_providers_delegation` section for examples (with exception +about using :py:class:`DelegatedSingleton` instead of +:py:class:`DelegatedFactory`). Singleton providers specialization ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -90,9 +74,6 @@ Singleton providers specialization :py:class:`Singleton` provider could be specialized for any kind of needs via declaring its subclasses. -One of such `builtin` features is a limitation to :py:class:`Singleton` -provided type: - -.. literalinclude:: ../../examples/providers/singleton_provided_type.py - :language: python - :linenos: +Specialization of :py:class:`Singleton` providers is the same as +:py:class:`Factory` providers specialization, please follow +:ref:`factory_providers_specialization` section for examples. diff --git a/examples/providers/delegated_singleton.py b/examples/providers/delegated_singleton.py deleted file mode 100644 index f5c85ea3..00000000 --- a/examples/providers/delegated_singleton.py +++ /dev/null @@ -1,18 +0,0 @@ -"""`DelegatedSingleton` providers example.""" - -import dependency_injector.providers as providers - - -# Some delegated singleton provider: -singleton_provider = providers.DelegatedSingleton(object) -registry = providers.DelegatedSingleton(dict, - object1=singleton_provider, - object2=singleton_provider) - -# Getting several references to singleton object: -registry = registry() -singleton_object1 = registry['object1']() -singleton_object2 = registry['object2']() - -# Making some asserts: -assert singleton_object1 is singleton_object2 diff --git a/examples/providers/singleton.py b/examples/providers/singleton.py index 1e42ad9a..92fcdf9d 100644 --- a/examples/providers/singleton.py +++ b/examples/providers/singleton.py @@ -1,20 +1,19 @@ """`Singleton` providers example.""" +import collections + import dependency_injector.providers as providers -class UserService(object): - """Example class UserService.""" +UsersService = collections.namedtuple('UsersService', []) # Singleton provider creates new instance of specified class on first call and # returns same instance on every next call. -users_service_provider = providers.Singleton(UserService) +users_service_provider = providers.Singleton(UsersService) # Retrieving several UserService objects: -user_service1 = users_service_provider() -user_service2 = users_service_provider() +users_service1 = users_service_provider() +users_service2 = users_service_provider() # Making some asserts: -assert user_service1 is user_service2 -assert isinstance(user_service1, UserService) -assert isinstance(user_service2, UserService) +assert users_service1 is users_service2 diff --git a/examples/providers/singleton_delegation.py b/examples/providers/singleton_delegation.py deleted file mode 100644 index 1b7e324c..00000000 --- a/examples/providers/singleton_delegation.py +++ /dev/null @@ -1,13 +0,0 @@ -"""`Singleton` providers delegation example.""" - -import dependency_injector.providers as providers - - -# Some singleton provider and few delegates of it: -singleton_provider = providers.Singleton(object) -singleton_provider_delegate1 = singleton_provider.delegate() -singleton_provider_delegate2 = providers.Delegate(singleton_provider) - -# Making some asserts: -assert singleton_provider_delegate1() is singleton_provider -assert singleton_provider_delegate2() is singleton_provider diff --git a/examples/providers/singleton_reseting.py b/examples/providers/singleton_reseting.py index fa58bf4a..8fe2f5a7 100644 --- a/examples/providers/singleton_reseting.py +++ b/examples/providers/singleton_reseting.py @@ -1,28 +1,27 @@ """`Singleton` providers resetting example.""" +import collections + import dependency_injector.providers as providers -class UserService(object): - """Example class UserService.""" +UsersService = collections.namedtuple('UsersService', []) # Users service singleton provider: -users_service_provider = providers.Singleton(UserService) +users_service_provider = providers.Singleton(UsersService) -# Retrieving several UserService objects: -user_service1 = users_service_provider() -user_service2 = users_service_provider() +# Retrieving several UsersService objects: +users_service1 = users_service_provider() +users_service2 = users_service_provider() # Making some asserts: -assert user_service1 is user_service2 -assert isinstance(user_service1, UserService) -assert isinstance(user_service2, UserService) +assert users_service1 is users_service2 # Resetting of memorized instance: users_service_provider.reset() # Retrieving one more UserService object: -user_service3 = users_service_provider() +users_service3 = users_service_provider() # Making some asserts: -assert user_service3 is not user_service1 +assert users_service3 is not users_service1