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

Alexander Belopolsky alexander.belopolsky at gmail.com
Thu Nov 11 06:41:16 CET 2010

On Wed, Nov 10, 2010 at 6:10 PM, Ron Adam <rrr at 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>.

More information about the Python-Dev mailing list