classification
Title: Document that urllib.parse.{Defrag,Split,Parse}Result are namedtuples
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.8, Python 3.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: lisroach Nosy List: Allen Li, cheryl.sabella, docs@python, eric.araujo, fdrake, lisroach, serhiy.storchaka, vapier
Priority: normal Keywords: easy, patch

Created on 2017-10-19 18:54 by Allen Li, last changed 2019-03-24 22:07 by cheryl.sabella. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 4434 merged lisroach, 2017-11-17 06:06
PR 12528 merged miss-islington, 2019-03-24 21:50
Messages (9)
msg304637 - (view) Author: Allen Li (Allen Li) Date: 2017-10-19 18:54
It would be useful to document that urllib.parse.{Defrag,Split,Parse}Result are namedtuples, and make that API officially public if it was not otherwise.

These classes are implemented as namedtuples in Python 2 and 3, and I am not aware of a reason that that would need to change in the future.

In particular, the namedtuple _replace() method is very useful for modifying parts of a URL, a common use case.

 u = urllib.parse.urlsplit(some_url)
 u = u._replace(netloc=other_netloc)
 urllib.parse.urlunsplit(u)

 # Alternatives not depending on namedtuple API
 parts = list(u)
 parts[1] = other_netloc  # Using a magic index
 urllib.parse.urlunsplit(u)

 u = urllib.parse.SplitResult(  # Very ugly
     scheme=u.scheme,
     netloc=other_netloc,
     path=u.path,
     query=u.query,
     fragment=u.fragment)
msg304638 - (view) Author: Mike Frysinger (vapier) Date: 2017-10-19 19:24
specifically, the docs for these classes:
https://docs.python.org/2/library/urlparse.html#results-of-urlparse-and-urlsplit
https://docs.python.org/3/library/urllib.parse.html#urlparse-result-object

> The result objects from the urlparse() and urlsplit() functions are subclasses
> of the tuple type. These subclasses add the attributes described in those
> functions, as well as provide an additional method:
> ...
> class urlparse.SplitResult(scheme, netloc, path, query, fragment)
>   Concrete class for urlsplit() results.

changing "subclasses of the tuple type" to "subclasses of collections.namedtuples" would be great.  also adding hints to use _replace to update values would be great :).
msg304832 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2017-10-23 19:05
collections.namedtuples is not a class.
msg304833 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2017-10-23 19:08
I suggest using :term:`named tuple` for the link (+ an example of using _replace as Mike said)
msg338645 - (view) Author: Fred Drake (fdrake) (Python committer) Date: 2019-03-23 05:53
Unfortunately, when the implementation was migrated to use collections.namedtuple (a benefit), the _replace method wasn't extended to support the additional computed addresses for these types.

That would really be useful.
msg338646 - (view) Author: Fred Drake (fdrake) (Python committer) Date: 2019-03-23 05:59
To clarify: I'm not suggesting that an API expansion should be considered as part of this issue.
msg338756 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2019-03-24 21:28
New changeset 13c1f72cd1d91fdc2654f2f57356b2eacb75f164 by Cheryl Sabella (Lisa Roach) in branch 'master':
bpo-31822: Document that urllib.parse.{Defrag,Split,Parse}Result are namedtuples (GH-4434)
https://github.com/python/cpython/commit/13c1f72cd1d91fdc2654f2f57356b2eacb75f164
msg338761 - (view) Author: miss-islington (miss-islington) Date: 2019-03-24 21:56
New changeset fc0010236341a32db7a3703f21e0bddbb36103dd by Miss Islington (bot) in branch '3.7':
bpo-31822: Document that urllib.parse.{Defrag,Split,Parse}Result are namedtuples (GH-4434)
https://github.com/python/cpython/commit/fc0010236341a32db7a3703f21e0bddbb36103dd
msg338763 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2019-03-24 22:07
Thanks @Allen Li for the initial report, @lisroach for the PR, and @eric.araujo for the review.

Issue 36418 has been opened to track @fdrake's request in msg338645.
History
Date User Action Args
2019-03-24 22:07:59cheryl.sabellasetstatus: open -> closed

versions: + Python 3.8, - Python 2.7, Python 3.6
nosy: - miss-islington

messages: + msg338763
resolution: fixed
stage: patch review -> resolved
2019-03-24 21:56:31miss-islingtonsetnosy: + miss-islington
messages: + msg338761
2019-03-24 21:50:54miss-islingtonsetpull_requests: + pull_request12479
2019-03-24 21:28:51cheryl.sabellasetnosy: + cheryl.sabella
messages: + msg338756
2019-03-23 05:59:29fdrakesetmessages: + msg338646
2019-03-23 05:53:26fdrakesetnosy: + fdrake
messages: + msg338645
2019-03-23 00:17:59martin.panterlinkissue27464 superseder
2017-11-17 06:06:11lisroachsetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request4378
2017-10-23 19:08:43eric.araujosetmessages: + msg304833
2017-10-23 19:05:32serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg304832
2017-10-23 18:07:59eric.araujosetkeywords: + easy
nosy: + eric.araujo
stage: needs patch

versions: + Python 3.7
2017-10-22 21:28:55rhettingersetassignee: docs@python -> lisroach

nosy: + lisroach
2017-10-19 19:24:20vapiersetnosy: + vapier
messages: + msg304638
2017-10-19 18:54:33Allen Licreate