[issue15865] reflect bare star * in function signature documentation
New submission from Chris Jerdonek: This issue is to make sure that the bare * in the function signatures of pure Python functions is properly reflected in the documentation. This will bring the signatures in the documentation closer to the signatures that we have in the Python code -- a goal articulated by Ezio in a comment to issue 15831. For example, configparser.RawConfigParser() has this function signature: def __init__(self, defaults=None, dict_type=_default_dict, allow_no_value=False, *, delimiters=('=', ':'), comment_prefixes=('#', ';'), inline_comment_prefixes=None, strict=True, empty_lines_in_values=True, default_section=DEFAULTSECT, interpolation=_UNSET): But its documentation has no *: class configparser.RawConfigParser(defaults=None, dict_type=collections.OrderedDict, allow_no_value=False, delimiters=('=', ':'), comment_prefixes=('#', ';'), inline_comment_prefixes=None, strict=True, empty_lines_in_values=True, default_section=configaparser.DEFAULTSECT, interpolation=None) (from http://docs.python.org/dev/library/configparser.html#configparser.RawConfigP... )
From a search of the code, there are about 60 occurrences of a bare * in the signature of a pure Python function (not all of which will need to be updated).
----------
assignee: docs@python
components: Documentation
keywords: easy
messages: 169850
nosy: cjerdonek, docs@python, ezio.melotti
priority: normal
severity: normal
status: open
title: reflect bare star * in function signature documentation
type: behavior
versions: Python 3.3
_______________________________________
Python tracker
Changes by Ezio Melotti
Éric Araujo added the comment:
So is the root problem that Sphinx does not handle keyword-only arguments?
----------
versions: +Python 3.2
_______________________________________
Python tracker
Chris Jerdonek added the comment:
So is the root problem that Sphinx does not handle keyword-only arguments?
I don't think so. Sphinx renders the * just fine. It's just that in some of the reST files, the * was left out.
----------
_______________________________________
Python tracker
Chris Jerdonek added the comment:
Actually, it looks like configparser is the *only* file with missing single *'s. :) However, I did find a few other typos in the process of checking those signatures in the other files.
Patch attached.
----------
keywords: +patch
Added file: http://bugs.python.org/file27124/issue-15865-1.patch
_______________________________________
Python tracker
Changes by Chris Jerdonek
Terry J. Reedy added the comment:
By looking at x.py, I confirmed that the added stars are correct.
Also, the correction of 'header' to 'hdr' is correct.
However, for threading.py in 3.3.0, I see
class Thread:
...
def __init__(self, group=None, target=None, name=None,
args=(), kwargs=None, *, daemon=None):
whereas the patch and existing .rst
-.. class:: Thread(group=None, target=None, name=None, args=(), kwargs={},
+.. class:: Thread(group=None, target=None, name=None, args=(), kwargs={}, \
verbose=None, *, daemon=None)
has an extra 'verbose=None' that should be removed there and in any explanatory text that follows.
(The fact that we found 2 doc signature errors other than the 4 missing *s suggests that we need a tool to systematically compare doc signature to code signature.)
----------
nosy: +terry.reedy
_______________________________________
Python tracker
Chris Jerdonek added the comment: Thanks, Terry. If anyone is curious, it looks like the verbose keyword argument was added to the docs (and to threading.py) in revision f71acc4b2341, and then subsequently removed (but not from the docs) in revision 8ec51b2e57c2.
(The fact that we found 2 doc signature errors other than the 4 missing *s suggests that we need a tool to systematically compare doc signature to code signature.)
Out of curiosity, can anyone summarize what our existing tooling might already be able to do in this regard (e.g. Sphinx or pydoc)?
I will update the patch.
----------
_______________________________________
Python tracker
Chris Jerdonek added the comment:
Here is an updated patch that incorporates Terry's suggestion.
----------
Added file: http://bugs.python.org/file27145/issue-15865-2.patch
_______________________________________
Python tracker
Roundup Robot added the comment:
New changeset a30b3915228b by Ezio Melotti in branch '3.2':
#15865: add "*" in the signature to document keyword-only args in the docs. Patch by Chris Jerdonek.
http://hg.python.org/cpython/rev/a30b3915228b
New changeset 694c725f241a by Ezio Melotti in branch 'default':
#15865: merge with 3.2.
http://hg.python.org/cpython/rev/694c725f241a
----------
nosy: +python-dev
_______________________________________
Python tracker
Ezio Melotti added the comment:
Fixed, thanks for the patch!
----------
assignee: docs@python -> ezio.melotti
resolution: -> fixed
stage: patch review -> committed/rejected
status: open -> closed
_______________________________________
Python tracker
participants (5)
-
Chris Jerdonek -
Ezio Melotti
-
Roundup Robot
-
Terry J. Reedy
-
Éric Araujo