From d94d137bac481089c2c7a121d40744e1ae9fe2fa Mon Sep 17 00:00:00 2001 From: Christian Franke Date: Tue, 30 Jun 2020 13:24:47 +0200 Subject: Fix wording in the documentation --- docs/documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/documentation.md') diff --git a/docs/documentation.md b/docs/documentation.md index 898a46d..27b4b99 100644 --- a/docs/documentation.md +++ b/docs/documentation.md @@ -1131,7 +1131,7 @@ the dispatch argument simply by passing its name as a string. (Note that if you misspell the name you will get an error.) The decorated function `write` is turned into a generic function ( -`write` is a function at the idea it is decorated; it will be turned +`write` is a function at the time it is decorated; it will be turned into a method later, at class instantiation time), and it is called if there are no more specialized implementations. -- cgit v1.2.1 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 --- docs/documentation.md | 32 ++++++++++++++------------------ 1 file changed, 14 insertions(+), 18 deletions(-) (limited to 'docs/documentation.md') diff --git a/docs/documentation.md b/docs/documentation.md index 27b4b99..18aa0e0 100644 --- a/docs/documentation.md +++ b/docs/documentation.md @@ -93,7 +93,7 @@ some experience and it is not as easy as it could be. For instance, typical implementations of decorators involve nested functions, and we all know that flat is better than nested. -The aim of the ``decorator`` module is to simplify the usage of +The aim of the ``decorator`` module it to simplify the usage of decorators for the average programmer, and to popularize decorators by showing various non-trivial examples. Of course, as all techniques, decorators can be abused (I have seen that) and you should not try to @@ -475,9 +475,11 @@ Here is an example of usage: >>> func() 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: @@ -490,9 +492,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): @@ -506,22 +507,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: ```python @@ -1131,7 +1127,7 @@ the dispatch argument simply by passing its name as a string. (Note that if you misspell the name you will get an error.) The decorated function `write` is turned into a generic function ( -`write` is a function at the time it is decorated; it will be turned +`write` is a function at the idea it is decorated; it will be turned into a method later, at class instantiation time), and it is called if there are no more specialized implementations. -- 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 --- docs/documentation.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/documentation.md') diff --git a/docs/documentation.md b/docs/documentation.md index 18aa0e0..fb41ae9 100644 --- a/docs/documentation.md +++ b/docs/documentation.md @@ -37,7 +37,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. @@ -475,6 +475,7 @@ Here is an example of usage: >>> func() calling func with args (), {} + ``` Decorator factories -- cgit v1.2.1