diff --git a/docs/images/providers/callable.png b/docs/images/providers/callable.png deleted file mode 100644 index f34b2a6a..00000000 Binary files a/docs/images/providers/callable.png and /dev/null differ diff --git a/docs/main/changelog.rst b/docs/main/changelog.rst index ba3196e7..60bb4e70 100644 --- a/docs/main/changelog.rst +++ b/docs/main/changelog.rst @@ -9,8 +9,8 @@ follows `Semantic versioning`_ Development version ------------------- -- Update ``Singleton`` provider documentation. -- Rework ``Singleton`` provider examples. +- Update ``Singleton`` provider documentation and rework examples. +- Update ``Callable`` provider documentation and rework examples. 3.34.0 ------ diff --git a/docs/providers/callable.rst b/docs/providers/callable.rst index 9c82c87f..e0cb5089 100644 --- a/docs/providers/callable.rst +++ b/docs/providers/callable.rst @@ -1,69 +1,20 @@ -Callable providers ------------------- +Callable provider +----------------- + +.. meta:: + :keywords: Python,DI,Dependency injection,IoC,Inversion of Control,Function,Method,Example + :description: Callable provider helps to make dependencies injection into functions. This page + demonstrates how to use a Callable provider. .. currentmodule:: dependency_injector.providers -:py:class:`Callable` provider calls wrapped callable on every call. +:py:class:`Callable` provider calls a function, a method or another callable. -Callable providers and injections -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:py:class:`Callable` provider takes a various number of positional and keyword -arguments that are used as wrapped callable injections. Every time, when -:py:class:`Callable` provider is called, positional and keyword argument -injections would be passed as callable arguments. - -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 :ref:`callable_providers_delegation`. -+ All other injectable values are provided *"as is"*. -+ Positional context arguments will be appended after :py:class:`Callable` - positional injections. -+ Keyword context arguments have priority on :py:class:`Callable` keyword - injections and will be merged over them. - -Example that shows usage of :py:class:`Callable` with positional argument -injections: - -.. literalinclude:: ../../examples/providers/callable_args.py +.. literalinclude:: ../../examples/providers/callable.py :language: python + :lines: 3- -Next one example shows usage of :py:class:`Callable` with keyword argument -injections: - -.. image:: /images/providers/callable.png - :width: 100% - :align: center - -.. literalinclude:: ../../examples/providers/callable_kwargs.py - :language: python - -.. _callable_providers_delegation: - -Callable providers delegation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:py:class:`Callable` provider could be delegated to any other provider via -any kind of injection. - -Delegation of :py:class:`Callable` providers is the same as -:py:class:`Factory` providers delegation, please follow -:ref:`factory_providers_delegation` section for examples (with exception -of using :py:class:`DelegatedCallable` instead of -:py:class:`DelegatedFactory`). - -Abstract callable providers -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:py:class:`AbstractCallable` provider is a :py:class:`Callable` provider that -must be explicitly overridden before calling. - -Behaviour of :py:class:`AbstractCallable` providers is the same as of -:py:class:`AbstractFactory`, please follow :ref:`abstract_factory_providers` -section for examples (with exception of using :py:class:`AbstractCallable` -provider instead of :py:class:`AbstractFactory`). +``Callable`` provider handles an injection of the dependencies the same way like a +:ref:`factory-provider`. .. disqus:: diff --git a/examples/providers/callable.py b/examples/providers/callable.py new file mode 100644 index 00000000..40e0d363 --- /dev/null +++ b/examples/providers/callable.py @@ -0,0 +1,18 @@ +"""`Callable` provider example.""" + +import passlib.hash + +from dependency_injector import providers + + +password_hasher = providers.Callable( + passlib.hash.sha256_crypt.hash, + salt_size=16, + rounds=10000, +) +password_verifier = providers.Callable(passlib.hash.sha256_crypt.verify) + + +if __name__ == '__main__': + hashed_password = password_hasher('super secret') + assert password_verifier('super secret', hashed_password) diff --git a/examples/providers/callable_args.py b/examples/providers/callable_args.py deleted file mode 100644 index a4292de4..00000000 --- a/examples/providers/callable_args.py +++ /dev/null @@ -1,16 +0,0 @@ -"""`Callable` providers with positional arguments example.""" - -import dependency_injector.providers as providers - - -# Creating even and odd filter providers: -even_filter = providers.Callable(filter, lambda x: x % 2 == 0) -odd_filter = providers.Callable(filter, lambda x: x % 2 != 0) - -# Creating even and odd ranges using range() and filter providers: -even_range = even_filter(range(1, 10)) -odd_range = odd_filter(range(1, 10)) - -# Making some asserts: -assert even_range == [2, 4, 6, 8] -assert odd_range == [1, 3, 5, 7, 9] diff --git a/examples/providers/callable_kwargs.py b/examples/providers/callable_kwargs.py deleted file mode 100644 index a6b89990..00000000 --- a/examples/providers/callable_kwargs.py +++ /dev/null @@ -1,16 +0,0 @@ -"""`Callable` providers with keyword arguments example.""" - -import passlib.hash - -import dependency_injector.providers as providers - - -# Password hasher and verifier providers: -password_hasher = providers.Callable(passlib.hash.sha256_crypt.encrypt, - salt_size=16, - rounds=10000) -password_verifier = providers.Callable(passlib.hash.sha256_crypt.verify) - -# Making some asserts: -hashed_password = password_hasher('super secret') -assert password_verifier('super secret', hashed_password)