From 0c39d3af5106278cfaff1047a6db400ff548d52e Mon Sep 17 00:00:00 2001 From: Michele Simionato Date: Mon, 27 Jul 2020 06:17:27 +0200 Subject: Improved a bit the documentation --- src/tests/documentation.py | 27 ++++++++++++--------------- 1 file changed, 12 insertions(+), 15 deletions(-) (limited to 'src/tests/documentation.py') diff --git a/src/tests/documentation.py b/src/tests/documentation.py index 70f5c3c..4e4ee3d 100644 --- a/src/tests/documentation.py +++ b/src/tests/documentation.py @@ -381,6 +381,9 @@ calling func with args (), {} ``` +Decorator factories +------------------------------------------- + The `decorator` function can also be used to define factories of decorators, i.e. functions returning decorators. In general you can just write something like this: @@ -393,9 +396,8 @@ def decfactory(param1, param2, ...): ``` This is fully general but requires an additional level of nesting. For this -reason since version 4.2 there is a facility to build -decorator factories by using a single caller with default arguments i.e. -writing something like this: +reason since version 4.2 there is a facility to build decorator factories by +using a single caller with default arguments i.e. writing something like this: ```python def caller(f, param1=default1, param2=default2, ..., *args, **kw): @@ -409,22 +411,17 @@ restriction, there exists an unique default decorator, i.e. the member of the family which uses the default values for all parameters. Such decorator can be written as ``decfactory()`` with no parameters specified; moreover, as a shortcut, it is also possible to elide the parenthesis, -a feature much requested by the users. For years I have been opposite -to this feature request, since having explicit parenthesis to me is more clear +a feature much requested by the users. For years I have been opposing +the request, since having explicit parenthesis to me is more clear and less magic; however once this feature entered in decorators of the Python standard library (I am referring to the [dataclass decorator]( https://www.python.org/dev/peps/pep-0557/)) I finally gave up. -The example below will show how it works in practice. - -Decorator factories -------------------------------------------- - -Sometimes one has to deal with blocking resources, such as ``stdin``. -Sometimes it is better to receive a "busy" message than just blocking -everything. -This can be accomplished with a suitable family of decorators (decorator -factory), parameterize by a string, the busy message: +The example below shows how it works in practice. The goal is to +convert a function relying on a blocking resource into a function +returning a "busy" message if the resource is not available. +This can be accomplished with a suitable family of decorators +parameterize by a string, the busy message: $$blocking -- cgit v1.2.1 From 54dc3a2a98e4bf0e73be74b8d6b32f85be709f96 Mon Sep 17 00:00:00 2001 From: Michele Simionato Date: Mon, 27 Jul 2020 16:03:48 +0200 Subject: Removed obsolete reference to readthedocs --- src/tests/documentation.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'src/tests/documentation.py') diff --git a/src/tests/documentation.py b/src/tests/documentation.py index 4e4ee3d..29fe75c 100644 --- a/src/tests/documentation.py +++ b/src/tests/documentation.py @@ -53,7 +53,7 @@ What's New in version 4 - **New documentation** There is now a single manual for all Python versions, so I took the - opportunity to overhaul the documentation and to move it to readthedocs.org. + opportunity to overhaul the documentation. Even if you are a long-time user, you may want to revisit the docs, since several examples have been improved. -- cgit v1.2.1