Issue 23684: urlparse() documentation does not account for default scheme

The documentation for urlsplit() says:

'''
urlparse(urlstring, scheme='', allow_fragments=True)

. . .

If the scheme argument is specified, it gives the default addressing scheme, to be used only if the URL does not specify one. The default value for this argument is the empty string.
'''

However this contradicts the table of attributes, which gives:

Attribute: scheme, . . . Value if not present: empty string

Similarly for urlsplit(). Of course, the description of the “scheme” parameter is correct, and the table is only correct when no “scheme” parameter is given:

>>> urlparse("//example.net").scheme
''
>>> urlparse(b"//example.net").scheme
b''
>>> urlparse("//example.net", "http").scheme
'http'

This issue is split off another where I tried to sneak in a quick fix, but the wording probably needs more thought. Original change: <https://bugs.python.org/review/22852/patch/14176/52720#old-line-92>.

Maybe change it to this?

Value if not present: empty string or default scheme

+1 to the change, but I'd propose maybe "value of *scheme*" given the tables are inline with both urlsplit and urlparse docs?

Here is a patch changing the table entries to “*scheme* argument”. Hopefully this is fairly obvious and doesn’t sound like it defaults to itself.

I also made the descriptions of “scheme” and “allow_fragments” more specific, and added some unit tests, because there didn’t seem to be any exercising them.

LGTM. Added a minor question on Rietveld.

New changeset 368db4b1ced9 by Berker Peksag in branch '3.4':
Issue #23684: Clarify the return value of the scheme attribute of ParseResult and SplitResult objects.
https://hg.python.org/cpython/rev/368db4b1ced9

New changeset 68629ebe0fee by Berker Peksag in branch '3.5':
Issue #23684: Clarify the return value of the scheme attribute of ParseResult and SplitResult objects.
https://hg.python.org/cpython/rev/68629ebe0fee

New changeset 7846aadbd4f5 by Berker Peksag in branch 'default':
Issue #23684: Clarify the return value of the scheme attribute of ParseResult and SplitResult objects.
https://hg.python.org/cpython/rev/7846aadbd4f5

New changeset 7bf9e10fc32f by Berker Peksag in branch '2.7':
Issue #23684: Clarify the return value of the scheme attribute of ParseResult and SplitResult objects.
https://hg.python.org/cpython/rev/7bf9e10fc32f

Thanks Martin.

stage: commit review -> resolved

assignee: docs@python -> berker.peksag
stage: patch review -> commit review

components: + Tests
versions: + Python 2.7, Python 3.4, Python 3.5, Python 3.6
keywords: + patch
type: behavior
messages: + msg244531
stage: patch review