[Python-Dev] Breaking undocumented API

[Michael Foord]

On 17/11/2010 21:57, Steven D'Aprano wrote:
> 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.
>

Along with the others +1

I think how we handle the deprecations (legacy modules with unclear or 
clearly wrong naming policies) is the least interesting part of this 
discussion. For deprecating existing names we have *no choice* but to 
proceed on a case-by-case basis evaluating how likely the deprecation is 
to break other code, whether or not the name was originally intended to 
be public or not. (At least that is how we *should* proceed and part of 
our standard deprecation policy - it is why we aren't removing 
unittest.TestCase.assertEquals and assert_ even though they are 
deprecated. They are just too widely used.)

What is more important is that we have a clearly stated policy for new 
modules and adding names to existing modules so that we don't have to 
repeat this debate in five years time.

My suggestion, which fits in with the use of __all__ by the language and 
also the convention widely in use by the community already boils down to:

* If __all__ exists it is definitive
* Imported names are never part of the public API of a module unless in 
__all__ or documented to be part of the API
* Names with leading underscores are private unless in __all__ (and if 
you want to export leading underscore names as part of a public API you 
should define __all__ or "import *" won't export them)
* Leading underscore convention extends to packages and class members; 
no members of a package or class whose name begins with a leading 
underscore are public

It is still good practise that public APIs *should* be documented (and 
*should* have docstrings). There is however no corollary that private 
APIs should not be documented (and they may have docstrings).

All the best,

Michael Foord



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


-- 

http://www.voidspace.org.uk/

READ CAREFULLY. By accepting and reading this email you agree,
on behalf of your employer, to release me from all obligations
and waivers arising from any and all NON-NEGOTIATED agreements,
licenses, terms-of-service, shrinkwrap, clickwrap, browsewrap,
confidentiality, non-disclosure, non-compete and acceptable use
policies (”BOGUS AGREEMENTS”) that I have entered into with your
employer, its partners, licensors, agents and assigns, in
perpetuity, without prejudice to my ongoing rights and privileges.
You further represent that you have the authority to release me
from any BOGUS AGREEMENTS on behalf of your employer.