Skip to content

Commit 2468aaf

Browse files
encukouencukou
authored
pythongh-135755: Document __future__.* and CO_* as proper Sphinx objects (pythonGH-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.
1 parent cb99d99 commit 2468aaf

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)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

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.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy