[issue10434] Document the rules for "public names"

[mike mcleod]

mike mcleod  added the comment:

I would like to help on this issue. Is there anyone available to push a PR 
through? If I make the changes.

--
nosy: +mikecmcleod

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue10434] Document the rules for "public names"

[Nick Coghlan]

Nick Coghlan added the comment:

PEP 8 now covers the developer side of things: 
http://www.python.org/dev/peps/pep-0008/#public-and-internal-interfaces

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 :)

--
nosy: +ncoghlan

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue10434] Document the rules for "public names"

[Barry A. Warsaw]

Changes by Barry A. Warsaw :


--
nosy: +barry

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue10434] Document the rules for "public names"

[Ezio Melotti]

Changes by Ezio Melotti :


--
keywords: +easy
type:  -> enhancement
versions: +Python 3.3, Python 3.4

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue10434] Document the rules for "public names"

[Fred L. Drake, Jr.]

Changes by Fred L. Drake, Jr. :


--
nosy: +fdrake

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue10434] Document the rules for "public names"

[Ezio Melotti]

Changes by Ezio Melotti :


--
nosy: +ezio.melotti

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue10434] Document the rules for "public names"

[Ron Adam]

Ron Adam  added the comment:

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.


Other topics that may be of interest.

IDENTIFIERS
NAMESPACES
PACKAGES
PRIVATENAMES
SPECIALATTRIBUTES
SPECIALIDENTIFIERS
SPECIALMETHODS

--
nosy: +ron_adam

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue10434] Document the rules for "public names"

[Alexander Belopolsky]

Alexander Belopolsky  added the comment:

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

--
nosy: +michael.foord

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue10434] Document the rules for "public names"

[Alexander Belopolsky]

New submission from Alexander Belopolsky :

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

--
assignee: d...@python
components: Documentation
messages: 121297
nosy: belopolsky, d...@python
priority: normal
severity: normal
stage: needs patch
status: open
title: Document the rules for "public names"
versions: Python 3.2

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com