[Python-checkins] peps: Added PEP 224, Attribute Docstrings, assigned to MAL.
georg.brandl
python-checkins at python.org
Wed Mar 23 21:27:03 CET 2011
http://hg.python.org/peps/rev/c7d930a89453
changeset: 153:c7d930a89453
user: Barry Warsaw <barry at python.org>
date: Wed Aug 23 16:51:21 2000 +0000
summary:
Added PEP 224, Attribute Docstrings, assigned to MAL.
files:
pep-0000.txt | 2 +
pep-0224.txt | 150 +++++++++++++++++++++++++++++++++++++++
2 files changed, 152 insertions(+), 0 deletions(-)
diff --git a/pep-0000.txt b/pep-0000.txt
--- a/pep-0000.txt
+++ b/pep-0000.txt
@@ -48,6 +48,7 @@
SA 221 pep-0221.txt Import As Wouters
SD 222 pep-0222.txt Web Library Enhancements Kuchling
S 223 pep-0223.txt Change the Meaning of \x Escapes Peters
+ S 224 pep-0224.txt Attribute Docstrings Lemburg
Key
@@ -67,6 +68,7 @@
Drake, Fred fdrake at beopen.com
Hylton, Jeremy jeremy at beopen.com
Kuchling, Andrew akuchlin at mems-exchange.org
+ Lemburg, Marc-Andre mal at lemburg.com
McMillan, Gordon gmcm at hypernet.com
Peters, Tim tpeters at beopen.com
Prescod, Paul paul at prescod.net
diff --git a/pep-0224.txt b/pep-0224.txt
new file mode 100644
--- /dev/null
+++ b/pep-0224.txt
@@ -0,0 +1,150 @@
+PEP: 224
+Title: Attribute Docstrings
+Version: $Revision$
+Author: mal at lemburg.com (Marc-Andre Lemburg)
+Status: Draft
+Type: Standards Track
+Python-Version: 2.0
+Created: 23-Aug-2000
+Post-History:
+
+
+Introduction
+
+ This PEP describes the "attribute docstring" proposal for Python
+ 2.0. This PEP tracks the status and ownership of this feature.
+ It contains a description of the feature and outlines changes
+ necessary to support the feature. The CVS revision history of
+ this file contains the definitive historical record.
+
+
+Rationale
+
+ This PEP proposes a small addition to the way Python currently
+ handles docstrings embedded in Python code.
+
+ Python currently only handles the case of docstrings which appear
+ directly after a class definition, a function definition or as
+ first string literal in a module. The string literals are added
+ to the objects in question under the __doc__ attribute and are
+ from then on available for introspection tools which can extract
+ the contained information for help, debugging and documentation
+ purposes.
+
+ Docstrings appearing in locations other than the ones mentioned
+ are simply ignored and don't result in any code generation.
+
+ Here is an example:
+
+ class C:
+ "class C doc-string"
+
+ a = 1
+ "attribute C.a doc-string (1)"
+
+ b = 2
+ "attribute C.b doc-string (2)"
+
+ The docstrings (1) and (2) are currently being ignored by the
+ Python byte code compiler, but could obviously be put to good use
+ for documenting the named assignments that precede them.
+
+ This PEP proposes to also make use of these cases by proposing
+ semantics for adding their content to the objects in which they
+ appear under new generated attribute names.
+
+ The original idea behind this approach which also inspired the
+ above example was to enable inline documentation of class
+ attributes, which can currently only be documented in the class's
+ docstring or using comments which are not available for
+ introspection.
+
+
+Implementation
+
+ Docstrings are handled by the byte code compiler as expressions.
+ The current implementation special cases the few locations
+ mentioned above to make use of these expressions, but otherwise
+ ignores the strings completely.
+
+ To enable use of these docstrings for documenting named
+ assignments (which is the natural way of defining e.g. class
+ attributes), the compiler will have to keep track of the last
+ assigned name and then use this name to assign the content of the
+ docstring to an attribute of the containing object by means of
+ storing it in as a constant which is then added to the object's
+ namespace during object construction time.
+
+ In order to preserve features like inheritance and hiding of
+ Python's special attributes (ones with leading and trailing double
+ underscores), a special name mangling has to be applied which
+ uniquely identifies the docstring as belonging to the name
+ assignment and allows finding the docstring later on by inspecting
+ the namespace.
+
+ The following name mangling scheme achieves all of the above:
+
+ __doc__<attributename>__
+
+ To keep track of the last assigned name, the byte code compiler
+ stores this name in a variable of the compiling structure. This
+ variable defaults to NULL. When it sees a docstring, it then
+ checks the variable and uses the name as basis for the above name
+ mangling to produce an implicit assignment of the docstring to the
+ mangled name. It then resets the variable to NULL to avoid
+ duplicate assignments.
+
+ If the variable does not point to a name (i.e. is NULL), no
+ assignments are made. These will continue to be ignored like
+ before. All classical docstrings fall under this case, so no
+ duplicate assignments are done.
+
+ In the above example this would result in the following new class
+ attributes to be created:
+
+ C.__doc__a__ == "attribute C.a doc-string (1)"
+ C.__doc__b__ == "attribute C.b doc-string (2)"
+
+
+Caveats of the Implementation
+
+ Since the implementation does not reset the compiling structure
+ variable when processing a non-expression, e.g. a function
+ definition, the last assigned name remains active until either the
+ next assignment or the next occurrence of a docstring.
+
+ This can lead to cases where the docstring and assignment may be
+ separated by other expressions:
+
+ class C:
+ "C doc string"
+
+ b = 2
+
+ def x(self):
+ "C.x doc string"
+ y = 3
+ return 1
+
+ "b's doc string"
+
+ Since the definition of method "x" currently does not reset the
+ used assignment name variable, it is still valid when the compiler
+ reaches [TBD: please finish your thought!]
+
+
+Copyright
+
+ This document has been placed in the Public Domain.
+
+
+References
+
+ [1] http://sourceforge.net/patch/?func=detailpatch&patch_id=XXX&group_id=5470
+
+
+
+Local Variables:
+mode: indented-text
+indent-tabs-mode: nil
+End:
--
Repository URL: http://hg.python.org/peps
More information about the Python-checkins
mailing list