gh-129667: Update annotation in documentation

[donBarbos]

• Issue: Update annotation parameters for objects in documentation #129667

---

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

[rhettinger]

IIRC there was a decision to not litter the docs the trailing backslash. People find it confusing and it doesn't seem to help them in any way.

[donBarbos]

@rhettinger sorry, I fixed it. but other changes are relevant, isn't it?

[AlexWaygood]

IIRC there was a decision to not litter the docs the trailing backslash. People find it confusing and it doesn't seem to help them in any way.

@rhettinger, the Editorial Board's recent decision was that PEP-570 syntax should be used in documentation. This is now documented in the devguide; see python/devguide#1344. The Editorial Board has a standing delegation from the Steering Council on all documentation matters: https://github.com/python/steering-council/blob/main/process/standing-delegations.md#documentation-editorial-board

[donBarbos]

@AlexWaygood

the Editorial Board's recent decision was that PEP-570 syntax should be used in documentation. This is now documented in the devguide; see python/devguide#1344. The Editorial Board has a standing delegation from the Steering Council on all documentation matters: https://github.com/python/steering-council/blob/main/process/standing-delegations.md#documentation-editorial-board

So should I put / back or wait for rhettinger's answer?

[rhettinger]

the Editorial Board's recent decision was that PEP-570 syntax should be used in documentation.

Then this PR can go forward.

It's a bummer though. Signatures with trailing backslashes are intrinsically less readable. People who are only occasional users of Python find it confusing (likely because no other language does this). This makes the docs less accessible to average users. A high school student shouldn't have to see len(obj, /). It just gets in the way of learning and makes Python look cryptic even for its simplest functions.

[donBarbos]

A high school student shouldn't have to see len(obj, /).

I think they use other sources of knowledge, and most likely the docs reader is familiar with python syntax.

And also it would be nice to add "skip news" label

[rhettinger]

I think they use other sources of knowledge, and most likely the docs reader is familiar with python syntax.

My direct experience says otherwise. When people take an introductory python course, the positional-only/keword-only syntax is rarely covered. There is just too much else to talk about. Introductory books on Python typically defer discussion on this topic until all other core topics have been covered.

Also, it seems like an anti-goal to reduce accessiblity and expect some user categories to search elsewhere for knowledge. AFAICT, we've always wanted to maximize accessibility for all users.

[nedbat]

At a recent Editorial Board meeting, we re-affirmed the principle of the reference documentation being precise. The function signatures should have slashes to indicate arguments that are positional-only. It can be a bit confusing to new learners, so we'll be experimenting with adjustments to the Sphinx rendering to help people understand the syntax.

[picnixz]

I'm a bit conflicted with the fact that we're now showing the internal parameters in the signatures. Yes, it could be helpful indeed, but it also exposes implementation details. For functions, I think we could implicitly not include them because an external caller is not meant to use them (probably), however for methods, if the class can be inherited, then children classes may want to know the complete signature just to be sure that they do not violate the Liskov substitution principle.

However, as I said on some functions/methods, I prefer that we don't add new parameters in this PR but only add the positional-only markers. In separate PRs, each added parameter should either explicitly be marked as internal (in the docs) or we should not show it if callers or subclasses do not need to know about it.

[picnixz]

Shouldn't ctxkwargs be documented as well?

[donBarbos]

I added a description and found PR #124548 where this argument was added

[picnixz]

As it's 3.14+, this means that this should not be backported. So a separate PR is easier to handle as well. And we can make it part of gh-124694 instead.

[picnixz]

Can you first address the new comments and then check that all the remaining modifications are actually backportable to 3.12 as well? TiA

[picnixz]

I don't really know what kwargs means here so I would appreciate that it's documented in a separate PR as well.

[picnixz]

It's not "next" as this was added in a previous release (just find the major.minor version where it was added, I think it's still 3.14)

[picnixz]

What's prepare_context? it doesn't help when we refer to functions without any docs.

[picnixz]

I think we should have a separate PR for re-documenting InteractiveConsole methods. In addition, I'm still unsure whether private parameters should be exposed or not. Personally, I would rather prefer not having them exposed but if subclasses need to override the method, I think their signature should then be compatible. Note that https://github.com/python/typeshed/blob/1c17cd429c2f91b0066547deb99c537af3e54d39/stdlib/code.pyi#L23-L37 does not expose this private parameter, so I think we shouldn't as well (and let this inconsistency with the signature remain; mypy wouldn't complain as typeshed also doesn't specify it.

Finally, filename seems to be only 3.13+ so we should also be careful with the backports (therefore I'd prefer having a separate PR for InteractiveConsole)

[picnixz]

As it's 3.14+, this means that this should not be backported. So a separate PR is easier to handle as well. And we can make it part of gh-124694 instead.