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

[Petr Viktorin]

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