diff --git a/docs/images/providers/singleton.png b/docs/images/providers/singleton.png index 605b8b19..595d359f 100644 Binary files a/docs/images/providers/singleton.png and b/docs/images/providers/singleton.png differ diff --git a/docs/images/providers/singleton_internals.png b/docs/images/providers/singleton_internals.png index 3bb05828..f05fb902 100644 Binary files a/docs/images/providers/singleton_internals.png and b/docs/images/providers/singleton_internals.png differ diff --git a/docs/providers/singleton.rst b/docs/providers/singleton.rst index ba0bee96..c372e50d 100644 --- a/docs/providers/singleton.rst +++ b/docs/providers/singleton.rst @@ -1,7 +1,7 @@ Singleton providers ------------------- -``Singleton`` provider creates new instance of specified class on first call +``di.Singleton`` provider creates new instance of specified class on first call and returns same instance on every next call. Example: @@ -16,9 +16,9 @@ Example: Singleton providers and injections ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -``Singleton`` providers use ``Factory`` providers for first creation of +``di.Singleton`` providers use ``di.Factory`` providers for first creation of specified class instance, so, all of the rules about injections are the same, -as for ``Factory`` providers. +as for ``di.Factory`` providers. .. image:: /images/providers/singleton_internals.png :width: 80% @@ -26,27 +26,29 @@ as for ``Factory`` providers. .. note:: - Due that ``Singleton`` provider creates specified class instance only on + Due that ``di.Singleton`` provider creates specified class instance only on the first call, all injections are done once, during the first call, also. Every next call, while instance has been already created and memorized, no - injections are done, ``Singleton`` provider just returns memorized earlier - instance. + injections are done, ``di.Singleton`` provider just returns memorized + earlier instance. This may cause some problems, for example, in case of trying to bind - ``Factory`` provider with ``Singleton`` provider (provided by dependent - ``Factory`` instance will be injected only once, during the first call). - Be aware that such behaviour was made with opened eyes and is not a bug. + ``di.Factory`` provider with ``di.Singleton`` provider (provided by + dependent ``di.Factory`` instance will be injected only once, during the + first call). Be aware that such behaviour was made with opened eyes and is + not a bug. - By the way, in such case, ``Delegate`` provider can be useful. It makes + By the way, in such case, ``di.Delegate`` provider can be useful. It makes possible to inject providers *as is*. Please check out full example in *Providers delegation* section. Singleton providers resetting ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Created and memorized by ``Singleton`` instance can be reset. Reset of -``Singleton``'s memorized instance is done by clearing reference to it. Further -lifecycle of memorized instance is out of ``Singleton`` provider's control. +Created and memorized by ``di.Singleton`` instance can be reset. Reset of +``di.Singleton``'s memorized instance is done by clearing reference to it. +Further lifecycle of memorized instance is out of ``di.Singleton`` provider's +control. Example: @@ -56,13 +58,14 @@ Example: Singleton providers delegation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -``Singleton`` provider could be delegated to any other provider via any kind of -injection. Delegation of ``Singleton`` providers is the same as ``Factory`` -providers delegation, please follow *Factory providers delegation* section for -example. +``di.Singleton`` provider could be delegated to any other provider via any +kind of injection. Delegation of ``di.Singleton`` providers is the same as +``di.Factory`` providers delegation, please follow +*Factory providers delegation* section for example. -``Singleton`` delegate could be created obviously using -``Delegate(Singleton())`` or by calling ``Singleton.delegate()`` method. +``di.Singleton`` delegate could be created obviously using +``di.Delegate(di.Singleton())`` or by calling ``di.Singleton.delegate()`` +method. Example: diff --git a/examples/providers/singleton.py b/examples/providers/singleton.py index 934437b7..0697e218 100644 --- a/examples/providers/singleton.py +++ b/examples/providers/singleton.py @@ -1,6 +1,6 @@ -"""`Singleton` providers example.""" +"""`di.Singleton` providers example.""" -from dependency_injector.providers import Singleton +import dependency_injector as di class UserService(object): @@ -9,7 +9,7 @@ class UserService(object): # Singleton provider creates new instance of specified class on first call and # returns same instance on every next call. -users_service_provider = Singleton(UserService) +users_service_provider = di.Singleton(UserService) # Retrieving several UserService objects: user_service1 = users_service_provider() diff --git a/examples/providers/singleton_delegation.py b/examples/providers/singleton_delegation.py index e15fe51f..ebc9aa2e 100644 --- a/examples/providers/singleton_delegation.py +++ b/examples/providers/singleton_delegation.py @@ -1,13 +1,12 @@ -"""`Singleton` providers delegation example.""" +"""`di.Singleton` providers delegation example.""" -from dependency_injector.providers import Singleton -from dependency_injector.providers import Delegate +import dependency_injector as di # Some singleton provider and few delegates of it: -singleton_provider = Singleton(object) +singleton_provider = di.Singleton(object) singleton_provider_delegate1 = singleton_provider.delegate() -singleton_provider_delegate2 = Delegate(singleton_provider) +singleton_provider_delegate2 = di.Delegate(singleton_provider) # Making some asserts: assert singleton_provider_delegate1() is singleton_provider diff --git a/examples/providers/singleton_reseting.py b/examples/providers/singleton_reseting.py index a6dc2012..8495dd6c 100644 --- a/examples/providers/singleton_reseting.py +++ b/examples/providers/singleton_reseting.py @@ -1,6 +1,6 @@ -"""`Singleton` providers resetting example.""" +"""`di.Singleton` providers resetting example.""" -from dependency_injector.providers import Singleton +import dependency_injector as di class UserService(object): @@ -8,7 +8,7 @@ class UserService(object): """Example class UserService.""" # Users service singleton provider: -users_service_provider = Singleton(UserService) +users_service_provider = di.Singleton(UserService) # Retrieving several UserService objects: user_service1 = users_service_provider()