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)

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

collections.namedtuples is not a class.

I suggest using :term:`named tuple` for the link (+ an example of using _replace as Mike said)

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.

To clarify: I'm not suggesting that an API expansion should be considered as part of this issue.

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

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

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.