Title: Document the rules for "public names"
Type: enhancement Stage: needs patch
Components: Documentation Versions: Python 3.2, Python 3.3, Python 3.4
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: barry, belopolsky, docs@python, ezio.melotti, fdrake, michael.foord, ncoghlan, ron_adam
Priority: normal Keywords: easy

Created on 2010-11-16 14:55 by belopolsky, last changed 2013-08-01 13:05 by ncoghlan.

Messages (4)
msg121297 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-11-16 14:55
As discussed in "Breaking undocumented API" thread [1] on python-dev,  a definition of "public names" is buried deep in the language reference manual:

The public names defined by a module are determined by checking the
includes all names found in the module’s namespace which do not begin
public API. It is intended to avoid accidentally exporting items that
and used within the module).
"""  [2]

It has been argued that this is not the authoritative definition and alternatives have been suggested such as "any name that does not begin with an underscore except imported modules."
mportant for the users and developers of cpython and other python implementations to know what names they can rely upon to stay defined between releases, the rules for "public names" should be documented.

I agree that the library manual is a more appropriate place for such documentation.  The definition should include the naming conventions and the set of promises that Python makes about public name availability in the future releases.

msg121299 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-11-16 15:48
Michael Foord suggested adding the following to developer documentation such as PEP 8. [1] I am not sure PEP 8 is the right place for it.  In my opinion, PEP 8 is mostly about stylistic choices that don't have a major impact on the users.  In other words, unless you are developing python itself, you are unlikely to consult PEP 8.  The API stability rules, however affect every user who programmed in python long enough to see a major release.  I don't have objections to Michael's definitions below, but if included in the library manual, they should be reworded to address the user rather than the developer of the API.

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.

public, whether or not they begin with a leading underscore.


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.
""" [1]

msg121304 - (view) Author: Ron Adam (ron_adam) * Date: 2010-11-16 16:29
You may also want to update help topics.


Identifiers (Names)

An identifier occurring as an atom is a name.  See section
*Identifiers and keywords* for lexical definition and section *Naming
and binding* for documentation of naming and binding.

raises a ``NameError`` exception.

a class definition begins with two or more underscore characters and
name* of that class. Private names are transformed to a longer form
before code is generated for them.  The transformation inserts the
transformed to ``_Ham__spam``.  This transformation is independent of
the syntactical context in which the identifier is used.  If the
transformed name is extremely long (longer than 255 characters),
implementation defined truncation may happen.  If the class name
consists only of underscores, no transformation is done.

Other topics that may be of interest.

msg194067 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-08-01 13:05
PEP 8 now covers the developer side of things:

A user facing counterpart describing our backwards compatibility policy is still desirable. Updating PEP 5 wouldn't go astray, since that's *supposed* to serve that purpose :)
Date User Action Args
2013-08-01 13:05:17ncoghlansetnosy: + ncoghlan
messages: + msg194067
2013-07-17 01:13:28barrysetnosy: + barry
2012-11-08 08:26:58ezio.melottisetkeywords: + easy
type: enhancement
versions: + Python 3.3, Python 3.4
2010-11-19 21:03:11fdrakesetnosy: + fdrake
2010-11-19 20:57:48ezio.melottisetnosy: + ezio.melotti
2010-11-16 16:29:40ron_adamsetnosy: + ron_adam
messages: + msg121304
2010-11-16 15:48:41belopolskysetnosy: + michael.foord
messages: + msg121299
2010-11-16 14:55:37belopolskycreate