From 128aa8188386c20fd88f162efcbb56ed380adf2a Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Sat, 8 Nov 2025 16:39:13 -0500 Subject: [PATCH 1/5] Document Py_func_type_input --- Doc/c-api/veryhigh.rst | 90 ++++++++++++++++++++++++++---------------- 1 file changed, 55 insertions(+), 35 deletions(-) diff --git a/Doc/c-api/veryhigh.rst b/Doc/c-api/veryhigh.rst index 0b2b55b6387bd1..ec73cdd8286025 100644 --- a/Doc/c-api/veryhigh.rst +++ b/Doc/c-api/veryhigh.rst @@ -13,8 +13,9 @@ the interpreter. Several of these functions accept a start symbol from the grammar as a parameter. The available start symbols are :c:data:`Py_eval_input`, -:c:data:`Py_file_input`, and :c:data:`Py_single_input`. These are described -following the functions which accept them as parameters. +:c:data:`Py_file_input`, :c:data:`Py_single_input`, and +:c:data:`Py_func_type_input`. These are described following the functions +which accept them as parameters. Note also that several of these functions take :c:expr:`FILE*` parameters. One particular issue which needs to be handled carefully is that the :c:type:`FILE` @@ -183,8 +184,7 @@ the same library that the Python runtime is using. objects *globals* and *locals* with the compiler flags specified by *flags*. *globals* must be a dictionary; *locals* can be any object that implements the mapping protocol. The parameter *start* specifies - the start symbol and must one of the following: - :c:data:`Py_eval_input`, :c:data:`Py_file_input`, or :c:data:`Py_single_input`. + the start symbol and must one of the :ref:`available start symbols `. Returns the result of executing the code as a Python object, or ``NULL`` if an exception was raised. @@ -233,11 +233,10 @@ the same library that the Python runtime is using. Parse and compile the Python source code in *str*, returning the resulting code object. The start symbol is given by *start*; this can be used to constrain the - code which can be compiled and should be :c:data:`Py_eval_input`, - :c:data:`Py_file_input`, or :c:data:`Py_single_input`. The filename specified by - *filename* is used to construct the code object and may appear in tracebacks or - :exc:`SyntaxError` exception messages. This returns ``NULL`` if the code - cannot be parsed or compiled. + code which can be compiled and should be one of the :ref:`available start symbols `. + The filename specified by *filename* is used to construct the code object + and may appear in tracebacks or :exc:`SyntaxError` exception messages. + This returns ``NULL`` if the code cannot be parsed or compiled. The integer *optimize* specifies the optimization level of the compiler; a value of ``-1`` selects the optimization level of the interpreter as given by @@ -297,32 +296,6 @@ the same library that the Python runtime is using. true on success, false on failure. -.. c:var:: int Py_eval_input - - .. index:: single: Py_CompileString (C function) - - The start symbol from the Python grammar for isolated expressions; for use with - :c:func:`Py_CompileString`. - - -.. c:var:: int Py_file_input - - .. index:: single: Py_CompileString (C function) - - The start symbol from the Python grammar for sequences of statements as read - from a file or other source; for use with :c:func:`Py_CompileString`. This is - the symbol to use when compiling arbitrarily long Python source code. - - -.. c:var:: int Py_single_input - - .. index:: single: Py_CompileString (C function) - - The start symbol from the Python grammar for a single statement; for use with - :c:func:`Py_CompileString`. This is the symbol used for the interactive - interpreter loop. - - .. c:struct:: PyCompilerFlags This is the structure used to hold compiler flags. In cases where code is only @@ -366,3 +339,50 @@ the same library that the Python runtime is using. as :c:macro:`CO_FUTURE_ANNOTATIONS` to enable features normally selectable using :ref:`future statements `. See :ref:`c_codeobject_flags` for a complete list. + + +.. _start-symbols: + +Available start symbols +^^^^^^^^^^^^^^^^^^^^^^^ + + +.. c:var:: int Py_eval_input + + .. index:: single: Py_CompileString (C function) + + The start symbol from the Python grammar for isolated expressions; for use with + :c:func:`Py_CompileString`. + + +.. c:var:: int Py_file_input + + .. index:: single: Py_CompileString (C function) + + The start symbol from the Python grammar for sequences of statements as read + from a file or other source; for use with :c:func:`Py_CompileString`. This is + the symbol to use when compiling arbitrarily long Python source code. + + +.. c:var:: int Py_single_input + + .. index:: single: Py_CompileString (C function) + + The start symbol from the Python grammar for a single statement; for use with + :c:func:`Py_CompileString`. This is the symbol used for the interactive + interpreter loop. + + +.. c:var:: int Py_func_type_input + + .. index:: single: Py_CompileString (C function) + + The start symbol from the Python grammar for a function type; for use with + :c:func:`Py_CompileString`. This is used for parsing function ``# type:`` + comments. + + This requires the :c:macro:`PyCF_ONLY_AST` flag to be set. + + .. seealso:: + :py:class:`ast.FunctionType` + From 27769ebd900c433ffff0d3406d4a60c30639ab39 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Sat, 8 Nov 2025 16:42:05 -0500 Subject: [PATCH 2/5] Improve diff. --- Doc/c-api/veryhigh.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/Doc/c-api/veryhigh.rst b/Doc/c-api/veryhigh.rst index ec73cdd8286025..6e62291349b552 100644 --- a/Doc/c-api/veryhigh.rst +++ b/Doc/c-api/veryhigh.rst @@ -233,10 +233,11 @@ the same library that the Python runtime is using. Parse and compile the Python source code in *str*, returning the resulting code object. The start symbol is given by *start*; this can be used to constrain the - code which can be compiled and should be one of the :ref:`available start symbols `. - The filename specified by *filename* is used to construct the code object - and may appear in tracebacks or :exc:`SyntaxError` exception messages. - This returns ``NULL`` if the code cannot be parsed or compiled. + code which can be compiled and should be :ref:`available start symbols + `. The filename specified by + *filename* is used to construct the code object and may appear in tracebacks or + :exc:`SyntaxError` exception messages. This returns ``NULL`` if the code + cannot be parsed or compiled. The integer *optimize* specifies the optimization level of the compiler; a value of ``-1`` selects the optimization level of the interpreter as given by From 50f3fefbf112707206436948ab6ed75711600347 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Sat, 8 Nov 2025 16:53:26 -0500 Subject: [PATCH 3/5] Add versionadded note. --- Doc/c-api/veryhigh.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/Doc/c-api/veryhigh.rst b/Doc/c-api/veryhigh.rst index 6e62291349b552..d5bf27688df1e3 100644 --- a/Doc/c-api/veryhigh.rst +++ b/Doc/c-api/veryhigh.rst @@ -387,3 +387,4 @@ Available start symbols .. seealso:: :py:class:`ast.FunctionType` + .. versionadded:: 3.8 From fba4e429856d70d951e357970185484cf180a516 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Sun, 9 Nov 2025 11:07:14 -0500 Subject: [PATCH 4/5] Change wording to include PEP 484. --- Doc/c-api/veryhigh.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/veryhigh.rst b/Doc/c-api/veryhigh.rst index d5bf27688df1e3..9aa390c9574275 100644 --- a/Doc/c-api/veryhigh.rst +++ b/Doc/c-api/veryhigh.rst @@ -379,12 +379,13 @@ Available start symbols .. index:: single: Py_CompileString (C function) The start symbol from the Python grammar for a function type; for use with - :c:func:`Py_CompileString`. This is used for parsing function ``# type:`` - comments. + :c:func:`Py_CompileString`. This is used to parse "signature type comments" + from :pep:`484`. This requires the :c:macro:`PyCF_ONLY_AST` flag to be set. .. seealso:: :py:class:`ast.FunctionType` + :pep:`484` .. versionadded:: 3.8 From cc34603d4b8f5afdd0a4c286efb564004e914c46 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Sun, 9 Nov 2025 11:15:44 -0500 Subject: [PATCH 5/5] Fix small typo. --- Doc/c-api/veryhigh.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/veryhigh.rst b/Doc/c-api/veryhigh.rst index 9aa390c9574275..916c616dfee589 100644 --- a/Doc/c-api/veryhigh.rst +++ b/Doc/c-api/veryhigh.rst @@ -385,7 +385,7 @@ Available start symbols This requires the :c:macro:`PyCF_ONLY_AST` flag to be set. .. seealso:: - :py:class:`ast.FunctionType` - :pep:`484` + * :py:class:`ast.FunctionType` + * :pep:`484` .. versionadded:: 3.8