Skip to content

Commit dc10264

Browse files
miss-islingtonFidget-Spinnerencukou
authored
bpo-40939: Remove documentation for PyParser_* & add porting notes (GH-26855) (GH-26898)
I tried to be relatively thorough and give lots of links. One reason is that this wasn't deprecated very long; also it seems people running into this tend to not be familiar with similar APIs. (cherry picked from commit 29987f7) Co-authored-by: Ken Jin <[email protected]> Co-authored-by: Petr Viktorin <[email protected]>
1 parent f4b31cd commit dc10264

File tree

5 files changed

+41
-98
lines changed

5 files changed

+41
-98
lines changed

Doc/c-api/veryhigh.rst

-36
Original file line numberDiff line numberDiff line change
@@ -185,42 +185,6 @@ the same library that the Python runtime is using.
185185
:c:func:`PyMem_RawRealloc`, instead of being allocated by
186186
:c:func:`PyMem_Malloc` or :c:func:`PyMem_Realloc`.
187187
188-
189-
.. c:function:: struct _node* PyParser_SimpleParseString(const char *str, int start)
190-
191-
This is a simplified interface to
192-
:c:func:`PyParser_SimpleParseStringFlagsFilename` below, leaving *filename* set
193-
to ``NULL`` and *flags* set to ``0``.
194-
195-
196-
.. c:function:: struct _node* PyParser_SimpleParseStringFlags( const char *str, int start, int flags)
197-
198-
This is a simplified interface to
199-
:c:func:`PyParser_SimpleParseStringFlagsFilename` below, leaving *filename* set
200-
to ``NULL``.
201-
202-
203-
.. c:function:: struct _node* PyParser_SimpleParseStringFlagsFilename( const char *str, const char *filename, int start, int flags)
204-
205-
Parse Python source code from *str* using the start token *start* according to
206-
the *flags* argument. The result can be used to create a code object which can
207-
be evaluated efficiently. This is useful if a code fragment must be evaluated
208-
many times. *filename* is decoded from the :term:`filesystem encoding and
209-
error handler`.
210-
211-
212-
.. c:function:: struct _node* PyParser_SimpleParseFile(FILE *fp, const char *filename, int start)
213-
214-
This is a simplified interface to :c:func:`PyParser_SimpleParseFileFlags` below,
215-
leaving *flags* set to ``0``.
216-
217-
218-
.. c:function:: struct _node* PyParser_SimpleParseFileFlags(FILE *fp, const char *filename, int start, int flags)
219-
220-
Similar to :c:func:`PyParser_SimpleParseStringFlagsFilename`, but the Python
221-
source code is read from *fp* instead of an in-memory string.
222-
223-
224188
.. c:function:: PyObject* PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals)
225189
226190
This is a simplified interface to :c:func:`PyRun_StringFlags` below, leaving

Doc/data/refcounts.dat

-26
Original file line numberDiff line numberDiff line change
@@ -1791,32 +1791,6 @@ PyObject_TypeCheck:int:::
17911791
PyObject_TypeCheck:PyObject*:o:0:
17921792
PyObject_TypeCheck:PyTypeObject*:type:0:
17931793

1794-
PyParser_SimpleParseFile:struct _node*:::
1795-
PyParser_SimpleParseFile:FILE*:fp::
1796-
PyParser_SimpleParseFile:const char*:filename::
1797-
PyParser_SimpleParseFile:int:start::
1798-
1799-
PyParser_SimpleParseFileFlags:struct _node*:::
1800-
PyParser_SimpleParseFileFlags:FILE*:fp::
1801-
PyParser_SimpleParseFileFlags:const char*:filename::
1802-
PyParser_SimpleParseFileFlags:int:start::
1803-
PyParser_SimpleParseFileFlags:int:flags::
1804-
1805-
PyParser_SimpleParseString:struct _node*:::
1806-
PyParser_SimpleParseString:const char*:str::
1807-
PyParser_SimpleParseString:int:start::
1808-
1809-
PyParser_SimpleParseStringFlags:struct _node*:::
1810-
PyParser_SimpleParseStringFlags:const char*:str::
1811-
PyParser_SimpleParseStringFlags:int:start::
1812-
PyParser_SimpleParseStringFlags:int:flags::
1813-
1814-
PyParser_SimpleParseStringFlagsFilename:struct _node*:::
1815-
PyParser_SimpleParseStringFlagsFilename:const char*:str::
1816-
PyParser_SimpleParseStringFlagsFilename:const char*:filename::
1817-
PyParser_SimpleParseStringFlagsFilename:int:start::
1818-
PyParser_SimpleParseStringFlagsFilename:int:flags::
1819-
18201794
PyRun_AnyFile:int:::
18211795
PyRun_AnyFile:FILE*:fp::
18221796
PyRun_AnyFile:const char*:filename::

Doc/faq/extending.rst

+2-33
Original file line numberDiff line numberDiff line change
@@ -275,39 +275,8 @@ for more hints.
275275

276276
However sometimes you have to run the embedded Python interpreter in the same
277277
thread as your rest application and you can't allow the
278-
:c:func:`PyRun_InteractiveLoop` to stop while waiting for user input. The one
279-
solution then is to call :c:func:`PyParser_ParseString` and test for ``e.error``
280-
equal to ``E_EOF``, which means the input is incomplete. Here's a sample code
281-
fragment, untested, inspired by code from Alex Farber::
282-
283-
#define PY_SSIZE_T_CLEAN
284-
#include <Python.h>
285-
#include <node.h>
286-
#include <errcode.h>
287-
#include <grammar.h>
288-
#include <parsetok.h>
289-
#include <compile.h>
290-
291-
int testcomplete(char *code)
292-
/* code should end in \n */
293-
/* return -1 for error, 0 for incomplete, 1 for complete */
294-
{
295-
node *n;
296-
perrdetail e;
297-
298-
n = PyParser_ParseString(code, &_PyParser_Grammar,
299-
Py_file_input, &e);
300-
if (n == NULL) {
301-
if (e.error == E_EOF)
302-
return 0;
303-
return -1;
304-
}
305-
306-
PyNode_Free(n);
307-
return 1;
308-
}
309-
310-
Another solution is trying to compile the received string with
278+
:c:func:`PyRun_InteractiveLoop` to stop while waiting for user input.
279+
A solution is trying to compile the received string with
311280
:c:func:`Py_CompileString`. If it compiles without errors, try to execute the
312281
returned code object by calling :c:func:`PyEval_EvalCode`. Otherwise save the
313282
input for later. If the compilation fails, find out if it's an error or just

Doc/whatsnew/3.10.rst

+38-3
Original file line numberDiff line numberDiff line change
@@ -1696,9 +1696,9 @@ Removed
16961696
that were only being used by the old parser, including ``node.h``, ``parser.h``,
16971697
``graminit.h`` and ``grammar.h``.
16981698
1699-
* Removed the Public C API functions :c:func:`PyParser_SimpleParseStringFlags`,
1700-
:c:func:`PyParser_SimpleParseStringFlagsFilename`,
1701-
:c:func:`PyParser_SimpleParseFileFlags` and :c:func:`PyNode_Compile`
1699+
* Removed the Public C API functions ``PyParser_SimpleParseStringFlags``,
1700+
``PyParser_SimpleParseStringFlagsFilename``,
1701+
``PyParser_SimpleParseFileFlags`` and ``PyNode_Compile``
17021702
that were deprecated in 3.9 due to the switch to the new PEG parser.
17031703
17041704
* Removed the ``formatter`` module, which was deprecated in Python 3.4.
@@ -1812,6 +1812,41 @@ Changes in the Python API
18121812
also inherits the current builtins.
18131813
(Contributed by Victor Stinner in :issue:`42990`.)
18141814
1815+
Changes in the C API
1816+
--------------------
1817+
1818+
* The C API functions ``PyParser_SimpleParseStringFlags``,
1819+
``PyParser_SimpleParseStringFlagsFilename``,
1820+
``PyParser_SimpleParseFileFlags``, ``PyNode_Compile`` and the type
1821+
used by these functions, ``struct _node``, were removed due to the switch
1822+
to the new PEG parser.
1823+
1824+
Source should be now be compiled directly to a code object using, for
1825+
example, :c:func:`Py_CompileString`. The resulting code object can then be
1826+
evaluated using, for example, :c:func:`PyEval_EvalCode`.
1827+
1828+
Specifically:
1829+
1830+
* A call to ``PyParser_SimpleParseStringFlags`` followed by
1831+
``PyNode_Compile`` can be replaced by calling :c:func:`Py_CompileString`.
1832+
1833+
* There is no direct replacement for ``PyParser_SimpleParseFileFlags``.
1834+
To compile code from a ``FILE *`` argument, you will need to read
1835+
the file in C and pass the resulting buffer to :c:func:`Py_CompileString`.
1836+
1837+
* To compile a file given a ``char *`` filename, explicitly open the file, read
1838+
it and compile the result. One way to do this is using the :py:mod:`io`
1839+
module with :c:func:`PyImport_ImportModule`, :c:func:`PyObject_CallMethod`,
1840+
:c:func:`PyBytes_AsString` and :c:func:`Py_CompileString`,
1841+
as sketched below. (Declarations and error handling are omitted.) ::
1842+
1843+
io_module = Import_ImportModule("io");
1844+
fileobject = PyObject_CallMethod(io_module, "open", "ss", filename, "rb");
1845+
source_bytes_object = PyObject_CallMethod(fileobject, "read", "");
1846+
result = PyObject_CallMethod(fileobject, "close", "");
1847+
source_buf = PyBytes_AsString(source_bytes_object);
1848+
code = Py_CompileString(source_buf, filename, Py_file_input);
1849+
18151850
CPython bytecode changes
18161851
========================
18171852
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Removed documentation for the removed ``PyParser_*`` C API.

0 commit comments

Comments
 (0)