This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Mark new limited C API
Type: Stage: resolved
Components: Interpreter Core Versions: Python 3.7, Python 3.6
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: serhiy.storchaka Nosy List: eric.snow, python-dev, serhiy.storchaka, steve.dower, vstinner
Priority: normal Keywords: patch

Created on 2016-12-24 00:11 by serhiy.storchaka, last changed 2022-04-11 14:58 by admin. This issue is now closed.

Files
File name Uploaded Description Edit
limited-api.patch serhiy.storchaka, 2016-12-24 00:11 review
limited-api-2.patch serhiy.storchaka, 2016-12-26 18:59 review
Pull Requests
URL Status Linked Edit
PR 552 closed dstufft, 2017-03-31 16:36
Messages (13)
msg283910 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) 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.
msg284008 - (view) Author: Steve Dower (steve.dower) * (Python committer) 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.
msg284009 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) 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.
msg284037 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) 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.
msg284092 - (view) Author: Roundup Robot (python-dev) (Python triager) 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
msg284095 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) 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.
msg284103 - (view) Author: Steve Dower (steve.dower) * (Python committer) 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)?
msg284110 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2016-12-27 16:34
Just defining Py_LIMITED_API actually implies =0x03020000.

I have no idea where a #warn can be added.
msg284129 - (view) Author: Steve Dower (steve.dower) * (Python committer) 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.
msg284131 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) 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_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).
msg284132 - (view) Author: Steve Dower (steve.dower) * (Python committer) 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).
msg286013 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) 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_API

I think this would break too much code. And contradicts to the documentation.

If you mean something different, could you provide a patch?
msg286024 - (view) Author: Steve Dower (steve.dower) * (Python committer) 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:41adminsetgithub: 73244
2017-03-31 16:36:37dstufftsetpull_requests: + pull_request1090
2017-01-22 19:16:06serhiy.storchakasetstatus: open -> closed
2017-01-22 18:41:24steve.dowersetmessages: + msg286024
2017-01-22 16:13:51serhiy.storchakasetmessages: + msg286013
2016-12-27 20:13:43steve.dowersetmessages: + msg284132
2016-12-27 19:59:32serhiy.storchakasetstatus: closed -> open

messages: + msg284131
2016-12-27 19:32:07steve.dowersetmessages: + msg284129
2016-12-27 16:34:47serhiy.storchakasetmessages: + msg284110
2016-12-27 14:44:37steve.dowersetmessages: + msg284103
2016-12-27 13:21:17serhiy.storchakasetstatus: open -> closed
versions: - Python 3.5
messages: + msg284095

assignee: serhiy.storchaka
resolution: fixed
stage: patch review -> resolved
2016-12-27 13:05:21python-devsetnosy: + python-dev
messages: + msg284092
2016-12-26 18:59:34serhiy.storchakasetfiles: + limited-api-2.patch

messages: + msg284037
2016-12-25 23:09:18serhiy.storchakasetnosy: + eric.snow
messages: + msg284009
2016-12-25 21:00:39steve.dowersetnosy: + steve.dower
messages: + msg284008
2016-12-24 20:49:59serhiy.storchakalinkissue23903 dependencies
2016-12-24 00:11:50serhiy.storchakacreate