[C API] Deprecate legacy API for configure Python initialization

[vstinner]

BPO	44113
Nosy	@vstinner, @corona10, @joukewitteveen
PRs	bpo-44113: Deprecate old functions to config Python init #26060 bpo-43956: Doc/c-api: Fix default program name #24876 bpo-44113: Update __xxtestfuzz not to use Py_SetProgramName #26083 bpo-44113: Fix compiler warning in PySys_AddWarnOption() #26084 bpo-44113: Update fromzenmain not to use Py_SetProgramName #26085 bpo-44113: Move the What's New entry to Deprecate section #28974

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2021-05-14.12:21:54.201>
created_at = <Date 2021-05-12.10:20:54.214>
labels = ['expert-C-API', '3.11', 'docs']
title = '[C API] Deprecate legacy API for configure Python initialization'
updated_at = <Date 2021-10-15.11:43:51.791>
user = 'https://github.com/vstinner'

bugs.python.org fields:

activity = <Date 2021-10-15.11:43:51.791>
actor = 'vstinner'
assignee = 'docs@python'
closed = True
closed_date = <Date 2021-05-14.12:21:54.201>
closer = 'vstinner'
components = ['Documentation', 'C API']
creation = <Date 2021-05-12.10:20:54.214>
creator = 'vstinner'
dependencies = []
files = []
hgrepos = []
issue_num = 44113
keywords = ['patch']
message_count = 8.0
messages = ['393499', '393550', '393551', '393553', '393641', '393647', '393648', '404005']
nosy_count = 4.0
nosy_names = ['vstinner', 'docs@python', 'corona10', 'joukewitteveen']
pr_nums = ['26060', '24876', '26083', '26084', '26085', '28974']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue44113'
versions = ['Python 3.11']

[vstinner]

The https://docs.python.org/dev/c-api/init.html documentation lists many functions which is the legacy way to configure the Python initialization. These functions are kept for backward compatibility but have flaws and are less reliable than the new PyConfig API (PEP-587) documented at https://docs.python.org/dev/c-api/init_config.html

I propose to deprecate the legacy functions to configure the Python initialization. Examples:

• Py_SetPath()
• Py_SetProgramName()
• Py_SetPythonHome()
• Py_SetStandardStreamEncoding()
• PySys_AddWarnOption()
• PySys_AddWarnOptionUnicode()
• PySys_AddXOption()

I don't propose to schedule the removal of these functions, only mark them as deprecated in the *documentation*.

Related issue: bpo-43956 "C-API: Incorrect default value for Py_SetProgramName" and PR 24876.

[vstinner]

PyConfig API was added to Python 3.8, so it's now widely available. Python 3.8 always switched to security fixes only phase. So IMO it's ok to deprecate the old API now.

[vstinner]

"""
Check warning on line 82 in Python/frozenmain.c
GitHub Actions / Ubuntu
‘Py_SetProgramName’ is deprecated [-Wdeprecated-declarations]
"""

Well, Py_FrozenMain() should be rewritten with PyConfig, I want to do that for a long time, but I don't know how to test it. It would be nice to have a very basic test for Py_FrozenMain().

See also:
https://mail.python.org/archives/list/capi-sig@python.org/thread/5QLI3NUP3OSGLCCIBAQOTX4GEJQBWJ6F/

[vstinner]

commit 6cd0446
Author: Victor Stinner <vstinner@python.org>
Date: Wed May 12 23:59:25 2021 +0200

bpo-44113: Deprecate old functions to config Python init (GH-26060)

Deprecate the following functions to configure the Python
initialization:

* PySys_AddWarnOption()
* PySys_AddWarnOptionUnicode()
* PySys_AddXOption()
* PySys_HasWarnOptions()
* Py_SetPath()
* Py_SetProgramName()
* Py_SetPythonHome()
* Py_SetStandardStreamEncoding()
* _Py_SetProgramFullPath()

Use the new PyConfig API of the Python Initialization Configuration
instead (PEP-587).

commit a0ccc40
Author: Dong-hee Na <donghee.na@python.org>
Date: Thu May 13 08:22:18 2021 +0900

bpo-44113: Update __xxtestfuzz not to use Py_SetProgramName (GH-26083)

commit ec7c09b
Author: Victor Stinner <vstinner@python.org>
Date: Thu May 13 02:27:56 2021 +0200

bpo-44113: Fix compiler warning in PySys_AddWarnOption() (GH-26084)

Ignore Py_DEPRECATED() warning on purpose.

[vstinner]

commit 7565586
Author: Dong-hee Na <donghee.na@python.org>
Date: Thu May 13 10:19:46 2021 +0900

bpo-44113: Update fromzenmain not to use Py_SetProgramName (GH-26085)

[vstinner]

Well, Py_FrozenMain() should be rewritten with PyConfig, I want to do that for a long time, but I don't know how to test it. It would be nice to have a very basic test for Py_FrozenMain().

I created bpo-44131: [C API] Add tests on Py_FrozenMain().

[vstinner]

Thanks for the help Dong-hee ;-) I close the issue, functions are now deprecated.