[Python-ideas] Was `os.errno` undocumented?
storchaka at gmail.com
Tue May 29 10:37:06 EDT 2018
29.05.18 13:06, Petr Viktorin пише:
> 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.
Unlike to os.path, which is explicitly documented and included in
__all__, os.abc, os.errno, os.sys and os.st are not documented and not
included in __all__. They were always an implementations detail.
os.errno was added as a side effect of issue1755179. 
> 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.
We have removed over 100 module attributes in 3.6  and over 200
module attributes in 3.7 .
Some of these removals broke third-part projects , even removals of
underscored names. If we will document the removal of os.errno, we
should to document the removal of at least other names for which there
are known examples of breaking third-party projects, e.g.
re._pattern_type, uuid._uuid_generate_time and several typing attributes.
More information about the Python-ideas