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]

what is a user supposed to do if they find PySet_MINSIZE somewhere?

This is indeed not obvious. All the more reason for the docs to mention it, if we want to add docs.

What about something like:

Suggested change

	This is a :term:`soft deprecated` constant representing the size of a
	preallocated table inside :c:type:`PySetObject` instances.
	This is documented solely for completeness and not useful to users in any
	way. If looking for the size of a set, use :c:func:`PySet_Size` instead.
	A :term:`soft deprecated` constant representing the size of an internal
	preallocated table inside :c:type:`PySetObject` instances.
	This is documented solely for completeness, as there are no guarantees
	that a given version of CPython uses preallocated tables with a fixed
	size.
	In code that does not deal with unstable set internals,
	:c:macro:`!PySet_MINSIZE` can be replaced with a small constant like ``8``.
	If looking for the size of a set, use :c:func:`PySet_Size` instead.
	.. deprecated:: next
	The constant is :term:`soft deprecated`.

[ZeroIntensity]

I'm not too fond of using .. deprecated for this, because the next (or whatever version we put in there) would imply that it's fine to use for earlier versions. We don't want people using this on any version.

[encukou]

That's fair.
On the other hand, without .. deprecated, automated tools won't be able to tell that these are deprecated.

[ZeroIntensity]

Unfortunately, I don't think our documentation is sufficient for automated tools yet. (For example, we document a bunch of macros as functions, which would break if used to generate bindings.) I do agree that we should eventually get C API documentation to that point, but that's a project I plan to work on once #141004 is done.

[encukou]

I still think .. deprecated is better in the mean time. But I won't block the PR on that :)

[encukou]

Here I'd recommend listing the equivalent expressions, to make these easier to replace.

[ZeroIntensity]

Done.

[vstinner]

It can be 15, see the configure option --enable-big-digits.

[ZeroIntensity]

Fixed via Petr's suggestion.