[Python-checkins] peps: Settle on __qualname__ since __qname__ is non-obvious for some people.

[antoine.pitrou]

http://hg.python.org/peps/rev/ae222922450a
changeset:   3995:ae222922450a
user:        Antoine Pitrou <solipsis at pitrou.net>
date:        Fri Nov 18 20:50:49 2011 +0100
summary:
  Settle on __qualname__ since __qname__ is non-obvious for some people.

files:
  pep-3155.txt |  40 +++++++++++++++++++++++++++++-----------
  1 files changed, 29 insertions(+), 11 deletions(-)


diff --git a/pep-3155.txt b/pep-3155.txt
--- a/pep-3155.txt
+++ b/pep-3155.txt
@@ -59,16 +59,16 @@
 Proposal
 ========
 
-This PEP proposes the addition of a ``__qname__`` attribute to
+This PEP proposes the addition of a ``__qualname__`` attribute to
 functions and classes.  For top-level functions and classes, the
-``__qname__`` attribute is equal to the ``__name__`` attribute.  For
-nested classed, methods, and nested functions, the ``__qname__``
+``__qualname__`` attribute is equal to the ``__name__`` attribute.  For
+nested classed, methods, and nested functions, the ``__qualname__``
 attribute contains a dotted path leading to the object from the module
 top-level.  A function's local namespace is represented in that dotted
 path by a component named ``<locals>``.
 
 The repr() and str() of functions and classes is modified to use
-``__qname__`` rather than ``__name__``.
+``__qualname__`` rather than ``__name__``.
 
 Example with nested classes
 ---------------------------
@@ -78,13 +78,13 @@
 ...   class D:
 ...     def g(): pass
 ...
->>> C.__qname__
+>>> C.__qualname__
 'C'
->>> C.f.__qname__
+>>> C.f.__qualname__
 'C.f'
->>> C.D.__qname__
+>>> C.D.__qualname__
 'C.D'
->>> C.D.g.__qname__
+>>> C.D.g.__qualname__
 'C.D.g'
 
 Example with nested functions
@@ -94,9 +94,9 @@
 ...   def g(): pass
 ...   return g
 ...
->>> f.__qname__
+>>> f.__qualname__
 'f'
->>> f().__qname__
+>>> f().__qualname__
 'f.<locals>.g'
 
 
@@ -108,16 +108,34 @@
 namespace is not available from the outside.  It will still be more
 helpful to the human reader than the bare ``__name__``.
 
-As the ``__name__`` attribute, the ``__qname__`` attribute is computed
+As the ``__name__`` attribute, the ``__qualname__`` attribute is computed
 statically and it will not automatically follow rebinding.
 
 
+Naming choice
+=============
+
+"Qualified name" is the best approximation, as a short phrase, of what the
+additional attribute is about.  It is not a "full name" or "fully qualified
+name" since it (deliberately) does not include the module name.  Calling
+it a "path" would risk confusion with filesystem paths and the ``__file__``
+attribute.
+
+The first proposal for the attribute name was to call it ``__qname__`` but
+many people (who are not aware of previous use of such jargon in e.g. the
+XML specification [2]_) found it obscure and non-obvious, which is why the
+slightly less short and more explicit ``__qualname__`` was finally chosen.
+
+
 References
 ==========
 
 .. [1] "pickle should support methods":
    http://bugs.python.org/issue9276
 
+.. [2] "QName" entry in Wikipedia:
+   http://en.wikipedia.org/wiki/QName
+
 
 Copyright
 =========

-- 
Repository URL: http://hg.python.org/peps