mirror of
https://github.com/python/cpython.git
synced 2025-07-07 11:25:30 +00:00
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.
This commit is contained in:
Petr Viktorin
GitHub
parent
cb99d99277
commit
2468aafe98
3 changed files with 115 additions and 36 deletions
|
|
@ -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
|
||||
-----------------
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue