On Wed, Nov 10, 2010 at 05:47, Michael Foord <fuzzy...@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@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