Skip to content

Commit 5df4f35

Browse files
miss-islingtonencukou
miss-islington
and
encukou
authored
[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 2468aaf) Co-authored-by: Petr Viktorin <[email protected]>
1 parent f02be2d commit 5df4f35

File tree

3 files changed

+115
-36
lines changed

3 files changed

+115
-36
lines changed

‎Doc/c-api/code.rst

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -211,6 +211,71 @@ bound into a function.
211211
.. versionadded:: 3.12
212212
213213
214+
.. _c_codeobject_flags:
215+
216+
Code Object Flags
217+
-----------------
218+
219+
Code objects contain a bit-field of flags, which can be retrieved as the
220+
:attr:`~codeobject.co_flags` Python attribute (for example using
221+
:c:func:`PyObject_GetAttrString`), and set using a *flags* argument to
222+
:c:func:`PyUnstable_Code_New` and similar functions.
223+
224+
Flags whose names start with ``CO_FUTURE_`` correspond to features normally
225+
selectable by :ref:`future statements <future>`. These flags can be used in
226+
:c:member:`PyCompilerFlags.cf_flags`.
227+
Note that many ``CO_FUTURE_`` flags are mandatory in current versions of
228+
Python, and setting them has no effect.
229+
230+
The following flags are available.
231+
For their meaning, see the linked documentation of their Python equivalents.
232+
233+
234+
.. list-table::
235+
:widths: auto
236+
:header-rows: 1
237+
238+
* * Flag
239+
* Meaning
240+
* * .. c:macro:: CO_OPTIMIZED
241+
* :py:data:`inspect.CO_OPTIMIZED`
242+
* * .. c:macro:: CO_NEWLOCALS
243+
* :py:data:`inspect.CO_NEWLOCALS`
244+
* * .. c:macro:: CO_VARARGS
245+
* :py:data:`inspect.CO_VARARGS`
246+
* * .. c:macro:: CO_VARKEYWORDS
247+
* :py:data:`inspect.CO_VARKEYWORDS`
248+
* * .. c:macro:: CO_NESTED
249+
* :py:data:`inspect.CO_NESTED`
250+
* * .. c:macro:: CO_GENERATOR
251+
* :py:data:`inspect.CO_GENERATOR`
252+
* * .. c:macro:: CO_COROUTINE
253+
* :py:data:`inspect.CO_COROUTINE`
254+
* * .. c:macro:: CO_ITERABLE_COROUTINE
255+
* :py:data:`inspect.CO_ITERABLE_COROUTINE`
256+
* * .. c:macro:: CO_ASYNC_GENERATOR
257+
* :py:data:`inspect.CO_ASYNC_GENERATOR`
258+
* * .. c:macro:: CO_HAS_DOCSTRING
259+
* :py:data:`inspect.CO_HAS_DOCSTRING`
260+
* * .. c:macro:: CO_METHOD
261+
* :py:data:`inspect.CO_METHOD`
262+
263+
* * .. c:macro:: CO_FUTURE_DIVISION
264+
* no effect (:py:data:`__future__.division`)
265+
* * .. c:macro:: CO_FUTURE_ABSOLUTE_IMPORT
266+
* no effect (:py:data:`__future__.absolute_import`)
267+
* * .. c:macro:: CO_FUTURE_WITH_STATEMENT
268+
* no effect (:py:data:`__future__.with_statement`)
269+
* * .. c:macro:: CO_FUTURE_PRINT_FUNCTION
270+
* no effect (:py:data:`__future__.print_function`)
271+
* * .. c:macro:: CO_FUTURE_UNICODE_LITERALS
272+
* no effect (:py:data:`__future__.unicode_literals`)
273+
* * .. c:macro:: CO_FUTURE_GENERATOR_STOP
274+
* no effect (:py:data:`__future__.generator_stop`)
275+
* * .. c:macro:: CO_FUTURE_ANNOTATIONS
276+
* :py:data:`__future__.annotations`
277+
278+
214279
Extra information
215280
-----------------
216281

‎Doc/c-api/veryhigh.rst

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

‎Doc/library/__future__.rst

Lines changed: 46 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -37,38 +37,52 @@ No feature description will ever be deleted from :mod:`__future__`. Since its
3737
introduction in Python 2.1 the following features have found their way into the
3838
language using this mechanism:
3939

40-
+------------------+-------------+--------------+---------------------------------------------+
41-
| feature | optional in | mandatory in | effect |
42-
+==================+=============+==============+=============================================+
43-
| nested_scopes | 2.1.0b1 | 2.2 | :pep:`227`: |
44-
| | | | *Statically Nested Scopes* |
45-
+------------------+-------------+--------------+---------------------------------------------+
46-
| generators | 2.2.0a1 | 2.3 | :pep:`255`: |
47-
| | | | *Simple Generators* |
48-
+------------------+-------------+--------------+---------------------------------------------+
49-
| division | 2.2.0a2 | 3.0 | :pep:`238`: |
50-
| | | | *Changing the Division Operator* |
51-
+------------------+-------------+--------------+---------------------------------------------+
52-
| absolute_import | 2.5.0a1 | 3.0 | :pep:`328`: |
53-
| | | | *Imports: Multi-Line and Absolute/Relative* |
54-
+------------------+-------------+--------------+---------------------------------------------+
55-
| with_statement | 2.5.0a1 | 2.6 | :pep:`343`: |
56-
| | | | *The "with" Statement* |
57-
+------------------+-------------+--------------+---------------------------------------------+
58-
| print_function | 2.6.0a2 | 3.0 | :pep:`3105`: |
59-
| | | | *Make print a function* |
60-
+------------------+-------------+--------------+---------------------------------------------+
61-
| unicode_literals | 2.6.0a2 | 3.0 | :pep:`3112`: |
62-
| | | | *Bytes literals in Python 3000* |
63-
+------------------+-------------+--------------+---------------------------------------------+
64-
| generator_stop | 3.5.0b1 | 3.7 | :pep:`479`: |
65-
| | | | *StopIteration handling inside generators* |
66-
+------------------+-------------+--------------+---------------------------------------------+
67-
| annotations | 3.7.0b1 | Never [1]_ | :pep:`563`: |
68-
| | | | *Postponed evaluation of annotations*, |
69-
| | | | :pep:`649`: *Deferred evaluation of |
70-
| | | | annotations using descriptors* |
71-
+------------------+-------------+--------------+---------------------------------------------+
40+
41+
.. list-table::
42+
:widths: auto
43+
:header-rows: 1
44+
45+
* * feature
46+
* optional in
47+
* mandatory in
48+
* effect
49+
* * .. data:: nested_scopes
50+
* 2.1.0b1
51+
* 2.2
52+
* :pep:`227`: *Statically Nested Scopes*
53+
* * .. data:: generators
54+
* 2.2.0a1
55+
* 2.3
56+
* :pep:`255`: *Simple Generators*
57+
* * .. data:: division
58+
* 2.2.0a2
59+
* 3.0
60+
* :pep:`238`: *Changing the Division Operator*
61+
* * .. data:: absolute_import
62+
* 2.5.0a1
63+
* 3.0
64+
* :pep:`328`: *Imports: Multi-Line and Absolute/Relative*
65+
* * .. data:: with_statement
66+
* 2.5.0a1
67+
* 2.6
68+
* :pep:`343`: *The “with” Statement*
69+
* * .. data:: print_function
70+
* 2.6.0a2
71+
* 3.0
72+
* :pep:`3105`: *Make print a function*
73+
* * .. data:: unicode_literals
74+
* 2.6.0a2
75+
* 3.0
76+
* :pep:`3112`: *Bytes literals in Python 3000*
77+
* * .. data:: generator_stop
78+
* 3.5.0b1
79+
* 3.7
80+
* :pep:`479`: *StopIteration handling inside generators*
81+
* * .. data:: annotations
82+
* 3.7.0b1
83+
* Never [1]_
84+
* :pep:`563`: *Postponed evaluation of annotations*,
85+
:pep:`649`: *Deferred evaluation of annotations using descriptors*
7286

7387
.. XXX Adding a new entry? Remember to update simple_stmts.rst, too.
7488

0 commit comments

Comments
 (0)