[Python-checkins] python/nondist/peps pep-0257.txt,1.7,1.8
goodger@users.sourceforge.net
goodger@users.sourceforge.net
Fri, 29 Nov 2002 17:49:40 -0800
- Previous message: [Python-checkins] python/dist/src/Mac/Lib EasyDialogs.py,1.39,1.40 FrameWork.py,1.53,1.54 PixMapWrapper.py,1.3,1.4 bgenlocations.py,1.1,1.2
- Next message: [Python-checkins] python/nondist/peps pep-0291.txt,1.2,1.3
- Messages sorted by:
[ date ]
[ thread ]
[ subject ]
[ author ]
Update of /cvsroot/python/python/nondist/peps
In directory sc8-pr-cvs1:/tmp/cvs-serv17981/python/nondist/peps
Modified Files:
pep-0257.txt
Log Message:
Added "Handling Docstring Indentation" section.
Index: pep-0257.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/peps/pep-0257.txt,v
retrieving revision 1.7
retrieving revision 1.8
diff -C2 -d -r1.7 -r1.8
*** pep-0257.txt 28 Nov 2002 03:59:50 -0000 1.7
--- pep-0257.txt 30 Nov 2002 01:49:37 -0000 1.8
***************
*** 137,149 ****
tools; it is important that it fits on one line and is separated from
the rest of the docstring by a blank line. The summary line may be on
! the same line as the opening quotes or on the next line.
!
! The entire docstring is indented the same as the quotes at its first
! line (see example below). Docstring processing tools will strip a
! uniform amount of indentation from the second and further lines of the
! docstring, equal to the minimum indentation of all non-blank lines
! after the first line of the docstring. Relative indentation of later
! lines in the docstring is retained. Any indentation on the first line
! of the docstring (i.e., before the first newline) is removed.
Insert a blank line before and after all docstrings (one-line or
--- 137,143 ----
tools; it is important that it fits on one line and is separated from
the rest of the docstring by a blank line. The summary line may be on
! the same line as the opening quotes or on the next line. The entire
! docstring is indented the same as the quotes at its first line (see
! example below).
Insert a blank line before and after all docstrings (one-line or
***************
*** 217,220 ****
--- 211,284 ----
the closing quotes on a line by themselves. This way, Emacs'
``fill-paragraph`` command can be used on it.
+
+
+ Handling Docstring Indentation
+ ------------------------------
+
+ Docstring processing tools will strip a uniform amount of indentation
+ from the second and further lines of the docstring, equal to the
+ minimum indentation of all non-blank lines after the first line. Any
+ indentation in the first line of the docstring (i.e., up to the first
+ newline) is insignificant and removed. Relative indentation of later
+ lines in the docstring is retained. Blank lines should be removed
+ from the beginning and end of the docstring.
+
+ Since code is much more precise than words, here is an implementation
+ of the algorithm::
+
+ def trim(docstring):
+ if not docstring:
+ return ''
+ # Convert tabs to spaces (following the normal Python rules)
+ # and split into a list of lines:
+ lines = docstring.expandtabs().splitlines()
+ # Determine minimum indentation (first line doesn't count):
+ indent = sys.maxint
+ for line in lines[1:]:
+ stripped = line.lstrip()
+ if stripped:
+ indent = min(indent, len(line) - len(stripped))
+ # Remove indentation (first line is special):
+ trimmed = [lines[0].strip()]
+ if indent < sys.maxint:
+ for line in lines[1:]:
+ trimmed.append(line[indent:].rstrip())
+ # Strip off trailing and leading blank lines:
+ while trimmed and not trimmed[-1]:
+ trimmed.pop()
+ while trimmed and not trimmed[0]:
+ trimmed.pop(0)
+ # Return a single string:
+ return '\n'.join(trimmed)
+
+ The docstring in this example contains two newline characters and is
+ therefore 3 lines long. The first and last lines are blank::
+
+ def foo():
+ """
+ This is the second line of the docstring.
+ """
+
+ To illustrate::
+
+ >>> print repr(foo.__doc__)
+ '\n This is the second line of the docstring.\n '
+ >>> foo.__doc__.splitlines()
+ ['', ' This is the second line of the docstring.', ' ']
+ >>> trim(foo.__doc__)
+ 'This is the second line of the docstring.'
+
+ Once trimmed, these docstrings are equivalent::
+
+ def foo():
+ """A multi-line
+ docstring.
+ """
+
+ def bar():
+ """
+ A multi-line
+ docstring.
+ """
- Previous message: [Python-checkins] python/dist/src/Mac/Lib EasyDialogs.py,1.39,1.40 FrameWork.py,1.53,1.54 PixMapWrapper.py,1.3,1.4 bgenlocations.py,1.1,1.2
- Next message: [Python-checkins] python/nondist/peps pep-0291.txt,1.2,1.3
- Messages sorted by:
[ date ]
[ thread ]
[ subject ]
[ author ]