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

[Steven D'Aprano]

On Tue, May 29, 2018 at 05:37:06PM +0300, Serhiy Storchaka wrote:

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

Yes, people will rely on undocumented features. Even when you tell them 
not to.

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

I disagree. I think that _leading underscore names can be removed 
without mentioning the removal. If it breaks code, too bad. Anyone using 
an explicitly named _private name has only themselves to blame.

But non-public names *without* a leading underscore are in a grey area, 
since they *look* like public names.
 
I think we can afford to be kind by documenting such removals -- 
especially since it may help to educate people that imported modules 
without a leading underscore are still considered implementation 
details.


-- 
Steve