PEP 842 postmortem: how do we protect the standard library?

[steve.dower]

@ZeroIntensity

I realize you were AFK for most of PEP 842, but I’ve explained myself here many times already, so I apologize for my frustration with this.

Been there Your frustration is barely showing, btw, you’ve got a lot further to go before you start being accused of being cranky

I’m also aware that I missed most of the discussion, so I’m intentionally trying not to re-litigate issues that I’m sure came up (while also preserving my own sanity by not actually reading that entire thread - if GitHub wasn’t down right now I’d probably even be doing useful work instead of catching up on dpo ).

@ZeroIntensity

I think it’s quite common for users to take an example from the README, start using it as a “hello world”, and iterate using autocomplete/dir() (or in today’s age, LLMs) from there.

Totally agree, which is why all my suggestions were things that would be accessible at runtime. Back when I worked on one of the earliest IDEs that was exposing this information to developers in real-time we had these kinds of discussions all the time.

The unavoidable premise is that the docs are the definitive source of truth on what’s “public” (aka. intended to be used), because that’s how it’s always been done. If a user doesn’t follow the docs, they’re out of support, and we aren’t obliged to treat their issue as a bug (because, e.g., they used something they weren’t told to and we broke it in an update).

The current problem is that a number of rules have grown up around that, which seem to keep being thrown around as the definitive rules, when they just aren’t. We’ve got docs and years of convention, which sometimes get codified into rules, but we also don’t like rules so the rules get exceptions (like “we should use a leading underscore for private, but because we haven’t always done that you shouldn’t assume the absence of a leading underscore means public, and we also don’t want a drive-by PR that renames everything to add an underscore so don’t do that either”).

So as Paul says, we need the clearer set of rules, and it’s likely more of a design manifesto than a simple easy-to-follow PEP. It’ll require a lot of research into discussions from the past to get a good, unbiased read on what was intended by the things that did get written down, and distilling that into something that is complete enough to be read and followed in isolation. The great thing is that virtually all of these discussions will be in mailing list archives, because we did so little in person until relatively recently. Endless amounts of Guido’s wisdom (from when he was the final decision maker on everything) is right there waiting to be collected

@pf_moore

Is an unstated part of the issue here that LLMs don’t read documentation, and will use anything that works? Or maybe less controversially, that IDEs don’t read documentation and offer private APIs on an equal footing with public ones?

My experience has been the opposite - the LLMs do read documentation and docstrings and follow them. IDEs certainly don’t do a lot to filter, other than the leading underscore, though we were adding all sort of statistical methods to Visual Studio (and presumably VS Code, though I haven’t been as involved there) to prioritise the members that people actually use over the ones that aren’t, and those tended to be more than good enough. We invested quite a lot in trying to filter in ways that helped our users, whether the library developers had done it or not, I don’t know that we ever saw users blaming us for showing them members they weren’t meant to be using, but maybe that’s changed in the last decade.