Merge branch 'main' into gh-161415-pydoc-related-topics

Author: andresdelfino

.github/CODEOWNERS

@@ -172,8 +172,12 @@ Lib/_osx_support.py           @python/macos-team
 Lib/test/test__osx_support.py @python/macos-team
 
 # WebAssembly (Emscripten)
-Platforms/emscripten          @freakboy3742 @emmatyping
-Tools/wasm/emscripten         @freakboy3742 @emmatyping
+Platforms/emscripten          @freakboy3742 @emmatyping @hoodmane
+Tools/wasm/emscripten         @freakboy3742 @emmatyping @hoodmane
+Python/wasm_trampoline.c      @hoodmane
+Python/emscripten_signal.c    @hoodmane
+Python/emscripten_syscalls.c  @hoodmane
+.github/workflows/reusable-emscripten.yml @hoodmane
 
 # WebAssembly (WASI)
 Platforms/WASI                @brettcannon @emmatyping @savannahostrowski

Doc/c-api/code.rst

@@ -44,6 +44,14 @@ bound into a function.
       The old name is deprecated, but will remain available until the
       signature changes again.
 
+.. c:function:: PyObject* PyUnstable_Code_GetLocalPlusNames(PyCodeObject *co)
+
+   Return a :term:`strong reference` to a tuple of names of the local, cell and
+   free variables of a code object. The names are in the same order as the
+   values returned by :c:func:`PyUnstable_InterpreterFrame_GetLocal`.
+
+   .. versionadded:: next
+
 .. c:function:: PyCodeObject* PyUnstable_Code_New(int argcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, PyObject *qualname, int firstlineno, PyObject *linetable, PyObject *exceptiontable)
 
    Return a new code object.  If you need a dummy code object to create a frame,

Doc/c-api/frame.rst

@@ -241,3 +241,21 @@ Unless using :pep:`523`, you will not need this.
    Return the currently executing line number, or -1 if there is no line number.
 
    .. versionadded:: 3.12
+
+
+.. c:function:: int PyUnstable_InterpreterFrame_GetLocal(struct _PyInterpreterFrame *frame, Py_ssize_t index, PyObject **result)
+
+   Retrieve the local variable at *index*.
+   To determine the index of a particular variable, use
+   :c:func:`PyUnstable_InterpreterFrame_GetCode` and
+   :c:func:`PyUnstable_Code_GetLocalPlusNames`.
+
+   Cell and free variables are unboxed to their contents.  Free variables are
+   resolved from the function closure, so this also works on a frame that has
+   not started executing.
+
+   * On success, store a new :term:`strong reference` in *result* and return ``1``.
+   * If the slot is unset or hidden, store ``NULL`` in *result* and return ``0``.
+   * On error, raise an exception, store ``NULL`` in *result* and return ``-1``.
+
+   .. versionadded:: next

Doc/c-api/tuple.rst

@@ -133,16 +133,36 @@ Tuple Objects
 
 .. c:function:: int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)
 
-   Can be used to resize a tuple.  *newsize* will be the new length of the tuple.
-   Because tuples are *supposed* to be immutable, this should only be used if there
-   is only one reference to the object.  Do *not* use this if the tuple may already
-   be known to some other part of the code.  The tuple will always grow or shrink
-   at the end.  Think of this as destroying the old tuple and creating a new one,
-   only more efficiently.  Returns ``0`` on success. Client code should never
-   assume that the resulting value of ``*p`` will be the same as before calling
-   this function. If the object referenced by ``*p`` is replaced, the original
-   ``*p`` is destroyed.  On failure, returns ``-1`` and sets ``*p`` to ``NULL``, and
-   raises :exc:`MemoryError` or :exc:`SystemError`.
+   Resize a tuple.
+   *newsize* will be the new length of the tuple.
+
+   Because tuples are *supposed* to be immutable, this should only be used if
+   there is only one reference to the object.
+   Do *not* use this if the tuple may already be known to some other part of
+   the code.
+   The tuple hash value must not be computed yet.
+
+   The tuple will always grow or shrink at the end.
+   Think of this as destroying the old tuple and creating a new one, only more
+   efficiently.
+
+   Returns ``0`` on success.
+   Client code should never assume that the resulting value of ``*p`` will be
+   the same as before calling this function.
+   If the object referenced by ``*p`` is replaced, the original ``*p`` is
+   destroyed.
+
+   On failure, returns ``-1`` and sets ``*p`` to ``NULL``, and raises
+   :exc:`MemoryError` or :exc:`SystemError`.
+
+   While tuple objects are usually immutable in Python, this special C API
+   allows mutating a tuple object in-place.
+   The returned tuple object can still be mutated using
+   :c:func:`PyTuple_SetItem`; except if *newsize* is zero in which case it
+   returns the immutable empty tuple.
+
+   .. versionchanged:: next
+      The function now fails if the tuple hash value was already computed.
 
 
 .. _struct-sequence-objects:

Doc/library/profiling.sampling.rst

@@ -29,6 +29,13 @@ code changes or restarts. Because sampling occurs externally to the target
 process, overhead is virtually zero, making Tachyon suitable for both
 development and production environments.
 
+Tachyon follows earlier work on external sampling profilers such as
+`Austin <https://github.com/P403n1x87/austin>`__,
+`py-spy <https://github.com/benfred/py-spy>`__,
+`Pyflame <https://github.com/uber-archive/pyflame>`__, and
+`rbspy <https://github.com/rbspy/rbspy>`__. We thank their authors and the wider
+profiling community for their work and ideas.
+
 
 What is statistical profiling?
 ==============================

Doc/whatsnew/3.15.rst

@@ -356,6 +356,13 @@ A new statistical sampling profiler (Tachyon) has been added as
 :mod:`profiling.sampling`. This profiler enables low-overhead performance analysis of
 running Python processes without requiring code modification or process restart.
 
+Tachyon follows earlier work on external sampling profilers such as
+`Austin <https://github.com/P403n1x87/austin>`__,
+`py-spy <https://github.com/benfred/py-spy>`__,
+`Pyflame <https://github.com/uber-archive/pyflame>`__, and
+`rbspy <https://github.com/rbspy/rbspy>`__. We thank their authors and the wider
+profiling community for their work and ideas.
+
 Unlike deterministic profilers (such as :mod:`profiling.tracing`) that instrument
 every function call, the sampling profiler periodically captures stack traces from
 running processes.  This approach provides virtually zero overhead while achieving

Doc/whatsnew/3.16.rst

@@ -1394,6 +1394,12 @@ New features
 * Add the :ref:`PyUnicodeWriter API <pyunicodewriter>` to the limited C API.
   (Contributed by Victor Stinner in :gh:`161172`.)
 
+* Add :c:func:`PyUnstable_InterpreterFrame_GetLocal` to read a local variable
+  of an internal interpreter frame by its localsplus index, and
+  :c:func:`PyUnstable_Code_GetLocalPlusNames` to get the matching variable
+  names.
+  (Contributed by Guilherme Leobas in :gh:`156133`.)
+
 Porting to Python 3.16
 ----------------------
 

Include/ceval.h

@@ -122,14 +122,12 @@ PyAPI_FUNC(void) PyEval_ReleaseThread(PyThreadState *tstate);
 #define Py_END_ALLOW_THREADS    PyEval_RestoreThread(_save); \
                  }
 
-/* Masks and values used by FORMAT_VALUE opcode. */
+/* String conversion constants. */
 #define FVC_MASK      0x3
 #define FVC_NONE      0x0
 #define FVC_STR       0x1
 #define FVC_REPR      0x2
 #define FVC_ASCII     0x3
-#define FVS_MASK      0x4
-#define FVS_HAVE_SPEC 0x4
 
 #ifndef Py_LIMITED_API
 #  define Py_CPYTHON_CEVAL_H

Include/cpython/code.h

@@ -177,6 +177,11 @@ static inline int PyUnstable_Code_GetFirstFree(PyCodeObject *op) {
     return op->co_nlocalsplus - op->co_nfreevars;
 }
 
+static inline PyObject *PyUnstable_Code_GetLocalPlusNames(PyCodeObject *op) {
+    assert(PyCode_Check(op));
+    return Py_NewRef(op->co_localsplusnames);
+}
+
 Py_DEPRECATED(3.13) static inline int PyCode_GetFirstFree(PyCodeObject *op) {
     return PyUnstable_Code_GetFirstFree(op);
 }

Include/cpython/pyframe.h

@@ -35,3 +35,8 @@ PyAPI_FUNC(int) PyUnstable_InterpreterFrame_GetLasti(struct _PyInterpreterFrame
 /* Returns the currently executing line number, or -1 if there is no line number.
  * Does not raise an exception. */
 PyAPI_FUNC(int) PyUnstable_InterpreterFrame_GetLine(struct _PyInterpreterFrame *frame);
+
+/* Returns a new (strong) reference to the local variable at `index` in the
+ * frame's localsplus array. */
+PyAPI_FUNC(int) PyUnstable_InterpreterFrame_GetLocal(
+    struct _PyInterpreterFrame *frame, Py_ssize_t index, PyObject **result);