[Python-Dev] Attribute Docstring PEP (2.0 Release Plans)

2000年8月23日 17:38:31 +0200

This is a multi-part message in MIME format.
--------------E566E4B4F5AFC0BF9ECC11DD
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit
"Fred L. Drake, Jr." wrote:
>> M.-A. Lemburg writes:
> > Does this mean I can still splip in that minor patch to allow
> > for attribute doc-strings in 2.0b1 provided I write up a short
> > PEP really fast ;-) ?
>> Write a PEP if you like; I think I'd really like to look at this
> before you change any code, and I've not had a chance to read your
> messages about this yet. This is *awefully* late to be making a
> change that hasn't been substantially hashed out and reviewed, and I'm
> under the impression that this is pretty new (the past week or so).

FYI, I've attached the pre-PEP below (I also sent it to Barry
for review).
This PEP is indeed very new, but AFAIK it doesn't harm any existing
code and also doesn't add much code complexity to achieve what it's
doing (see the patch).
> > BTW, what the new standard on releasing ideas to dev public ?
> > I know I'll have to write a PEP, but where should I put the
> > patch ? Into the SF patch manager or on a separate page on the
> > Internet ?
>> Patches should still go to the SF patch manager.

Here it is:
http://sourceforge.net/patch/?func=detailpatch&patch_id=101264&group_id=5470
-- 
Marc-Andre Lemburg
______________________________________________________________________
Business: http://www.lemburg.com/
Python Pages: http://www.lemburg.com/python/
--------------E566E4B4F5AFC0BF9ECC11DD
Content-Type: text/plain; charset=us-ascii;
 name="pep-0224.txt"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline;
 filename="pep-0224.txt"
PEP: 224
Title: Attribute Docstrings
Version: $Revision: 1.0 $
Owner: mal@lemburg.com (Marc-Andre Lemburg)
Python-Version: 2.0
Status: Draft
Created: 23-Aug-2000
Type: Standards Track
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. 
 Until now, Python 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 introspecition tools which can extract the
 contained information for help, debugging and documentation
 purposes.
 Docstrings appearing in other locations as 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 preceed 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'
 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 inheritence 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)"
 A patch to the current CVS version of Python 2.0 which implements
 the above is available on SourceForge at [1].
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 

Copyright
 This document has been placed in the Public Domain.
References
 [1]
http://sourceforge.net/patch/?func=detailpatch&patch_id=101264&group_id=5470

Local Variables:
mode: indented-text
indent-tabs-mode: nil
End:
--------------E566E4B4F5AFC0BF9ECC11DD--