Document the rules for "public names"

abalkin commented 13 years ago

BPO	10434
Nosy	@freddrake, @warsaw, @ncoghlan, @abalkin, @ezio-melotti, @voidspace, @MaxwellDupre

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields: ```python assignee = None closed_at = None created_at = labels = ['easy', 'type-feature', 'docs'] title = 'Document the rules for "public names"' updated_at = user = 'https://github.com/abalkin' ``` bugs.python.org fields: ```python activity = actor = 'mikecmcleod' assignee = 'docs@python' closed = False closed_date = None closer = None components = ['Documentation'] creation = creator = 'belopolsky' dependencies = [] files = [] hgrepos = [] issue_num = 10434 keywords = ['easy'] message_count = 5.0 messages = ['121297', '121299', '121304', '194067', '411158'] nosy_count = 9.0 nosy_names = ['fdrake', 'barry', 'ncoghlan', 'belopolsky', 'ron_adam', 'ezio.melotti', 'michael.foord', 'docs@python', 'mikecmcleod'] pr_nums = [] priority = 'normal' resolution = None stage = 'needs patch' status = 'open' superseder = None type = 'enhancement' url = 'https://bugs.python.org/issue10434' versions = ['Python 3.2', 'Python 3.3', 'Python 3.4'] ```

abalkin commented 13 years ago

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 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). """ [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.

[1] http://mail.python.org/pipermail/python-dev/2010-November/105490.html [2] http://docs.python.org/reference/simple_stmts.html

abalkin commented 13 years ago

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.

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

[1] http://mail.python.org/pipermail/python-dev/2010-November/105476.html

a64a965f-f898-4e4f-8130-4f9381f9f181 commented 13 years ago

You may also want to update help topics.

help("PRIVATENAMES").

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.

When the name is bound to an object, evaluation of the atom yields that object. When a name is not bound, an attempt to evaluate it raises a NameError exception.

Private name mangling: When an identifier that textually occurs in a class definition begins with two or more underscore characters and does not end in two or more underscores, it is considered a private name of that class. Private names are transformed to a longer form before code is generated for them. The transformation inserts the class name in front of the name, with leading underscores removed, and a single underscore inserted in front of the class name. For example, the identifier __spam occurring in a class named Ham will be 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.

python / cpython

Document the rules for "public names" #54643