Argument Clinic: functions with valid sig but no docstring have no __text_signature__

[zware]

BPO	20586
Nosy	@larryhastings, @zware
Files	issue20586.diff: Rietveld-friendly patch. issue20586.v2.diff issue20586.v3.diff

^{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 = 'https://github.com/zware'
closed_at = <Date 2015-04-13.23:24:09.608>
created_at = <Date 2014-02-10.20:28:26.115>
labels = ['type-bug', 'expert-argument-clinic']
title = 'Argument Clinic: functions with valid sig but no docstring have no __text_signature__'
updated_at = <Date 2015-04-13.23:24:09.606>
user = 'https://github.com/zware'

bugs.python.org fields:

activity = <Date 2015-04-13.23:24:09.606>
actor = 'zach.ware'
assignee = 'zach.ware'
closed = True
closed_date = <Date 2015-04-13.23:24:09.608>
closer = 'zach.ware'
components = ['Demos and Tools', 'Argument Clinic']
creation = <Date 2014-02-10.20:28:26.115>
creator = 'zach.ware'
dependencies = []
files = ['36143', '36275', '38969']
hgrepos = []
issue_num = 20586
keywords = ['patch']
message_count = 8.0
messages = ['210864', '210869', '224777', '224881', '240784', '240802', '240805', '240806']
nosy_count = 3.0
nosy_names = ['larry', 'python-dev', 'zach.ware']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue20586'
versions = ['Python 3.5']

[zware]

Builtins with a valid signature embedded in the docstring, but with no other docstring content are not picked up by the __text_signature__ getter because the docstring ends with ")\n--" rather than ")\n--\n\n". The attached patch adjusts clinic.CLanguage.docstring_for_c_string to make sure that the rendered docstring ends in "--\n\n" rather than "--".

The result is a correct __text_signature__ and a __doc__ of ''.

[zware]

Forgot to mention, there are no current examples of this checked in. winreg.HKEYType has a couple of methods with no docstring (enter and __exit__), and _winapi has several docstring-less functions, though.

[larryhastings]

This looks reasonable to me. However I'd also change _PyType_GetDocFromInternalDoc() so that it also returns None if the first byte of the doc is \0.

[zware]

Something about like this? Note that this does change the behavior in the case where the whole docstring is empty but provided (such as when WITH_DOC_STRINGS == 0; see the changed line in test_capi).

[zware]

Here's an updated patch for clean application. Larry, could you give this a look?

[larryhastings]

LGTM

[python-dev]

New changeset e75fd221a53e by Zachary Ware in branch 'default':
Issue bpo-20586: Argument Clinic now ensures signatures on functions without docstrings.
https://hg.python.org/cpython/rev/e75fd221a53e

[zware]

Thanks Larry