[Python-Dev] [Python-checkins] cpython (3.3): Issue #16641: Fix default values of sched.scheduler.enter arguments were

[Eli Bendersky]

On Sat, Dec 29, 2012 at 11:17 AM, serhiy.storchaka <
python-checkins at python.org> wrote:

> http://hg.python.org/cpython/rev/1c9c0f92df65
> changeset:   81134:1c9c0f92df65
> branch:      3.3
> parent:      81132:5db0833f135b
> user:        Serhiy Storchaka <storchaka at gmail.com>
> date:        Sat Dec 29 21:13:45 2012 +0200
> summary:
>   Issue #16641: Fix default values of sched.scheduler.enter arguments were
> modifiable.
>
> files:
>   Doc/library/sched.rst |  23 ++++++++++++++---------
>   Lib/sched.py          |   8 ++++++--
>   Misc/NEWS             |   3 +++
>   3 files changed, 23 insertions(+), 11 deletions(-)
>
>
> diff --git a/Doc/library/sched.rst b/Doc/library/sched.rst
> --- a/Doc/library/sched.rst
> +++ b/Doc/library/sched.rst
> @@ -36,19 +36,22 @@
>
>     >>> import sched, time
>     >>> s = sched.scheduler(time.time, time.sleep)
> -   >>> def print_time(): print("From print_time", time.time())
> +   >>> def print_time(a='default'):
> +   ...     print("From print_time", time.time(), a)
>     ...
>     >>> def print_some_times():
>     ...     print(time.time())
> -   ...     s.enter(5, 1, print_time, ())
> -   ...     s.enter(10, 1, print_time, ())
> +   ...     s.enter(10, 1, print_time)
> +   ...     s.enter(5, 2, print_time, argument=('positional',))
> +   ...     s.enter(5, 1, print_time, kwargs={'a': 'keyword'})
>     ...     s.run()
>     ...     print(time.time())
>     ...
>     >>> print_some_times()
>     930343690.257
> -   From print_time 930343695.274
> -   From print_time 930343700.273
> +   From print_time 930343695.274 positional
> +   From print_time 930343695.275 keyword
> +   From print_time 930343700.273 default
>     930343700.276
>
>  .. _scheduler-objects:
> @@ -59,7 +62,7 @@
>  :class:`scheduler` instances have the following methods and attributes:
>
>
> -.. method:: scheduler.enterabs(time, priority, action, argument=[],
> kwargs={})
> +.. method:: scheduler.enterabs(time, priority, action, argument=(),
> kwargs={})
>
>     Schedule a new event. The *time* argument should be a numeric type
> compatible
>     with the return value of the *timefunc* function passed  to the
> constructor.
> @@ -67,8 +70,10 @@
>     *priority*.
>
>     Executing the event means executing ``action(*argument, **kwargs)``.
> -   *argument* must be a sequence holding the parameters for *action*.
> -   *kwargs* must be a dictionary holding the keyword parameters for
> *action*.
> +   Optional *argument* argument must be a sequence holding the parameters
> +   for *action* if any used.
> +   Optional *kwargs* argument must be a dictionary holding the keyword
> +   parameters for *action* if any used.
>

I don't see how this change improves the documentation. To keep the grammar
correct and just state that the arguments are optional, I would simply
replace "must be" by "is". For example:

  *argument* is a sequence holding the parameters for *action*.

This is short, and since the function signature clearly shows that argument
has a default value, I think it conveys the meaning it should.

Eli
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20121229/74357614/attachment-0001.html>