From 42f49f776a8a4f70a66212dc69bf10f4e3b742c7 Mon Sep 17 00:00:00 2001
From: Petr Viktorin <encukou@gmail.com>
Date: Mon, 7 Jul 2025 12:31:13 +0200
Subject: [PATCH 1/2] [3.13] gh-135755: Document __future__.* and CO_* as
 proper Sphinx objects (GH-135980)

* 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 2468aafe984fdf923811ef0c6969e3d6c1b92a82)

Co-authored-by: Petr Viktorin <encukou@gmail.com>
---
 Doc/c-api/code.rst         | 65 +++++++++++++++++++++++++++++++++
 Doc/c-api/veryhigh.rst     |  8 ++--
 Doc/library/__future__.rst | 75 +++++++++++++++++++++++---------------
 3 files changed, 114 insertions(+), 34 deletions(-)

diff --git a/Doc/c-api/code.rst b/Doc/c-api/code.rst
index 42594f063b0709..717b0da8f87c7f 100644
--- a/Doc/c-api/code.rst
+++ b/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
 -----------------
 
diff --git a/Doc/c-api/veryhigh.rst b/Doc/c-api/veryhigh.rst
index 1ef4181d52eb10..fb07fec7effce8 100644
--- a/Doc/c-api/veryhigh.rst
+++ b/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
-
-      This bit can be set in *flags* to cause division operator ``/`` to be
-      interpreted as "true division" according to :pep:`238`.
+   The "``PyCF``" flags above can be combined with "``CO_FUTURE``" flags such
+   as :c:macro:`CO_FUTURE_ANNOTATIONS` to enable features normally
+   selectable using :ref:`future statements <future>`.
+   See :ref:`c_codeobject_flags` for a complete list.
diff --git a/Doc/library/__future__.rst b/Doc/library/__future__.rst
index 1ebff4409b1e95..fcc7e282a7a7af 100644
--- a/Doc/library/__future__.rst
+++ b/Doc/library/__future__.rst
@@ -37,36 +37,51 @@ 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                                      |
-+==================+=============+==============+=============================================+
-| nested_scopes    | 2.1.0b1     | 2.2          | :pep:`227`:                                 |
-|                  |             |              | *Statically Nested Scopes*                  |
-+------------------+-------------+--------------+---------------------------------------------+
-| generators       | 2.2.0a1     | 2.3          | :pep:`255`:                                 |
-|                  |             |              | *Simple Generators*                         |
-+------------------+-------------+--------------+---------------------------------------------+
-| division         | 2.2.0a2     | 3.0          | :pep:`238`:                                 |
-|                  |             |              | *Changing the Division Operator*            |
-+------------------+-------------+--------------+---------------------------------------------+
-| absolute_import  | 2.5.0a1     | 3.0          | :pep:`328`:                                 |
-|                  |             |              | *Imports: Multi-Line and Absolute/Relative* |
-+------------------+-------------+--------------+---------------------------------------------+
-| with_statement   | 2.5.0a1     | 2.6          | :pep:`343`:                                 |
-|                  |             |              | *The "with" Statement*                      |
-+------------------+-------------+--------------+---------------------------------------------+
-| print_function   | 2.6.0a2     | 3.0          | :pep:`3105`:                                |
-|                  |             |              | *Make print a function*                     |
-+------------------+-------------+--------------+---------------------------------------------+
-| unicode_literals | 2.6.0a2     | 3.0          | :pep:`3112`:                                |
-|                  |             |              | *Bytes literals in Python 3000*             |
-+------------------+-------------+--------------+---------------------------------------------+
-| generator_stop   | 3.5.0b1     | 3.7          | :pep:`479`:                                 |
-|                  |             |              | *StopIteration handling inside generators*  |
-+------------------+-------------+--------------+---------------------------------------------+
-| annotations      | 3.7.0b1     | TBD [1]_     | :pep:`563`:                                 |
-|                  |             |              | *Postponed evaluation of annotations*       |
-+------------------+-------------+--------------+---------------------------------------------+
+
+.. list-table::
+   :widths: auto
+   :header-rows: 1
+
+   * * feature
+     * optional in
+     * mandatory in
+     * effect
+   * * .. data:: nested_scopes
+     * 2.1.0b1
+     * 2.2
+     * :pep:`227`: *Statically Nested Scopes*
+   * * .. data:: generators
+     * 2.2.0a1
+     * 2.3
+     * :pep:`255`: *Simple Generators*
+   * * .. data:: division
+     * 2.2.0a2
+     * 3.0
+     * :pep:`238`: *Changing the Division Operator*
+   * * .. data:: absolute_import
+     * 2.5.0a1
+     * 3.0
+     * :pep:`328`: *Imports: Multi-Line and Absolute/Relative*
+   * * .. data:: with_statement
+     * 2.5.0a1
+     * 2.6
+     * :pep:`343`: *The “with” Statement*
+   * * .. data:: print_function
+     * 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*
 
 .. XXX Adding a new entry?  Remember to update simple_stmts.rst, too.
 

From b30cafa2b43e91a8ea661261a6eaca5e78bc9995 Mon Sep 17 00:00:00 2001
From: Petr Viktorin <encukou@gmail.com>
Date: Mon, 7 Jul 2025 12:54:16 +0200
Subject: [PATCH 2/2] Remove constants that don't exist in 3.13

---
 Doc/c-api/code.rst | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/Doc/c-api/code.rst b/Doc/c-api/code.rst
index 717b0da8f87c7f..f187cad4e63054 100644
--- a/Doc/c-api/code.rst
+++ b/Doc/c-api/code.rst
@@ -255,10 +255,6 @@ For their meaning, see the linked documentation of their Python equivalents.
      * :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`)

<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'>
<html xmlns='http://www.w3.org/1999/xhtml'>
<head>
<title>pFad - Phonifier reborn</title>
<meta http-equiv='Content-Type' content='text/html; charset=utf-8' />
</head>
<body>
<h1>Pfad - The Proxy pFad of &#169; 2024 Garber Painting. All rights reserved.</h1>


<!-- Disclaimer -->
<p>Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.</p>
<br>
<p>Alternative Proxies:</p><p><a href="http://rainy.clevelandohioweatherforecast.com/php-proxy/index.php?q=https://patch-diff.githubusercontent.com/raw/python/cpython/pull/136371.patch" target="_blank">Alternative Proxy</a></p><p><a href="http://rainy.clevelandohioweatherforecast.com/pFad/index.php?u=https://patch-diff.githubusercontent.com/raw/python/cpython/pull/136371.patch" target="_blank">pFad Proxy</a></p><p><a href="http://rainy.clevelandohioweatherforecast.com/pFad/v3index.php?u=https://patch-diff.githubusercontent.com/raw/python/cpython/pull/136371.patch" target="_blank">pFad v3 Proxy</a></p><p><a href="http://rainy.clevelandohioweatherforecast.com/pFad/v4index.php?u=https://patch-diff.githubusercontent.com/raw/python/cpython/pull/136371.patch" target="_blank">pFad v4 Proxy</a></p></body>
</html>