[Python-Dev] Breaking undocumented API

[Michael Foord]

On 08/11/2010 22:07, Raymond Hettinger wrote:
> On Nov 8, 2010, at 11:58 AM, Brett Cannon wrote:
>
>> I think we need to, as a group, decide how to handle undocumented APIs
>> that don't have a leading underscore: they get treated just the same
>> as the documented APIs, or are they private regardless and thus we can
>> change them at our whim?
> To start with, it doesn't hurt for a maintainer to add an __all__ entry and to only document the parts of the API we think need to be exposed.  That way, we can at least declare the parts that are intended to be public on a go-forward basis.
>
> For the most part, the non-underscored parts of the API shouldn't be changed "at our whim".  Some sense needs to be applied to the decision.  Google's code search is great for showing how people actually have used a module in real world code.  If that shows that people are accessing and/or changing an attribute, it probably needs to remain exposed.   In the absence of a code search, good guesses can be made about what someone might reasonably and usefully be accessing (i.e. glob0 isn't likely).   The goal is to improve the standard library while minimizing breakage, and that will involve trade-offs depending on what is being changed.
>
> IIRC, we've been trying to get away from deprecations because they're so disruptive.  For example, when the pprint rewrite is finally ready, if there is an incompatible API change, I expect that a new clean class will be offered, but that the old will be left in-place so that tons of existing code won't break).  Likewise, with the unittest clean-ups, I'm expecting that Michael will introduce aliases when fixing-up mis-named methods, rather than break code that uses the existing names.
>

So it is obvious that we don't have a clearly stated policy for what 
defines the public API of standard library modules.

How about making this explicit (either pep 8 or our developer docs):

If a module or package defines __all__ that authoritatively defines the 
public interface. Modules with __all__ SHOULD still respect the naming 
conventions (leading underscore for private members) to avoid confusing 
users. Modules SHOULD NOT export private members in __all__.

Names imported into a module a never considered part of its public API 
unless documented to be so or included in __all__.

Methods / functions / classes and module attributes whose names begin 
with a leading underscore are private.

If a class name begins with a leading underscore none of its members are 
public, whether or not they begin with a leading underscore.

If a module name in a package begins with a leading underscore none of 
its members are public, whether or not they begin with a leading underscore.

If a module or package doesn't define __all__ then all names that don't 
start with a leading underscore are public.

All public members MUST be documented. Public functions, methods and 
classes SHOULD have docstrings. Private members may have docstrings.


Where in the standard library this means that a module exports stuff 
that isn't helpful or shouldn't be part of the public API we need to 
migrate to private names and follow our deprecation process for the 
public names.

All the best,


Michael Foord
> my-two-cents,
>
>
> Raymond
>
>
>
>
> _______________________________________________
> Python-Dev mailing list
> Python-Dev at python.org
> http://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe: http://mail.python.org/mailman/options/python-dev/fuzzyman%40voidspace.org.uk


-- 

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.