Naming

[encukou]

Most of this is already in PEP-7. IMO we should move guidelines with user-visible effects out of the style guide.

For new API, all public names must be prefixed with Py.
Names that users should not use directly, but should be visible to the compiler/linker, should be prefixed with _Py.
This applies to all names in a global namespace: functions, macros, variables, typedefs, structs, enums, etc.; not to parameters or struct fields.

(XXX: In C, “all identifiers that begin [...] with an underscore (_) followed by an uppercase letter are reserved for any use”. Using the _Py prefix has undefined behavior.)

The Py_ prefix is reserved for global service routines like Py_FatalError; specific groups of APIs use a longer prefix, e.g. PyString_ for string functions.

The prefix is in mixed case, even in macro names (e.g. PyString_AS_STRING).

Unstable API is prefixed with PyUnstable_ instead of Py, e.g. PyUnstable_Long_IsCompact or *PyUnstable_String_GET_SIZE.

[encukou]

I'd also say:

After API is removed, the name should not be reused.

Old docs live forever 📚

[encukou]

To be clear: I think this should include configure macros like SIZEOF_UINTPTR_T or HAVE_FORK. If we add any new ones, they should be Py_SIZEOF_* or Py_HAVE_*.
(And we should eventually replace the old ones, in a non-breaking way -- preferably by C89 sizeof & C11 _Alignof.)

[serhiy-storchaka]

Currently there are 77 names with the PY_ prefix (was 46 in 3.12, but 30 new names were added in 3.12).

I think that the PY_ prefix is more suitable for macros supposed to be used in the preprocessor directives like PY_VERSION_HEX, PY_SSIZE_T_MAX, PY_HAVE_THREAD_NATIVE_ID. Not all compile-time constants can be used in the preprocessor directives (for example expressions involving sizeof can not), so the PY_ prefix could be an indication that the name can be used in the preprocessor directives.

[encukou]

Using Py_ rather than PY_ is explicitly mentioned in PEP 7. Are you suggesting to change the PEP?

[serhiy-storchaka]

PY_ is not mentioned in PEP 7. I think this is an omission.

I propose to legalize the use of PY_ in macro names whose main purpose is to be used in the preprocessor #if directives. Either as the defined() argument or as the part of the expression. This should include PY_HAVE_<feature>, PY_<headername>_H, PY_<type>_MAX, PY_SIZEOF_<type>.

Unfortunately, there is a number of Py_ names used for such purpose: from Py_DEBUG and Py_LIMITED_API to Py_STATS and Py_BUILD_CORE. So this rule cannot be made universal.

[encukou]

PY_ is not mentioned in PEP 7. I think this is an omission.

The Naming conventions section of PEP 7 says Macros should have a MixedCase prefix, right after defining what “prefix” is. IMO, it's very clear that you should use Py rather than PY.

It's of course possible to break that rule to be consistent with surrounding code that also breaks it, and we can of course change existing guidelines.

Not all compile-time constants can be used in the preprocessor directives (for example expressions involving sizeof can not), so the PY_ prefix could be an indication that the name can be used in the preprocessor directives.

Oh, we'd promise that the macro can be used in #if, even in future Python versions? I like that!

Unfortunately, we have some PY_ macros that don't follow this rule, so we can't make that promise unconditionally today. But, theren't are too many exceptions.
As for Py_DEBUG and such, introducing the PY_ version and soft-deprecating the old one would be very cheap to do.

[encukou]

I opened a wider discussion: https://discuss.python.org/t/py-prefix-for-if-friendly-macros/60825