Address reviews

python · pablogsal · Oct 27, 2022 · Aug 29, 2022 · Aug 30, 2022 · Aug 30, 2022
commit cbe8b162faacfa7d8a7d8be9a55b6cd52467bbd3
diff --git a/Doc/howto/perf_profiling.rst b/Doc/howto/perf_profiling.rst
@@ -151,41 +151,45 @@ Instead, if we run the same experiment with ``perf`` support enabled we get:
 How to enable ``perf`` profiling support
 ----------------------------------------
 
-There are three ways to enable ``perf`` profiling support:
+There are three ways to enable ``perf`` profiling support;
+the environment variable :envvar:`PYTHONPERFSUPPORT` and the
+:option:`-X perf <-X>` option allow you to enable perf profiling from the start,
+whereas the :func:`sys.activate_stack_trampoline` and
+:func:`sys.deactivate_stack_trampoline` functions allow you to enable and
+disable it dynamically.
 
-* using the :option:`-Xperf <-X>` command-line option
-* using the :envvar:`PYTHONPERFSUPPORT` environment variable
-* using the :func:`sys.activate_stack_trampoline` and
-  :func:`sys.deactivate_stack_trampoline` APIs
+The :mod:`!sys` functions take precedence over the :option:`!-X` option,
+the :option:`!-X` option takes precedence over the environment variable.
 
-If you want profiling to be active when you start the Python interpreter,
-use the :option:`-Xperf <-X>` option::
+Example, using the environment variable::
 
-    $ python -Xperf my_script.py
+   $ PYTHONPERFSUPPORT=1
+   $ python script1.py
+   $ python script2.py
+   $ python script3.py
+   $ perf report -g -i perf.data
 
-If you need to enable ``perf`` profiling support globally,
-set the environment variable :envvar:`PYTHONPERFSUPPORT`
-to a nonzero value.
+Example, using the :option:`!-X` option::
 
-If you need to dynamically enable and disable ``perf`` profiling
-in response to a signal or other communication mechanisms with your process,
-use the :func:`sys.activate_stack_trampoline` and
-:func:`sys.deactivate_stack_trampoline` APIs:
+   $ python -X perf script1.py
+   $ perf report -g -i perf.data
 
-.. code-block:: python
+Example, using the :mod:`sys` APIs in file :file:`example.py`:
 
-    import sys
-    sys.activate_stack_trampoline("perf")
+.. code-block:: python
 
-    # Run some code with Perf profiling active
+   import sys
 
-    sys.deactivate_stack_trampoline()
+   sys.activate_stack_trampoline("perf")
+   do_profiled_stuff()
+   sys.deactivate_stack_trampoline()
 
-    # Perf profiling is not active anymore
+   non_profiled_stuff()
 
-Now we can analyze the data with ``perf report``::
+...then::
 
-    $ perf report -g -i perf.data
+   $ python ./example.py
+   $ perf report -g -i perf.data
 
 
 How to obtain the best results

diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
@@ -1540,15 +1540,17 @@ always available.
 
 .. function:: deactivate_stack_trampoline()
 
-   Deactivate the stack profiler trampoline.
+   Deactivate the current stack profiler trampoline backend.
+
+   If no stack profiler is activated, this function has no effect.
 
    .. availability:: Linux.
 
    .. versionadded:: 3.12
 
 .. function:: is_stack_trampoline_active()
 
-   Return ``True`` if the stack profiler trampoline is active.
+   Return ``True`` if a stack profiler trampoline is active.
 
    .. availability:: Linux.
 

diff --git a/Doc/whatsnew/3.12.rst b/Doc/whatsnew/3.12.rst
@@ -74,9 +74,10 @@ Important deprecations, removals or restrictions:
 New Features
 ============
 
-* Add :ref:`perf_profiling` through the new command-line option
-  :option:`-X perf <-X>`, as well as the new
-  :func:`sys.activate_stack_trampoline`,
+* Add :ref:`perf_profiling` through the new
+  environment variable :envvar:`PYTHONPERFSUPPORT`,
+  the new command-line option :option:`-X perf <-X>`,
+  as well as the new :func:`sys.activate_stack_trampoline`,
   :func:`sys.deactivate_stack_trampoline`,
   and :func:`sys.is_stack_trampoline_active` APIs.
   (Design by Pablo Galindo. Contributed by Pablo Galindo and Christian Heimes

diff --git a/Misc/NEWS.d/next/Core and Builtins/2022-08-20-18-36-40.gh-issue-96143.nh3GFM.rst b/Misc/NEWS.d/next/Core and Builtins/2022-08-20-18-36-40.gh-issue-96143.nh3GFM.rst
@@ -1,6 +1,8 @@
-Add :ref:`perf_profiling` through the new command-line option
-:option:`-X perf <-X>`, as well as the new
-:func:`sys.activate_stack_trampoline`, :func:`sys.deactivate_stack_trampoline`,
+Add :ref:`perf_profiling` through the new
+environment variable :envvar:`PYTHONPERFSUPPORT`,
+the new command-line option :option:`-X perf <-X>`,
+as well as the new :func:`sys.activate_stack_trampoline`,
+:func:`sys.deactivate_stack_trampoline`,
 and :func:`sys.is_stack_trampoline_active` APIs.
-Design by Pablo Galindo. Patch by Pablo Galindo and Christian Heimes
+Design by Pablo Galindo. Contributed by Pablo Galindo and Christian Heimes
 with contributions from Gregory P. Smith [Google] and Mark Shannon.
@@ -2095,12 +2095,14 @@ sys_activate_stack_trampoline_impl(PyObject *module, const char *backend)
 /*[clinic input]
 sys.deactivate_stack_trampoline
 
-Dectivate stack profiler trampoline backend.
+Deactivate the current stack profiler trampoline backend.
+
+If no stack profiler is activated, this function has no effect.
 [clinic start generated code]*/
 
 static PyObject *
 sys_deactivate_stack_trampoline_impl(PyObject *module)
-/*[clinic end generated code: output=b50da25465df0ef1 input=be0c9a8737fe7e8f]*/
+/*[clinic end generated code: output=b50da25465df0ef1 input=9f629a6be9fe7fc8]*/
 {
     if  (_PyPerfTrampoline_Init(0) < 0) {
         return NULL;
@@ -2111,12 +2113,12 @@ sys_deactivate_stack_trampoline_impl(PyObject *module)
 /*[clinic input]
 sys.is_stack_trampoline_active
 
-Return *True* if the stack profiler trampoline is active.
+    Return *True* if a stack profiler trampoline is active.
 [clinic start generated code]*/
 
 static PyObject *
 sys_is_stack_trampoline_active_impl(PyObject *module)
-/*[clinic end generated code: output=ab2746de0ad9d293 input=d802fd4a1afa2de8]*/
+/*[clinic end generated code: output=ab2746de0ad9d293 input=29616b7bf6a0b703]*/
 {
 #ifdef PY_HAVE_PERF_TRAMPOLINE
     if (_PyIsPerfTrampolineActive()) {