From dd5cc79dd1b1da3e8e6ad28683239e33d39a623b Mon Sep 17 00:00:00 2001 From: Roman Mogilatov Date: Thu, 22 Oct 2015 16:51:16 +0300 Subject: [PATCH] Update docs of Callable provider with description of positional agrument injections and new example --- docs/main/changelog.rst | 2 +- docs/providers/callable.rst | 34 +++++++++++++++---- examples/providers/callable_args.py | 16 +++++++++ ...lable_injections.py => callable_kwargs.py} | 4 +-- 4 files changed, 46 insertions(+), 10 deletions(-) create mode 100644 examples/providers/callable_args.py rename examples/providers/{callable_injections.py => callable_kwargs.py} (86%) diff --git a/docs/main/changelog.rst b/docs/main/changelog.rst index c3890dda..f1b62b10 100644 --- a/docs/main/changelog.rst +++ b/docs/main/changelog.rst @@ -16,7 +16,7 @@ Development version - Add images for catalog "Writing catalogs" and "Operating with catalogs" examples. - Add functionality for using positional argument injections with - ``di.Factory`` and ``di.Singleton`` providers. + ``di.Factory``, ``di.Singleton`` and ``di.Callable`` providers. - Add optimization for ``di.Injection.value`` property that will compute type of injection once, instead of doing this on every call. - Add functionality for decorating classes with ``@di.inject``. diff --git a/docs/providers/callable.rst b/docs/providers/callable.rst index ce8b7be2..0fcf0944 100644 --- a/docs/providers/callable.rst +++ b/docs/providers/callable.rst @@ -8,20 +8,40 @@ callable. Callable providers and injections ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -``di.Callable`` provider uses keyword argument injections. Keyword argument -injections are done by passing injectable values as keyword arguments during -call time. +``di.Callable`` takes a various number of positional and keyword arguments +that are used as decorated callable injections. Every time, when +``di.Callable`` is called, positional and keyword argument injections would be +passed as an callable arguments. -Context keyword arguments have higher priority than keyword argument -injections. +Such behaviour is very similar to the standard Python ``functools.partial`` +object, except of one thing: all injectable values are provided +*"as is"*, except of providers (subclasses of ``di.Provider``). Providers +will be called every time, when injection needs to be done. For example, +if injectable value of injection is a ``di.Factory``, it will provide new one +instance (as a result of its call) every time, when injection needs to be done. -Example: +``di.Callable`` behaviour with context positional and keyword arguments is +very like a standard Python ``functools.partial``: + +- Positional context arguments will be appended after ``di.Callable`` + positional injections. +- Keyword context arguments have priority on ``di.Callable`` keyword + injections and will be merged over them. + +Example that shows usage of ``di.Callable`` with positional argument +injections: + +.. literalinclude:: ../../examples/providers/callable_args.py + :language: python + +Next one example shows usage of ``di.Callable`` with keyword argument +injections: .. image:: /images/providers/callable.png :width: 100% :align: center -.. literalinclude:: ../../examples/providers/callable_injections.py +.. literalinclude:: ../../examples/providers/callable_kwargs.py :language: python Callable providers delegation diff --git a/examples/providers/callable_args.py b/examples/providers/callable_args.py new file mode 100644 index 00000000..3be82b6f --- /dev/null +++ b/examples/providers/callable_args.py @@ -0,0 +1,16 @@ +"""`di.Callable` providers with positional arguments example.""" + +import dependency_injector as di + + +# Creating even and odd filter providers: +even_filter = di.Callable(filter, lambda x: x % 2 == 0) +odd_filter = di.Callable(filter, lambda x: x % 2 != 0) + +# Creating even and odd ranges using xrange() and filter providers: +even_range = even_filter(xrange(1, 10)) +odd_range = odd_filter(xrange(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_injections.py b/examples/providers/callable_kwargs.py similarity index 86% rename from examples/providers/callable_injections.py rename to examples/providers/callable_kwargs.py index 339164ad..7119667d 100644 --- a/examples/providers/callable_injections.py +++ b/examples/providers/callable_kwargs.py @@ -1,4 +1,4 @@ -"""`di.Callable` providers example.""" +"""`di.Callable` providers with keyword arguments example.""" import passlib.hash import dependency_injector as di @@ -10,6 +10,6 @@ password_hasher = di.Callable(passlib.hash.sha256_crypt.encrypt, rounds=10000) password_verifier = di.Callable(passlib.hash.sha256_crypt.verify) -# Making some asserts (client's code): +# Making some asserts: hashed_password = password_hasher('super secret') assert password_verifier('super secret', hashed_password)