[Python-Dev] Breaking undocumented API

[Steven D'Aprano]

Nick Coghlan wrote:

> The policy we're aiming to clarify here is what we should do when we
> come across standard library APIs that land in the grey area, with
> there being two appropriate ways to deal with them:
> 1. Document them and make them officially public
> 2. Deprecate the public names and make them officially private (with
> the public names later removed in accordance with normal deprecation
> procedures)

You missed at least two other options:

3. Treat "documented" and "public" as orthogonal, not synonymous: 
undocumented public API is not an oxymoron, and neither is documented 
private API.

4. Do nothing. Inertia wins. Is this problem we're trying to solve so 
serious that we need to solve it now except on a case-by-case basis?

The approach that gives us the most flexibility is #3. Clearly one would 
not need to document private APIs for the use of the general public, but 
adding docstrings to private functions and classes for in-house use is a 
sensible thing to do. This applies equally to the standard library as to 
any other major project.

Likewise, one might introduce a public function into some module, but 
for whatever reason, choose not to document it. (Perhaps it's a lack of 
hours in the day, perhaps it is a deliberate decision.) In this case, 
the mere lack of documentation shouldn't relieve us of the 
responsibility of treating the function as public.

For emphasis: I strongly believe that public/private and 
documented/undocumented are orthogonal qualities, and should not be 
treated as, or forced to be, identical.

The use of imported modules is possibly an exception. If a user is 
writing something like (say) getopt.os.getcwd() instead of importing os 
directly, then they're on shaky ground. We shouldn't expect module 
authors to write "import os as _os" just to avoid making os a part of 
their public API.

I'd be prepared to make an exception to the rule "no leading underscore 
means public": imported modules are implementation details unless 
explicitly documented otherwise. E.g. the os module explicitly makes 
path part of its public API, but os.sys is an implementation detail.



-- 
Steven