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

[Terry Reedy]

On 5/29/2018 6:06 AM, Petr Viktorin wrote:

> Python 3.7 removes the undocumented internal import `os.errno`.

Among a couple of hundred others, including some from idlelib.

> We consider that a an implementation detail, which can be changed 
> *without notice* even in a bugfix release.

We core developers occasionally run a linter on our code, or someone 
does it for us.  Those of us who like clean code attend to warnings such 
as 'unused import'.  I removed a couple of idlelib inports because of 
someone else running flake8.

> Projects that depend on it are incorrect and should be fixed.

I think we can agree that better warning of 'use of stdlib internal 
import' would be great.

> 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.

Since I agree that *this* removal may possibly have the greatest impact, 
and that the purpose of What's New is to help users, I am glad Guido 
spoke up to say 'do it'.  See my reponse to his post for a suggested entry.

> 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!

Suppose a naive beginner who confuses 'IDLE' with 'python' (they exist!) 
thinks "Where can I find re functions?  How about 'pyshell'

 >>> import idlelib.pyshell as ps
 >>> ps.<completion box>r<jumps to re><return>
<module 're' from 'C:\\Programs\\Python37\\lib\\re.py'>
 >>> help(ps.re)
Help on module re:

!

> Is that reasoning sound?

Do you claim that os.errno is more documented (by the 'official' docs 
and help) than idlelib.pyshell.re?

-- 
Terry Jan Reedy