[Python-ideas] Was `os.errno` undocumented?
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
> Effectively, while `os.errno` is not very *discoverable*
> using official docs alone, I don't think calling it *undocumented* is
`pydoc os` shows:
- 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
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