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@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.
_______________________________________________
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
