PEP 727: Documentation Metadata in Typing

[BrenBarn (Brendan Barnwell)]

@Jelle

@BrenBarn

I’m not sure what other people think, but in my view motivations of the form “eliminate the possibility of X” are essentially unpythonic.

That’s a strange claim. Sebastián’s argument is essentially that the existing way to do this is error-prone, so we should provide a new approach that is not prone to this category of errors. That’s a common argument for new features: for example, the Rationale section for PEP 498 (introducing f-strings) opens with an account of how % formatting is prone to a certain category of mistakes. Similarly, PEP 616 (str.removeprefix) is motivated by the fact that str.strip()-like methods are prone to certain categories of mistakes.

I mean, you’re right of course, but so am I. Any proposed change can be viewed either as a way to avoid bad things or to provide good things. All I’m saying is that a framing of “we want to eliminate problem X” isn’t convincing to me, because problem X won’t be eliminated; all we’re doing is adding a new thing that we hope is better.

That’s also the case for PEP 498, and, rereading the PEP, I don’t see that it was couched in terms of “the goal is to eliminate these problems”. Rather it was “there are some problems with % formatting, and str.format has some advantages but is too verbose, so we’re adding a new way that tries to build on what went before”. If we wanted to “eliminate” the problems with the old formatting mechanisms, we’d have to propose removing those old mechanisms. And likewise if we wanted to “eliminate” problems of mismatches between docs and runtime behavior, we’d have to propose some kind of mandatory annotations (and even that wouldn’t do it, since no tool can read the doc strings and tell us if they will correctly communicate what they intend to communicate to a human).

And that’s not being proposed here. So my point is just that claiming this change will “eliminate the possibility of inconsistencies” in docstrings is overstating the benefit. It will provide a possible way to avoid some such inconsistencies — at a cost of readability and time to write the function.

@Jelle

It’s absolutely Pythonic to design the language in such a way that mistakes are as unlikely as possible.

No doubt. But we also want to avoid making non-mistakes difficult as well. As @pf_moore said, a lot of this comes down to preference. It’s a trade-off between certain up-front costs (e.g., everyone is expected to take extra time to craft more verbose function signatures and take extra time to read and understand them) and certain future benefits (e.g., writing those signatures will make a certain class of runtime errors less likely), and different people have different preferences on that. As I mentioned on another thread though, my own feeling is that this kind of tradeoff isn’t ultimately going to provide all the benefits that people hope for in Python, because the whole world of such annotations is disconnected from the actual runtime behavior. Either there will be too many holes through which errors can pass, or the chore of patching them all with increasingly verbose annotations will become too burdensome.