[issue37970] urllib.parse docstrings incomplete

[Ido Michael]

Ido Michael  added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37970] urllib.parse docstrings incomplete

[Ido Michael]

Change by Ido Michael :


--
pull_requests: +17997
pull_request: https://github.com/python/cpython/pull/18631

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37970] urllib.parse docstrings incomplete

[Tal Einat]

Tal Einat  added the comment:

Indeed.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37970] urllib.parse docstrings incomplete

[Ido Michael]

Ido Michael  added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37970] urllib.parse docstrings incomplete

[Tal Einat]

Tal Einat  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37970] urllib.parse docstrings incomplete

[Tal Einat]

Tal Einat  added the comment:


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


--
nosy: +taleinat

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37970] urllib.parse docstrings incomplete

[Ido Michael]

Ido Michael  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37970] urllib.parse docstrings incomplete

[Senthil Kumaran]

Senthil Kumaran  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37970] urllib.parse docstrings incomplete

[Ido Michael]

Ido Michael  added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37970] urllib.parse docstrings incomplete

[Ido Michael]

Ido Michael  added the comment:

Committed a PR: GH-16458

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

Ido

--
nosy: +Ido Michael

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37970] urllib.parse docstrings incomplete

[Ido Michael]

Change by Ido Michael :


--
keywords: +patch
pull_requests: +16039
stage: needs patch -> patch review
pull_request: https://github.com/python/cpython/pull/16458

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37970] urllib.parse docstrings incomplete

[sushma]

sushma  added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37970] urllib.parse docstrings incomplete

[Zachary Ware]

Zachary Ware  added the comment:

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:
:///?#

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.
```

--
nosy: +orsenthil

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37970] urllib.parse docstrings incomplete

[sushma]

sushma  added the comment:

I guess what I'm wondering is this: 

urlsplit(url, scheme='', allow_fragments=True)
Parse a URL into 5 components:
:///?#
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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37970] urllib.parse docstrings incomplete

[Zachary Ware]

Zachary Ware  added the comment:

>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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37970] urllib.parse docstrings incomplete

[sushma]

sushma  added the comment:

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!

--
nosy: +syadlapalli

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37970] urllib.parse docstrings incomplete

[Joannah Nanjekye]

Joannah Nanjekye  added the comment:

> 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.

--
nosy: +nanjekyejoannah

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37970] urllib.parse docstrings incomplete

[Zachary Ware]

New submission from Zachary Ware :

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:
:///?#
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.

--
assignee: docs@python
components: Documentation, Library (Lib)
keywords: newcomer friendly
messages: 350668
nosy: docs@python, zach.ware
priority: normal
severity: normal
stage: needs patch
status: open
title: urllib.parse docstrings incomplete
versions: Python 3.7, Python 3.8, Python 3.9

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com