On Wed, Nov 10, 2010 at 6:10 PM, Ron Adam <r...@ronadam.com> wrote: .. >> On Nov 10, 2010, at 5:47 AM, Michael Foord wrote: >>> >>> 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): >> .. > The way I read Guido's email is that it is a situation dependent judgment > call for those cases that aren't clear. > > I think what Micheal is trying to say is for us to agree on some things so > we can go forward with a little more clarity.
I don't understand why everyone seem to have accepted Michael's premise that "we don't have a clearly stated policy for what defines the public API of standard library modules." We do have such a policy and it is well known (while the location in the reference manual may not be): """ The public names defined by a module are determined by checking the module’s namespace for a variable named __all__; if defined, it must be a sequence of strings which are names defined or imported by that module. The names given in __all__ are all considered public and are required to exist. If __all__ is not defined, the set of public names includes all names found in the module’s namespace which do not begin with an underscore character ('_'). __all__ should contain the entire public API. It is intended to avoid accidentally exporting items that are not part of the API (such as library modules which were imported and used within the module). """ -- <http://docs.python.org/reference/simple_stmts.html> The question that I had when I started this thread was not about a definition of "public API." It was about a policy with respect to modules that precede the introduction of __all__ and the modern definition of public names. (See r18692 "Two changes to from...import", and r23920 ' adding a definition of "public names"'.) Is it OK to add __all__ to such modules that does not include all names not starting with an underscore? Is it OK to then remove names that clearly were not intended to be public? Case in point: trace.rx_blank. See also <http://bugs.python.org/issue10371>. _______________________________________________ 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