homepage

Functions added to a limited API after 3.2 should be available only when Py_LIMITED_API is not defined or is set to corresponding hexadecimal Python version (e.g. 0x03050000).
Proposed patch makes following names available only for corresponding versions of a limited API.
Removed declaration: PyErr_SetExcWithArgsKwargs().
Excluded from stable ABI: _PyBytes_DecodeEscape(), PyInit_imp().
3.3: Py_hexdigits, PyImport_ExecCodeModuleObject(), PyImport_AddModuleObject(), PyImport_ImportFrozenModuleObject(), PyMemoryView_FromMemory(), PyModule_NewObject(), PyModule_GetNameObject(), PyObject_GenericSetDict(), PyErr_GetExcInfo(), PyErr_SetExcInfo(), PyErr_SetImportError(), PyParser_SimpleParseStringFlagsFilename(), PyThread_GetInfo(), PyUnicode_Substring(), PyUnicode_AsUCS4(), PyUnicode_AsUCS4Copy(), PyUnicode_GetLength(), PyUnicode_ReadChar(), PyUnicode_WriteChar(), PyUnicode_DecodeCodePageStateful(), PyUnicode_EncodeCodePage(), PyUnicode_DecodeLocaleAndSize(), PyUnicode_DecodeLocale(), PyUnicode_EncodeLocale(), PyUnicode_FindChar(), and a number of OSError subclasses.
3.4: PyErr_SetFromErrnoWithFilenameObjects(), PyErr_SetExcFromWindowsErrWithFilenameObjects().
3.5: PyNumber_MatrixMultiply(), PyNumber_InPlaceMatrixMultiply(), PyCodec_NameReplaceErrors(), Py_DecodeLocale(), Py_EncodeLocale(), PyImport_ImportModuleLevelObject(), PyObject_Calloc(), PyExc_StopAsyncIteration, PyExc_RecursionError, PyMem_Calloc(), 
a number of PyODict_* macros.
3.6: Py_FileSystemDefaultEncodeErrors, PyOS_FSPath(), PyExc_ModuleNotFoundError, PyErr_SetImportErrorSubclass(), PyErr_ResourceWarning().
However it may be better that some was added to stable ABI by mistake. Py_hexdigits looks as a stuff for internal use, PyThread_GetInfo() and PyODict_* macros are not documented.

Those changes all look good to me, though it's a shame we can't leave some of those functions out altogether.

Actually PyODict_Check, PyODict_CheckExact, and PyODict_SIZE should be excluded from limited API. These macros are expanded to the code that don't work with limited API (needed PyODict_Type and PyDictObject). PyODict_HasKey is expanded to syntactically invalid code.

Updated patch removes PyODict_HasKey() at all, removes PyODict_Check(), PyODict_CheckExact(), PyODict_SIZE() and Py_hexdigits from stable API.

New changeset f26c16aba11e by Serhiy Storchaka in branch '3.6':
Issue #29058: All stable API extensions added after Python 3.2 are now
https://hg.python.org/cpython/rev/f26c16aba11e
New changeset 77f5f31bf699 by Serhiy Storchaka in branch 'default':
Issue #29058: All stable API extensions added after Python 3.2 are now
https://hg.python.org/cpython/rev/77f5f31bf699 

Changes are not applied to 3.5. It is harder to do since many private functions in 3.5 are still available in limited API. And there is a risk to break third-party code that defines Py_LIMITED_API, but uses API with higher version than required.

Can we add a #warn to the headers then? So people know that just defining Py_LIMITED_API actually implies =0x03050000 (or whatever value is appropriate)?

Just defining Py_LIMITED_API actually implies =0x03020000.
I have no idea where a #warn can be added.

> Just defining Py_LIMITED_API actually implies =0x03020000.
That's the intent, but if it were actually the case then this issue wouldn't exist :)
On 3.5.3, building with Py_LIMITED_API=1 will include APIs that should only be included when Py_LIMITED_API=0x03050000. You considered fixing that too likely to break existing users (and I agree), but that doesn't mean we shouldn't make it clear that it's not doing exactly the right thing.
> I have no idea where a #warn can be added.
pyport.h or pymacro.h are probably the best places. If you null-merge into 3.6 then we shouldn't have to worry about the warning showing up in later versions.

Sorry, but perhaps I don't fully understand you.
It is legitimately to just define Py_LIMITED_API without requiring specific version:
 #define Py_LIMITED_API
In that case you can use the stable API of the version 3.2, but can't use PyType_FromSpecWithBases() and PyModule_AddFunctions(), because they are correctly attributed as API of versions 3.3 and 3.5. You can also mistakenly use PyImport_ImportModuleLevelObject() added in 3.5, this is a matter of this issue. But you shouldn't.
The problem is that the warning should be emitted only for users that use incorrect API. But it shouldn't be emitted for users that use just 3.2 API (perhaps the code was written at the time of 3.2 and was not changed since).

You've described it correctly.
> The problem is that the warning should be emitted only for users that use incorrect API. But it shouldn't be emitted for users that use just 3.2 API
This is why I suggested #warn and not #error. It's okay to ignore warnings if you know what you're doing, but if there's no warning then people who don't know what they're doing will get it wrong. We know that some people are subtly broken here, and ought to tell them.
Further, if we make the warning only appear for "defined(Py_LIMITED_API) && Py_LIMITED_API+0<0x03000000" then the warning can be suppressed by setting the exact version you intend to use (even though this doesn't prevent you from using the incorrect functions).

Do you suggest to emit a warning when the user just defines Py_LIMITED_API without specifying concrete version?
 #define Py_LIMITED_API
I think this would break too much code. And contradicts to the documentation.
If you mean something different, could you provide a patch?

I don't care enough to argue about it with you. Let's just fix the API as soon as we can and apologize to people who hit inconsistencies in earlier versions.