gh-63293: Deprecate providing false values besides strings, bytes, or `None` to urllib.parse functions by jacobtylerwalls · Pull Request #26687 · python/cpython · GitHub

bpo-19094 and bpo-22234

Like a recent change in parse_qsl() (#116903) to require strings, bytes, or None, require this in other urllib.parse functions as well, with a deprecation cycle for false values.

Previously, although truthy values failed with AttributeError: ... has no attribute 'decode', falsy values such as [] were silently accepted.

Original patch by @vajrasky.

I noticed in 3.11 (d597fdc) some inappropriate types will fail first in urlsplit() (only) via the @functools.lru_cache decorator requiring hashable types. This is the chief reason for rotating unsupported types in the test cases.

>>> import urllib.parse
>>> urllib.parse.urlsplit([])
Traceback (most recent call last):
  File "<string>", line 1, in <module>
TypeError: unhashable type: 'list'
>>> urllib.parse.urlsplit(())
SplitResultBytes(scheme=b'', netloc=b'', path=b'', query=b'', fragment=b'')

https://bugs.python.org/issue19094

Issue: urljoin should raise a TypeError if URL is not a string #63293

Closes #63293
Closes #66430

I just did a bpo search for duplicates and found bpo-22234. The discussion eventually came round to a similar solution after discussing the necessity of a deprecation period (believe the consensus = not needed).

But in looking at the discussion there I realized it's safe to extend this solution to the other functions in the module and just factor this TypeError out to _coerce_args(). DRY is good. Will push again and update title and body.

The failing test is caused by pip relying on the undocumented duck-typing in question:

https://github.com/pypa/pip/blob/main/src/pip/_internal/models/link.py#L150-L154

I'll raise a PR against pip. So this may need to wait, unless we add a friendly shim.

Notice that the other patch in bpo-22234 explicitly regarded this as an error condition:

+        with self.assertRaises(TypeError):
+            urlunsplit(("http", "www.python.org", "", "", None))

Update: pip merged my PR: pypa/pip#10064

This PR is stale because it has been open for 30 days with no activity.

From the failing docs job, I see requests relies on this behavior. I'll change to a emit a deprecation warning. Serhiy has a draft patch on bpo-22234 doing something similar. That patch also allows duck-typing for types having an "encode" attribute.

Looks ok.

@orsenthil I'm wondering if you have a view as a maintainer of urllib?

Previously, values other than strings or bytes either failed cryptically with AttributeError if truthy or were accepted silently if falsy. In 3.11 one falsy value will now start failing cryptically with TypeError, described in OP.

Is this a useful cleanup? I included a deprecation path for the falsy values.

This PR is stale because it has been open for 30 days with no activity.

…or inappropriate types

Documentation build overview

📚 cpython-previews | 🛠️ Build #33551094 | 📁 Comparing f5bc232 against main (3fd61b7)

🔍 Preview build

271 files changed · + 9 added · ± 261 modified · - 1 deleted

+ Added

± Modified

- Deleted

library/asyncio-policy.html

the-knights-who-say-ni added the CLA signed label Jun 12, 2021

bedevere-bot added the awaiting review label Jun 12, 2021

jacobtylerwalls mentioned this pull request Jun 12, 2021

Speed up test_urlsplit_normalization #26688

Merged

nanjekyejoannah reviewed Jun 12, 2021

View reviewed changes

Comment thread Lib/urllib/parse.py Outdated

jacobtylerwalls changed the title bpo-19094: Raise TypeError in urljoin(), urlparse(), and urlsplit() for inappropriate types bpo-19094: Raise TypeError in urllib.parse for inappropriate types Jun 13, 2021

This comment was marked as outdated.

Sign in to view

jacobtylerwalls changed the title bpo-19094: Raise TypeError in urllib.parse for inappropriate types bpo-19094: Raise TypeError in urllib.parse for objects besides strings or bytes Jun 14, 2021

github-actions Bot added the stale Stale PR or inactive for long period of time. label Jul 15, 2021

jacobtylerwalls force-pushed the urllib-typeerror branch from f156d42 to d2f1bb9 Compare October 31, 2021 02:18

jacobtylerwalls changed the title bpo-19094: Raise TypeError in urllib.parse for objects besides strings or bytes bpo-19094: Deprecate providing false values besides strings to urllib.parse functions Feb 23, 2022

jacobtylerwalls changed the title bpo-19094: Deprecate providing false values besides strings to urllib.parse functions bpo-19094: Deprecate providing false values besides strings or bytes to urllib.parse functions Feb 23, 2022

MaxwellDupre approved these changes Mar 22, 2022

View reviewed changes

bedevere-bot added awaiting core review and removed awaiting review labels Mar 22, 2022

jacobtylerwalls changed the title bpo-19094: Deprecate providing false values besides strings or bytes to urllib.parse functions gh-63293: Deprecate providing false values besides strings or bytes to urllib.parse functions Jun 18, 2022

ezio-melotti removed the CLA signed label Jul 13, 2022

github-actions Bot removed the stale Stale PR or inactive for long period of time. label Aug 9, 2022

bedevere-bot added awaiting review and removed awaiting core review labels May 6, 2023

arhadthedev added stdlib Standard Library Python modules in the Lib/ directory python labels Nov 19, 2023

jaraco mentioned this pull request Nov 19, 2023

urljoin should raise a TypeError if URL is not a string #63293

Open

arhadthedev added the 3.13 bugs and security fixes label Nov 19, 2023

pablogsal requested review from pablogsal and removed request for pablogsal November 19, 2023 17:39

AlexWaygood removed the python label Nov 29, 2023

github-actions Bot added the stale Stale PR or inactive for long period of time. label Apr 9, 2026

bpo-19094: Raise TypeError in urljoin(), urlparse(), and urlsplit() f…

c83d003

…or inappropriate types

jacobtylerwalls force-pushed the urllib-typeerror branch from 57464b3 to c83d003 Compare April 20, 2026 16:04

jacobtylerwalls requested a review from AA-Turner as a code owner April 20, 2026 16:04

jacobtylerwalls mentioned this pull request Apr 20, 2026

Deprecate support of false values in urllib.parse.parse_qsl() #116897

Closed

jacobtylerwalls added 2 commits April 20, 2026 19:11

fix missing elif

3ec0a4b

fix condition

2bf57f3

This comment was marked as resolved.

Sign in to view

jacobtylerwalls marked this pull request as draft April 20, 2026 19:57

bedevere-app Bot removed the awaiting review label Apr 20, 2026

jacobtylerwalls added 4 commits April 20, 2026 16:03

Allow NoneType

bffbd32

Relax assertion

01809a9

fixups

6fc2901

fixups

4f2c686

github-actions Bot removed the stale Stale PR or inactive for long period of time. label May 10, 2026

jacobtylerwalls added 2 commits July 11, 2026 21:14

Merge remote-tracking branch 'upstream' into urllib-typeerror

9f028ea

Bump docs

03d4f21

cosmetic

a34c412

jacobtylerwalls marked this pull request as ready for review July 12, 2026 01:28

bedevere-app Bot added the awaiting review label Jul 12, 2026

Resolve BytesWarning

f5bc232

jacobtylerwalls changed the title gh-63293: Deprecate providing false values besides strings or bytes to urllib.parse functions gh-63293: Deprecate providing false values besides strings, bytes, or None to urllib.parse functions Jul 12, 2026

gh-63293: Deprecate providing false values besides strings, bytes, or `None` to urllib.parse functions by jacobtylerwalls · Pull Request #26687 · python/cpython · GitHub

Uh oh!

Uh oh!

gh-63293: Deprecate providing false values besides strings, bytes, or None to urllib.parse functions - #26687

gh-63293: Deprecate providing false values besides strings, bytes, or None to urllib.parse functions#26687
jacobtylerwalls wants to merge 11 commits into
python:mainfrom
jacobtylerwalls:urllib-typeerror

jacobtylerwalls commented Jun 12, 2021 •
edited
Loading

Uh oh!

Uh oh!

Uh oh!

jacobtylerwalls commented Jun 13, 2021 •
edited by bedevere-bot
Loading

Uh oh!

Uh oh!

jacobtylerwalls commented Jun 13, 2021 •
edited
Loading

Uh oh!

Uh oh!

This comment was marked as outdated.

github-actions Bot commented Jul 15, 2021

Uh oh!

jacobtylerwalls commented Feb 23, 2022 •
edited by bedevere-bot
Loading

Uh oh!

Uh oh!

MaxwellDupre left a comment

Uh oh!

jacobtylerwalls commented Oct 9, 2022

Uh oh!

github-actions Bot commented Apr 9, 2026

Uh oh!

This comment was marked as resolved.

read-the-docs-community Bot commented Jul 12, 2026 •
edited
Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

gh-63293: Deprecate providing false values besides strings, bytes, or `None` to urllib.parse functions by jacobtylerwalls · Pull Request #26687 · python/cpython · GitHub

Uh oh!

Uh oh!

gh-63293: Deprecate providing false values besides strings, bytes, or None to urllib.parse functions - #26687

gh-63293: Deprecate providing false values besides strings, bytes, or None to urllib.parse functions#26687jacobtylerwalls wants to merge 11 commits intopython:mainpython/cpython:mainfrom jacobtylerwalls:urllib-typeerrorjacobtylerwalls/cpython:urllib-typeerrorCopy head branch name to clipboard

Conversation

jacobtylerwalls commented Jun 12, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

jacobtylerwalls commented Jun 13, 2021 • edited by bedevere-bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jacobtylerwalls commented Jun 13, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

github-actions Bot commented Jul 15, 2021

Uh oh!

jacobtylerwalls commented Feb 23, 2022 • edited by bedevere-bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

MaxwellDupre left a comment

Choose a reason for hiding this comment

Uh oh!

jacobtylerwalls commented Oct 9, 2022

Uh oh!

github-actions Bot commented Apr 9, 2026

Uh oh!

This comment was marked as resolved.

read-the-docs-community Bot commented Jul 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

gh-63293: Deprecate providing false values besides strings, bytes, or None to urllib.parse functions#26687
jacobtylerwalls wants to merge 11 commits into
python:mainfrom
jacobtylerwalls:urllib-typeerror

jacobtylerwalls commented Jun 12, 2021 •
edited
Loading

jacobtylerwalls commented Jun 13, 2021 •
edited by bedevere-bot
Loading

jacobtylerwalls commented Jun 13, 2021 •
edited
Loading

jacobtylerwalls commented Feb 23, 2022 •
edited by bedevere-bot
Loading

read-the-docs-community Bot commented Jul 12, 2026 •
edited
Loading