python · JelleZijlstra · Jul 13, 2024 · Jun 13, 2024 · Jun 13, 2024 · Jun 13, 2024
diff --git a/Doc/faq/programming.rst b/Doc/faq/programming.rst
@@ -1739,7 +1739,8 @@ Variable names with double leading underscores are "mangled" to provide a simple
 but effective way to define class private variables.  Any identifier of the form
 ``__spam`` (at least two leading underscores, at most one trailing underscore)
 is textually replaced with ``_classname__spam``, where ``classname`` is the
-current class name with any leading underscores stripped.
+current class name with any leading underscores stripped
+(see :ref:`here <private-name-mangling>` for details and special cases).
 
 This doesn't guarantee privacy: an outside user can still deliberately access
 the "_classname__spam" attribute, and private values are visible in the object's

@@ -83,17 +83,27 @@ exception.
    pair: name; mangling
    pair: private; names
 
-**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 :dfn:`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, with leading underscores
-removed and a single underscore inserted, in front of the 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.
+.. rubric:: 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 :dfn:`private name` of that class.
+
+More precisely, private names are transformed to a longer form before code is
+generated for them.  The transformation rule is defined as follows:
+
+- If the class name consists only of underscores, no transformation is done,
+  e.g., the identifier ``__spam`` occurring in a class named ``_`` or ``__``
+  is left as is.
+
+- Otherwise, the transformation inserts the class name, with leading
+  underscores removed and a single underscore inserted, in front of
+  the identifier, e.g., the identifier ``__spam`` occurring in a class
+  named ``Ham``, ``_Ham`` or ``__Ham`` is transformed to ``_Ham__spam``.
+
+The transformation is independent of the syntactical context in which the
+identifier is used.  Nonetheless, if the transformed name is extremely long
+(longer than 255 characters), implementation-defined truncation may happen.
 
 
 .. _atom-literals:

diff --git a/Doc/tutorial/classes.rst b/Doc/tutorial/classes.rst
@@ -684,7 +684,7 @@ clashes of names with names defined by subclasses), there is limited support for
 such a mechanism, called :dfn:`name mangling`.  Any identifier of the form
 ``__spam`` (at least two leading underscores, at most one trailing underscore)
 is textually replaced with ``_classname__spam``, where ``classname`` is the
-current class name with leading underscore(s) stripped.  This mangling is done
+current class name with leading underscore(s) stripped. [#]_ This mangling is done
 without regard to the syntactic position of the identifier, as long as it
 occurs within the definition of a class.
 
@@ -930,3 +930,5 @@ Examples::
    namespace; the name :attr:`~object.__dict__` is an attribute but not a global name.
    Obviously, using this violates the abstraction of namespace implementation, and
    should be restricted to things like post-mortem debuggers.
+
+.. [#] See :ref:`here <private-name-mangling>` for details and special cases.