[Python-checkins] bpo-31822: Document that urllib.parse.{Defrag, Split, Parse}Result are namedtuples (GH-4434)
Miss Islington (bot)
webhook-mailer at python.org
Sun Mar 24 17:56:31 EDT 2019
https://github.com/python/cpython/commit/fc0010236341a32db7a3703f21e0bddbb36103dd
commit: fc0010236341a32db7a3703f21e0bddbb36103dd
branch: 3.7
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: GitHub <noreply at github.com>
date: 2019-03-24T14:56:27-07:00
summary:
bpo-31822: Document that urllib.parse.{Defrag,Split,Parse}Result are namedtuples (GH-4434)
(cherry picked from commit 13c1f72cd1d91fdc2654f2f57356b2eacb75f164)
Co-authored-by: Lisa Roach <lisaroach14 at gmail.com>
files:
M Doc/library/urllib.parse.rst
diff --git a/Doc/library/urllib.parse.rst b/Doc/library/urllib.parse.rst
index b565e1edd321..ddc3ee23f48a 100644
--- a/Doc/library/urllib.parse.rst
+++ b/Doc/library/urllib.parse.rst
@@ -39,8 +39,9 @@ or on combining URL components into a URL string.
.. function:: urlparse(urlstring, scheme='', allow_fragments=True)
- Parse a URL into six components, returning a 6-tuple. This corresponds to the
- general structure of a URL: ``scheme://netloc/path;parameters?query#fragment``.
+ Parse a URL into six components, returning a 6-item :term:`named tuple`. This
+ corresponds to the general structure of a URL:
+ ``scheme://netloc/path;parameters?query#fragment``.
Each tuple item is a string, possibly empty. The components are not broken up in
smaller parts (for example, the network location is a single string), and %
escapes are not expanded. The delimiters as shown above are not part of the
@@ -88,8 +89,8 @@ or on combining URL components into a URL string.
or query component, and :attr:`fragment` is set to the empty string in
the return value.
- The return value is actually an instance of a subclass of :class:`tuple`. This
- class has the following additional read-only convenience attributes:
+ The return value is a :term:`named tuple`, which means that its items can
+ be accessed by index or as named attributes, which are:
+------------------+-------+--------------------------+----------------------+
| Attribute | Index | Value | Value if not present |
@@ -129,6 +130,24 @@ or on combining URL components into a URL string.
``#``, ``@``, or ``:`` will raise a :exc:`ValueError`. If the URL is
decomposed before parsing, no error will be raised.
+ As is the case with all named tuples, the subclass has a few additional methods
+ and attributes that are particularly useful. One such method is :meth:`_replace`.
+ The :meth:`_replace` method will return a new ParseResult object replacing specified
+ fields with new values.
+
+ .. doctest::
+ :options: +NORMALIZE_WHITESPACE
+
+ >>> from urllib.parse import urlparse
+ >>> u = urlparse('//www.cwi.nl:80/%7Eguido/Python.html')
+ >>> u
+ ParseResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
+ params='', query='', fragment='')
+ >>> u._replace(scheme='http')
+ ParseResult(scheme='http', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
+ params='', query='', fragment='')
+
+
.. versionchanged:: 3.2
Added IPv6 URL parsing capabilities.
@@ -230,11 +249,13 @@ or on combining URL components into a URL string.
This should generally be used instead of :func:`urlparse` if the more recent URL
syntax allowing parameters to be applied to each segment of the *path* portion
of the URL (see :rfc:`2396`) is wanted. A separate function is needed to
- separate the path segments and parameters. This function returns a 5-tuple:
- (addressing scheme, network location, path, query, fragment identifier).
+ separate the path segments and parameters. This function returns a 5-item
+ :term:`named tuple`::
+
+ (addressing scheme, network location, path, query, fragment identifier).
- The return value is actually an instance of a subclass of :class:`tuple`. This
- class has the following additional read-only convenience attributes:
+ The return value is a :term:`named tuple`, its items can be accessed by index
+ or as named attributes:
+------------------+-------+-------------------------+----------------------+
| Attribute | Index | Value | Value if not present |
@@ -330,8 +351,8 @@ or on combining URL components into a URL string.
string. If there is no fragment identifier in *url*, return *url* unmodified
and an empty string.
- The return value is actually an instance of a subclass of :class:`tuple`. This
- class has the following additional read-only convenience attributes:
+ The return value is a :term:`named tuple`, its items can be accessed by index
+ or as named attributes:
+------------------+-------+-------------------------+----------------------+
| Attribute | Index | Value | Value if not present |
More information about the Python-checkins
mailing list