[docs] [issue37134] Use PEP570 syntax in the documentation

[Grant Jenks]

Grant Jenks <grant.jenks at gmail.com> added the comment:

Pablo, I never intended disrespect toward you personally. And I am sorry my words came across that way. I would rather the feature be one of Python's more esoteric qualities.

I think Carol has described the most reasonable way forward. And in particular, I like this creative idea:

> A Sphinx extension may also be made to show a simple user-friendly view and with a click the fully accurate view.

I agree too with Raymond in this point:

> I don't think inclusion in 3.9 should be automatic.

As anecdata: I showed the PEP and feature to an intermediate class of 15 professional software engineers today. The first question I got was, "when should I use that in my Python code?" And I think the answer is rarely. We reviewed the motivating cases in the PEP and those made sense to them. But I was left feeling concern that if it were prominent and frequent in the docs then people will be likely to imitate, not least of which through simple copy/paste, what they see there without understanding the C-API and why it is that way.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue37134>
_______________________________________