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

[Serhiy Storchaka]

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. [1]

> 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 [2] and over 200 
module attributes in 3.7 [3].

Some of these removals broke third-part projects [4], 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.

[1] https://bugs.python.org/issue1755179
[2] https://bugs.python.org/msg317881
[3] https://bugs.python.org/msg317876
[4] https://bugs.python.org/msg317998