https://github.com/python/cpython/commit/2468aafe984fdf923811ef0c6969e3d6c1b92a82
commit: 2468aafe984fdf923811ef0c6969e3d6c1b92a82
branch: main
author: Petr Viktorin <[email protected]>
committer: encukou <[email protected]>
date: 2025-07-07T12:31:13+02:00
summary:
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.
files:
M Doc/c-api/code.rst
M Doc/c-api/veryhigh.rst
M Doc/library/__future__.rst
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 4f3b663006fb28..5d916b30112d3c 100644
--- a/Doc/library/__future__.rst
+++ b/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
|
-+==================+=============+==============+=============================================+
-| 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 | Never [1]_ | :pep:`563`:
|
-| | | | *Postponed evaluation of
annotations*, |
-| | | | :pep:`649`: *Deferred
evaluation of |
-| | | | annotations using
descriptors* |
-+------------------+-------------+--------------+---------------------------------------------+
+
+.. 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*,
+ :pep:`649`: *Deferred evaluation of annotations using descriptors*
.. XXX Adding a new entry? Remember to update simple_stmts.rst, too.
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]
