[Python-Dev] Breaking undocumented API

[Brett Cannon]

On Wed, Nov 10, 2010 at 05:47, Michael Foord <fuzzyman at voidspace.org.uk> wrote:
> 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 sounds reasonable to me and what common practice out in the community is.

-Brett

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