[issue15979] Improve timeit documentation
New submission from Ezio Melotti: The documentation of timeit can be improved in several ways: * it should start with a couple of short and comprehensible examples that show the basic usage from the command-line and from the code; * the 3 convenience functions should be moved before the class documentation (and their order inverted); * the methods in the class should be reordered to show the important one first; * more comprehensive (but still comprehensible) examples should be added at the end; * sh syntax highlight should be used for the command-line usage examples; * the note about Python 2.3 can be removed from 3.x docs; http://docs.python.org/dev/library/timeit.html ---------- assignee: docs@python components: Documentation messages: 170785 nosy: docs@python, ezio.melotti priority: normal severity: normal stage: needs patch status: open title: Improve timeit documentation type: enhancement versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15979> _______________________________________
Raymond Hettinger added the comment: +1 ---------- nosy: +rhettinger _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15979> _______________________________________
Ezio Melotti added the comment: The sh syntax highlight can be enabled with: .. code-block:: sh $ ... ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15979> _______________________________________
Ezio Melotti added the comment: Here's a patch. ---------- assignee: docs@python -> ezio.melotti keywords: +patch stage: needs patch -> patch review Added file: http://bugs.python.org/file27273/issue15979.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15979> _______________________________________
Antoine Pitrou added the comment: I don't think there's a need for two separate examples sections (one "basic examples" and one "examples"). Also, you say a couple of times "The equivalent can be achieved from the :ref:`python-interface`", but that's not true since the command-line interface auto-calibrates, which the Python API (unfortunately) doesn't. Besides, the results use different units and can't be directly compared. ---------- nosy: +pitrou _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15979> _______________________________________
Ezio Melotti added the comment: The first example shows the basic usage and it's right at the beginning, all the other "advanced" examples are at the bottom. About the autocalibration you are right, I'll rephrase the sentence (see also #6422). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15979> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- stage: patch review -> commit review Added file: http://bugs.python.org/file27382/issue15979-2.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15979> _______________________________________
Chris Jerdonek added the comment: I copy-edited the patch just looking for minor things like punctuation, etc: +a :ref:`command-line-interface` as well as :ref:`callable <python-interface>` a callable one +See also Tim Peters' introduction to the "Algorithms" chapter in the Python +Cookbook, published by O'Reilly. italicize or underline book titles (is there a reST directive for books?) +The following example shows how the :ref:`command-line-interface`, no comma +Python interface Python Interface + Create a :class:`Timer` instance with the given statement, setup code and timer + function and run its :meth:`.timeit` method with *number* executions. stars around setup and timer like there is with *number*? + Create a :class:`Timer` instance with the given statement, setup code and timer + function and run its :meth:`.repeat` method with the given *repeat* count and ditto + Define a default timer, in a platform specific manner. On Windows, platform-specific + :func:`time.clock` has microsecond granularity but :func:`time.time`'s granularity, but + granularity is 1/60th of a second; on Unix, :func:`time.clock` has 1/100th of I would just split this into two sentences since it already combines two compound sentences (i.e. it is effectively four sentences): second. On Unix, + a second granularity and :func:`time.time` is much more precise. On either granularity, and + Time *number* executions of the main statement. This executes the setup statement. This + statement once, and then returns the time it takes to execute the main statement + a number of times, measured in seconds as a float. The argument is the number *number* times + baseline overhead can be measured by invoking the program without arguments and arguments, and ---------- nosy: +chris.jerdonek _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15979> _______________________________________
Roundup Robot added the comment: New changeset 60c831305e73 by Ezio Melotti in branch '2.7': #15979: improve timeit documentation. http://hg.python.org/cpython/rev/60c831305e73 New changeset d5a4300702c1 by Ezio Melotti in branch '3.2': #15979: improve timeit documentation. http://hg.python.org/cpython/rev/d5a4300702c1 New changeset ff32d390f897 by Ezio Melotti in branch '3.3': #15979: merge with 3.2. http://hg.python.org/cpython/rev/ff32d390f897 New changeset 85b6c1c19cb8 by Ezio Melotti in branch 'default': #15979: merge with 3.3. http://hg.python.org/cpython/rev/85b6c1c19cb8 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15979> _______________________________________
Ezio Melotti added the comment: Fixed, thanks for the review! ---------- resolution: -> fixed stage: commit review -> committed/rejected status: open -> closed versions: +Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15979> _______________________________________
Raymond Hettinger added the comment: +1 ---------- nosy: +rhettinger _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15979> _______________________________________
Ezio Melotti added the comment: The sh syntax highlight can be enabled with: .. code-block:: sh $ ... ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15979> _______________________________________
Ezio Melotti added the comment: Here's a patch. ---------- assignee: docs@python -> ezio.melotti keywords: +patch stage: needs patch -> patch review Added file: http://bugs.python.org/file27273/issue15979.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15979> _______________________________________
Antoine Pitrou added the comment: I don't think there's a need for two separate examples sections (one "basic examples" and one "examples"). Also, you say a couple of times "The equivalent can be achieved from the :ref:`python-interface`", but that's not true since the command-line interface auto-calibrates, which the Python API (unfortunately) doesn't. Besides, the results use different units and can't be directly compared. ---------- nosy: +pitrou _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15979> _______________________________________
Ezio Melotti added the comment: The first example shows the basic usage and it's right at the beginning, all the other "advanced" examples are at the bottom. About the autocalibration you are right, I'll rephrase the sentence (see also #6422). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15979> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- stage: patch review -> commit review Added file: http://bugs.python.org/file27382/issue15979-2.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15979> _______________________________________
Chris Jerdonek added the comment: I copy-edited the patch just looking for minor things like punctuation, etc: +a :ref:`command-line-interface` as well as :ref:`callable <python-interface>` a callable one +See also Tim Peters' introduction to the "Algorithms" chapter in the Python +Cookbook, published by O'Reilly. italicize or underline book titles (is there a reST directive for books?) +The following example shows how the :ref:`command-line-interface`, no comma +Python interface Python Interface + Create a :class:`Timer` instance with the given statement, setup code and timer + function and run its :meth:`.timeit` method with *number* executions. stars around setup and timer like there is with *number*? + Create a :class:`Timer` instance with the given statement, setup code and timer + function and run its :meth:`.repeat` method with the given *repeat* count and ditto + Define a default timer, in a platform specific manner. On Windows, platform-specific + :func:`time.clock` has microsecond granularity but :func:`time.time`'s granularity, but + granularity is 1/60th of a second; on Unix, :func:`time.clock` has 1/100th of I would just split this into two sentences since it already combines two compound sentences (i.e. it is effectively four sentences): second. On Unix, + a second granularity and :func:`time.time` is much more precise. On either granularity, and + Time *number* executions of the main statement. This executes the setup statement. This + statement once, and then returns the time it takes to execute the main statement + a number of times, measured in seconds as a float. The argument is the number *number* times + baseline overhead can be measured by invoking the program without arguments and arguments, and ---------- nosy: +chris.jerdonek _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15979> _______________________________________
Roundup Robot added the comment: New changeset 60c831305e73 by Ezio Melotti in branch '2.7': #15979: improve timeit documentation. http://hg.python.org/cpython/rev/60c831305e73 New changeset d5a4300702c1 by Ezio Melotti in branch '3.2': #15979: improve timeit documentation. http://hg.python.org/cpython/rev/d5a4300702c1 New changeset ff32d390f897 by Ezio Melotti in branch '3.3': #15979: merge with 3.2. http://hg.python.org/cpython/rev/ff32d390f897 New changeset 85b6c1c19cb8 by Ezio Melotti in branch 'default': #15979: merge with 3.3. http://hg.python.org/cpython/rev/85b6c1c19cb8 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15979> _______________________________________
Ezio Melotti added the comment: Fixed, thanks for the review! ---------- resolution: -> fixed stage: commit review -> committed/rejected status: open -> closed versions: +Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15979> _______________________________________
participants (5)
-
Antoine Pitrou -
Chris Jerdonek
-
Ezio Melotti
-
Raymond Hettinger
-
Roundup Robot