[Python-ideas] Was `os.errno` undocumented?
steve at pearwood.info
Tue May 29 07:57:57 EDT 2018
On Tue, May 29, 2018 at 12:06:42PM +0200, Petr Viktorin wrote:
> 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:
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.
More information about the Python-ideas