Issue 29058: Mark new limited C API (original) (raw)
Created on 2016-12-24 00:11 by serhiy.storchaka, last changed 2022-04-11 14:58 by admin. This issue is now closed.
Messages (13)
Author: Serhiy Storchaka (serhiy.storchaka) * 
Date: 2016-12-24 00:11
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.
Author: Steve Dower (steve.dower) *
Date: 2016-12-25 21:00
Those changes all look good to me, though it's a shame we can't leave some of those functions out altogether.
Author: Serhiy Storchaka (serhiy.storchaka) *
Date: 2016-12-25 23:09
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.
Author: Serhiy Storchaka (serhiy.storchaka) *
Date: 2016-12-26 18:59
Updated patch removes PyODict_HasKey() at all, removes PyODict_Check(), PyODict_CheckExact(), PyODict_SIZE() and Py_hexdigits from stable API.
Author: Roundup Robot (python-dev) 
Date: 2016-12-27 13:05
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
Author: Serhiy Storchaka (serhiy.storchaka) *
Date: 2016-12-27 13:21
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.
Author: Steve Dower (steve.dower) *
Date: 2016-12-27 14:44
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)?
Author: Serhiy Storchaka (serhiy.storchaka) *
Date: 2016-12-27 16:34
Just defining Py_LIMITED_API actually implies =0x03020000.
I have no idea where a #warn can be added.
Author: Steve Dower (steve.dower) *
Date: 2016-12-27 19:32
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.
Author: Serhiy Storchaka (serhiy.storchaka) *
Date: 2016-12-27 19:59
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_APIIn 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).
Author: Steve Dower (steve.dower) *
Date: 2016-12-27 20:13
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).
Author: Serhiy Storchaka (serhiy.storchaka) *
Date: 2017-01-22 16:13
Do you suggest to emit a warning when the user just defines Py_LIMITED_API without specifying concrete version?
#define Py_LIMITED_APII think this would break too much code. And contradicts to the documentation.
If you mean something different, could you provide a patch?
Author: Steve Dower (steve.dower) *
Date: 2017-01-22 18:41
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.
History
Date
User
Action
Args
2022-04-11 14:58:41
admin
set
github: 73244
2017-03-31 16:36:37
dstufft
set
pull_requests: + <pull%5Frequest1090>
2017-01-22 19:16:06
serhiy.storchaka
set
status: open -> closed
2017-01-22 18:41:24
steve.dower
set
messages: +
2017-01-22 16:13:51
serhiy.storchaka
set
messages: +
2016-12-27 20:13:43
steve.dower
set
messages: +
2016-12-27 19:59:32
serhiy.storchaka
set
status: closed -> open
messages: +
2016-12-27 19:32:07
steve.dower
set
messages: +
2016-12-27 16:34:47
serhiy.storchaka
set
messages: +
2016-12-27 14:44:37
steve.dower
set
messages: +
2016-12-27 13:21:17
serhiy.storchaka
set
status: open -> closed
versions: - Python 3.5
messages: +
assignee: serhiy.storchaka
resolution: fixed
stage: patch review -> resolved
2016-12-27 13:05:21
python-dev
set
nosy: + python-dev
messages: +
2016-12-26 18:59:34
serhiy.storchaka
set
files: + limited-api-2.patch
messages: +
2016-12-25 23:09:18
serhiy.storchaka
set
nosy: + eric.snow
messages: +
2016-12-25 21:00:39
steve.dower
set
nosy: + steve.dower
messages: +
2016-12-24 20:49:59
serhiy.storchaka
link
2016-12-24 00:11:50
serhiy.storchaka
create