Merge in the main branch (re-applying additions from #144279)

Author: encukou

Doc/c-api/intro.rst

@@ -157,8 +157,8 @@ Others of a more general utility are defined here.  This is not necessarily a
 complete listing.
 
 
-Utilities
----------
+Arithmetic Utilities
+--------------------
 
 .. c:macro:: Py_ABS(x)
 
@@ -184,11 +184,125 @@ Utilities
 
    .. versionadded:: 3.3
 
+.. c:macro:: Py_ARITHMETIC_RIGHT_SHIFT(type, integer, positions)
+   Similar to ``integer >> positions``, but forces sign extension, as the C
+   standard does not define whether a right-shift of a signed integer will
+   perform sign extension or a zero-fill.
+
+   *integer* should be any signed integer type.
+   *positions* is the number of positions to shift to the right.
+
+   Both *integer* and *positions* can be evaluated more than once;
+   consequently, avoid directly passing a function call or some other
+   operation with side-effects to this macro. Instead, store the result as a
+   variable and then pass it.
+
+   *type* is unused and only kept for backwards compatibility. Historically,
+   *type* was used to cast *integer*.
+
+   .. versionchanged:: 3.1
+
+      This macro is now valid for all signed integer types, not just those for
+      which ``unsigned type`` is legal. As a result, *type* is no longer
+      used.
+
+.. c:macro:: Py_SAFE_DOWNCAST(value, larger, smaller)
+   Cast *value* to type *smaller* from type *larger*, validating that no
+   information was lost.
+
+   On release builds of Python, this is roughly equivalent to
+   ``(smaller) value`` (in C++, ``static_cast<smaller>(value)`` will be
+   used instead).
+
+   On debug builds (implying that :c:macro:`Py_DEBUG` is defined), this asserts
+   that no information was lost with the cast from *larger* to *smaller*.
+
+   *value*, *larger*, and *smaller* may all be evaluated more than once in the
+   expression; consequently, do not pass an expression with side-effects
+   directly to this macro.
+
+.. c:macro:: Py_CHARMASK(c)
+
+   Argument must be a character or an integer in the range [-128, 127] or [0,
+   255].  This macro returns ``c`` cast to an ``unsigned char``.
+
+
+Python-specific utilities
+-------------------------
+
 .. c:macro:: Py_GETENV(s)
 
    Like :samp:`getenv({s})`, but returns ``NULL`` if :option:`-E` was passed
    on the command line (see :c:member:`PyConfig.use_environment`).
 
+.. c:macro:: Py_CAN_START_THREADS
+   If this macro is defined, then the current system is able to start threads.
+
+   Currently, all systems supported by CPython (per :pep:`11`), with the
+   exception of some WebAssembly platforms, support starting threads.
+
+   .. versionadded:: 3.13
+
+Docstring utilities
+^^^^^^^^^^^^^^^^^^^
+
+.. c:macro:: PyDoc_STRVAR(name, str)
+
+   Creates a variable with name *name* that can be used in docstrings.
+   If Python is built :option:`without docstrings <--without-doc-strings>`,
+   the value will be an empty string.
+
+   Example::
+
+      PyDoc_STRVAR(pop_doc, "Remove and return the rightmost element.");
+
+      static PyMethodDef deque_methods[] = {
+          // ...
+          {"pop", (PyCFunction)deque_pop, METH_NOARGS, pop_doc},
+          // ...
+      }
+
+   Expands to :samp:`PyDoc_VAR({name}) = PyDoc_STR({str})`.
+
+.. c:macro:: PyDoc_STR(str)
+
+   Expands to the given input string, or an empty string
+   if docstrings are :option:`disabled <--without-doc-strings>`.
+
+   Example::
+
+      static PyMethodDef pysqlite_row_methods[] = {
+          {"keys", (PyCFunction)pysqlite_row_keys, METH_NOARGS,
+              PyDoc_STR("Returns the keys of the row.")},
+          {NULL, NULL}
+      };
+
+.. c:macro:: PyDoc_VAR(name)
+
+   Declares a static character array variable with the given *name*.
+   Expands to :samp:`static const char {name}[]`
+
+   For example::
+
+      PyDoc_VAR(python_doc) = PyDoc_STR(
+         "A genus of constricting snakes in the Pythonidae family native "
+         "to the tropics and subtropics of the Eastern Hemisphere.");
+
+General Utilities
+-----------------
+
+The following macros common tasks not specific to Python.
+
+.. c:macro:: Py_UNUSED(arg)
+
+   Use this for unused arguments in a function definition to silence compiler
+   warnings. Example: ``int func(int a, int Py_UNUSED(b)) { return a; }``.
+
+   .. versionadded:: 3.4
+
+Assertions
+^^^^^^^^^^
+
 .. c:macro:: Py_UNREACHABLE()
 
    Use this when you have a code path that cannot be reached by design.
@@ -213,27 +327,6 @@ Utilities
 
    .. versionadded:: 3.7
 
-.. c:macro:: Py_MEMBER_SIZE(type, member)
-
-   Return the size of a structure (*type*) *member* in bytes.
-
-   Corresponds roughly to :samp:`sizeof((({type} *)NULL)->{member})`.
-
-   .. versionadded:: 3.6
-
-.. c:macro:: Py_ARRAY_LENGTH(array)
-
-   Compute the length of a statically allocated C array at compile time.
-
-   The *array* argument must be a C array with a size known at compile time.
-   Passing an array with an unknown size, such as a heap-allocated array,
-   will result in a compilation error on some compilers, or otherwise produce
-   incorrect results.
-
-   This is roughly equivalent to::
-
-      sizeof(array) / sizeof((array)[0])
-
 .. c:macro:: Py_BUILD_ASSERT(cond)
 
    Asserts a compile-time condition *cond*, as a statement.
@@ -259,78 +352,51 @@ Utilities
 
    .. versionadded:: 3.3
 
-.. c:macro:: Py_STRINGIFY(x)
-
-   Convert ``x`` to a C string.  For example, ``Py_STRINGIFY(123)`` returns
-   ``"123"``.
-
-   .. versionadded:: 3.4
-
-.. c:macro:: Py_UNUSED(arg)
-
-   Use this for unused arguments in a function definition to silence compiler
-   warnings. Example: ``int func(int a, int Py_UNUSED(b)) { return a; }``.
-
-   .. versionadded:: 3.4
-
-.. c:macro:: Py_CHARMASK(c)
-
-   Argument must be a character or an integer in the range [-128, 127] or [0,
-   255].  This macro returns ``c`` cast to an ``unsigned char``.
-
-.. c:macro:: Py_MEMCPY(dest, src, n)
-
-   This is a :term:`soft deprecated` alias to :c:func:`!memcpy`.
-   Use :c:func:`!memcpy` directly instead.
-
-   .. deprecated:: 3.14
-      The macro is :term:`soft deprecated`.
+Size helpers
+^^^^^^^^^^^^
 
+.. c:macro:: Py_MEMBER_SIZE(type, member)
 
-Docstring utilities
--------------------
+   Return the size of a structure (*type*) *member* in bytes.
 
-.. c:macro:: PyDoc_STRVAR(name, str)
+   Corresponds roughly to :samp:`sizeof((({type} *)NULL)->{member})`.
 
-   Creates a variable with name *name* that can be used in docstrings.
-   If Python is built :option:`without docstrings <--without-doc-strings>`,
-   the value will be an empty string.
+   .. versionadded:: 3.6
 
-   Example::
+.. c:macro:: Py_ARRAY_LENGTH(array)
 
-      PyDoc_STRVAR(pop_doc, "Remove and return the rightmost element.");
+   Compute the length of a statically allocated C array at compile time.
 
-      static PyMethodDef deque_methods[] = {
-          // ...
-          {"pop", (PyCFunction)deque_pop, METH_NOARGS, pop_doc},
-          // ...
-      }
+   The *array* argument must be a C array with a size known at compile time.
+   Passing an array with an unknown size, such as a heap-allocated array,
+   will result in a compilation error on some compilers, or otherwise produce
+   incorrect results.
 
-   Expands to :samp:`PyDoc_VAR({name}) = PyDoc_STR({str})`.
+   This is roughly equivalent to::
 
-.. c:macro:: PyDoc_STR(str)
+      sizeof(array) / sizeof((array)[0])
 
-   Expands to the given input string, or an empty string
-   if docstrings are :option:`disabled <--without-doc-strings>`.
+Macro helpers
+^^^^^^^^^^^^^
 
-   Example::
+.. c:macro:: Py_STRINGIFY(x)
 
-      static PyMethodDef pysqlite_row_methods[] = {
-          {"keys", (PyCFunction)pysqlite_row_keys, METH_NOARGS,
-              PyDoc_STR("Returns the keys of the row.")},
-          {NULL, NULL}
-      };
+   Convert ``x`` to a C string.  For example, ``Py_STRINGIFY(123)`` returns
+   ``"123"``.
 
-.. c:macro:: PyDoc_VAR(name)
+   .. versionadded:: 3.4
 
-   Declares a static character array variable with the given *name*.
-   Expands to :samp:`static const char {name}[]`
+.. c:macro:: Py_FORCE_EXPANSION(X)
+   This is equivalent to ``X``, which is useful for token-pasting in
+   macros, as macro expansions in *X* are forcefully evaluated by the
+   preprocessor.
 
-   For example::
+.. c:macro:: Py_GCC_ATTRIBUTE(name)
+   Use a GCC attribute *name*, hiding it from compilers that don't support GCC
+   attributes (such as MSVC).
 
-      PyDoc_VAR(python_doc) = PyDoc_STR(
-         "A genus of constricting snakes in the Pythonidae family native "
-         "to the tropics and subtropics of the Eastern Hemisphere.");
+   This expands to ``__attribute__((name))`` on a GCC compiler, and expands
+   to nothing on compilers that don't support GCC attributes.
 
 
 Declaration utilities
@@ -383,7 +449,7 @@ to the C language.
 
 .. c:macro:: Py_DEPRECATED(version)
 
-   Use this to declare APIs that were deprecated in a specific CPYthon version.
+   Use this to declare APIs that were deprecated in a specific CPython version.
    The macro must be placed before the symbol name.
 
    Example::
@@ -444,6 +510,48 @@ to the C language.
    extension modules should not use it for their own symbols.
 
 
+Outdated macros
+---------------
+
+The following macros have been used to features that have been standardized
+in C11.
+They are still available for code that uses them.
+
+.. c:macro:: Py_ALIGNED(num)
+   Specify alignment to *num* bytes on compilers that support it.
+
+   Consider using the C11 standard ``_Alignas`` specifier over this macro.
+
+.. c:macro:: Py_LL(number)
+             Py_ULL(number)
+
+   Use *number* as a ``long long`` or ``unsigned long long`` integer literal,
+   respectively.
+
+   Expands to *number* followed by `LL`` or ``LLU``, respectively, but will
+   expand to some compiler-specific suffixes on some older compilers.
+
+   Consider using the C99 standard suffixes ``LL` and ``LLU`` directly.
+
+.. c:macro:: Py_MEMCPY(dest, src, n)
+
+   This is a :term:`soft deprecated` alias to :c:func:`!memcpy`.
+   Use :c:func:`!memcpy` directly instead.
+
+   .. deprecated:: 3.14
+      The macro is :term:`soft deprecated`.
+
+.. c:macro:: Py_VA_COPY
+
+   This is a :term:`soft deprecated` alias to the C99-standard ``va_copy``
+   function.
+
+   Historically, this would use a compiler-specific method to copy a ``va_list``.
+
+   .. versionchanged:: 3.6
+      This is now an alias to ``va_copy``.
+
+
 .. _api-objects:
 
 Objects, Types and Reference Counts

Doc/glossary.rst

@@ -786,6 +786,19 @@ Glossary
       An object that both finds and loads a module; both a
       :term:`finder` and :term:`loader` object.
 
+   index
+      A numeric value that represents the position of an element in
+      a :term:`sequence`.
+
+      In Python, indexing starts at zero.
+      For example, ``things[0]`` names the *first* element of ``things``;
+      ``things[1]`` names the second one.
+
+      In some contexts, Python allows negative indexes for counting from the
+      end of a sequence, and indexing using :term:`slices <slice>`.
+
+      See also :term:`subscript`.
+
    interactive
       Python has an interactive interpreter which means you can enter
       statements and expressions at the interpreter prompt, immediately
@@ -863,6 +876,9 @@ Glossary
          CPython does not guarantee :term:`thread-safe` behavior of iterator
          operations.
 
+   key
+      A value that identifies an entry in a :term:`mapping`.
+      See also :term:`subscript`.
 
    key function
       A key function or collation function is a callable that returns a value
@@ -1417,10 +1433,11 @@ Glossary
       chosen based on the type of a single argument.
 
    slice
-      An object usually containing a portion of a :term:`sequence`.  A slice is
-      created using the subscript notation, ``[]`` with colons between numbers
-      when several are given, such as in ``variable_name[1:3:5]``.  The bracket
-      (subscript) notation uses :class:`slice` objects internally.
+      An object of type :class:`slice`, used to describe a portion of
+      a :term:`sequence`.
+      A slice object is created when using the :ref:`slicing <slicings>` form
+      of :ref:`subscript notation <subscriptions>`, with colons inside square
+      brackets, such as in ``variable_name[1:3:5]``.
 
    soft deprecated
       A soft deprecated API should not be used in new code,
@@ -1478,6 +1495,14 @@ Glossary
 
       See also :term:`borrowed reference`.
 
+   subscript
+      The expression in square brackets of a
+      :ref:`subscription expression <subscriptions>`, for example,
+      the ``3`` in ``items[3]``.
+      Usually used to select an element of a container.
+      Also called a :term:`key` when subscripting a :term:`mapping`,
+      or an :term:`index` when subscripting a :term:`sequence`.
+
    synchronization primitive
       A basic building block for coordinating (synchronizing) the execution of
       multiple threads to ensure :term:`thread-safe` access to shared resources.