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

INADA Naoki songofacandy at gmail.com
Tue May 29 06:24:32 EDT 2018

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

Agree, but...

>   Effectively, while `os.errno` is not very *discoverable*
> using official docs alone, I don't think calling it *undocumented* is

`pydoc os` shows:

     This exports:
       - all functions from posix or nt, e.g. unlink, stat, etc.
       - os.path is either posixpath or ntpath
       - os.name is either 'posix' or 'nt'
       - os.curdir is a string representing the current directory (always
       - os.pardir is a string representing the parent directory (always
       - os.sep is the (or a most common) pathname separator ('/' or '\\')
       - os.extsep is the extension separator (always '.')
       - os.altsep is the alternate pathname separator (None or '/')
       - os.pathsep is the component separator used in $PATH etc
       - os.linesep is the line separator in text files ('\r' or '\n' or
       - os.defpath is the default search path for executables
       - os.devnull is the file path of the null device ('/dev/null', etc.)

So I think calling `os.errno` as *undocumented* is fair.

> So, removing it without notice is not very friendly to our users.

> Is that reasoning sound?

Depending on such subimports is common pitfall all experienced
Python programmer knows.
Of course, it's not very friendly, but a pitfall.  But I don't think it's
reason to call it *documented*.

> Should our policy on removing internal imports take that into account?

Maybe, we should use `_` prefix for all new private subimports.
I don't have any idea having better "maintainability : user friendly" ratio
than it.

Third party linter may be able to notice warning for using private
in user code.


INADA Naoki  <songofacandy at gmail.com>

More information about the Python-ideas mailing list