parthtamu/rag-code-assistant
0
1<!DOCTYPE html>2 3<html lang="en" data-content_root="../">4 <head>5 <meta charset="utf-8" />6 <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />7<meta property="og:title" content="urllib.parse — Parse URLs into components" />8<meta property="og:type" content="website" />9<meta property="og:url" content="https://docs.python.org/3/library/urllib.parse.html" />10<meta property="og:site_name" content="Python documentation" />11<meta property="og:description" content="Source code: Lib/urllib/parse.py This module defines a standard interface to break Uniform Resource Locator (URL) strings up in components (addressing scheme, network location, path etc.), to combi..." />12<meta property="og:image:width" content="1146" />13<meta property="og:image:height" content="600" />14<meta property="og:image" content="https://docs.python.org/3.15/_images/social_previews/summary_library_urllib.parse_ce343eb8.png" />15<meta property="og:image:alt" content="Source code: Lib/urllib/parse.py This module defines a standard interface to break Uniform Resource Locator (URL) strings up in components (addressing scheme, network location, path etc.), to combi..." />16<meta name="description" content="Source code: Lib/urllib/parse.py This module defines a standard interface to break Uniform Resource Locator (URL) strings up in components (addressing scheme, network location, path etc.), to combi..." />17<meta name="twitter:card" content="summary_large_image" />18<meta name="theme-color" content="#3776ab">19 20 <title>urllib.parse — Parse URLs into components — Python 3.15.0a6 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">21 22 <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />23 <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />24 <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=89a2f22a" />25 <link rel="stylesheet" type="text/css" href="../_static/profiling-sampling-visualization.css?v=0c2600ae" />26 <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />27 28 <script src="../_static/documentation_options.js?v=6b7c9ff5"></script>29 <script src="../_static/doctools.js?v=9bcbadda"></script>30 <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>31 <script src="../_static/profiling-sampling-visualization.js?v=9811ed04"></script>32 33 <script src="../_static/sidebar.js"></script>34 35 <link rel="search" type="application/opensearchdescription+xml"36 title="Search within Python 3.15.0a6 documentation"37 href="../_static/opensearch.xml"/>38 <link rel="author" title="About these documents" href="../about.html" />39 <link rel="index" title="Index" href="../genindex.html" />40 <link rel="search" title="Search" href="../search.html" />41 <link rel="copyright" title="Copyright" href="../copyright.html" />42 <link rel="next" title="urllib.error — Exception classes raised by urllib.request" href="urllib.error.html" />43 <link rel="prev" title="urllib.request — Extensible library for opening URLs" href="urllib.request.html" />44 45 46 <script defer file-types="bz2,epub,zip" data-domain="docs.python.org" src="https://analytics.python.org/js/script.file-downloads.outbound-links.js"></script>47 48 <link rel="canonical" href="https://docs.python.org/3/library/urllib.parse.html">49 50 51 52 53 <style>54 @media only screen {55 table.full-width-table {56 width: 100%;57 }58 }59 </style>60<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">61 <link rel="shortcut icon" type="image/png" href="../_static/py.svg">62 <script type="text/javascript" src="../_static/copybutton.js"></script>63 <script type="text/javascript" src="../_static/menu.js"></script>64 <script type="text/javascript" src="../_static/search-focus.js"></script>65 <script type="text/javascript" src="../_static/themetoggle.js"></script> 66 <script type="text/javascript" src="../_static/rtd_switcher.js"></script>67 <meta name="readthedocs-addons-api-version" content="1">68 69 </head>70<body>71<div class="mobile-nav">72 <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"73 aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">74 <nav class="nav-content" role="navigation">75 <label for="menuToggler" class="toggler__label">76 <span></span>77 </label>78 <span class="nav-items-wrapper">79 <a href="https://www.python.org/" class="nav-logo">80 <img src="../_static/py.svg" alt="Python logo">81 </a>82 <span class="version_switcher_placeholder"></span>83 <form role="search" class="search" action="../search.html" method="get">84 <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">85 <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>86 </svg>87 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q">88 <input type="submit" value="Go">89 </form>90 </span>91 </nav>92 <div class="menu-wrapper">93 <nav class="menu" role="navigation" aria-label="main navigation">94 <div class="language_switcher_placeholder"></div>95 96<label class="theme-selector-label">97 Theme98 <select class="theme-selector" oninput="activateTheme(this.value)">99 <option value="auto" selected>Auto</option>100 <option value="light">Light</option>101 <option value="dark">Dark</option>102 </select>103</label>104 <div>105 <h3><a href="../contents.html">Table of Contents</a></h3>106 <ul>107<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">urllib.parse</span></code> — Parse URLs into components</a><ul>108<li><a class="reference internal" href="#url-parsing">URL Parsing</a></li>109<li><a class="reference internal" href="#url-parsing-security">URL parsing security</a></li>110<li><a class="reference internal" href="#parsing-ascii-encoded-bytes">Parsing ASCII Encoded Bytes</a></li>111<li><a class="reference internal" href="#structured-parse-results">Structured Parse Results</a></li>112<li><a class="reference internal" href="#url-quoting">URL Quoting</a></li>113</ul>114</li>115</ul>116 117 </div>118 <div>119 <h4>Previous topic</h4>120 <p class="topless"><a href="urllib.request.html"121 title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">urllib.request</span></code> — Extensible library for opening URLs</a></p>122 </div>123 <div>124 <h4>Next topic</h4>125 <p class="topless"><a href="urllib.error.html"126 title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">urllib.error</span></code> — Exception classes raised by urllib.request</a></p>127 </div>128 <script>129 document.addEventListener('DOMContentLoaded', () => {130 const title = document.querySelector('meta[property="og:title"]').content;131 const elements = document.querySelectorAll('.improvepage');132 const pageurl = window.location.href.split('?')[0];133 elements.forEach(element => {134 const url = new URL(element.href.split('?')[0].replace("-nojs", ""));135 url.searchParams.set('pagetitle', title);136 url.searchParams.set('pageurl', pageurl);137 url.searchParams.set('pagesource', "library/urllib.parse.rst");138 element.href = url.toString();139 });140 });141 </script>142 <div role="note" aria-label="source link">143 <h3>This page</h3>144 <ul class="this-page-menu">145 <li><a href="../bugs.html">Report a bug</a></li>146 <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>147 <li>148 <a href="https://github.com/python/cpython/blob/main/Doc/library/urllib.parse.rst?plain=1"149 rel="nofollow">Show source150 </a>151 </li>152 153 </ul>154 </div>155 </nav>156 </div>157</div>158 159 160 <div class="related" role="navigation" aria-label="Related">161 <h3>Navigation</h3>162 <ul>163 <li class="right" style="margin-right: 10px">164 <a href="../genindex.html" title="General Index"165 accesskey="I">index</a></li>166 <li class="right" >167 <a href="../py-modindex.html" title="Python Module Index"168 >modules</a> |</li>169 <li class="right" >170 <a href="urllib.error.html" title="urllib.error — Exception classes raised by urllib.request"171 accesskey="N">next</a> |</li>172 <li class="right" >173 <a href="urllib.request.html" title="urllib.request — Extensible library for opening URLs"174 accesskey="P">previous</a> |</li>175 176 <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>177 <li><a href="https://www.python.org/">Python</a> »</li>178 <li class="switchers">179 <div class="language_switcher_placeholder"></div>180 <div class="version_switcher_placeholder"></div>181 </li>182 <li>183 184 </li>185 <li id="cpython-language-and-version">186 <a href="../index.html">3.15.0a6 Documentation</a> »187 </li>188 189 <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>190 <li class="nav-item nav-item-2"><a href="internet.html" accesskey="U">Internet Protocols and Support</a> »</li>191 <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">urllib.parse</span></code> — Parse URLs into components</a></li>192 <li class="right">193 194 195 <div class="inline-search" role="search">196 <form class="inline-search" action="../search.html" method="get">197 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">198 <input type="submit" value="Go">199 </form>200 </div>201 |202 </li>203 <li class="right">204<label class="theme-selector-label">205 Theme206 <select class="theme-selector" oninput="activateTheme(this.value)">207 <option value="auto" selected>Auto</option>208 <option value="light">Light</option>209 <option value="dark">Dark</option>210 </select>211</label> |</li>212 213 </ul>214 </div> 215 216 <div class="document">217 <div class="documentwrapper">218 <div class="bodywrapper">219 <div class="body" role="main">220 221 <section id="module-urllib.parse">222<span id="urllib-parse-parse-urls-into-components"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">urllib.parse</span></code> — Parse URLs into components<a class="headerlink" href="#module-urllib.parse" title="Link to this heading">¶</a></h1>223<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/main/Lib/urllib/parse.py">Lib/urllib/parse.py</a></p>224<hr class="docutils" id="index-0" />225<p>This module defines a standard interface to break Uniform Resource Locator (URL)226strings up in components (addressing scheme, network location, path etc.), to227combine the components back into a URL string, and to convert a “relative URL”228to an absolute URL given a “base URL.”</p>229<p>The module has been designed to match the internet RFC on Relative Uniform230Resource Locators. It supports the following URL schemes: <code class="docutils literal notranslate"><span class="pre">file</span></code>, <code class="docutils literal notranslate"><span class="pre">ftp</span></code>,231<code class="docutils literal notranslate"><span class="pre">gopher</span></code>, <code class="docutils literal notranslate"><span class="pre">hdl</span></code>, <code class="docutils literal notranslate"><span class="pre">http</span></code>, <code class="docutils literal notranslate"><span class="pre">https</span></code>, <code class="docutils literal notranslate"><span class="pre">imap</span></code>, <code class="docutils literal notranslate"><span class="pre">itms-services</span></code>, <code class="docutils literal notranslate"><span class="pre">mailto</span></code>, <code class="docutils literal notranslate"><span class="pre">mms</span></code>,232<code class="docutils literal notranslate"><span class="pre">news</span></code>, <code class="docutils literal notranslate"><span class="pre">nntp</span></code>, <code class="docutils literal notranslate"><span class="pre">prospero</span></code>, <code class="docutils literal notranslate"><span class="pre">rsync</span></code>, <code class="docutils literal notranslate"><span class="pre">rtsp</span></code>, <code class="docutils literal notranslate"><span class="pre">rtsps</span></code>, <code class="docutils literal notranslate"><span class="pre">rtspu</span></code>,233<code class="docutils literal notranslate"><span class="pre">sftp</span></code>, <code class="docutils literal notranslate"><span class="pre">shttp</span></code>, <code class="docutils literal notranslate"><span class="pre">sip</span></code>, <code class="docutils literal notranslate"><span class="pre">sips</span></code>, <code class="docutils literal notranslate"><span class="pre">snews</span></code>, <code class="docutils literal notranslate"><span class="pre">svn</span></code>, <code class="docutils literal notranslate"><span class="pre">svn+ssh</span></code>,234<code class="docutils literal notranslate"><span class="pre">telnet</span></code>, <code class="docutils literal notranslate"><span class="pre">wais</span></code>, <code class="docutils literal notranslate"><span class="pre">ws</span></code>, <code class="docutils literal notranslate"><span class="pre">wss</span></code>.</p>235<div class="impl-detail compound">236<p><strong>CPython implementation detail:</strong> The inclusion of the <code class="docutils literal notranslate"><span class="pre">itms-services</span></code> URL scheme can prevent an app from237passing Apple’s App Store review process for the macOS and iOS App Stores.238Handling for the <code class="docutils literal notranslate"><span class="pre">itms-services</span></code> scheme is always removed on iOS; on239macOS, it <em>may</em> be removed if CPython has been built with the240<a class="reference internal" href="../using/configure.html#cmdoption-with-app-store-compliance"><code class="xref std std-option docutils literal notranslate"><span class="pre">--with-app-store-compliance</span></code></a> option.</p>241</div>242<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">urllib.parse</span></code> module defines functions that fall into two broad243categories: URL parsing and URL quoting. These are covered in detail in244the following sections.</p>245<p>This module’s functions use the deprecated term <code class="docutils literal notranslate"><span class="pre">netloc</span></code> (or <code class="docutils literal notranslate"><span class="pre">net_loc</span></code>),246which was introduced in <span class="target" id="index-1"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc1808.html"><strong>RFC 1808</strong></a>. However, this term has been obsoleted by247<span class="target" id="index-2"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc3986.html"><strong>RFC 3986</strong></a>, which introduced the term <code class="docutils literal notranslate"><span class="pre">authority</span></code> as its replacement.248The use of <code class="docutils literal notranslate"><span class="pre">netloc</span></code> is continued for backward compatibility.</p>249<section id="url-parsing">250<h2>URL Parsing<a class="headerlink" href="#url-parsing" title="Link to this heading">¶</a></h2>251<p>The URL parsing functions focus on splitting a URL string into its components,252or on combining URL components into a URL string.</p>253<dl class="py function">254<dt class="sig sig-object py" id="urllib.parse.urlsplit">255<span class="sig-prename descclassname"><span class="pre">urllib.parse.</span></span><span class="sig-name descname"><span class="pre">urlsplit</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">urlstring</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">scheme</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">allow_fragments</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">missing_as_none</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.urlsplit" title="Link to this definition">¶</a></dt>256<dd><p>Parse a URL into five components, returning a 5-item <a class="reference internal" href="../glossary.html#term-named-tuple"><span class="xref std std-term">named tuple</span></a>257<a class="reference internal" href="#urllib.parse.SplitResult" title="urllib.parse.SplitResult"><code class="xref py py-class docutils literal notranslate"><span class="pre">SplitResult</span></code></a> or <a class="reference internal" href="#urllib.parse.SplitResultBytes" title="urllib.parse.SplitResultBytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">SplitResultBytes</span></code></a>.258This corresponds to the general structure of a URL:259<code class="docutils literal notranslate"><span class="pre">scheme://netloc/path?query#fragment</span></code>.260Each tuple item is a string, possibly empty, or <code class="docutils literal notranslate"><span class="pre">None</span></code> if261<em>missing_as_none</em> is true.262Not defined component are represented an empty string (by default) or263<code class="docutils literal notranslate"><span class="pre">None</span></code> if <em>missing_as_none</em> is true.264The components are not broken up265into smaller parts (for example, the network location is a single string), and %266escapes are not expanded. The delimiters as shown above are not part of the267result, except for a leading slash in the <em>path</em> component, which is retained if268present. For example:</p>269<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">urllib.parse</span><span class="w"> </span><span class="kn">import</span> <span class="n">urlsplit</span>270<span class="gp">>>> </span><span class="n">urlsplit</span><span class="p">(</span><span class="s2">"scheme://netloc/path?query#fragment"</span><span class="p">)</span>271<span class="go">SplitResult(scheme='scheme', netloc='netloc', path='/path',</span>272<span class="go"> query='query', fragment='fragment')</span>273<span class="gp">>>> </span><span class="n">o</span> <span class="o">=</span> <span class="n">urlsplit</span><span class="p">(</span><span class="s2">"http://docs.python.org:80/3/library/urllib.parse.html?"</span>274<span class="gp">... </span> <span class="s2">"highlight=params#url-parsing"</span><span class="p">)</span>275<span class="gp">>>> </span><span class="n">o</span>276<span class="go">SplitResult(scheme='http', netloc='docs.python.org:80',</span>277<span class="go"> path='/3/library/urllib.parse.html',</span>278<span class="go"> query='highlight=params', fragment='url-parsing')</span>279<span class="gp">>>> </span><span class="n">o</span><span class="o">.</span><span class="n">scheme</span>280<span class="go">'http'</span>281<span class="gp">>>> </span><span class="n">o</span><span class="o">.</span><span class="n">netloc</span>282<span class="go">'docs.python.org:80'</span>283<span class="gp">>>> </span><span class="n">o</span><span class="o">.</span><span class="n">hostname</span>284<span class="go">'docs.python.org'</span>285<span class="gp">>>> </span><span class="n">o</span><span class="o">.</span><span class="n">port</span>286<span class="go">80</span>287<span class="gp">>>> </span><span class="n">o</span><span class="o">.</span><span class="n">_replace</span><span class="p">(</span><span class="n">fragment</span><span class="o">=</span><span class="s2">""</span><span class="p">)</span><span class="o">.</span><span class="n">geturl</span><span class="p">()</span>288<span class="go">'http://docs.python.org:80/3/library/urllib.parse.html?highlight=params'</span>289<span class="gp">>>> </span><span class="n">urlsplit</span><span class="p">(</span><span class="s2">"http://docs.python.org?"</span><span class="p">)</span>290<span class="go">SplitResult(scheme='http', netloc='docs.python.org', path='',</span>291<span class="go"> query='', fragment='')</span>292<span class="gp">>>> </span><span class="n">urlsplit</span><span class="p">(</span><span class="s2">"http://docs.python.org?"</span><span class="p">,</span> <span class="n">missing_as_none</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>293<span class="go">SplitResult(scheme='http', netloc='docs.python.org', path='',</span>294<span class="go"> query='', fragment=None)</span>295</pre></div>296</div>297<p>Following the syntax specifications in <span class="target" id="index-3"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc1808.html"><strong>RFC 1808</strong></a>, <code class="xref py py-func docutils literal notranslate"><span class="pre">urlsplit()</span></code> recognizes298a netloc only if it is properly introduced by ‘//’. Otherwise the299input is presumed to be a relative URL and thus to start with300a path component.</p>301<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">urllib.parse</span><span class="w"> </span><span class="kn">import</span> <span class="n">urlsplit</span>302<span class="gp">>>> </span><span class="n">urlsplit</span><span class="p">(</span><span class="s1">'//www.cwi.nl:80/</span><span class="si">%7E</span><span class="s1">guido/Python.html'</span><span class="p">)</span>303<span class="go">SplitResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',</span>304<span class="go"> query='', fragment='')</span>305<span class="gp">>>> </span><span class="n">urlsplit</span><span class="p">(</span><span class="s1">'www.cwi.nl/</span><span class="si">%7E</span><span class="s1">guido/Python.html'</span><span class="p">)</span>306<span class="go">SplitResult(scheme='', netloc='', path='www.cwi.nl/%7Eguido/Python.html',</span>307<span class="go"> query='', fragment='')</span>308<span class="gp">>>> </span><span class="n">urlsplit</span><span class="p">(</span><span class="s1">'help/Python.html'</span><span class="p">)</span>309<span class="go">SplitResult(scheme='', netloc='', path='help/Python.html',</span>310<span class="go"> query='', fragment='')</span>311<span class="gp">>>> </span><span class="n">urlsplit</span><span class="p">(</span><span class="s1">'help/Python.html'</span><span class="p">,</span> <span class="n">missing_as_none</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>312<span class="go">SplitResult(scheme=None, netloc=None, path='help/Python.html',</span>313<span class="go"> query=None, fragment=None)</span>314</pre></div>315</div>316<p>The <em>scheme</em> argument gives the default addressing scheme, to be317used only if the URL does not specify one. It should be the same type318(text or bytes) as <em>urlstring</em> or <code class="docutils literal notranslate"><span class="pre">None</span></code>, except that the <code class="docutils literal notranslate"><span class="pre">''</span></code> is319always allowed, and is automatically converted to <code class="docutils literal notranslate"><span class="pre">b''</span></code> if appropriate.</p>320<p>If the <em>allow_fragments</em> argument is false, fragment identifiers are not321recognized. Instead, they are parsed as part of the path322or query component, and <code class="xref py py-attr docutils literal notranslate"><span class="pre">fragment</span></code> is set to <code class="docutils literal notranslate"><span class="pre">None</span></code> or the empty323string (depending on the value of <em>missing_as_none</em>) in the return value.</p>324<p>The return value is a <a class="reference internal" href="../glossary.html#term-named-tuple"><span class="xref std std-term">named tuple</span></a>, which means that its items can325be accessed by index or as named attributes, which are:</p>326<table class="docutils align-default">327<thead>328<tr class="row-odd"><th class="head"><p>Attribute</p></th>329<th class="head"><p>Index</p></th>330<th class="head"><p>Value</p></th>331<th class="head"><p>Value if not present</p></th>332</tr>333</thead>334<tbody>335<tr class="row-even"><td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">scheme</span></code></p></td>336<td><p>0</p></td>337<td><p>URL scheme specifier</p></td>338<td><p><em>scheme</em> parameter or339empty string <a class="footnote-reference brackets" href="#id5" id="id1" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a></p></td>340</tr>341<tr class="row-odd"><td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">netloc</span></code></p></td>342<td><p>1</p></td>343<td><p>Network location part</p></td>344<td><p><code class="docutils literal notranslate"><span class="pre">None</span></code> or empty string <a class="footnote-reference brackets" href="#id5" id="id2" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a></p></td>345</tr>346<tr class="row-even"><td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">path</span></code></p></td>347<td><p>2</p></td>348<td><p>Hierarchical path</p></td>349<td><p>empty string</p></td>350</tr>351<tr class="row-odd"><td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">query</span></code></p></td>352<td><p>3</p></td>353<td><p>Query component</p></td>354<td><p><code class="docutils literal notranslate"><span class="pre">None</span></code> or empty string <a class="footnote-reference brackets" href="#id5" id="id3" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a></p></td>355</tr>356<tr class="row-even"><td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">fragment</span></code></p></td>357<td><p>4</p></td>358<td><p>Fragment identifier</p></td>359<td><p><code class="docutils literal notranslate"><span class="pre">None</span></code> or empty string <a class="footnote-reference brackets" href="#id5" id="id4" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a></p></td>360</tr>361<tr class="row-odd"><td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">username</span></code></p></td>362<td></td>363<td><p>User name</p></td>364<td><p><code class="docutils literal notranslate"><span class="pre">None</span></code></p></td>365</tr>366<tr class="row-even"><td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">password</span></code></p></td>367<td></td>368<td><p>Password</p></td>369<td><p><code class="docutils literal notranslate"><span class="pre">None</span></code></p></td>370</tr>371<tr class="row-odd"><td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">hostname</span></code></p></td>372<td></td>373<td><p>Host name (lower case)</p></td>374<td><p><code class="docutils literal notranslate"><span class="pre">None</span></code></p></td>375</tr>376<tr class="row-even"><td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">port</span></code></p></td>377<td></td>378<td><p>Port number as integer,379if present</p></td>380<td><p><code class="docutils literal notranslate"><span class="pre">None</span></code></p></td>381</tr>382</tbody>383</table>384<aside class="footnote-list brackets">385<aside class="footnote brackets" id="id5" role="doc-footnote">386<span class="label"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></span>387<span class="backrefs">(<a role="doc-backlink" href="#id1">1</a>,<a role="doc-backlink" href="#id2">2</a>,<a role="doc-backlink" href="#id3">3</a>,<a role="doc-backlink" href="#id4">4</a>)</span>388<p>Depending on the value of the <em>missing_as_none</em> argument.</p>389</aside>390</aside>391<p>Reading the <code class="xref py py-attr docutils literal notranslate"><span class="pre">port</span></code> attribute will raise a <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> if392an invalid port is specified in the URL. See section393<a class="reference internal" href="#urlparse-result-object"><span class="std std-ref">Structured Parse Results</span></a> for more information on the result object.</p>394<p>Unmatched square brackets in the <code class="xref py py-attr docutils literal notranslate"><span class="pre">netloc</span></code> attribute will raise a395<a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a>.</p>396<p>Characters in the <code class="xref py py-attr docutils literal notranslate"><span class="pre">netloc</span></code> attribute that decompose under NFKC397normalization (as used by the IDNA encoding) into any of <code class="docutils literal notranslate"><span class="pre">/</span></code>, <code class="docutils literal notranslate"><span class="pre">?</span></code>,398<code class="docutils literal notranslate"><span class="pre">#</span></code>, <code class="docutils literal notranslate"><span class="pre">@</span></code>, or <code class="docutils literal notranslate"><span class="pre">:</span></code> will raise a <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a>. If the URL is399decomposed before parsing, no error will be raised.</p>400<p>Following some of the <a class="reference external" href="https://url.spec.whatwg.org/#concept-basic-url-parser">WHATWG spec</a> that updates <span class="target" id="index-4"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc3986.html"><strong>RFC 3986</strong></a>, leading C0401control and space characters are stripped from the URL. <code class="docutils literal notranslate"><span class="pre">\n</span></code>,402<code class="docutils literal notranslate"><span class="pre">\r</span></code> and tab <code class="docutils literal notranslate"><span class="pre">\t</span></code> characters are removed from the URL at any position.</p>403<p>As is the case with all named tuples, the subclass has a few additional methods404and attributes that are particularly useful. One such method is <code class="xref py py-meth docutils literal notranslate"><span class="pre">_replace()</span></code>.405The <code class="xref py py-meth docutils literal notranslate"><span class="pre">_replace()</span></code> method will return a new <a class="reference internal" href="#urllib.parse.SplitResult" title="urllib.parse.SplitResult"><code class="xref py py-class docutils literal notranslate"><span class="pre">SplitResult</span></code></a> object406replacing specified fields with new values.</p>407<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">urllib.parse</span><span class="w"> </span><span class="kn">import</span> <span class="n">urlsplit</span>408<span class="gp">>>> </span><span class="n">u</span> <span class="o">=</span> <span class="n">urlsplit</span><span class="p">(</span><span class="s1">'//www.cwi.nl:80/</span><span class="si">%7E</span><span class="s1">guido/Python.html'</span><span class="p">)</span>409<span class="gp">>>> </span><span class="n">u</span>410<span class="go">SplitResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',</span>411<span class="go"> query='', fragment='')</span>412<span class="gp">>>> </span><span class="n">u</span><span class="o">.</span><span class="n">_replace</span><span class="p">(</span><span class="n">scheme</span><span class="o">=</span><span class="s1">'http'</span><span class="p">)</span>413<span class="go">SplitResult(scheme='http', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',</span>414<span class="go"> query='', fragment='')</span>415</pre></div>416</div>417<div class="admonition warning">418<p class="admonition-title">Warning</p>419<p><code class="xref py py-func docutils literal notranslate"><span class="pre">urlsplit()</span></code> does not perform validation. See <a class="reference internal" href="#url-parsing-security"><span class="std std-ref">URL parsing420security</span></a> for details.</p>421</div>422<div class="versionchanged">423<p><span class="versionmodified changed">Changed in version 3.2: </span>Added IPv6 URL parsing capabilities.</p>424</div>425<div class="versionchanged">426<p><span class="versionmodified changed">Changed in version 3.3: </span>The fragment is now parsed for all URL schemes (unless <em>allow_fragments</em> is427false), in accordance with <span class="target" id="index-5"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc3986.html"><strong>RFC 3986</strong></a>. Previously, an allowlist of428schemes that support fragments existed.</p>429</div>430<div class="versionchanged">431<p><span class="versionmodified changed">Changed in version 3.6: </span>Out-of-range port numbers now raise <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a>, instead of432returning <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>433</div>434<div class="versionchanged">435<p><span class="versionmodified changed">Changed in version 3.8: </span>Characters that affect netloc parsing under NFKC normalization will436now raise <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a>.</p>437</div>438<div class="versionchanged">439<p><span class="versionmodified changed">Changed in version 3.10: </span>ASCII newline and tab characters are stripped from the URL.</p>440</div>441<div class="versionchanged">442<p><span class="versionmodified changed">Changed in version 3.12: </span>Leading WHATWG C0 control and space characters are stripped from the URL.</p>443</div>444<div class="versionchanged">445<p><span class="versionmodified changed">Changed in version 3.15: </span>Added the <em>missing_as_none</em> parameter.</p>446</div>447</dd></dl>448 449<dl class="py function">450<dt class="sig sig-object py" id="urllib.parse.parse_qs">451<span class="sig-prename descclassname"><span class="pre">urllib.parse.</span></span><span class="sig-name descname"><span class="pre">parse_qs</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">qs</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">keep_blank_values</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">strict_parsing</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">encoding</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'utf-8'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">errors</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'replace'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">max_num_fields</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">separator</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'&'</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.parse_qs" title="Link to this definition">¶</a></dt>452<dd><p>Parse a query string given as a string argument (data of type453<em class="mimetype">application/x-www-form-urlencoded</em>). Data are returned as a454dictionary. The dictionary keys are the unique query variable names and the455values are lists of values for each name.</p>456<p>The optional argument <em>keep_blank_values</em> is a flag indicating whether blank457values in percent-encoded queries should be treated as blank strings. A true value458indicates that blanks should be retained as blank strings. The default false459value indicates that blank values are to be ignored and treated as if they were460not included.</p>461<p>The optional argument <em>strict_parsing</em> is a flag indicating what to do with462parsing errors. If false (the default), errors are silently ignored. If true,463errors raise a <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> exception.</p>464<p>The optional <em>encoding</em> and <em>errors</em> parameters specify how to decode465percent-encoded sequences into Unicode characters, as accepted by the466<a class="reference internal" href="stdtypes.html#bytes.decode" title="bytes.decode"><code class="xref py py-meth docutils literal notranslate"><span class="pre">bytes.decode()</span></code></a> method.</p>467<p>The optional argument <em>max_num_fields</em> is the maximum number of fields to468read. If set, then throws a <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> if there are more than469<em>max_num_fields</em> fields read.</p>470<p>The optional argument <em>separator</em> is the symbol to use for separating the471query arguments. It defaults to <code class="docutils literal notranslate"><span class="pre">&</span></code>.</p>472<p>Use the <a class="reference internal" href="#urllib.parse.urlencode" title="urllib.parse.urlencode"><code class="xref py py-func docutils literal notranslate"><span class="pre">urllib.parse.urlencode()</span></code></a> function (with the <code class="docutils literal notranslate"><span class="pre">doseq</span></code>473parameter set to <code class="docutils literal notranslate"><span class="pre">True</span></code>) to convert such dictionaries into query474strings.</p>475<div class="versionchanged">476<p><span class="versionmodified changed">Changed in version 3.2: </span>Add <em>encoding</em> and <em>errors</em> parameters.</p>477</div>478<div class="versionchanged">479<p><span class="versionmodified changed">Changed in version 3.8: </span>Added <em>max_num_fields</em> parameter.</p>480</div>481<div class="versionchanged">482<p><span class="versionmodified changed">Changed in version 3.10: </span>Added <em>separator</em> parameter with the default value of <code class="docutils literal notranslate"><span class="pre">&</span></code>. Python483versions earlier than Python 3.10 allowed using both <code class="docutils literal notranslate"><span class="pre">;</span></code> and <code class="docutils literal notranslate"><span class="pre">&</span></code> as484query parameter separator. This has been changed to allow only a single485separator key, with <code class="docutils literal notranslate"><span class="pre">&</span></code> as the default separator.</p>486</div>487<div class="deprecated">488<p><span class="versionmodified deprecated">Deprecated since version 3.14: </span>Accepting objects with false values (like <code class="docutils literal notranslate"><span class="pre">0</span></code> and <code class="docutils literal notranslate"><span class="pre">[]</span></code>) except empty489strings and byte-like objects and <code class="docutils literal notranslate"><span class="pre">None</span></code> is now deprecated.</p>490</div>491</dd></dl>492 493<dl class="py function">494<dt class="sig sig-object py" id="urllib.parse.parse_qsl">495<span class="sig-prename descclassname"><span class="pre">urllib.parse.</span></span><span class="sig-name descname"><span class="pre">parse_qsl</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">qs</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">keep_blank_values</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">strict_parsing</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">encoding</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'utf-8'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">errors</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'replace'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">max_num_fields</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">separator</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'&'</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.parse_qsl" title="Link to this definition">¶</a></dt>496<dd><p>Parse a query string given as a string argument (data of type497<em class="mimetype">application/x-www-form-urlencoded</em>). Data are returned as a list of498name, value pairs.</p>499<p>The optional argument <em>keep_blank_values</em> is a flag indicating whether blank500values in percent-encoded queries should be treated as blank strings. A true value501indicates that blanks should be retained as blank strings. The default false502value indicates that blank values are to be ignored and treated as if they were503not included.</p>504<p>The optional argument <em>strict_parsing</em> is a flag indicating what to do with505parsing errors. If false (the default), errors are silently ignored. If true,506errors raise a <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> exception.</p>507<p>The optional <em>encoding</em> and <em>errors</em> parameters specify how to decode508percent-encoded sequences into Unicode characters, as accepted by the509<a class="reference internal" href="stdtypes.html#bytes.decode" title="bytes.decode"><code class="xref py py-meth docutils literal notranslate"><span class="pre">bytes.decode()</span></code></a> method.</p>510<p>The optional argument <em>max_num_fields</em> is the maximum number of fields to511read. If set, then throws a <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> if there are more than512<em>max_num_fields</em> fields read.</p>513<p>The optional argument <em>separator</em> is the symbol to use for separating the514query arguments. It defaults to <code class="docutils literal notranslate"><span class="pre">&</span></code>.</p>515<p>Use the <a class="reference internal" href="#urllib.parse.urlencode" title="urllib.parse.urlencode"><code class="xref py py-func docutils literal notranslate"><span class="pre">urllib.parse.urlencode()</span></code></a> function to convert such lists of pairs into516query strings.</p>517<div class="versionchanged">518<p><span class="versionmodified changed">Changed in version 3.2: </span>Add <em>encoding</em> and <em>errors</em> parameters.</p>519</div>520<div class="versionchanged">521<p><span class="versionmodified changed">Changed in version 3.8: </span>Added <em>max_num_fields</em> parameter.</p>522</div>523<div class="versionchanged">524<p><span class="versionmodified changed">Changed in version 3.10: </span>Added <em>separator</em> parameter with the default value of <code class="docutils literal notranslate"><span class="pre">&</span></code>. Python525versions earlier than Python 3.10 allowed using both <code class="docutils literal notranslate"><span class="pre">;</span></code> and <code class="docutils literal notranslate"><span class="pre">&</span></code> as526query parameter separator. This has been changed to allow only a single527separator key, with <code class="docutils literal notranslate"><span class="pre">&</span></code> as the default separator.</p>528</div>529</dd></dl>530 531<dl class="py function">532<dt class="sig sig-object py" id="urllib.parse.urlunsplit">533<span class="sig-prename descclassname"><span class="pre">urllib.parse.</span></span><span class="sig-name descname"><span class="pre">urlunsplit</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">parts</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.urlunsplit" title="Link to this definition">¶</a></dt>534<dt class="sig sig-object py">535<span class="sig-prename descclassname"><span class="pre">urllib.parse.</span></span><span class="sig-name descname"><span class="pre">urlunsplit</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">parts</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">keep_empty</span></span></em><span class="sig-paren">)</span></dt>536<dd><p>Construct a URL from a tuple as returned by <a class="reference internal" href="#urllib.parse.urlsplit" title="urllib.parse.urlsplit"><code class="xref py py-func docutils literal notranslate"><span class="pre">urlsplit()</span></code></a>. The <em>parts</em>537argument can be any five-item iterable.</p>538<p>This may result in a slightly different, but equivalent URL, if the539URL that was parsed originally had unnecessary delimiters (for example,540a <code class="docutils literal notranslate"><span class="pre">?</span></code> with an empty query; the RFC states that these are equivalent).</p>541<p>If <em>keep_empty</em> is true, empty strings are kept in the result (for example,542a <code class="docutils literal notranslate"><span class="pre">?</span></code> for an empty query), only <code class="docutils literal notranslate"><span class="pre">None</span></code> components are omitted.543This allows rebuilding a URL that was parsed with option544<code class="docutils literal notranslate"><span class="pre">missing_as_none=True</span></code>.545By default, <em>keep_empty</em> is true if <em>parts</em> is the result of the546<a class="reference internal" href="#urllib.parse.urlsplit" title="urllib.parse.urlsplit"><code class="xref py py-func docutils literal notranslate"><span class="pre">urlsplit()</span></code></a> call with <code class="docutils literal notranslate"><span class="pre">missing_as_none=True</span></code>.</p>547<div class="versionchanged">548<p><span class="versionmodified changed">Changed in version 3.15: </span>Added the <em>keep_empty</em> parameter.</p>549</div>550</dd></dl>551 552<dl class="py function">553<dt class="sig sig-object py" id="urllib.parse.urlparse">554<span class="sig-prename descclassname"><span class="pre">urllib.parse.</span></span><span class="sig-name descname"><span class="pre">urlparse</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">urlstring</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">scheme</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">allow_fragments</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">missing_as_none</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.urlparse" title="Link to this definition">¶</a></dt>555<dd><p>This is similar to <a class="reference internal" href="#urllib.parse.urlsplit" title="urllib.parse.urlsplit"><code class="xref py py-func docutils literal notranslate"><span class="pre">urlsplit()</span></code></a>, but additionally splits the <em>path</em>556component on <em>path</em> and <em>params</em>.557This function returns a 6-item <a class="reference internal" href="../glossary.html#term-named-tuple"><span class="xref std std-term">named tuple</span></a> <a class="reference internal" href="#urllib.parse.ParseResult" title="urllib.parse.ParseResult"><code class="xref py py-class docutils literal notranslate"><span class="pre">ParseResult</span></code></a>558or <a class="reference internal" href="#urllib.parse.ParseResultBytes" title="urllib.parse.ParseResultBytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">ParseResultBytes</span></code></a>.559Its items are the same as for the <code class="xref py py-func docutils literal notranslate"><span class="pre">urlsplit()</span></code> result, except that560<em>params</em> is inserted at index 3, between <em>path</em> and <em>query</em>.</p>561<p>This function is based on obsoleted <span class="target" id="index-6"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc1738.html"><strong>RFC 1738</strong></a> and <span class="target" id="index-7"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc1808.html"><strong>RFC 1808</strong></a>, which562listed <em>params</em> as the main URL component.563The more recent URL syntax allows parameters to be applied to each segment564of the <em>path</em> portion of the URL (see <span class="target" id="index-8"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc3986.html"><strong>RFC 3986</strong></a>).565<a class="reference internal" href="#urllib.parse.urlsplit" title="urllib.parse.urlsplit"><code class="xref py py-func docutils literal notranslate"><span class="pre">urlsplit()</span></code></a> should generally be used instead of <code class="xref py py-func docutils literal notranslate"><span class="pre">urlparse()</span></code>.566A separate function is needed to separate the path segments and parameters.</p>567</dd></dl>568 569<dl class="py function">570<dt class="sig sig-object py" id="urllib.parse.urlunparse">571<span class="sig-prename descclassname"><span class="pre">urllib.parse.</span></span><span class="sig-name descname"><span class="pre">urlunparse</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">parts</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.urlunparse" title="Link to this definition">¶</a></dt>572<dt class="sig sig-object py">573<span class="sig-prename descclassname"><span class="pre">urllib.parse.</span></span><span class="sig-name descname"><span class="pre">urlunparse</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">parts</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">keep_empty</span></span></em><span class="sig-paren">)</span></dt>574<dd><p>Combine the elements of a tuple as returned by <a class="reference internal" href="#urllib.parse.urlparse" title="urllib.parse.urlparse"><code class="xref py py-func docutils literal notranslate"><span class="pre">urlparse()</span></code></a> into a575complete URL as a string. The <em>parts</em> argument can be any six-item576iterable.</p>577<p>This may result in a slightly different, but equivalent URL, if the578URL that was parsed originally had unnecessary delimiters (for example,579a <code class="docutils literal notranslate"><span class="pre">?</span></code> with an empty query; the RFC states that these are equivalent).</p>580<p>If <em>keep_empty</em> is true, empty strings are kept in the result (for example,581a <code class="docutils literal notranslate"><span class="pre">?</span></code> for an empty query), only <code class="docutils literal notranslate"><span class="pre">None</span></code> components are omitted.582This allows rebuilding a URL that was parsed with option583<code class="docutils literal notranslate"><span class="pre">missing_as_none=True</span></code>.584By default, <em>keep_empty</em> is true if <em>parts</em> is the result of the585<a class="reference internal" href="#urllib.parse.urlparse" title="urllib.parse.urlparse"><code class="xref py py-func docutils literal notranslate"><span class="pre">urlparse()</span></code></a> call with <code class="docutils literal notranslate"><span class="pre">missing_as_none=True</span></code>.</p>586<div class="versionchanged">587<p><span class="versionmodified changed">Changed in version 3.15: </span>Added the <em>keep_empty</em> parameter.</p>588</div>589</dd></dl>590 591<dl class="py function">592<dt class="sig sig-object py" id="urllib.parse.urljoin">593<span class="sig-prename descclassname"><span class="pre">urllib.parse.</span></span><span class="sig-name descname"><span class="pre">urljoin</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">base</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">url</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">allow_fragments</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.urljoin" title="Link to this definition">¶</a></dt>594<dd><p>Construct a full (“absolute”) URL by combining a “base URL” (<em>base</em>) with595another URL (<em>url</em>). Informally, this uses components of the base URL, in596particular the addressing scheme, the network location and (part of) the597path, to provide missing components in the relative URL. For example:</p>598<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">urllib.parse</span><span class="w"> </span><span class="kn">import</span> <span class="n">urljoin</span>599<span class="gp">>>> </span><span class="n">urljoin</span><span class="p">(</span><span class="s1">'http://www.cwi.nl/</span><span class="si">%7E</span><span class="s1">guido/Python.html'</span><span class="p">,</span> <span class="s1">'FAQ.html'</span><span class="p">)</span>600<span class="go">'http://www.cwi.nl/%7Eguido/FAQ.html'</span>601</pre></div>602</div>603<p>The <em>allow_fragments</em> argument has the same meaning and default as for604<a class="reference internal" href="#urllib.parse.urlsplit" title="urllib.parse.urlsplit"><code class="xref py py-func docutils literal notranslate"><span class="pre">urlsplit()</span></code></a>.</p>605<div class="admonition note">606<p class="admonition-title">Note</p>607<p>If <em>url</em> is an absolute URL (that is, it starts with <code class="docutils literal notranslate"><span class="pre">//</span></code> or <code class="docutils literal notranslate"><span class="pre">scheme://</span></code>),608the <em>url</em>’s hostname and/or scheme will be present in the result. For example:</p>609<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">urljoin</span><span class="p">(</span><span class="s1">'http://www.cwi.nl/</span><span class="si">%7E</span><span class="s1">guido/Python.html'</span><span class="p">,</span>610<span class="gp">... </span> <span class="s1">'//www.python.org/</span><span class="si">%7E</span><span class="s1">guido'</span><span class="p">)</span>611<span class="go">'http://www.python.org/%7Eguido'</span>612</pre></div>613</div>614<p>If you do not want that behavior, preprocess the <em>url</em> with <a class="reference internal" href="#urllib.parse.urlsplit" title="urllib.parse.urlsplit"><code class="xref py py-func docutils literal notranslate"><span class="pre">urlsplit()</span></code></a> and615<a class="reference internal" href="#urllib.parse.urlunsplit" title="urllib.parse.urlunsplit"><code class="xref py py-func docutils literal notranslate"><span class="pre">urlunsplit()</span></code></a>, removing possible <em>scheme</em> and <em>netloc</em> parts.</p>616</div>617<div class="admonition warning">618<p class="admonition-title">Warning</p>619<p>Because an absolute URL may be passed as the <code class="docutils literal notranslate"><span class="pre">url</span></code> parameter, it is620generally <strong>not secure</strong> to use <code class="docutils literal notranslate"><span class="pre">urljoin</span></code> with an attacker-controlled621<code class="docutils literal notranslate"><span class="pre">url</span></code>. For example in,622<code class="docutils literal notranslate"><span class="pre">urljoin("https://website.com/users/",</span> <span class="pre">username)</span></code>, if <code class="docutils literal notranslate"><span class="pre">username</span></code> can623contain an absolute URL, the result of <code class="docutils literal notranslate"><span class="pre">urljoin</span></code> will be the absolute624URL.</p>625</div>626<div class="versionchanged">627<p><span class="versionmodified changed">Changed in version 3.5: </span>Behavior updated to match the semantics defined in <span class="target" id="index-9"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc3986.html"><strong>RFC 3986</strong></a>.</p>628</div>629</dd></dl>630 631<dl class="py function">632<dt class="sig sig-object py" id="urllib.parse.urldefrag">633<span class="sig-prename descclassname"><span class="pre">urllib.parse.</span></span><span class="sig-name descname"><span class="pre">urldefrag</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">url</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">missing_as_none</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.urldefrag" title="Link to this definition">¶</a></dt>634<dd><p>If <em>url</em> contains a fragment identifier, return a modified version of <em>url</em>635with no fragment identifier, and the fragment identifier as a separate636string. If there is no fragment identifier in <em>url</em>, return <em>url</em> unmodified637and an empty string (by default) or <code class="docutils literal notranslate"><span class="pre">None</span></code> if <em>missing_as_none</em> is true.</p>638<p>The return value is a <a class="reference internal" href="../glossary.html#term-named-tuple"><span class="xref std std-term">named tuple</span></a>, its items can be accessed by index639or as named attributes:</p>640<table class="docutils align-default">641<thead>642<tr class="row-odd"><th class="head"><p>Attribute</p></th>643<th class="head"><p>Index</p></th>644<th class="head"><p>Value</p></th>645<th class="head"><p>Value if not present</p></th>646</tr>647</thead>648<tbody>649<tr class="row-even"><td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">url</span></code></p></td>650<td><p>0</p></td>651<td><p>URL with no fragment</p></td>652<td><p>empty string</p></td>653</tr>654<tr class="row-odd"><td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">fragment</span></code></p></td>655<td><p>1</p></td>656<td><p>Fragment identifier</p></td>657<td><p><code class="docutils literal notranslate"><span class="pre">None</span></code> or empty string <a class="footnote-reference brackets" href="#id7" id="id6" role="doc-noteref"><span class="fn-bracket">[</span>3<span class="fn-bracket">]</span></a></p></td>658</tr>659</tbody>660</table>661<aside class="footnote-list brackets">662<aside class="footnote brackets" id="id7" role="doc-footnote">663<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id6">3</a><span class="fn-bracket">]</span></span>664<p>Depending on the value of the <em>missing_as_none</em> argument.</p>665</aside>666</aside>667<p>See section <a class="reference internal" href="#urlparse-result-object"><span class="std std-ref">Structured Parse Results</span></a> for more information on the result668object.</p>669<div class="versionchanged">670<p><span class="versionmodified changed">Changed in version 3.2: </span>Result is a structured object rather than a simple 2-tuple.</p>671</div>672<div class="versionchanged">673<p><span class="versionmodified changed">Changed in version 3.15: </span>Added the <em>missing_as_none</em> parameter.</p>674</div>675</dd></dl>676 677<dl class="py function">678<dt class="sig sig-object py" id="urllib.parse.unwrap">679<span class="sig-prename descclassname"><span class="pre">urllib.parse.</span></span><span class="sig-name descname"><span class="pre">unwrap</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">url</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.unwrap" title="Link to this definition">¶</a></dt>680<dd><p>Extract the url from a wrapped URL (that is, a string formatted as681<code class="docutils literal notranslate"><span class="pre"><URL:scheme://host/path></span></code>, <code class="docutils literal notranslate"><span class="pre"><scheme://host/path></span></code>, <code class="docutils literal notranslate"><span class="pre">URL:scheme://host/path</span></code>682or <code class="docutils literal notranslate"><span class="pre">scheme://host/path</span></code>). If <em>url</em> is not a wrapped URL, it is returned683without changes.</p>684</dd></dl>685 686</section>687<section id="url-parsing-security">688<span id="id8"></span><h2>URL parsing security<a class="headerlink" href="#url-parsing-security" title="Link to this heading">¶</a></h2>689<p>The <a class="reference internal" href="#urllib.parse.urlsplit" title="urllib.parse.urlsplit"><code class="xref py py-func docutils literal notranslate"><span class="pre">urlsplit()</span></code></a> and <a class="reference internal" href="#urllib.parse.urlparse" title="urllib.parse.urlparse"><code class="xref py py-func docutils literal notranslate"><span class="pre">urlparse()</span></code></a> APIs do not perform <strong>validation</strong> of690inputs. They may not raise errors on inputs that other applications consider691invalid. They may also succeed on some inputs that might not be considered692URLs elsewhere. Their purpose is for practical functionality rather than693purity.</p>694<p>Instead of raising an exception on unusual input, they may instead return some695component parts as empty strings or <code class="docutils literal notranslate"><span class="pre">None</span></code> (depending on the value of the696<em>missing_as_none</em> argument).697Or components may contain more than perhaps they should.</p>698<p>We recommend that users of these APIs where the values may be used anywhere699with security implications code defensively. Do some verification within your700code before trusting a returned component part. Does that <code class="docutils literal notranslate"><span class="pre">scheme</span></code> make701sense? Is that a sensible <code class="docutils literal notranslate"><span class="pre">path</span></code>? Is there anything strange about that702<code class="docutils literal notranslate"><span class="pre">hostname</span></code>? etc.</p>703<p>What constitutes a URL is not universally well defined. Different applications704have different needs and desired constraints. For instance the living <a class="reference external" href="https://url.spec.whatwg.org/#concept-basic-url-parser">WHATWG705spec</a> describes what user facing web clients such as a web browser require.706While <span class="target" id="index-10"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc3986.html"><strong>RFC 3986</strong></a> is more general. These functions incorporate some aspects of707both, but cannot be claimed compliant with either. The APIs and existing user708code with expectations on specific behaviors predate both standards leading us709to be very cautious about making API behavior changes.</p>710</section>711<section id="parsing-ascii-encoded-bytes">712<span id="id9"></span><h2>Parsing ASCII Encoded Bytes<a class="headerlink" href="#parsing-ascii-encoded-bytes" title="Link to this heading">¶</a></h2>713<p>The URL parsing functions were originally designed to operate on character714strings only. In practice, it is useful to be able to manipulate properly715quoted and encoded URLs as sequences of ASCII bytes. Accordingly, the716URL parsing functions in this module all operate on <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> and717<a class="reference internal" href="stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a> objects in addition to <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> objects.</p>718<p>If <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> data is passed in, the result will also contain only719<code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code> data. If <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> or <a class="reference internal" href="stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a> data is720passed in, the result will contain only <code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code> data.</p>721<p>Attempting to mix <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> data with <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> or722<a class="reference internal" href="stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a> in a single function call will result in a723<a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> being raised, while attempting to pass in non-ASCII724byte values will trigger <a class="reference internal" href="exceptions.html#UnicodeDecodeError" title="UnicodeDecodeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UnicodeDecodeError</span></code></a>.</p>725<p>To support easier conversion of result objects between <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> and726<a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a>, all return values from URL parsing functions provide727either an <code class="xref py py-meth docutils literal notranslate"><span class="pre">encode()</span></code> method (when the result contains <code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code>728data) or a <code class="xref py py-meth docutils literal notranslate"><span class="pre">decode()</span></code> method (when the result contains <code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code>729data). The signatures of these methods match those of the corresponding730<code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code> and <code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code> methods (except that the default encoding731is <code class="docutils literal notranslate"><span class="pre">'ascii'</span></code> rather than <code class="docutils literal notranslate"><span class="pre">'utf-8'</span></code>). Each produces a value of a732corresponding type that contains either <code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code> data (for733<code class="xref py py-meth docutils literal notranslate"><span class="pre">encode()</span></code> methods) or <code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code> data (for734<code class="xref py py-meth docutils literal notranslate"><span class="pre">decode()</span></code> methods).</p>735<p>Applications that need to operate on potentially improperly quoted URLs736that may contain non-ASCII data will need to do their own decoding from737bytes to characters before invoking the URL parsing methods.</p>738<p>The behaviour described in this section applies only to the URL parsing739functions. The URL quoting functions use their own rules when producing740or consuming byte sequences as detailed in the documentation of the741individual URL quoting functions.</p>742<div class="versionchanged">743<p><span class="versionmodified changed">Changed in version 3.2: </span>URL parsing functions now accept ASCII encoded byte sequences</p>744</div>745</section>746<section id="structured-parse-results">747<span id="urlparse-result-object"></span><h2>Structured Parse Results<a class="headerlink" href="#structured-parse-results" title="Link to this heading">¶</a></h2>748<p>The result objects from the <a class="reference internal" href="#urllib.parse.urlsplit" title="urllib.parse.urlsplit"><code class="xref py py-func docutils literal notranslate"><span class="pre">urlsplit()</span></code></a>, <a class="reference internal" href="#urllib.parse.urlparse" title="urllib.parse.urlparse"><code class="xref py py-func docutils literal notranslate"><span class="pre">urlparse()</span></code></a> and749<a class="reference internal" href="#urllib.parse.urldefrag" title="urllib.parse.urldefrag"><code class="xref py py-func docutils literal notranslate"><span class="pre">urldefrag()</span></code></a> functions are subclasses of the <a class="reference internal" href="stdtypes.html#tuple" title="tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a> type.750These subclasses add the attributes listed in the documentation for751those functions, the encoding and decoding support described in the752previous section, as well as an additional method:</p>753<dl class="py method">754<dt class="sig sig-object py" id="urllib.parse.urllib.parse.SplitResult.geturl">755<span class="sig-prename descclassname"><span class="pre">urllib.parse.SplitResult.</span></span><span class="sig-name descname"><span class="pre">geturl</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.urllib.parse.SplitResult.geturl" title="Link to this definition">¶</a></dt>756<dd><p>Return the re-combined version of the original URL as a string. This may757differ from the original URL in that the scheme may be normalized to lower758case and empty components may be dropped. Specifically, empty parameters,759queries, and fragment identifiers will be removed unless the URL was parsed760with <code class="docutils literal notranslate"><span class="pre">missing_as_none=True</span></code>.</p>761<p>For <a class="reference internal" href="#urllib.parse.urldefrag" title="urllib.parse.urldefrag"><code class="xref py py-func docutils literal notranslate"><span class="pre">urldefrag()</span></code></a> results, only empty fragment identifiers will be removed.762For <a class="reference internal" href="#urllib.parse.urlsplit" title="urllib.parse.urlsplit"><code class="xref py py-func docutils literal notranslate"><span class="pre">urlsplit()</span></code></a> and <a class="reference internal" href="#urllib.parse.urlparse" title="urllib.parse.urlparse"><code class="xref py py-func docutils literal notranslate"><span class="pre">urlparse()</span></code></a> results, all noted changes will be763made to the URL returned by this method.</p>764<p>The result of this method remains unchanged if passed back through the original765parsing function:</p>766<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">urllib.parse</span><span class="w"> </span><span class="kn">import</span> <span class="n">urlsplit</span>767<span class="gp">>>> </span><span class="n">url</span> <span class="o">=</span> <span class="s1">'HTTP://www.Python.org/doc/#'</span>768<span class="gp">>>> </span><span class="n">r1</span> <span class="o">=</span> <span class="n">urlsplit</span><span class="p">(</span><span class="n">url</span><span class="p">)</span>769<span class="gp">>>> </span><span class="n">r1</span><span class="o">.</span><span class="n">geturl</span><span class="p">()</span>770<span class="go">'http://www.Python.org/doc/'</span>771<span class="gp">>>> </span><span class="n">r2</span> <span class="o">=</span> <span class="n">urlsplit</span><span class="p">(</span><span class="n">r1</span><span class="o">.</span><span class="n">geturl</span><span class="p">())</span>772<span class="gp">>>> </span><span class="n">r2</span><span class="o">.</span><span class="n">geturl</span><span class="p">()</span>773<span class="go">'http://www.Python.org/doc/'</span>774<span class="gp">>>> </span><span class="n">r3</span> <span class="o">=</span> <span class="n">urlsplit</span><span class="p">(</span><span class="n">url</span><span class="p">,</span> <span class="n">missing_as_none</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>775<span class="gp">>>> </span><span class="n">r3</span><span class="o">.</span><span class="n">geturl</span><span class="p">()</span>776<span class="go">'http://www.Python.org/doc/#'</span>777</pre></div>778</div>779</dd></dl>780 781<p>The following classes provide the implementations of the structured parse782results when operating on <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> objects:</p>783<dl class="py class">784<dt class="sig sig-object py" id="urllib.parse.DefragResult">785<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">urllib.parse.</span></span><span class="sig-name descname"><span class="pre">DefragResult</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">url</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">fragment</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.DefragResult" title="Link to this definition">¶</a></dt>786<dd><p>Concrete class for <a class="reference internal" href="#urllib.parse.urldefrag" title="urllib.parse.urldefrag"><code class="xref py py-func docutils literal notranslate"><span class="pre">urldefrag()</span></code></a> results containing <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>787data. The <code class="xref py py-meth docutils literal notranslate"><span class="pre">encode()</span></code> method returns a <a class="reference internal" href="#urllib.parse.DefragResultBytes" title="urllib.parse.DefragResultBytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">DefragResultBytes</span></code></a>788instance.</p>789<div class="versionadded">790<p><span class="versionmodified added">Added in version 3.2.</span></p>791</div>792</dd></dl>793 794<dl class="py class">795<dt class="sig sig-object py" id="urllib.parse.ParseResult">796<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">urllib.parse.</span></span><span class="sig-name descname"><span class="pre">ParseResult</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">scheme</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">netloc</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">path</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">params</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">query</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">fragment</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.ParseResult" title="Link to this definition">¶</a></dt>797<dd><p>Concrete class for <a class="reference internal" href="#urllib.parse.urlparse" title="urllib.parse.urlparse"><code class="xref py py-func docutils literal notranslate"><span class="pre">urlparse()</span></code></a> results containing <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>798data. The <code class="xref py py-meth docutils literal notranslate"><span class="pre">encode()</span></code> method returns a <a class="reference internal" href="#urllib.parse.ParseResultBytes" title="urllib.parse.ParseResultBytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">ParseResultBytes</span></code></a>799instance.</p>800</dd></dl>801 802<dl class="py class">803<dt class="sig sig-object py" id="urllib.parse.SplitResult">804<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">urllib.parse.</span></span><span class="sig-name descname"><span class="pre">SplitResult</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">scheme</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">netloc</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">path</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">query</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">fragment</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.SplitResult" title="Link to this definition">¶</a></dt>805<dd><p>Concrete class for <a class="reference internal" href="#urllib.parse.urlsplit" title="urllib.parse.urlsplit"><code class="xref py py-func docutils literal notranslate"><span class="pre">urlsplit()</span></code></a> results containing <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>806data. The <code class="xref py py-meth docutils literal notranslate"><span class="pre">encode()</span></code> method returns a <a class="reference internal" href="#urllib.parse.SplitResultBytes" title="urllib.parse.SplitResultBytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">SplitResultBytes</span></code></a>807instance.</p>808</dd></dl>809 810<p>The following classes provide the implementations of the parse results when811operating on <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> or <a class="reference internal" href="stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a> objects:</p>812<dl class="py class">813<dt class="sig sig-object py" id="urllib.parse.DefragResultBytes">814<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">urllib.parse.</span></span><span class="sig-name descname"><span class="pre">DefragResultBytes</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">url</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">fragment</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.DefragResultBytes" title="Link to this definition">¶</a></dt>815<dd><p>Concrete class for <a class="reference internal" href="#urllib.parse.urldefrag" title="urllib.parse.urldefrag"><code class="xref py py-func docutils literal notranslate"><span class="pre">urldefrag()</span></code></a> results containing <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a>816data. The <code class="xref py py-meth docutils literal notranslate"><span class="pre">decode()</span></code> method returns a <a class="reference internal" href="#urllib.parse.DefragResult" title="urllib.parse.DefragResult"><code class="xref py py-class docutils literal notranslate"><span class="pre">DefragResult</span></code></a>817instance.</p>818<div class="versionadded">819<p><span class="versionmodified added">Added in version 3.2.</span></p>820</div>821</dd></dl>822 823<dl class="py class">824<dt class="sig sig-object py" id="urllib.parse.ParseResultBytes">825<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">urllib.parse.</span></span><span class="sig-name descname"><span class="pre">ParseResultBytes</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">scheme</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">netloc</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">path</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">params</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">query</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">fragment</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.ParseResultBytes" title="Link to this definition">¶</a></dt>826<dd><p>Concrete class for <a class="reference internal" href="#urllib.parse.urlparse" title="urllib.parse.urlparse"><code class="xref py py-func docutils literal notranslate"><span class="pre">urlparse()</span></code></a> results containing <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a>827data. The <code class="xref py py-meth docutils literal notranslate"><span class="pre">decode()</span></code> method returns a <a class="reference internal" href="#urllib.parse.ParseResult" title="urllib.parse.ParseResult"><code class="xref py py-class docutils literal notranslate"><span class="pre">ParseResult</span></code></a>828instance.</p>829<div class="versionadded">830<p><span class="versionmodified added">Added in version 3.2.</span></p>831</div>832</dd></dl>833 834<dl class="py class">835<dt class="sig sig-object py" id="urllib.parse.SplitResultBytes">836<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">urllib.parse.</span></span><span class="sig-name descname"><span class="pre">SplitResultBytes</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">scheme</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">netloc</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">path</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">query</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">fragment</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.SplitResultBytes" title="Link to this definition">¶</a></dt>837<dd><p>Concrete class for <a class="reference internal" href="#urllib.parse.urlsplit" title="urllib.parse.urlsplit"><code class="xref py py-func docutils literal notranslate"><span class="pre">urlsplit()</span></code></a> results containing <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a>838data. The <code class="xref py py-meth docutils literal notranslate"><span class="pre">decode()</span></code> method returns a <a class="reference internal" href="#urllib.parse.SplitResult" title="urllib.parse.SplitResult"><code class="xref py py-class docutils literal notranslate"><span class="pre">SplitResult</span></code></a>839instance.</p>840<div class="versionadded">841<p><span class="versionmodified added">Added in version 3.2.</span></p>842</div>843</dd></dl>844 845</section>846<section id="url-quoting">847<h2>URL Quoting<a class="headerlink" href="#url-quoting" title="Link to this heading">¶</a></h2>848<p>The URL quoting functions focus on taking program data and making it safe849for use as URL components by quoting special characters and appropriately850encoding non-ASCII text. They also support reversing these operations to851recreate the original data from the contents of a URL component if that852task isn’t already covered by the URL parsing functions above.</p>853<dl class="py function">854<dt class="sig sig-object py" id="urllib.parse.quote">855<span class="sig-prename descclassname"><span class="pre">urllib.parse.</span></span><span class="sig-name descname"><span class="pre">quote</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">string</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">safe</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'/'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">encoding</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">errors</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.quote" title="Link to this definition">¶</a></dt>856<dd><p>Replace special characters in <em>string</em> using the <code class="samp docutils literal notranslate"><span class="pre">%</span><em><span class="pre">xx</span></em></code> escape. Letters,857digits, and the characters <code class="docutils literal notranslate"><span class="pre">'_.-~'</span></code> are never quoted. By default, this858function is intended for quoting the path section of a URL. The optional859<em>safe</em> parameter specifies additional ASCII characters that should not be860quoted — its default value is <code class="docutils literal notranslate"><span class="pre">'/'</span></code>.</p>861<p><em>string</em> may be either a <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> or a <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> object.</p>862<div class="versionchanged">863<p><span class="versionmodified changed">Changed in version 3.7: </span>Moved from <span class="target" id="index-11"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2396.html"><strong>RFC 2396</strong></a> to <span class="target" id="index-12"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc3986.html"><strong>RFC 3986</strong></a> for quoting URL strings. “~” is now864included in the set of unreserved characters.</p>865</div>866<p>The optional <em>encoding</em> and <em>errors</em> parameters specify how to deal with867non-ASCII characters, as accepted by the <a class="reference internal" href="stdtypes.html#str.encode" title="str.encode"><code class="xref py py-meth docutils literal notranslate"><span class="pre">str.encode()</span></code></a> method.868<em>encoding</em> defaults to <code class="docutils literal notranslate"><span class="pre">'utf-8'</span></code>.869<em>errors</em> defaults to <code class="docutils literal notranslate"><span class="pre">'strict'</span></code>, meaning unsupported characters raise a870<a class="reference internal" href="exceptions.html#UnicodeEncodeError" title="UnicodeEncodeError"><code class="xref py py-class docutils literal notranslate"><span class="pre">UnicodeEncodeError</span></code></a>.871<em>encoding</em> and <em>errors</em> must not be supplied if <em>string</em> is a872<a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a>, or a <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-class docutils literal notranslate"><span class="pre">TypeError</span></code></a> is raised.</p>873<p>Note that <code class="docutils literal notranslate"><span class="pre">quote(string,</span> <span class="pre">safe,</span> <span class="pre">encoding,</span> <span class="pre">errors)</span></code> is equivalent to874<code class="docutils literal notranslate"><span class="pre">quote_from_bytes(string.encode(encoding,</span> <span class="pre">errors),</span> <span class="pre">safe)</span></code>.</p>875<p>Example: <code class="docutils literal notranslate"><span class="pre">quote('/El</span> <span class="pre">Niño/')</span></code> yields <code class="docutils literal notranslate"><span class="pre">'/El%20Ni%C3%B1o/'</span></code>.</p>876</dd></dl>877 878<dl class="py function">879<dt class="sig sig-object py" id="urllib.parse.quote_plus">880<span class="sig-prename descclassname"><span class="pre">urllib.parse.</span></span><span class="sig-name descname"><span class="pre">quote_plus</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">string</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">safe</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">''</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">encoding</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">errors</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.quote_plus" title="Link to this definition">¶</a></dt>881<dd><p>Like <a class="reference internal" href="#urllib.parse.quote" title="urllib.parse.quote"><code class="xref py py-func docutils literal notranslate"><span class="pre">quote()</span></code></a>, but also replace spaces with plus signs, as required for882quoting HTML form values when building up a query string to go into a URL.883Plus signs in the original string are escaped unless they are included in884<em>safe</em>. It also does not have <em>safe</em> default to <code class="docutils literal notranslate"><span class="pre">'/'</span></code>.</p>885<p>Example: <code class="docutils literal notranslate"><span class="pre">quote_plus('/El</span> <span class="pre">Niño/')</span></code> yields <code class="docutils literal notranslate"><span class="pre">'%2FEl+Ni%C3%B1o%2F'</span></code>.</p>886</dd></dl>887 888<dl class="py function">889<dt class="sig sig-object py" id="urllib.parse.quote_from_bytes">890<span class="sig-prename descclassname"><span class="pre">urllib.parse.</span></span><span class="sig-name descname"><span class="pre">quote_from_bytes</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">bytes</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">safe</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'/'</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.quote_from_bytes" title="Link to this definition">¶</a></dt>891<dd><p>Like <a class="reference internal" href="#urllib.parse.quote" title="urllib.parse.quote"><code class="xref py py-func docutils literal notranslate"><span class="pre">quote()</span></code></a>, but accepts a <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> object rather than a892<a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>, and does not perform string-to-bytes encoding.</p>893<p>Example: <code class="docutils literal notranslate"><span class="pre">quote_from_bytes(b'a&\xef')</span></code> yields894<code class="docutils literal notranslate"><span class="pre">'a%26%EF'</span></code>.</p>895</dd></dl>896 897<dl class="py function">898<dt class="sig sig-object py" id="urllib.parse.unquote">899<span class="sig-prename descclassname"><span class="pre">urllib.parse.</span></span><span class="sig-name descname"><span class="pre">unquote</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">string</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">encoding</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'utf-8'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">errors</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'replace'</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.unquote" title="Link to this definition">¶</a></dt>900<dd><p>Replace <code class="samp docutils literal notranslate"><span class="pre">%</span><em><span class="pre">xx</span></em></code> escapes with their single-character equivalent.901The optional <em>encoding</em> and <em>errors</em> parameters specify how to decode902percent-encoded sequences into Unicode characters, as accepted by the903<a class="reference internal" href="stdtypes.html#bytes.decode" title="bytes.decode"><code class="xref py py-meth docutils literal notranslate"><span class="pre">bytes.decode()</span></code></a> method.</p>904<p><em>string</em> may be either a <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> or a <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> object.</p>905<p><em>encoding</em> defaults to <code class="docutils literal notranslate"><span class="pre">'utf-8'</span></code>.906<em>errors</em> defaults to <code class="docutils literal notranslate"><span class="pre">'replace'</span></code>, meaning invalid sequences are replaced907by a placeholder character.</p>908<p>Example: <code class="docutils literal notranslate"><span class="pre">unquote('/El%20Ni%C3%B1o/')</span></code> yields <code class="docutils literal notranslate"><span class="pre">'/El</span> <span class="pre">Niño/'</span></code>.</p>909<div class="versionchanged">910<p><span class="versionmodified changed">Changed in version 3.9: </span><em>string</em> parameter supports bytes and str objects (previously only str).</p>911</div>912</dd></dl>913 914<dl class="py function">915<dt class="sig sig-object py" id="urllib.parse.unquote_plus">916<span class="sig-prename descclassname"><span class="pre">urllib.parse.</span></span><span class="sig-name descname"><span class="pre">unquote_plus</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">string</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">encoding</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'utf-8'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">errors</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'replace'</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.unquote_plus" title="Link to this definition">¶</a></dt>917<dd><p>Like <a class="reference internal" href="#urllib.parse.unquote" title="urllib.parse.unquote"><code class="xref py py-func docutils literal notranslate"><span class="pre">unquote()</span></code></a>, but also replace plus signs with spaces, as required918for unquoting HTML form values.</p>919<p><em>string</em> must be a <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>.</p>920<p>Example: <code class="docutils literal notranslate"><span class="pre">unquote_plus('/El+Ni%C3%B1o/')</span></code> yields <code class="docutils literal notranslate"><span class="pre">'/El</span> <span class="pre">Niño/'</span></code>.</p>921</dd></dl>922 923<dl class="py function">924<dt class="sig sig-object py" id="urllib.parse.unquote_to_bytes">925<span class="sig-prename descclassname"><span class="pre">urllib.parse.</span></span><span class="sig-name descname"><span class="pre">unquote_to_bytes</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">string</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.unquote_to_bytes" title="Link to this definition">¶</a></dt>926<dd><p>Replace <code class="samp docutils literal notranslate"><span class="pre">%</span><em><span class="pre">xx</span></em></code> escapes with their single-octet equivalent, and return a927<a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> object.</p>928<p><em>string</em> may be either a <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> or a <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> object.</p>929<p>If it is a <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>, unescaped non-ASCII characters in <em>string</em>930are encoded into UTF-8 bytes.</p>931<p>Example: <code class="docutils literal notranslate"><span class="pre">unquote_to_bytes('a%26%EF')</span></code> yields <code class="docutils literal notranslate"><span class="pre">b'a&\xef'</span></code>.</p>932</dd></dl>933 934<dl class="py function">935<dt class="sig sig-object py" id="urllib.parse.urlencode">936<span class="sig-prename descclassname"><span class="pre">urllib.parse.</span></span><span class="sig-name descname"><span class="pre">urlencode</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">query</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">doseq</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">safe</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">''</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">encoding</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">errors</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">quote_via</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">quote_plus</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.urlencode" title="Link to this definition">¶</a></dt>937<dd><p>Convert a mapping object or a sequence of two-element tuples, which may938contain <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> or <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> objects, to a percent-encoded ASCII939text string. If the resultant string is to be used as a <em>data</em> for POST940operation with the <a class="reference internal" href="urllib.request.html#urllib.request.urlopen" title="urllib.request.urlopen"><code class="xref py py-func docutils literal notranslate"><span class="pre">urlopen()</span></code></a> function, then941it should be encoded to bytes, otherwise it would result in a942<a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>.</p>943<p>The resulting string is a series of <code class="docutils literal notranslate"><span class="pre">key=value</span></code> pairs separated by <code class="docutils literal notranslate"><span class="pre">'&'</span></code>944characters, where both <em>key</em> and <em>value</em> are quoted using the <em>quote_via</em>945function. By default, <a class="reference internal" href="#urllib.parse.quote_plus" title="urllib.parse.quote_plus"><code class="xref py py-func docutils literal notranslate"><span class="pre">quote_plus()</span></code></a> is used to quote the values, which946means spaces are quoted as a <code class="docutils literal notranslate"><span class="pre">'+'</span></code> character and ‘/’ characters are947encoded as <code class="docutils literal notranslate"><span class="pre">%2F</span></code>, which follows the standard for GET requests948(<code class="docutils literal notranslate"><span class="pre">application/x-www-form-urlencoded</span></code>). An alternate function that can be949passed as <em>quote_via</em> is <a class="reference internal" href="#urllib.parse.quote" title="urllib.parse.quote"><code class="xref py py-func docutils literal notranslate"><span class="pre">quote()</span></code></a>, which will encode spaces as <code class="docutils literal notranslate"><span class="pre">%20</span></code>950and not encode ‘/’ characters. For maximum control of what is quoted, use951<code class="docutils literal notranslate"><span class="pre">quote</span></code> and specify a value for <em>safe</em>.</p>952<p>When a sequence of two-element tuples is used as the <em>query</em>953argument, the first element of each tuple is a key and the second is a954value. The value element in itself can be a sequence and in that case, if955the optional parameter <em>doseq</em> evaluates to <code class="docutils literal notranslate"><span class="pre">True</span></code>, individual956<code class="docutils literal notranslate"><span class="pre">key=value</span></code> pairs separated by <code class="docutils literal notranslate"><span class="pre">'&'</span></code> are generated for each element of957the value sequence for the key. The order of parameters in the encoded958string will match the order of parameter tuples in the sequence.</p>959<p>The <em>safe</em>, <em>encoding</em>, and <em>errors</em> parameters are passed down to960<em>quote_via</em> (the <em>encoding</em> and <em>errors</em> parameters are only passed961when a query element is a <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>).</p>962<p>To reverse this encoding process, <a class="reference internal" href="#urllib.parse.parse_qs" title="urllib.parse.parse_qs"><code class="xref py py-func docutils literal notranslate"><span class="pre">parse_qs()</span></code></a> and <a class="reference internal" href="#urllib.parse.parse_qsl" title="urllib.parse.parse_qsl"><code class="xref py py-func docutils literal notranslate"><span class="pre">parse_qsl()</span></code></a> are963provided in this module to parse query strings into Python data structures.</p>964<p>Refer to <a class="reference internal" href="urllib.request.html#urllib-examples"><span class="std std-ref">urllib examples</span></a> to find out how the965<a class="reference internal" href="#urllib.parse.urlencode" title="urllib.parse.urlencode"><code class="xref py py-func docutils literal notranslate"><span class="pre">urllib.parse.urlencode()</span></code></a> method can be used for generating the query966string of a URL or data for a POST request.</p>967<div class="versionchanged">968<p><span class="versionmodified changed">Changed in version 3.2: </span><em>query</em> supports bytes and string objects.</p>969</div>970<div class="versionchanged">971<p><span class="versionmodified changed">Changed in version 3.5: </span>Added the <em>quote_via</em> parameter.</p>972</div>973<div class="deprecated">974<p><span class="versionmodified deprecated">Deprecated since version 3.14: </span>Accepting objects with false values (like <code class="docutils literal notranslate"><span class="pre">0</span></code> and <code class="docutils literal notranslate"><span class="pre">[]</span></code>) except empty975strings and byte-like objects and <code class="docutils literal notranslate"><span class="pre">None</span></code> is now deprecated.</p>976</div>977</dd></dl>978 979<div class="admonition seealso">980<p class="admonition-title">See also</p>981<dl class="simple">982<dt><a class="reference external" href="https://url.spec.whatwg.org/">WHATWG</a> - URL Living standard</dt><dd><p>Working Group for the URL Standard that defines URLs, domains, IP addresses, the983application/x-www-form-urlencoded format, and their API.</p>984</dd>985<dt><span class="target" id="index-13"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc3986.html"><strong>RFC 3986</strong></a> - Uniform Resource Identifiers</dt><dd><p>This is the current standard (STD66). Any changes to urllib.parse module986should conform to this. Certain deviations could be observed, which are987mostly for backward compatibility purposes and for certain de-facto988parsing requirements as commonly observed in major browsers.</p>989</dd>990<dt><span class="target" id="index-14"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2732.html"><strong>RFC 2732</strong></a> - Format for Literal IPv6 Addresses in URL’s.</dt><dd><p>This specifies the parsing requirements of IPv6 URLs.</p>991</dd>992<dt><span class="target" id="index-15"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2396.html"><strong>RFC 2396</strong></a> - Uniform Resource Identifiers (URI): Generic Syntax</dt><dd><p>Document describing the generic syntactic requirements for both Uniform Resource993Names (URNs) and Uniform Resource Locators (URLs).</p>994</dd>995<dt><span class="target" id="index-16"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2368.html"><strong>RFC 2368</strong></a> - The mailto URL scheme.</dt><dd><p>Parsing requirements for mailto URL schemes.</p>996</dd>997<dt><span class="target" id="index-17"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc1808.html"><strong>RFC 1808</strong></a> - Relative Uniform Resource Locators</dt><dd><p>This Request For Comments includes the rules for joining an absolute and a998relative URL, including a fair number of “Abnormal Examples” which govern the999treatment of border cases.</p>1000</dd>1001<dt><span class="target" id="index-18"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc1738.html"><strong>RFC 1738</strong></a> - Uniform Resource Locators (URL)</dt><dd><p>This specifies the formal syntax and semantics of absolute URLs.</p>1002</dd>1003</dl>1004</div>1005</section>1006</section>1007 1008 1009 <div class="clearer"></div>1010 </div>1011 </div>1012 </div>1013 <div class="sphinxsidebar" role="navigation" aria-label="Main">1014 <div class="sphinxsidebarwrapper">1015 <div>1016 <h3><a href="../contents.html">Table of Contents</a></h3>1017 <ul>1018<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">urllib.parse</span></code> — Parse URLs into components</a><ul>1019<li><a class="reference internal" href="#url-parsing">URL Parsing</a></li>1020<li><a class="reference internal" href="#url-parsing-security">URL parsing security</a></li>1021<li><a class="reference internal" href="#parsing-ascii-encoded-bytes">Parsing ASCII Encoded Bytes</a></li>1022<li><a class="reference internal" href="#structured-parse-results">Structured Parse Results</a></li>1023<li><a class="reference internal" href="#url-quoting">URL Quoting</a></li>1024</ul>1025</li>1026</ul>1027 1028 </div>1029 <div>1030 <h4>Previous topic</h4>1031 <p class="topless"><a href="urllib.request.html"1032 title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">urllib.request</span></code> — Extensible library for opening URLs</a></p>1033 </div>1034 <div>1035 <h4>Next topic</h4>1036 <p class="topless"><a href="urllib.error.html"1037 title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">urllib.error</span></code> — Exception classes raised by urllib.request</a></p>1038 </div>1039 <script>1040 document.addEventListener('DOMContentLoaded', () => {1041 const title = document.querySelector('meta[property="og:title"]').content;1042 const elements = document.querySelectorAll('.improvepage');1043 const pageurl = window.location.href.split('?')[0];1044 elements.forEach(element => {1045 const url = new URL(element.href.split('?')[0].replace("-nojs", ""));1046 url.searchParams.set('pagetitle', title);1047 url.searchParams.set('pageurl', pageurl);1048 url.searchParams.set('pagesource', "library/urllib.parse.rst");1049 element.href = url.toString();1050 });1051 });1052 </script>1053 <div role="note" aria-label="source link">1054 <h3>This page</h3>1055 <ul class="this-page-menu">1056 <li><a href="../bugs.html">Report a bug</a></li>1057 <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>1058 <li>1059 <a href="https://github.com/python/cpython/blob/main/Doc/library/urllib.parse.rst?plain=1"1060 rel="nofollow">Show source1061 </a>1062 </li>1063 1064 </ul>1065 </div>1066 </div>1067<div id="sidebarbutton" title="Collapse sidebar">1068<span>«</span>1069</div>1070 1071 </div>1072 <div class="clearer"></div>1073 </div> 1074 <div class="related" role="navigation" aria-label="Related">1075 <h3>Navigation</h3>1076 <ul>1077 <li class="right" style="margin-right: 10px">1078 <a href="../genindex.html" title="General Index"1079 >index</a></li>1080 <li class="right" >1081 <a href="../py-modindex.html" title="Python Module Index"1082 >modules</a> |</li>1083 <li class="right" >1084 <a href="urllib.error.html" title="urllib.error — Exception classes raised by urllib.request"1085 >next</a> |</li>1086 <li class="right" >1087 <a href="urllib.request.html" title="urllib.request — Extensible library for opening URLs"1088 >previous</a> |</li>1089 1090 <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>1091 <li><a href="https://www.python.org/">Python</a> »</li>1092 <li class="switchers">1093 <div class="language_switcher_placeholder"></div>1094 <div class="version_switcher_placeholder"></div>1095 </li>1096 <li>1097 1098 </li>1099 <li id="cpython-language-and-version">1100 <a href="../index.html">3.15.0a6 Documentation</a> »1101 </li>1102 1103 <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>1104 <li class="nav-item nav-item-2"><a href="internet.html" >Internet Protocols and Support</a> »</li>1105 <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">urllib.parse</span></code> — Parse URLs into components</a></li>1106 <li class="right">1107 1108 1109 <div class="inline-search" role="search">1110 <form class="inline-search" action="../search.html" method="get">1111 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">1112 <input type="submit" value="Go">1113 </form>1114 </div>1115 |1116 </li>1117 <li class="right">1118<label class="theme-selector-label">1119 Theme1120 <select class="theme-selector" oninput="activateTheme(this.value)">1121 <option value="auto" selected>Auto</option>1122 <option value="light">Light</option>1123 <option value="dark">Dark</option>1124 </select>1125</label> |</li>1126 1127 </ul>1128 </div> 1129 <div class="footer">1130 © <a href="../copyright.html">Copyright</a> 2001 Python Software Foundation.1131 <br>1132 This page is licensed under the Python Software Foundation License Version 2.1133 <br>1134 Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.1135 <br>1136 1137 See <a href="/license.html">History and License</a> for more information.<br>1138 1139 1140 <br>1141 1142 The Python Software Foundation is a non-profit corporation.1143<a href="https://www.python.org/psf/donations/">Please donate.</a>1144<br>1145 <br>1146 Last updated on Mar 10, 2026 (08:58 UTC).1147 1148 <a href="/bugs.html">Found a bug</a>?1149 1150 <br>1151 1152 Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.1153 </div>1154 1155 </body>1156</html>