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

Petr Viktorin encukou at gmail.com
Tue May 29 06:06:42 EDT 2018

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.

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.

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!

Even more serious:

# Hmm, this old example on some website tells me to use `os.errno`.
# It's the first time I'm hear about that, so I'll be extra careful;
 >>> import os
 >>> os.errno
<module 'errno' (built-in)>
# Yup, it's there! Let's double-check the docs.
 >>> help(os.errno)
Help on built-in module errno:
# Yup, looks quite alright! Let's use it!

As you can see, the built-in documentation does not contain *any* 
warnings against using `os.errno`.
You might think the fact that it's called "errno" and not "os.errno" is 
a red flag, but it's not, really -- "os.path" is (on my system) named 
"posixpath", yet "os.path" is the name to use.

While most people might prefer searching docs.python org to `help()`, 
editors are getting better and better to presenting introspection and 
the built-in docs, so more and more people are preferring `pydoc`-ish 
docs to going online.

I don't think we can reasonably expect people who used built-in help as 
above to go back and check that Python's official docs *do not* contain 
`os.errno`. Effectively, while `os.errno` is not very *discoverable* 
using official docs alone, I don't think calling it *undocumented* is fair.
So, removing it without notice is not very friendly to our users.

Is that reasoning sound?
Should our policy on removing internal imports take that into account?

More information about the Python-ideas mailing list