Formalize incomplete error exceptions to improve codeop module handling

[pablogsal]

Currently the way we detect incomplete errors in the codeop module is based on the exception text, which is suboptimal at least. To do this properly, add a new SyntaxError subclass called IncompleteInputError and use that in the codeop module to detect errors from the parser.

Linked PRs

• gh-113744: Add a new IncompleteInputError exception to improve incomplete input detection in the codeop module #113745

[encukou]

Since PyExc_IncompleteInputError was added to the stable API, it needs to be documented. Usually the C names for exceptions just link to the Python docs, so the Python docs are needed as well.

[encukou]

(If you want to delegate this to me, let me know. Currently I'd lean toward not including it in builtins and C-API.)

[pablogsal]

(If you want to delegate this to me, let me know. Currently I'd lean toward not including it in builtins and C-API.)

I think is fine to have it in builtins given that we have the other subclasses of SyntaxError, even if this is currently only used in codeop but if you feel strongly about this I am fine to have it removed.

I am fine removing it from the C-API 👍

WDYT?

[encukou]

Sounds good. It can always be added :)

[pablogsal]

@encukou can you refresh my memory on how can I make the API check not complain? Marking the exception as extern? Or there is a better way?

[pablogsal]

@encukou gentle ping

[encukou]

Sorry, I missed this notification.

Not sure which check you have in mind. If you have a PR where you just need to silence a check, could you send it?

I assume it's the Docs check? The exception either needs to be documented, or removed from limited API like this:

--- a/Include/pyerrors.h
+++ b/Include/pyerrors.h
@@ -108,7 +108,9 @@ PyAPI_DATA(PyObject *) PyExc_NotImplementedError;
 PyAPI_DATA(PyObject *) PyExc_SyntaxError;
 PyAPI_DATA(PyObject *) PyExc_IndentationError;
 PyAPI_DATA(PyObject *) PyExc_TabError;
+#if !defined(Py_LIMITED_API)
 PyAPI_DATA(PyObject *) PyExc_IncompleteInputError;
+#endif
 PyAPI_DATA(PyObject *) PyExc_ReferenceError;
 PyAPI_DATA(PyObject *) PyExc_SystemError;
 PyAPI_DATA(PyObject *) PyExc_SystemExit;
diff --git a/Misc/stable_abi.toml b/Misc/stable_abi.toml
index ca7cf029615..a7fb8e3c327 100644
--- a/Misc/stable_abi.toml
+++ b/Misc/stable_abi.toml
@@ -2485,8 +2485,6 @@
 [function._Py_SetRefcnt]
     added = '3.13'
     abi_only = true
-[data.PyExc_IncompleteInputError]
-    added = '3.13'
 [function.PyList_GetItemRef]
     added = '3.13'
 [typedef.PyCFunctionFast]
diff --git a/Include/pyerrors.h b/Include/pyerrors.h
index 68d7985dac8..9b7321e5ad5 100644

and run make regen-limited-abi, which will remove it from the Docs data (among other things).

Or to make it fully internal, move the declaration to internal/pycore_excetpions.h instead of using #if !defined(Py_LIMITED_API).

[pablogsal]

@encukou I am getting this:

Checked 110 modules (33 built-in, 76 shared, 0 n/a on macosx-14.3-arm64, 0 disabled, 1 missing, 0 failed on import)
./python.exe ./Tools/build/stable_abi.py --all ./Misc/stable_abi.toml
Some extra declarations were found in "Include/Python.h" with Py_LIMITED_API:
 - PyExc_IncompleteInputError
Traceback (most recent call last):
  File "/Users/pgalindo3/github/python/main/./Tools/build/stable_abi.py", line 758, in <module>
    main()
    ~~~~^^
  File "/Users/pgalindo3/github/python/main/./Tools/build/stable_abi.py", line 734, in main
    raise Exception(f"""
    ...<19 lines>...
    """)
Exception:
        These checks related to the stable ABI did not succeed:
            unixy_check

        If you see diffs in the output, files derived from the stable
        ABI manifest the were not regenerated.
        Run `make regen-limited-abi` to fix this.

        Otherwise, see the error(s) above.

        The stable ABI manifest is at: Misc/stable_abi.toml
        Note that there is a process to follow when modifying it.

        You can read more about the limited API and its contracts at:

        https://docs.python.org/3/c-api/stable.html

        And in PEP 384:

        https://peps.python.org/pep-0384/

make: *** [check-limited-abi] Error 1

and this doesn't go away when running make regen-limited-abi. This is after removing the exception from Misc/stable_abi.toml

[encukou]

Use the #if !defined(Py_LIMITED_API) guard from the comment above -- the first part of the diff.

[JacobCoffee]

Hi @pablogsal, is this good to close since #113745 is merged?