Path: csiph.com!usenet.pasdenom.info!dedibox.gegeweb.org!gegeweb.eu!nntpfeed.proxad.net!proxad.net!feeder1-2.proxad.net!usenet-fr.net!nerim.net!novso.com!newsfeed.xs4all.nl!newsfeed6.news.xs4all.nl!xs4all!newsgate.cistron.nl!newsgate.news.xs4all.nl!post.news.xs4all.nl!not-for-mail
Return-Path: <python-python-list@m.gmane.org>
X-Original-To: python-list@python.org
Delivered-To: python-list@mail.python.org
X-Spam-Status: OK 0.000
X-Spam-Evidence: '*H*': 1.00; '*S*': 0.00; 'algorithm': 0.03; 'ideally': 0.04; 'formatting': 0.07; 'parsing': 0.07; 'python': 0.09; 'docstrings': 0.09; 'parsed': 0.09; 'pep': 0.09; 'received:80.91': 0.09; 'received:80.91.229': 0.09; 'received:gmane.org': 0.09; 'received:list': 0.09; 'splitting': 0.09; 'subject:parsing': 0.09; 'textwrap': 0.09; 'url:peps': 0.09; 'component': 0.15; 'description)': 0.16; 'docstring': 0.16; 'literal.': 0.16; 'parts,': 0.16; 'received:80.91.229.3': 0.16; 'received:plane.gmane.org': 0.16; 'string': 0.17; 'library,': 0.17; 'url:dev': 0.17; 'code,': 0.18; 'all,': 0.21; 'import': 0.21; 'example': 0.23; 'seems': 0.23; 'header:User-Agent:1': 0.26; 'common': 0.26; 'done.': 0.27; '(as': 0.27; 'convention': 0.27; 'header:X-Complaints-To:1': 0.28; 'summary': 0.29; 'url:python': 0.32; 'structure': 0.32; 'goes': 0.33; 'says': 0.33; 'to:addr :python-list': 0.33; "can't": 0.34; 'described': 0.35; 'received:org': 0.36; 'but': 0.36; 'url:org': 0.36; 'should': 0.36; 'description': 0.39; 'to:addr:python.org': 0.39; 'where': 0.40; 'header:Received:5': 0.40; 'therefore': 0.65; 'skip:\xe2 10': 0.66; '8bit%:46': 0.71; '257': 0.84; 'write:': 0.91
X-Injected-Via-Gmane: http://gmane.org/
To: python-list@python.org
From: Ben Finney <ben+python@benfinney.id.au>
Subject: Docstring parsing and formatting
Date: Tue, 18 Sep 2012 12:03:09 +1000
Mime-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 8bit
X-Gmane-NNTP-Posting-Host: rasputin.madmonks.org
X-Public-Key-ID: 0xBD41714B
X-Public-Key-Fingerprint: 9CFE 12B0 791A 4267 887F  520C B7AC 2E51 BD41 714B
X-Public-Key-URL: http://www.benfinney.id.au/contact/bfinney-gpg.asc
X-Post-From: Ben Finney <bignose+hates-spam@benfinney.id.au>
User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/23.4 (gnu/linux)
Cancel-Lock: sha1:v34nKO2cK/wNp7RHo6aS7BAUgJM=
X-BeenThere: python-list@python.org
X-Mailman-Version: 2.1.15
Precedence: list
List-Id: General discussion list for the Python programming language <python-list.python.org>
List-Unsubscribe: <http://mail.python.org/mailman/options/python-list>, <mailto:python-list-request@python.org?subject=unsubscribe>
List-Archive: <http://mail.python.org/pipermail/python-list/>
List-Post: <mailto:python-list@python.org>
List-Help: <mailto:python-list-request@python.org?subject=help>
List-Subscribe: <http://mail.python.org/mailman/listinfo/python-list>, <mailto:python-list-request@python.org?subject=subscribe>
Newsgroups: comp.lang.python
Message-ID: <mailman.853.1347933804.27098.python-list@python.org>
Lines: 29
NNTP-Posting-Host: 2001:888:2000:d::a6
X-Trace: 1347933804 news.xs4all.nl 6850 [2001:888:2000:d::a6]:52069
X-Complaints-To: abuse@xs4all.nl
Xref: csiph.com comp.lang.python:29403

Howdy all,

Where can I find a standard implementation of the docstring parsing and
splitting algorithm from PEP 257?


PEP 257 describes a convention of structure and formatting for
docstrings <URL: http://www.python.org/dev/peps/pep-0257/>. Docstrings
that conform to this convention can therefore be parsed into their
component parts, and re-formatted.

The PEP describes <URL: http://www.python.org/dev/peps/pep-0257/#id20>
and algorithm for parsing the docstring as found in the string literal.
It says “Docstring processing tools will …” and goes on to describe, in
prose and example code, how the parsing should be done.

Where is a common implementation of that algorithm? It seems that it
should be in the Python standard library, but I can't find it.

Ideally what I want is to be able to write:

    import textwrap

    (summary, description) = textwrap.pep257_parse(foo.__doc__)

and have ‘summary’ as the docstring's summary line, and ‘description’ as
the docstring's description (as described in <URL:
http://www.python.org/dev/peps/pep-0257/#id19>).