gh-129342: Explain how to replace Py_GetProgramName() in C

[vstinner]

• Issue: docs of deprecated C function should propose replacement in C, not in Python #129342

---

📚 Documentation preview 📚: https://cpython-previews--129361.org.readthedocs.build/

[serhiy-storchaka]

I think that PyConfig_Get("executable") is more preferable in a new code, isn't it?

PySys_GetObject() will be deprecated in future (it returns a borrowed reference and silences errors).

[vstinner]

PySys_GetObject() works on all Python versions, whereas PyConfig_Get() is new in Python 3.14. The note can be updated once PySys_GetObject() will be deprecated.

[serhiy-storchaka]

We should suggest first what will work in future versions. We do not want users to rewrite the same code twice (and curse us twice).

[erlend-aasland]

PySys_GetObject() works on all Python versions, whereas PyConfig_Get() is new in Python 3.14.

I don't understand; this PR is for the 3.14 docs, so it should be ok to mention new-in-3.14 APIs here, no?

[vstinner]

If possible, I would prefer to provide a replacement working on old Python versions as well.

[vstinner]

I updated the PR to use only PyConfig_Get().

[serhiy-storchaka]

I think that we should postpone hard deprecation until there is a non-deprecated replacement that works in all maintained Python versions.

[vstinner]

PySys_GetObject() works on all Python versions, it's not deprecated: https://docs.python.org/dev/c-api/sys.html#c.PySys_GetObject

[vstinner]

You can use pythoncapi-compat to get PyConfig_Get() on Python 3.13 and older.

[vstinner]

@serhiy-storchaka: I think that we already had this discusssion about PySys_GetObject() which returns a borrowed reference. So I created #129367 to propose adding PySys_GetAttr() function which returns a strong reference and doesn't ignore errors :-)

[jwuttke]

Much better than status quo, but in my opinion not sufficient to resolve #129342.

Imagine the worst-case scenario, which is exactly what happened to me: Somebody has to maintain a huge amount of C code, with lots of dependencies, and without being an expert for each library dependency. Such a user, after hitting a deprecation warning, needs complete, self-contained instructions how to replace the deprecated code.

The current MR won't do, because the functions proposed for replacement return a different data type than the deprecated functions.

Therefore, in addition to the changes proposed here, we need a link to a separate page that explains how to replace a function that returned a const wchar_t* by a function that returns a PyObject*.

[vstinner]

Therefore, in addition to the changes proposed here, we need a link to a separate page that explains how to replace a function that returned a const wchar_t* by a function that returns a PyObject*.

If you have a Python str object, wstr = PyUnicode_AsWideCharString(str, NULL) can be used to get a wchar_t* string. It requires calling PyMem_Free(wstr) once done with the wide string.

[jwuttke]

If you have a Python str object, wstr = PyUnicode_AsWideCharString(str, NULL) can be used to get a wchar_t* string. It requires calling PyMem_Free(wstr) once done with the wide string.

Excellent. Just two sentences to be added to each deprecation note.

[StanFromIreland]

Everything looks good to me.

[vstinner]

@serhiy-storchaka @erlend-aasland: Please review the updated PR.

Are you ok with PyConfig_Get() or do you prefer to have a PySys function, so wait for capi-workgroup/decisions#54?

[erlend-aasland]

Are you ok with PyConfig_Get() or do you prefer to have a PySys function, so wait for capi-workgroup/decisions#54?

I'm fine with PyConfig_Get. We can amend the docs later if we add a new API.

[vstinner]

Merged, thanks for reviews.