https://github.com/python/cpython/commit/9d4a35c494cb1cfd9c77c619b22bd425695316c2
commit: 9d4a35c494cb1cfd9c77c619b22bd425695316c2
branch: main
author: Jacob Walls <[email protected]>
committer: orsenthil <[email protected]>
date: 2026-11-10T07:39:30-08:00
summary:

gh-63293: Reject non-string URL args and deprecate false values in urllib.parse

gh-63293: Reject non-string URL args and deprecate false values in urllib.parse 
Truthy values other than str/bytes previously failed with AttributeError.

False values such as 0 and [] were silently treated as empty. Require
str, bytes, or None in _coerce_args(): raise TypeError for other truthy 
values, and emit DeprecationWarning for other false values, scheduled 
to become TypeError in 3.18. This extends the 3.14 deprecation for 
parse_qsl()/parse_qs().

Original patch by Jacob Walls.

---- 

Co-authored-by: Senthil Kumaran <[email protected]>

files:
A Misc/NEWS.d/next/Library/2021-06-11-20-00-16.bpo-19094.rMRoIL.rst
M Doc/deprecations/pending-removal-in-3.18.rst
M Doc/library/urllib.parse.rst
M Doc/whatsnew/3.16.rst
M Lib/test/test_urlparse.py
M Lib/urllib/parse.py

diff --git a/Doc/deprecations/pending-removal-in-3.18.rst 
b/Doc/deprecations/pending-removal-in-3.18.rst
index 19113aab981bbc6..fb10420ab38c52f 100644
--- a/Doc/deprecations/pending-removal-in-3.18.rst
+++ b/Doc/deprecations/pending-removal-in-3.18.rst
@@ -11,6 +11,13 @@ Pending removal in Python 3.18
     C implementation, has been deprecated since Python 3.13.
     (Contributed by Serhiy Storchaka in :gh:`89902`.)
 
+* :mod:`urllib.parse`:
+
+  * Accepting objects with false values (like ``0`` and ``[]``) except empty
+    strings, byte-like objects and ``None`` in the URL parsing functions has
+    been deprecated since Python 3.16.
+    (Contributed by Jacob Walls in :gh:`63293`.)
+
 * Deprecations defined by :pep:`829`:
 
   * ``import`` lines in :file:`{name}.pth` files are silently ignored.
diff --git a/Doc/library/urllib.parse.rst b/Doc/library/urllib.parse.rst
index 26e159306c81070..9a8f8cf9bab012e 100644
--- a/Doc/library/urllib.parse.rst
+++ b/Doc/library/urllib.parse.rst
@@ -225,6 +225,16 @@ or on combining URL components into a URL string.
    .. versionchanged:: 3.15
       Added the *missing_as_none* parameter.
 
+   .. versionchanged:: 3.16
+      Passing an object that is not a string, bytes, or ``None`` as
+      *urlstring* or *scheme* now raises :exc:`TypeError` instead of
+      :exc:`AttributeError`.
+
+   .. deprecated:: 3.16
+      Accepting objects with false values (like ``0`` and ``[]``) except empty
+      strings, byte-like objects and ``None`` as *urlstring* or *scheme* is
+      now deprecated.  They will raise :exc:`TypeError` in Python 3.18.
+
 .. _WHATWG spec: https://url.spec.whatwg.org/#concept-basic-url-parser
 
 
@@ -341,6 +351,15 @@ or on combining URL components into a URL string.
    .. versionchanged:: 3.15
       Added the *keep_empty* parameter.
 
+   .. versionchanged:: 3.16
+      Passing an object that is not a string, bytes, or ``None`` in *parts*
+      now raises :exc:`TypeError` instead of :exc:`AttributeError`.
+
+   .. deprecated:: 3.16
+      Accepting objects with false values (like ``0`` and ``[]``) except empty
+      strings, byte-like objects and ``None`` in *parts* is now deprecated.
+      They will raise :exc:`TypeError` in Python 3.18.
+
 
 .. function:: urlparse(urlstring, scheme=None, allow_fragments=True, *, 
missing_as_none=False)
 
@@ -358,6 +377,16 @@ or on combining URL components into a URL string.
    :func:`urlsplit` should generally be used instead of :func:`urlparse`.
    A separate function is needed to separate the path segments and parameters.
 
+   .. versionchanged:: 3.16
+      Passing an object that is not a string, bytes, or ``None`` as
+      *urlstring* or *scheme* now raises :exc:`TypeError` instead of
+      :exc:`AttributeError`.
+
+   .. deprecated:: 3.16
+      Accepting objects with false values (like ``0`` and ``[]``) except empty
+      strings, byte-like objects and ``None`` as *urlstring* or *scheme* is
+      now deprecated.  They will raise :exc:`TypeError` in Python 3.18.
+
 .. function:: urlunparse(parts)
               urlunparse(parts, *, keep_empty)
 
@@ -379,6 +408,15 @@ or on combining URL components into a URL string.
    .. versionchanged:: 3.15
       Added the *keep_empty* parameter.
 
+   .. versionchanged:: 3.16
+      Passing an object that is not a string, bytes, or ``None`` in *parts*
+      now raises :exc:`TypeError` instead of :exc:`AttributeError`.
+
+   .. deprecated:: 3.16
+      Accepting objects with false values (like ``0`` and ``[]``) except empty
+      strings, byte-like objects and ``None`` in *parts* is now deprecated.
+      They will raise :exc:`TypeError` in Python 3.18.
+
 
 .. function:: urljoin(base, url, allow_fragments=True)
 
@@ -422,6 +460,15 @@ or on combining URL components into a URL string.
 
       Behavior updated to match the semantics defined in :rfc:`3986`.
 
+   .. versionchanged:: 3.16
+      Passing an object that is not a string, bytes, or ``None`` as *base* or
+      *url* now raises :exc:`TypeError` instead of :exc:`AttributeError`.
+
+   .. deprecated:: 3.16
+      Accepting objects with false values (like ``0`` and ``[]``) except empty
+      strings, byte-like objects and ``None`` as *base* or *url* is now
+      deprecated.  They will raise :exc:`TypeError` in Python 3.18.
+
 
 .. function:: urldefrag(url, *, missing_as_none=False)
 
@@ -452,6 +499,15 @@ or on combining URL components into a URL string.
    .. versionchanged:: 3.15
       Added the *missing_as_none* parameter.
 
+   .. versionchanged:: 3.16
+      Passing an object that is not a string, bytes, or ``None`` as *url* now
+      raises :exc:`TypeError` instead of :exc:`AttributeError`.
+
+   .. deprecated:: 3.16
+      Accepting objects with false values (like ``0`` and ``[]``) except empty
+      strings, byte-like objects and ``None`` as *url* is now deprecated.
+      They will raise :exc:`TypeError` in Python 3.18.
+
 .. function:: unwrap(url)
 
    Extract the url from a wrapped URL (that is, a string formatted as
diff --git a/Doc/whatsnew/3.16.rst b/Doc/whatsnew/3.16.rst
index 4af5d3c0bd072e2..84a5ffd186db65d 100644
--- a/Doc/whatsnew/3.16.rst
+++ b/Doc/whatsnew/3.16.rst
@@ -1258,6 +1258,16 @@ New deprecations
     Use :pep:`695` syntax instead.
     (Contributed by Nikita Sobolev in :gh:`150190`.)
 
+* :mod:`urllib.parse`:
+
+  * Accepting objects with false values (like ``0`` and ``[]``) except empty
+    strings, byte-like objects and ``None`` is now deprecated in the URL
+    parsing functions, and is scheduled to raise :exc:`TypeError` in Python
+    3.18.  This extends the same deprecation made in Python 3.14 for
+    :func:`~urllib.parse.parse_qsl`, :func:`~urllib.parse.parse_qs`, and
+    :func:`~urllib.parse.urlencode`.
+    (Contributed by Jacob Walls in :gh:`63293`.)
+
 .. Add deprecations above alphabetically, not here at the end.
 
 .. include:: ../deprecations/pending-removal-in-3.17.rst
diff --git a/Lib/test/test_urlparse.py b/Lib/test/test_urlparse.py
index 112cc139d597b6c..37e172f7f2caca3 100644
--- a/Lib/test/test_urlparse.py
+++ b/Lib/test/test_urlparse.py
@@ -1252,6 +1252,12 @@ def test_mixed_types_rejected(self):
         with self.assertRaisesRegex(TypeError, "Cannot mix str"):
             urllib.parse.urljoin(b"http://python.org";, "http://python.org";)
 
+    def test_non_string_true_values_rejected(self):
+        # True values raise informative TypeErrors
+        msg = "Expected str, bytes or None, not "
+        with self.assertRaisesRegex(TypeError, msg):
+            urllib.parse.urlsplit(1, b'http')
+
     def _check_result_type(self, str_type, str_args):
         bytes_type = str_type._encoded_counterpart
         self.assertIs(bytes_type._decoded_counterpart, str_type)
@@ -1987,6 +1993,23 @@ def test_to_bytes_deprecation(self):
         self.assertEqual(str(cm.warning),
                          'urllib.parse.to_bytes() is deprecated as of 3.8')
 
+    def test_falsey_deprecation(self):
+        cases = [
+            (urllib.parse.urljoin, ['http://www.python.org', []]),
+            (urllib.parse.urljoin, [[], b'docs']),
+            (urllib.parse.urlparse, [b'www.python.org', {}]),
+            (urllib.parse.urlparse, [{}, '']),
+            (urllib.parse.urlsplit, [0, b'http']),
+            (urllib.parse.urlsplit, [b'http://www.python.org', 0]),
+            (urllib.parse.urldefrag, [{}]),
+            (urllib.parse.urlunparse, [[None, b'www.python.org', (), (), (), 
()]]),
+            (urllib.parse.urlunsplit, [['http', 0, '', '', '']]),
+        ]
+        for func, args in cases:
+            with self.subTest(callable=func.__name__, args=args):
+                with self.assertWarnsRegex(DeprecationWarning, "false value"):
+                    func(*args)
+
 
 def str_encode(s):
     if s is None:
diff --git a/Lib/urllib/parse.py b/Lib/urllib/parse.py
index ee0bceb2928c06f..f6c94060054e48f 100644
--- a/Lib/urllib/parse.py
+++ b/Lib/urllib/parse.py
@@ -125,6 +125,13 @@ def _coerce_args(*args):
     #   - encoding function otherwise
     str_input = None
     for arg in args:
+        if not (arg is None or isinstance(arg, str) or hasattr(arg, 'decode')):
+            if arg:
+                raise TypeError("Expected str, bytes or None, "
+                                f"not {type(arg).__name__}")
+            warnings.warn(f"Accepting {type(arg).__name__} objects with false "
+                          f"value in urllib.parse is deprecated as of 3.16",
+                          DeprecationWarning, stacklevel=3)
         if arg:
             if str_input is None:
                 str_input = isinstance(arg, str)
@@ -712,12 +719,12 @@ def _urlunsplit(scheme, netloc, url, query, fragment):
 def urljoin(base, url, allow_fragments=True):
     """Join a base URL and a possibly relative URL to form an absolute
     interpretation of the latter."""
+    base, url, _coerce_result = _coerce_args(base, url)
     if not base:
-        return url
+        return _coerce_result(url)
     if not url:
-        return base
+        return _coerce_result(base)
 
-    base, url, _coerce_result = _coerce_args(base, url)
     bscheme, bnetloc, bpath, bquery, bfragment = \
             _urlsplit(base, None, allow_fragments)
     scheme, netloc, path, query, fragment = \
diff --git a/Misc/NEWS.d/next/Library/2021-06-11-20-00-16.bpo-19094.rMRoIL.rst 
b/Misc/NEWS.d/next/Library/2021-06-11-20-00-16.bpo-19094.rMRoIL.rst
new file mode 100644
index 000000000000000..53cae4448ed9d54
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2021-06-11-20-00-16.bpo-19094.rMRoIL.rst
@@ -0,0 +1,6 @@
+The :mod:`urllib.parse` URL parsing functions now raise :exc:`TypeError`
+instead of :exc:`AttributeError` when passed an object which is not a string,
+bytes, or ``None``.  Accepting objects with false values (like ``0`` and
+``[]``) except empty strings, byte-like objects and ``None`` is now
+deprecated, extending the deprecation made in Python 3.14 for
+:func:`~urllib.parse.parse_qsl` and :func:`~urllib.parse.parse_qs`.

_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]

Reply via email to