Regenerated the docs

1 files changed, 61 insertions, 21 deletions

diff --git a/docs/tests.documentation.rst b/docs/tests.documentation.rst
index f77cb10..df04e7c 100644
--- a/docs/tests.documentation.rst
+++ b/docs/tests.documentation.rst
@@ -3,7 +3,7 @@ The ``decorator`` module
 
 :Author: Michele Simionato
 :E-mail: michele.simionato@gmail.com
-:Version: 4.1.2 (2017-07-23)
+:Version: 4.1.2 (2018-01-14)
 :Supports: Python 2.6, 2.7, 3.0, 3.1, 3.2, 3.3, 3.4, 3.5, 3.6
 :Download page: http://pypi.python.org/pypi/decorator/4.1.2
 :Installation: ``pip install decorator``
@@ -39,9 +39,9 @@ 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. So, even if you are
-  a long-time user, you may want to revisit the docs, since several
-  examples have been improved.
+  opportunity to overhaul the documentation and to move it to readthedocs.org.
+  Even if you are a long-time user, you may want to revisit the docs, since
+  several examples have been improved.
 
 - **Packaging improvements**
   The code is now also available in wheel format. Integration with
@@ -72,6 +72,11 @@ What's New in version 4
   defined with the `async def` syntax, and to maintain the
   `inspect.iscoroutinefunction` check working for the decorated function.
 
+- **Decorator factories**
+
+  From version 4.2 there is facility to define factories of decorators in
+  a simple way, a feature requested by the users since a long time.
+
 Usefulness of decorators
 ------------------------------------------------
 
@@ -465,31 +470,66 @@ Here is an example of usage:
  >>> func()
  calling func with args (), {}
 
+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:
+
+.. code-block:: python
+
+   def decfactory(param1, param2, ...):
+      def caller(f, *args, **kw):
+          return somefunc(f, param1, param2, .., *args, **kw)
+      return decorator(caller)
+
+This is fully general but requires an additional level of nesting. For this
+reasone 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:
+
+.. code-block:: python
+
+   def caller(f, param1=default1, param2=default2, ..., *args, **kw):
+       return somefunc(f, param1, param2, *args, **kw)
+   decfactory = decorator(caller)
+
+Notice that this simplified approach *only works with default arguments*,
+i.e. `param1`, `param2` etc must have known defaults. Thanks to this
+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 expliciti 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.
+
 ``blocking``
 -------------------------------------------
 
 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,
-where the parameter is the busy message:
+This can be accomplished with a suitable family of decorators (decorator
+factory), parameterize by a string, the busy message:
 
 .. code-block:: python
 
- def blocking(not_avail):
-     def _blocking(f, *args, **kw):
-         if not hasattr(f, "thread"):  # no thread running
-             def set_result():
-                 f.result = f(*args, **kw)
-             f.thread = threading.Thread(None, set_result)
-             f.thread.start()
-             return not_avail
-         elif f.thread.isAlive():
-             return not_avail
-         else:  # the thread is ended, return the stored result
-             del f.thread
-             return f.result
-     return decorator(_blocking)
+ @decorator
+ def blocking(f, msg='blocking', *args, **kw):
+     if not hasattr(f, "thread"):  # no thread running
+         def set_result():
+             f.result = f(*args, **kw)
+         f.thread = threading.Thread(None, set_result)
+         f.thread.start()
+         return msg
+     elif f.thread.isAlive():
+         return msg
+     else:  # the thread is ended, return the stored result
+         del f.thread
+         return f.result
 
 
 Functions decorated with ``blocking`` will return a busy message if
@@ -498,7 +538,7 @@ available. For instance:
 
 .. code-block:: python
 
- >>> @blocking("Please wait ...")
+ >>> @blocking(msg="Please wait ...")
  ... def read_data():
  ...     time.sleep(3) # simulate a blocking resource
  ...     return "some data"