[Python-ideas] Was `os.errno` undocumented?

[Petr Viktorin]

Hello,
Python 3.7 removes the undocumented internal import `os.errno`.
We consider that a an implementation detail, which can be changed 
*without notice* even in a bugfix release. Projects that depend on it 
are incorrect and should be fixed.

On bpo-33666, there's a debate on whether the removal should be 
mentioned in release notes, on the grounds that it broke some projects, 
is used in quire a few tutorials/books/examples, and it's been working 
since Python 2.5 or so.


But here's the thing: the more I think about this, the less I consider 
`os.errno` as "undocumented". Here's what I consider a reasonable path a 
programmer might go through:

# Where do I find errno values?
# Maybe it's in `os`, like all other basic platform bindings?
 >>> import os
 >>> os.err<tab>
os.errno   os.error(
 >>> help(os.errno)
Help on built-in module errno:
...
# Yup, There it is!

Even more serious:

# Hmm, this old example on some website tells me to use `os.errno`.
# It's the first time I'm hear about that, so I'll be extra careful;
 >>> import os
 >>> os.errno
<module 'errno' (built-in)>
# Yup, it's there! Let's double-check the docs.
 >>> help(os.errno)
Help on built-in module errno:
...
# Yup, looks quite alright! Let's use it!

As you can see, the built-in documentation does not contain *any* 
warnings against using `os.errno`.
You might think the fact that it's called "errno" and not "os.errno" is 
a red flag, but it's not, really -- "os.path" is (on my system) named 
"posixpath", yet "os.path" is the name to use.

While most people might prefer searching docs.python org to `help()`, 
editors are getting better and better to presenting introspection and 
the built-in docs, so more and more people are preferring `pydoc`-ish 
docs to going online.

I don't think we can reasonably expect people who used built-in help as 
above to go back and check that Python's official docs *do not* contain 
`os.errno`. Effectively, while `os.errno` is not very *discoverable* 
using official docs alone, I don't think calling it *undocumented* is fair.
So, removing it without notice is not very friendly to our users.

Is that reasoning sound?
Should our policy on removing internal imports take that into account?