Add docstrings to fields of urllib.parse results

[serhiy-storchaka]

BPO	25822
Nosy	@rhettinger, @orsenthil, @berkerpeksag, @vadmium, @serhiy-storchaka
Files	iss_25822.patch: Fix for named tuple docstring. iss_25822_2.patch: Modified from previous review. iss_25822_3.patch iss_25822_4.patch: Added docstring for DefragResult.

^{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/orsenthil'
closed_at = <Date 2016-01-14.08:17:37.561>
created_at = <Date 2015-12-08.09:15:40.334>
labels = ['type-feature', 'library']
title = 'Add docstrings to fields of urllib.parse results'
updated_at = <Date 2016-01-15.05:29:35.891>
user = 'https://github.com/serhiy-storchaka'

bugs.python.org fields:

activity = <Date 2016-01-15.05:29:35.891>
actor = 'curioswati'
assignee = 'orsenthil'
closed = True
closed_date = <Date 2016-01-14.08:17:37.561>
closer = 'orsenthil'
components = ['Library (Lib)']
creation = <Date 2015-12-08.09:15:40.334>
creator = 'serhiy.storchaka'
dependencies = []
files = ['41283', '41290', '41300', '41456']
hgrepos = []
issue_num = 25822
keywords = ['patch']
message_count = 10.0
messages = ['256105', '256186', '256197', '256241', '256259', '256364', '257237', '258186', '258187', '258267']
nosy_count = 7.0
nosy_names = ['rhettinger', 'orsenthil', 'python-dev', 'berker.peksag', 'martin.panter', 'serhiy.storchaka', 'curioswati']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'patch review'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue25822'
versions = ['Python 3.6']

[serhiy-storchaka]

Results of urlsplit() and urlparse() functions in the urllib.parse module are named tuple with a number of fields. Since property docstrings are writable now (bpo-24064), we can provide docstrings for all these fields. See also bpo-24878.

[curioswati]

I can help with this. Should I propose the changes I am going to make before making them or just create the patch?

[curioswati]

Here is the patch, please review it. Do I need to write any test?

[berkerpeksag]

Thanks, Swati. I left a few comments on Rietveld: http://bugs.python.org/review/25822/

A test wouldn't hurt, but you can wait for further review comments to avoid updating tests each time you get a comment.

[vadmium]

[padding]
I left some comments.

I wonder if the doc strings are too specific when they mention “request”, “file”, “download”, “page”, etc. Maybe these could just be examples of what the fields are used for (e.g. “The hierarchical path, such as the path to a file to download”). Or maybe they could be changed to general terms, but this may be hard.

Also, some of them seem redundant. Does it really add anything to say the “query” field is “the query parameter”?

[rhettinger]

I wouldn't normally write a test for a docstring patch.

[serhiy-storchaka]

Could you please also add docstrings for _DefragResultBase?

I agree that there is no need to write tests.

[python-dev]

New changeset 7bfcb8b75ad9 by Senthil Kumaran in branch 'default':
Issue bpo-25822: Add docstrings to the fields of urllib.parse results.
https://hg.python.org/cpython/rev/7bfcb8b75ad9

[orsenthil]

Thank you, Swati.

I reviewed and committed your patch. I had to make some minor formatting changes while keeping an eye for the maintainability of the module and doc strings.

• Moved all the doc strings up to a single place just below the namespaces are declared.
• Followed pep-0257 conventions for doc strings.
• Tried DRY for parse result's sub-components.

Thanks for addressing the review comments from other developers.

[curioswati]

Thank you Senthil for the improvements, I'll try to make it better next time :)