(Apologies if you received an empty/unfinished e-mail here earlier; I
hit Send by mistake.)
On 05/29/18 13:57, Steven D'Aprano wrote:
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.
I agree that it's technically well within our rights to remove it
without notice.
But ... PEP8? A style guide defines what is a CPython implementation
detail? That's not a place to point to while saying "told you so!" --
perhaps "sorry for the inconvenience" would be more appropriate :)
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.
How do linters find out what's an internal import, and what's correct
usage (like os.path)?
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.
Indeed. That's unfortunate, but it is a reason for us to be careful, or
perhaps find/document a better policy for handling these.
I'm not looking for evidence to justify the changes; I'm looking for
ways to be more friendly to our users -- most of whom have not read all
of the docs.
_______________________________________________
Python-ideas mailing list
Python-ideas@python.org
https://mail.python.org/mailman/listinfo/python-ideas
Code of Conduct: http://python.org/psf/codeofconduct/
