Merge branch 'main' into urllib-parse-allow-none

Author: serhiy-storchaka

Doc/c-api/concrete.rst

@@ -109,6 +109,7 @@ Other Objects
    descriptor.rst
    slice.rst
    memoryview.rst
+   picklebuffer.rst
    weakref.rst
    capsule.rst
    frame.rst

Doc/c-api/picklebuffer.rst

@@ -0,0 +1,59 @@
+.. highlight:: c
+
+.. _picklebuffer-objects:
+
+.. index::
+   pair: object; PickleBuffer
+
+Pickle buffer objects
+---------------------
+
+.. versionadded:: 3.8
+
+A :class:`pickle.PickleBuffer` object wraps a :ref:`buffer-providing object
+<bufferobjects>` for out-of-band data transfer with the :mod:`pickle` module.
+
+
+.. c:var:: PyTypeObject PyPickleBuffer_Type
+
+   This instance of :c:type:`PyTypeObject` represents the Python pickle buffer type.
+   This is the same object as :class:`pickle.PickleBuffer` in the Python layer.
+
+
+.. c:function:: int PyPickleBuffer_Check(PyObject *op)
+
+   Return true if *op* is a pickle buffer instance.
+   This function always succeeds.
+
+
+.. c:function:: PyObject *PyPickleBuffer_FromObject(PyObject *obj)
+
+   Create a pickle buffer from the object *obj*.
+
+   This function will fail if *obj* doesn't support the :ref:`buffer protocol <bufferobjects>`.
+
+   On success, return a new pickle buffer instance.
+   On failure, set an exception and return ``NULL``.
+
+   Analogous to calling :class:`pickle.PickleBuffer` with *obj* in Python.
+
+
+.. c:function:: const Py_buffer *PyPickleBuffer_GetBuffer(PyObject *picklebuf)
+
+   Get a pointer to the underlying :c:type:`Py_buffer` that the pickle buffer wraps.
+
+   The returned pointer is valid as long as *picklebuf* is alive and has not been
+   released. The caller must not modify or free the returned :c:type:`Py_buffer`.
+   If the pickle buffer has been released, raise :exc:`ValueError`.
+
+   On success, return a pointer to the buffer view.
+   On failure, set an exception and return ``NULL``.
+
+
+.. c:function:: int PyPickleBuffer_Release(PyObject *picklebuf)
+
+   Release the underlying buffer held by the pickle buffer.
+
+   Return ``0`` on success. On failure, set an exception and return ``-1``.
+
+   Analogous to calling :meth:`pickle.PickleBuffer.release` in Python.

Doc/c-api/structures.rst

@@ -447,6 +447,25 @@ definition with the same method name.
    slot.  This is helpful because calls to PyCFunctions are optimized more
    than wrapper object calls.
 
+
+.. c:var:: PyTypeObject PyCMethod_Type
+
+   The type object corresponding to Python C method objects. This is
+   available as :class:`types.BuiltinMethodType` in the Python layer.
+
+
+.. c:function:: int PyCMethod_Check(PyObject *op)
+
+   Return true if *op* is an instance of the :c:type:`PyCMethod_Type` type
+   or a subtype of it. This function always succeeds.
+
+
+.. c:function:: int PyCMethod_CheckExact(PyObject *op)
+
+   This is the same as :c:func:`PyCMethod_Check`, but does not account for
+   subtypes.
+
+
 .. c:function:: PyObject * PyCMethod_New(PyMethodDef *ml, PyObject *self, PyObject *module, PyTypeObject *cls)
 
    Turn *ml* into a Python :term:`callable` object.
@@ -472,6 +491,24 @@ definition with the same method name.
    .. versionadded:: 3.9
 
 
+.. c:var:: PyTypeObject PyCFunction_Type
+
+   The type object corresponding to Python C function objects. This is
+   available as :class:`types.BuiltinFunctionType` in the Python layer.
+
+
+.. c:function:: int PyCFunction_Check(PyObject *op)
+
+   Return true if *op* is an instance of the :c:type:`PyCFunction_Type` type
+   or a subtype of it. This function always succeeds.
+
+
+.. c:function:: int PyCFunction_CheckExact(PyObject *op)
+
+   This is the same as :c:func:`PyCFunction_Check`, but does not account for
+   subtypes.
+
+
 .. c:function:: PyObject * PyCFunction_NewEx(PyMethodDef *ml, PyObject *self, PyObject *module)
 
    Equivalent to ``PyCMethod_New(ml, self, module, NULL)``.
@@ -482,6 +519,62 @@ definition with the same method name.
    Equivalent to ``PyCMethod_New(ml, self, NULL, NULL)``.
 
 
+.. c:function:: int PyCFunction_GetFlags(PyObject *func)
+
+   Get the function's flags on *func* as they were passed to
+   :c:member:`~PyMethodDef.ml_flags`.
+
+   If *func* is not a C function object, this fails with an exception.
+   *func* must not be ``NULL``.
+
+   This function returns the function's flags on success, and ``-1`` with an
+   exception set on failure.
+
+
+.. c:function:: int PyCFunction_GET_FLAGS(PyObject *func)
+
+   This is the same as :c:func:`PyCFunction_GetFlags`, but without error
+   or type checking.
+
+
+.. c:function:: PyCFunction PyCFunction_GetFunction(PyObject *func)
+
+   Get the function pointer on *func* as it was passed to
+   :c:member:`~PyMethodDef.ml_meth`.
+
+   If *func* is not a C function object, this fails with an exception.
+   *func* must not be ``NULL``.
+
+   This function returns the function pointer on success, and ``NULL`` with an
+   exception set on failure.
+
+
+.. c:function:: int PyCFunction_GET_FUNCTION(PyObject *func)
+
+   This is the same as :c:func:`PyCFunction_GetFunction`, but without error
+   or type checking.
+
+
+.. c:function:: PyObject *PyCFunction_GetSelf(PyObject *func)
+
+   Get the "self" object on *func*. This is the object that would be passed
+   to the first argument of a :c:type:`PyCFunction`. For C function objects
+   created through a :c:type:`PyMethodDef` on a :c:type:`PyModuleDef`, this
+   is the resulting module object.
+
+   If *func* is not a C function object, this fails with an exception.
+   *func* must not be ``NULL``.
+
+   This function returns a :term:`borrowed reference` to the "self" object
+   on success, and ``NULL`` with an exception set on failure.
+
+
+.. c:function:: PyObject *PyCFunction_GET_SELF(PyObject *func)
+
+   This is the same as :c:func:`PyCFunction_GetSelf`, but without error or
+   type checking.
+
+
 Accessing attributes of extension types
 ---------------------------------------
 

Doc/library/cmdline.rst

@@ -16,17 +16,17 @@ The following modules have a command-line interface.
 * :ref:`dis <dis-cli>`
 * :ref:`doctest <doctest-cli>`
 * :mod:`!encodings.rot_13`
-* :mod:`ensurepip`
+* :ref:`ensurepip <ensurepip-cli>`
 * :mod:`filecmp`
 * :mod:`fileinput`
 * :mod:`ftplib`
 * :ref:`gzip <gzip-cli>`
 * :ref:`http.server <http-server-cli>`
-* :mod:`!idlelib`
+* :ref:`idlelib <idlelib-cli>`
 * :ref:`inspect <inspect-module-cli>`
 * :ref:`json <json-commandline>`
 * :ref:`mimetypes <mimetypes-cli>`
-* :mod:`pdb`
+* :ref:`pdb <pdb-cli>`
 * :ref:`pickle <pickle-cli>`
 * :ref:`pickletools <pickletools-cli>`
 * :ref:`platform <platform-cli>`
@@ -52,8 +52,8 @@ The following modules have a command-line interface.
 * :mod:`turtledemo`
 * :ref:`unittest <unittest-command-line-interface>`
 * :ref:`uuid <uuid-cli>`
-* :mod:`venv`
-* :mod:`webbrowser`
+* :ref:`venv <venv-cli>`
+* :ref:`webbrowser <webbrowser-cli>`
 * :ref:`zipapp <zipapp-command-line-interface>`
 * :ref:`zipfile <zipfile-commandline>`
 

Doc/library/ensurepip.rst

@@ -42,7 +42,9 @@ when creating a virtual environment) or after explicitly uninstalling
 
 .. include:: ../includes/wasm-mobile-notavail.rst
 
-Command line interface
+.. _ensurepip-cli:
+
+Command-line interface
 ----------------------
 
 .. program:: ensurepip

Doc/library/gzip.rst

@@ -283,7 +283,7 @@ Example of how to GZIP compress a binary string::
 
 .. _gzip-cli:
 
-Command Line Interface
+Command-line interface
 ----------------------
 
 The :mod:`gzip` module provides a simple command line interface to compress or
@@ -296,7 +296,7 @@ Once executed the :mod:`gzip` module keeps the input file(s).
    Add a new command line interface with a usage.
    By default, when you will execute the CLI, the default compression level is 6.
 
-Command line options
+Command-line options
 ^^^^^^^^^^^^^^^^^^^^
 
 .. option:: file

Doc/library/idle.rst

@@ -661,7 +661,9 @@ looked for in the user's home directory.  Statements in this file will be
 executed in the Tk namespace, so this file is not useful for importing
 functions to be used from IDLE's Python shell.
 
-Command line usage
+.. _idlelib-cli:
+
+Command-line usage
 ^^^^^^^^^^^^^^^^^^
 
 .. program:: idle

Doc/library/inspect.rst

@@ -1788,7 +1788,7 @@ Buffer flags
 
 .. _inspect-module-cli:
 
-Command Line Interface
+Command-line interface
 ----------------------
 
 The :mod:`inspect` module also provides a basic introspection capability

Doc/library/pdb.rst

@@ -76,6 +76,10 @@ The debugger's prompt is ``(Pdb)``, which is the indicator that you are in debug
 
 
 .. _pdb-cli:
+
+Command-line interface
+----------------------
+
 .. program:: pdb
 
 You can also invoke :mod:`pdb` from the command line to debug other scripts.  For
@@ -334,7 +338,7 @@ access further features, you have to do this yourself:
 
 .. _debugger-commands:
 
-Debugger Commands
+Debugger commands
 -----------------
 
 The commands recognized by the debugger are listed below.  Most commands can be

Doc/library/profile.rst

@@ -265,6 +265,14 @@ Profile with real-time sampling statistics::
 
    Sample all threads in the process instead of just the main thread
 
+.. option:: --native
+
+   Include artificial ``<native>`` frames to denote calls to non-Python code.
+
+.. option:: --no-gc
+
+   Don't include artificial ``<GC>`` frames to denote active garbage collection.
+
 .. option:: --realtime-stats
 
    Print real-time sampling statistics during profiling
@@ -349,7 +357,7 @@ This section documents the programmatic interface for the :mod:`!profiling.sampl
 For command-line usage, see :ref:`sampling-profiler-cli`. For conceptual information
 about statistical profiling, see :ref:`statistical-profiling`
 
-.. function:: sample(pid, *, sort=2, sample_interval_usec=100, duration_sec=10, filename=None, all_threads=False, limit=None, show_summary=True, output_format="pstats", realtime_stats=False)
+.. function:: sample(pid, *, sort=2, sample_interval_usec=100, duration_sec=10, filename=None, all_threads=False, limit=None, show_summary=True, output_format="pstats", realtime_stats=False, native=False, gc=True)
 
    Sample a Python process and generate profiling data.
 
@@ -367,6 +375,8 @@ about statistical profiling, see :ref:`statistical-profiling`
    :param bool show_summary: Whether to show summary statistics (default: True)
    :param str output_format: Output format - 'pstats' or 'collapsed' (default: 'pstats')
    :param bool realtime_stats: Whether to display real-time statistics (default: False)
+   :param bool native: Whether to include ``<native>`` frames (default: False)
+   :param bool gc: Whether to include ``<GC>`` frames (default: True)
 
    :raises ValueError: If output_format is not 'pstats' or 'collapsed'