Repository navigation
Enhance Cmd support for docstrings and document it. #52161
Description
| BPO | 7913 |
|---|---|
| Nosy | @merwok, @bitdancer, @durban, @serhiy-storchaka |
| Files |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
assignee = None
closed_at = None
created_at = <Date 2010-02-11.18:57:20.772>
labels = ['3.7', 'type-feature', 'library']
title = 'Enhance Cmd support for docstrings and document it.'
updated_at = <Date 2017-03-26.10:12:56.047>
user = 'https://github.com/bitdancer'bugs.python.org fields:
activity = <Date 2017-03-26.10:12:56.047>
actor = 'serhiy.storchaka'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = ['Library (Lib)']
creation = <Date 2010-02-11.18:57:20.772>
creator = 'r.david.murray'
dependencies = []
files = ['16213']
hgrepos = []
issue_num = 7913
keywords = ['patch']
message_count = 7.0
messages = ['99233', '101837', '101843', '101844', '131485', '131502', '290520']
nosy_count = 4.0
nosy_names = ['eric.araujo', 'r.david.murray', 'daniel.urban', 'serhiy.storchaka']
pr_nums = []
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue7913'
versions = ['Python 3.7']
Activity
bitdancer commentedon Feb 11, 2010
Cmd currently has undocumented support for using the docstrings of 'do_' methods as the documentation for those methods. This is a very convenient facility, except that it leads to documentation being printed with a lot of leading whitespace.
I propose to enhance the docstring support to strip the leading whitespace from the docstring, and to document this facility. The proposed stripping algorithm is to strip a number of characters equal to the whitespace on the first non-blank line of the docstring. This means that existing docstrings, which will typically start right after the first """, will be displayed as they were previously, but that a docstring can be formatted by starting the documentation on a new line after the """, and whitespace will be properly stripped.
Patch attached with test and documentation update.
merwok commentedon Mar 27, 2010
Hello
This would be a nice improvement. This weakness is indeed mentioned on PyMotW.
How about using textwrap.dedent?
Regards
bitdancer commentedon Mar 27, 2010
The problem with using textwrap is that you'd have to identify paragraph boundaries and example code to avoid messing up the meaning of the doc string. At that point, one might as well go for full ReST markup parsing, and I don't think that is appropriate :)
merwok commentedon Mar 27, 2010
I thought dedent just worked. Can you provide a simple example to help
me understand this problem?
Does this help:
http://code.activestate.com/recipes/358228-extend-textwraptextwrapper-to-handle-multiple-para/
Regards
durban commentedon Mar 20, 2011
inspect.cleandoc (which is also used by inspect.getdoc and pydoc.getdoc) seems to do a similar thing. Maybe that could be used for this?
merwok commentedon Mar 20, 2011
You can apply the patch (which includes tests) and edit the code of cmd.py to use cleandoc.
serhiy-storchaka commentedon Mar 26, 2017
Can you create a pull request David?
fipachu commentedon Nov 17, 2023
ping
gh-52161: Enhance Cmd support for docstrings (#110987)
pythongh-52161: Enhance Cmd support for docstrings (python#110987)
pythongh-52161: Enhance Cmd support for docstrings (python#110987)
pythongh-52161: Enhance Cmd support for docstrings (python#110987)