[Python-ideas] Was `os.errno` undocumented?
tjreedy at udel.edu
Tue May 29 19:24:01 EDT 2018
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 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
More information about the Python-ideas