For example, urlsplit:

>>> from urllib.parse import urlsplit
>>> help(urlsplit)
Help on function urlsplit in module urllib.parse:

urlsplit(url, scheme='', allow_fragments=True)
    Parse a URL into 5 components:
    <scheme>://<netloc>/<path>?<query>#<fragment>
    Return a 5-tuple: (scheme, netloc, path, query, fragment).
    Note that we don't break the components up in smaller bits
    (e.g. netloc is a single string) and we don't expand % escapes.


The current docstring does not describe the `scheme` or `allow_fragments` arguments.  Also, the note about not splitting netloc is misleading; the components of netloc (username, password, hostname, and port) are available as extra attributes of the returned SplitResult.

urlparse has similar issues; other functions could stand to be checked.

> Also, the note about not splitting netloc is misleading; the components > of netloc (username, password, hostname, and port) are available as >extra attributes of the returned SplitResult.

Also, the docs in urllib.parse.rst should also be updated to correct this misleading statement.

hello!

I can see that we might want to add documentation for splitting netloc, but I don't understand why we'd have scheme and netloc, but nothing for path and query. What are you suggesting we add for scheme/allow_fragements? 

Thanks!

>I don't understand why we'd have scheme and netloc, but nothing for path and query.

I'm not sure what you mean here; can you please clarify?

> What are you suggesting we add for scheme/allow_fragements?

Just a brief description of what effect the arguments actually have on the returned result.

I guess what I'm wondering is this: 

urlsplit(url, scheme='', allow_fragments=True)
    Parse a URL into 5 components:
    <scheme>://<netloc>/<path>?<query>#<fragment>
    Return a 5-tuple: (scheme, netloc, path, query, fragment).
    Note that we don't break the components up in smaller bits
    (e.g. netloc is a single string) and we don't expand % escapes.
(END)

We don't have details regarding anything, i.e scheme, netloc, path or query or fragments. So I was curious about why we would have more documentation around netloc and scheme and nothing about path and query

Should we be adding information for all(scheme, netloc, path, query, fragment) of them, including extra attributes of the returned SplitResult? 

p.s - newbie trying to contribute here

I see.  I don't think we need to describe each returned component in the docstring; they're some combination of self-explanatory, described in the reference docs, or just industry-standard terms that are easily defined from other sources.  I'm not suggesting to add anything to the docstring about the `scheme` return component, but rather the *scheme* argument (which is the default value for the `scheme` return component when it's not found in the *url*).  The subcomponents of netloc should be mentioned because the docstring currently gives the impression that the user has to parse them out for themselves, which is not true.

Off the top of my head, I'd suggest changing the `urlsplit` docstring to something like:

```
Parse *url* and return a SplitResult.

SplitResult is a named 5-tuple of the following components:
<scheme>://<netloc>/<path>?<query>#<fragment>

The ``username``, ``password``, ``hostname``, and ``port``
sub-components of ``netloc`` can also be accessed as
attributes of the SplitResult object.

The *scheme* argument provides the default value of the
``scheme`` component when no scheme is found in *url*.

If *allow_fragments* is False, no attempt is made to
separate the ``fragment`` component from the previous
component, which can be either ``path`` or ``query``.

Note that % escapes are not expanded.
```

got it - thanks for the detailed explanation! I'll go ahead and create a PR soon

Committed a PR: GH-16458

I've read all of the thread and changed the docstring to the latest suggestion by @zach.ware

Ido

Any update on this? Adding @Tal Einat on the PR

Hi Ido, there was a change requested by a core-dev, Zachary , on your PR.

>  Please have a look at PEP 257 for docstring formatting guidelines.

https://github.com/python/cpython/pull/16458/files#r353422155

Please let us know if that is addressed.

Hey Senthil,
Yes the PEP guides was fixed a while ago, also the new comment of adding the same change for the second function were taken care of.

New changeset c33bdbb20cf55b3a2aa7a91bd3d91fcb59796fad by idomic in branch 'master':
bpo-37970: update and improve urlparse and urlsplit doc-strings (GH-16458)
https://github.com/python/cpython/commit/c33bdbb20cf55b3a2aa7a91bd3d91fcb59796fad

Ido Michael's PR GH-16458, which I've just merged, addresses the issues brought up here regarding the doc-strings.

From the discussion it seems that the documentation of these functions should be updated as well. I'll leave this issue open until that's done as well.

Tal, I can also fix that so we can close this issue.
Are you talking about the Doc/library/urllib.parse.rst file?

Indeed.

Created PR, most of the documentation besides the func signature looked alright: GH-18631