[Python-Dev] Breaking undocumented API (original) (raw)

Michael Foord fuzzyman at voidspace.org.uk
Wed Nov 10 14:47:39 CET 2010

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.

More information about the Python-Dev mailing list