[3.14] gh-135755: Document __future__.* and CO_* as proper Sphinx objects (GH-135980) (GH-136370)

* Turn the __future__ table to list-table.
  This'll make it easier to add entries that need longer markup
* Semantic markup for __future__ feature descriptions.
* Document CO_* C macros.

(cherry picked from commit 2468aafe98)

Co-authored-by: Petr Viktorin <encukou@gmail.com>

Doc/c-api/code.rst

@@ -211,6 +211,71 @@ bound into a function.
    .. versionadded:: 3.12
 
 
+.. _c_codeobject_flags:
+
+Code Object Flags
+-----------------
+
+Code objects contain a bit-field of flags, which can be retrieved as the
+:attr:`~codeobject.co_flags` Python attribute (for example using
+:c:func:`PyObject_GetAttrString`), and set using a *flags* argument to
+:c:func:`PyUnstable_Code_New` and similar functions.
+
+Flags whose names start with ``CO_FUTURE_`` correspond to features normally
+selectable by :ref:`future statements <future>`. These flags can be used in
+:c:member:`PyCompilerFlags.cf_flags`.
+Note that many ``CO_FUTURE_`` flags are mandatory in current versions of
+Python, and setting them has no effect.
+
+The following flags are available.
+For their meaning, see the linked documentation of their Python equivalents.
+
+
+.. list-table::
+   :widths: auto
+   :header-rows: 1
+
+   * * Flag
+     * Meaning
+   * * .. c:macro:: CO_OPTIMIZED
+     * :py:data:`inspect.CO_OPTIMIZED`
+   * * .. c:macro:: CO_NEWLOCALS
+     * :py:data:`inspect.CO_NEWLOCALS`
+   * * .. c:macro:: CO_VARARGS
+     * :py:data:`inspect.CO_VARARGS`
+   * * .. c:macro:: CO_VARKEYWORDS
+     * :py:data:`inspect.CO_VARKEYWORDS`
+   * * .. c:macro:: CO_NESTED
+     * :py:data:`inspect.CO_NESTED`
+   * * .. c:macro:: CO_GENERATOR
+     * :py:data:`inspect.CO_GENERATOR`
+   * * .. c:macro:: CO_COROUTINE
+     * :py:data:`inspect.CO_COROUTINE`
+   * * .. c:macro:: CO_ITERABLE_COROUTINE
+     * :py:data:`inspect.CO_ITERABLE_COROUTINE`
+   * * .. c:macro:: CO_ASYNC_GENERATOR
+     * :py:data:`inspect.CO_ASYNC_GENERATOR`
+   * * .. c:macro:: CO_HAS_DOCSTRING
+     * :py:data:`inspect.CO_HAS_DOCSTRING`
+   * * .. c:macro:: CO_METHOD
+     * :py:data:`inspect.CO_METHOD`
+
+   * * .. c:macro:: CO_FUTURE_DIVISION
+     * no effect (:py:data:`__future__.division`)
+   * * .. c:macro:: CO_FUTURE_ABSOLUTE_IMPORT
+     * no effect (:py:data:`__future__.absolute_import`)
+   * * .. c:macro:: CO_FUTURE_WITH_STATEMENT
+     * no effect (:py:data:`__future__.with_statement`)
+   * * .. c:macro:: CO_FUTURE_PRINT_FUNCTION
+     * no effect (:py:data:`__future__.print_function`)
+   * * .. c:macro:: CO_FUTURE_UNICODE_LITERALS
+     * no effect (:py:data:`__future__.unicode_literals`)
+   * * .. c:macro:: CO_FUTURE_GENERATOR_STOP
+     * no effect (:py:data:`__future__.generator_stop`)
+   * * .. c:macro:: CO_FUTURE_ANNOTATIONS
+     * :py:data:`__future__.annotations`
+
+
 Extra information
 -----------------
 

Doc/c-api/veryhigh.rst

@@ -361,7 +361,7 @@ the same library that the Python runtime is using.
       :py:mod:`!ast` Python module, which exports these constants under
       the same names.
 
-   .. c:var:: int CO_FUTURE_DIVISION
+   The "``PyCF``" flags above can be combined with "``CO_FUTURE``" flags such
-
+   as :c:macro:`CO_FUTURE_ANNOTATIONS` to enable features normally
-      This bit can be set in *flags* to cause division operator ``/`` to be
+   selectable using :ref:`future statements <future>`.
-      interpreted as "true division" according to :pep:`238`.
+   See :ref:`c_codeobject_flags` for a complete list.

Doc/library/__future__.rst

@@ -37,38 +37,52 @@ No feature description will ever be deleted from :mod:`__future__`. Since its
 introduction in Python 2.1 the following features have found their way into the
 language using this mechanism:
 
-+------------------+-------------+--------------+---------------------------------------------+
+
-| feature          | optional in | mandatory in | effect                                      |
+.. list-table::
-+==================+=============+==============+=============================================+
+   :widths: auto
-| nested_scopes    | 2.1.0b1     | 2.2          | :pep:`227`:                                 |
+   :header-rows: 1
-|                  |             |              | *Statically Nested Scopes*                  |
+
-+------------------+-------------+--------------+---------------------------------------------+
+   * * feature
-| generators       | 2.2.0a1     | 2.3          | :pep:`255`:                                 |
+     * optional in
-|                  |             |              | *Simple Generators*                         |
+     * mandatory in
-+------------------+-------------+--------------+---------------------------------------------+
+     * effect
-| division         | 2.2.0a2     | 3.0          | :pep:`238`:                                 |
+   * * .. data:: nested_scopes
-|                  |             |              | *Changing the Division Operator*            |
+     * 2.1.0b1
-+------------------+-------------+--------------+---------------------------------------------+
+     * 2.2
-| absolute_import  | 2.5.0a1     | 3.0          | :pep:`328`:                                 |
+     * :pep:`227`: *Statically Nested Scopes*
-|                  |             |              | *Imports: Multi-Line and Absolute/Relative* |
+   * * .. data:: generators
-+------------------+-------------+--------------+---------------------------------------------+
+     * 2.2.0a1
-| with_statement   | 2.5.0a1     | 2.6          | :pep:`343`:                                 |
+     * 2.3
-|                  |             |              | *The "with" Statement*                      |
+     * :pep:`255`: *Simple Generators*
-+------------------+-------------+--------------+---------------------------------------------+
+   * * .. data:: division
-| print_function   | 2.6.0a2     | 3.0          | :pep:`3105`:                                |
+     * 2.2.0a2
-|                  |             |              | *Make print a function*                     |
+     * 3.0
-+------------------+-------------+--------------+---------------------------------------------+
+     * :pep:`238`: *Changing the Division Operator*
-| unicode_literals | 2.6.0a2     | 3.0          | :pep:`3112`:                                |
+   * * .. data:: absolute_import
-|                  |             |              | *Bytes literals in Python 3000*             |
+     * 2.5.0a1
-+------------------+-------------+--------------+---------------------------------------------+
+     * 3.0
-| generator_stop   | 3.5.0b1     | 3.7          | :pep:`479`:                                 |
+     * :pep:`328`: *Imports: Multi-Line and Absolute/Relative*
-|                  |             |              | *StopIteration handling inside generators*  |
+   * * .. data:: with_statement
-+------------------+-------------+--------------+---------------------------------------------+
+     * 2.5.0a1
-| annotations      | 3.7.0b1     | Never [1]_   | :pep:`563`:                                 |
+     * 2.6
-|                  |             |              | *Postponed evaluation of annotations*,      |
+     * :pep:`343`: *The “with” Statement*
-|                  |             |              | :pep:`649`: *Deferred evaluation of         |
+   * * .. data:: print_function
-|                  |             |              | annotations using descriptors*              |
+     * 2.6.0a2
-+------------------+-------------+--------------+---------------------------------------------+
+     * 3.0
+     * :pep:`3105`: *Make print a function*
+   * * .. data:: unicode_literals
+     * 2.6.0a2
+     * 3.0
+     * :pep:`3112`: *Bytes literals in Python 3000*
+   * * .. data:: generator_stop
+     * 3.5.0b1
+     * 3.7
+     * :pep:`479`: *StopIteration handling inside generators*
+   * * .. data:: annotations
+     * 3.7.0b1
+     * Never [1]_
+     * :pep:`563`: *Postponed evaluation of annotations*,
+       :pep:`649`: *Deferred evaluation of annotations using descriptors*
 
 .. XXX Adding a new entry?  Remember to update simple_stmts.rst, too.