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

[Steven D'Aprano]

On Tue, May 29, 2018 at 12:06:42PM +0200, Petr Viktorin wrote:
> 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.

PEP 8 makes it clear that imports are implementation details unless 
explicitly documented otherwise:

    Imported names should always be considered an implementation detail. 
    Other modules must not rely on indirect access to such imported names 
    unless they are an explicitly documented part of the containing 
    module's API, such as os.path or a package's __init__ module that 
    exposes functionality from submodules.


This decision dates back to 2013:

https://mail.python.org/pipermail/python-dev/2013-July/127284.html

so it has been around for a while, long enough that linters ought to be 
enforcing it, and people ought to know about it. If not, that's a 
failure of the linter and/or the coder.


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

I don't see why there should be a debate about mentioning it in the 
release notes. There's no harm in adding a few lines:

"os.errno is a non-public implementation detail, as described in PEP 8, 
and has been removed. Import the errno module instead."

Being an implementation detail, we aren't *required* to do so, but given 
that (so you say) a few tutorials etc use it, I think it is the kind 
thing to do.



> 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:
[...]

All of this is reasonable, and I'm sympathetic, *except* that it is 
officially documented policy that imports are implementation details 
unless otherwise stated.

If os.errno was gone and there was no easy fix, I think we could be 
merciful and rethink the decision. But there is an easy fix: import 
errno directly instead.

And maybe this will encourage linters to flag this risky usage, if they 
aren't already doing so.


> As you can see, the built-in documentation does not contain *any* 
> warnings against using `os.errno`.

It doesn't need to.

And of course, help(os.errno) *cannot* warn about os.errno, since it 
only receives the errno module as argument, not the expression you used 
to pass it.


-- 
Steve