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

Created on 2017-10-19 18:54 by Allen Li, last changed 2017-11-17 06:06 by lisroach.

Pull Requests
URL Status Linked Edit
PR 4434 open lisroach, 2017-11-17 06:06
Messages (4)
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)
History
Date User Action Args
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