gh-141004: Document soft-deprecated symbols

[ZeroIntensity]

These are all APIs that expose implementation details. Instead of truly documenting them and what they do, this PR just adds a note saying "don't use this" with no additional information. This is a good compromise for us; if someone saw these in their IDE, Python will still provide some form of documentation for them, but they won't lead to any additional maintenance burden.

cc @vstinner @encukou -- I suspect both of you will have some strong opinions here.

• Issue: Document the entire C API #141004

---

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

[encukou]

I suspect […] you will have some strong opinions here.

Yes. My opinion is that documentation for deprecated API should tell you what to do if you find it in some dusty legacy codebase.
Here that would involve PyLong_GetNativeLayout for the PyLong details; open() for stdprinter, etc.

[ZeroIntensity]

Here that would involve PyLong_GetNativeLayout for the PyLong details; open() for stdprinter, etc.

Ok, I can do that.

I have a few ideas on how we could format this -- which do you prefer?

1. Keep all the symbols here, just with additional documentation pointing to the alternative.
2. The same as above, but on a dedicated page.
3. Move them next to the rest of their friends (e.g. other PyLong* functions), but contain the soft-deprecation note and the alternative.
4. The same as above, but a dedicated "Soft-deprecated symbols" section for every page.

[vstinner]

I'm not sure that a "Soft-deprecated" section is needed.

Move them next to the rest of their friends (e.g. other PyLong* functions), but contain the soft-deprecation note and the alternative.

That sounds like a reasonable approach.

[encukou]

The same as above, but a dedicated "Soft-deprecated symbols" section for every page.

I'd prefer “Deprecated API” sections at the end of pages. Alas, that might not be a popular preference :(
If you're not reading top-to-bottom, the order doesn't matter that much. If you are, you can skip the section.

Move them next to the rest of their friends (e.g. other PyLong* functions), but contain the soft-deprecation note and the alternative.

That makes sense for “close friends” -- e.g. if the porting instructions tell you to use a specific other function instead.

[vstinner]

I'd prefer “Deprecated API” sections at the end of pages. Alas, that might not be a popular preference :(

If others are fine with a Deprecated API section, I would also be fine with it.

[encukou]

See https://docs.python.org/3/c-api/unicode.html#deprecated-api for an example. I think it's working pretty well.

[vstinner]

See https://docs.python.org/3/c-api/unicode.html#deprecated-api for an example. I think it's working pretty well.

It looks nice.

[ZeroIntensity]

Updated, let me know what you think.

My opinion is that documentation for deprecated API should tell you what to do if you find it in some dusty legacy codebase.

In practice, we don't have great replacements for all of these, so I just documented some of them as "do not use". For example, what is a user supposed to do if they find PySet_MINSIZE somewhere?

[encukou]

Looks good! Hopefully the WG vote will be just a formality.