bpo-40484: Document compiler flags under AST module (GH-19885) (GH-22… · python/cpython@a358a0a

@@ -245,26 +245,24 @@ are always available. They are listed here in alphabetical order.

245245

interactive statement (in the latter case, expression statements that

246246

evaluate to something other than ``None`` will be printed).

247247248-

The optional arguments *flags* and *dont_inherit* control which :ref:`future

249-

statements <future>` affect the compilation of *source*. If neither

250-

is present (or both are zero) the code is compiled with those future

251-

statements that are in effect in the code that is calling :func:`compile`. If the

252-

*flags* argument is given and *dont_inherit* is not (or is zero) then the

253-

future statements specified by the *flags* argument are used in addition to

254-

those that would be used anyway. If *dont_inherit* is a non-zero integer then

255-

the *flags* argument is it -- the future statements in effect around the call

256-

to compile are ignored.

257-258-

Future statements are specified by bits which can be bitwise ORed together to

259-

specify multiple statements. The bitfield required to specify a given feature

260-

can be found as the :attr:`~__future__._Feature.compiler_flag` attribute on

261-

the :class:`~__future__._Feature` instance in the :mod:`__future__` module.

262-263-

The optional argument *flags* also controls whether the compiled source is

264-

allowed to contain top-level ``await``, ``async for`` and ``async with``.

265-

When the bit ``ast.PyCF_ALLOW_TOP_LEVEL_AWAIT`` is set, the return code

266-

object has ``CO_COROUTINE`` set in ``co_code``, and can be interactively

267-

executed via ``await eval(code_object)``.

248+

The optional argument *flags* and *dont_inherit* controls which

249+

:ref:`compiler options <ast-compiler-flags>` should be activated

250+

and which :ref:`future features <future>` should be allowed. If neither

251+

is present (or both are zero) the code is compiled with the same flags that

252+

affect the code that is calling :func:`compile`. If the *flags*

253+

argument is given and *dont_inherit* is not (or is zero) then the compiler

254+

options and the future statements specified by the *flags* argument are used

255+

in addition to those that would be used anyway. If *dont_inherit* is a

256+

non-zero integer then the *flags* argument is it -- the flags (future

257+

features and compiler options) in the surrounding code are ignored.

258+259+

Compiler options and future statements are specified by bits which can be

260+

bitwise ORed together to specify multiple options. The bitfield required to

261+

specify a given future feature can be found as the

262+

:attr:`~__future__._Feature.compiler_flag` attribute on the

263+

:class:`~__future__._Feature` instance in the :mod:`__future__` module.

264+

:ref:`Compiler flags <ast-compiler-flags>` can be found in :mod:`ast`

265+

module, with ``PyCF_`` prefix.

268266269267

The argument *optimize* specifies the optimization level of the compiler; the

270268

default value of ``-1`` selects the optimization level of the interpreter as