bpo-35511: Trivial docs updates for profile and resource library modules. (GH-11124)

polish documentation for profile and resource modules

diff --git a/Doc/library/profile.rst b/Doc/library/profile.rst
index 9ceb81603c951ec4f4bf21bb135d356b6832dd23..d8039fd28e0d8a8799d7a9762aa87ec0c4a1b383 100644 (file)
--- a/Doc/library/profile.rst
+++ b/Doc/library/profile.rst
@@ -265,8 +265,8 @@ functions:
       ps.print_stats()
       print(s.getvalue())
 
-   The :class:`Profile` class can also be used as a context manager (see
-   :ref:`typecontextmanager`)::
+   The :class:`Profile` class can also be used as a context manager (supported
+   only in :mod:`cProfile` module. see :ref:`typecontextmanager`)::
 
       import cProfile
 
@@ -280,11 +280,11 @@ functions:
 
    .. method:: enable()
 
-      Start collecting profiling data.
+      Start collecting profiling data. Only in :mod:`cProfile`.
 
    .. method:: disable()
 
-      Stop collecting profiling data.
+      Stop collecting profiling data. Only in :mod:`cProfile`.
 
    .. method:: create_stats()
 
@@ -540,9 +540,9 @@ less overhead (as the code does not need to be instrumented), but provides only
 relative indications of where time is being spent.
 
 In Python, since there is an interpreter active during execution, the presence
-of instrumented code is not required to do deterministic profiling.  Python
-automatically provides a :dfn:`hook` (optional callback) for each event.  In
-addition, the interpreted nature of Python tends to add so much overhead to
+of instrumented code is not required in order to do deterministic profiling.
+Python automatically provides a :dfn:`hook` (optional callback) for each event.
+In addition, the interpreted nature of Python tends to add so much overhead to
 execution, that deterministic profiling tends to only add small processing
 overhead in typical applications.  The result is that deterministic profiling is
 not that expensive, yet provides extensive run time statistics about the

diff --git a/Doc/library/resource.rst b/Doc/library/resource.rst
index bd49c87f1d78713d9648e6aadca8c4d95e67c97e..2ed15c136736689e58597e105889a49a3a08798d 100644 (file)
--- a/Doc/library/resource.rst
+++ b/Doc/library/resource.rst
@@ -261,6 +261,20 @@ These functions are used to retrieve resource usage information:
    *who* parameter should be specified using one of the :const:`RUSAGE_\*`
    constants described below.
 
+   A simple example::
+
+      from resource import *
+      import time
+
+      # a non CPU-bound task
+      time.sleep(3)
+      print(getrusage(RUSAGE_SELF))
+
+      # a CPU-bound task
+      for i in range(10 ** 8):
+         _ = 1 + 1
+      print(getrusage(RUSAGE_SELF))
+
    The fields of the return value each describe how a particular system resource
    has been used, e.g. amount of time spent running is user mode or number of times
    the process was swapped out of main memory. Some values are dependent on the
@@ -275,41 +289,41 @@ These functions are used to retrieve resource usage information:
    remaining values are integers. Consult the :manpage:`getrusage(2)` man page for
    detailed information about these values. A brief summary is presented here:
 
-   +--------+---------------------+-------------------------------+
-   | Index  | Field               | Resource                      |
-   +========+=====================+===============================+
-   | ``0``  | :attr:`ru_utime`    | time in user mode (float)     |
-   +--------+---------------------+-------------------------------+
-   | ``1``  | :attr:`ru_stime`    | time in system mode (float)   |
-   +--------+---------------------+-------------------------------+
-   | ``2``  | :attr:`ru_maxrss`   | maximum resident set size     |
-   +--------+---------------------+-------------------------------+
-   | ``3``  | :attr:`ru_ixrss`    | shared memory size            |
-   +--------+---------------------+-------------------------------+
-   | ``4``  | :attr:`ru_idrss`    | unshared memory size          |
-   +--------+---------------------+-------------------------------+
-   | ``5``  | :attr:`ru_isrss`    | unshared stack size           |
-   +--------+---------------------+-------------------------------+
-   | ``6``  | :attr:`ru_minflt`   | page faults not requiring I/O |
-   +--------+---------------------+-------------------------------+
-   | ``7``  | :attr:`ru_majflt`   | page faults requiring I/O     |
-   +--------+---------------------+-------------------------------+
-   | ``8``  | :attr:`ru_nswap`    | number of swap outs           |
-   +--------+---------------------+-------------------------------+
-   | ``9``  | :attr:`ru_inblock`  | block input operations        |
-   +--------+---------------------+-------------------------------+
-   | ``10`` | :attr:`ru_oublock`  | block output operations       |
-   +--------+---------------------+-------------------------------+
-   | ``11`` | :attr:`ru_msgsnd`   | messages sent                 |
-   +--------+---------------------+-------------------------------+
-   | ``12`` | :attr:`ru_msgrcv`   | messages received             |
-   +--------+---------------------+-------------------------------+
-   | ``13`` | :attr:`ru_nsignals` | signals received              |
-   +--------+---------------------+-------------------------------+
-   | ``14`` | :attr:`ru_nvcsw`    | voluntary context switches    |
-   +--------+---------------------+-------------------------------+
-   | ``15`` | :attr:`ru_nivcsw`   | involuntary context switches  |
-   +--------+---------------------+-------------------------------+
+   +--------+---------------------+---------------------------------------+
+   | Index  | Field               | Resource                              |
+   +========+=====================+=======================================+
+   | ``0``  | :attr:`ru_utime`    | time in user mode (float seconds)     |
+   +--------+---------------------+---------------------------------------+
+   | ``1``  | :attr:`ru_stime`    | time in system mode (float seconds)   |
+   +--------+---------------------+---------------------------------------+
+   | ``2``  | :attr:`ru_maxrss`   | maximum resident set size             |
+   +--------+---------------------+---------------------------------------+
+   | ``3``  | :attr:`ru_ixrss`    | shared memory size                    |
+   +--------+---------------------+---------------------------------------+
+   | ``4``  | :attr:`ru_idrss`    | unshared memory size                  |
+   +--------+---------------------+---------------------------------------+
+   | ``5``  | :attr:`ru_isrss`    | unshared stack size                   |
+   +--------+---------------------+---------------------------------------+
+   | ``6``  | :attr:`ru_minflt`   | page faults not requiring I/O         |
+   +--------+---------------------+---------------------------------------+
+   | ``7``  | :attr:`ru_majflt`   | page faults requiring I/O             |
+   +--------+---------------------+---------------------------------------+
+   | ``8``  | :attr:`ru_nswap`    | number of swap outs                   |
+   +--------+---------------------+---------------------------------------+
+   | ``9``  | :attr:`ru_inblock`  | block input operations                |
+   +--------+---------------------+---------------------------------------+
+   | ``10`` | :attr:`ru_oublock`  | block output operations               |
+   +--------+---------------------+---------------------------------------+
+   | ``11`` | :attr:`ru_msgsnd`   | messages sent                         |
+   +--------+---------------------+---------------------------------------+
+   | ``12`` | :attr:`ru_msgrcv`   | messages received                     |
+   +--------+---------------------+---------------------------------------+
+   | ``13`` | :attr:`ru_nsignals` | signals received                      |
+   +--------+---------------------+---------------------------------------+
+   | ``14`` | :attr:`ru_nvcsw`    | voluntary context switches            |
+   +--------+---------------------+---------------------------------------+
+   | ``15`` | :attr:`ru_nivcsw`   | involuntary context switches          |
+   +--------+---------------------+---------------------------------------+
 
    This function will raise a :exc:`ValueError` if an invalid *who* parameter is
    specified. It may also raise :exc:`error` exception in unusual circumstances.

diff --git a/Misc/NEWS.d/next/Documentation/2018-12-16-16-14-44.bpo-35511.iVcyav.rst b/Misc/NEWS.d/next/Documentation/2018-12-16-16-14-44.bpo-35511.iVcyav.rst
new file mode 100644 (file)
index 0000000..69c9d9f
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2018-12-16-16-14-44.bpo-35511.iVcyav.rst
@@ -0,0 +1,3 @@
+Specified that profile.Profile class doesn't not support enable or disable
+methods. Also, elaborated that Profile object as a context manager is only
+supported in cProfile module.