[docs] [issue10434] Document the rules for "public names"

Tue Nov 16 17:29:44 CET 2010

Ron Adam <ron_adam at users.sourceforge.net> 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.