871 lines
92 KiB
HTML
871 lines
92 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html xmlns="http://www.w3.org/1999/xhtml" lang="zh_CN">
|
||
<head>
|
||
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
|
||
|
||
<title>urllib.parse 用于解析 URL — Python 3.8.20 文档</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
|
||
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||
|
||
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
|
||
<script src="../_static/jquery.js"></script>
|
||
<script src="../_static/underscore.js"></script>
|
||
<script src="../_static/doctools.js"></script>
|
||
<script src="../_static/language_data.js"></script>
|
||
<script src="../_static/translations.js"></script>
|
||
|
||
<script src="../_static/sidebar.js"></script>
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml"
|
||
title="在 Python 3.8.20 文档 中搜索"
|
||
href="../_static/opensearch.xml"/>
|
||
<link rel="author" title="关于这些文档" href="../about.html" />
|
||
<link rel="index" title="索引" href="../genindex.html" />
|
||
<link rel="search" title="搜索" href="../search.html" />
|
||
<link rel="copyright" title="版权所有" href="../copyright.html" />
|
||
<link rel="next" title="urllib.error --- urllib.request 引发的异常类" href="urllib.error.html" />
|
||
<link rel="prev" title="urllib.request --- 用于打开 URL 的可扩展库" href="urllib.request.html" />
|
||
<link rel="canonical" href="https://docs.python.org/3/library/urllib.parse.html" />
|
||
|
||
|
||
|
||
|
||
|
||
<style>
|
||
@media only screen {
|
||
table.full-width-table {
|
||
width: 100%;
|
||
}
|
||
}
|
||
</style>
|
||
<link rel="shortcut icon" type="image/png" href="../_static/py.svg" />
|
||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||
<script type="text/javascript" src="../_static/menu.js"></script>
|
||
|
||
</head>
|
||
<body>
|
||
<div class="mobile-nav">
|
||
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
|
||
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />
|
||
<label for="menuToggler" class="toggler__label">
|
||
<span></span>
|
||
</label>
|
||
<nav class="nav-content" role="navigation">
|
||
<a href="https://www.python.org/" class="nav-logo">
|
||
<img src="../_static/py.svg" alt="Logo"/>
|
||
</a>
|
||
<div class="version_switcher_placeholder"></div>
|
||
<form role="search" class="search" action="../search.html" method="get">
|
||
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
|
||
<path fill-rule="nonzero"
|
||
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" fill="#444"></path>
|
||
</svg>
|
||
<input type="text" name="q" aria-label="快速搜索"/>
|
||
<input type="submit" value="转向"/>
|
||
</form>
|
||
</nav>
|
||
<div class="menu-wrapper">
|
||
<nav class="menu" role="navigation" aria-label="main navigation">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<h3><a href="../contents.html">目录</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">urllib.parse</span></code> 用于解析 URL</a><ul>
|
||
<li><a class="reference internal" href="#url-parsing">URL 解析</a></li>
|
||
<li><a class="reference internal" href="#url-parsing-security">URL parsing security</a></li>
|
||
<li><a class="reference internal" href="#parsing-ascii-encoded-bytes">解析ASCII编码字节</a></li>
|
||
<li><a class="reference internal" href="#structured-parse-results">结构化解析结果</a></li>
|
||
<li><a class="reference internal" href="#url-quoting">URL 转码</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>上一个主题</h4>
|
||
<p class="topless"><a href="urllib.request.html"
|
||
title="上一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">urllib.request</span></code> --- 用于打开 URL 的可扩展库</a></p>
|
||
<h4>下一个主题</h4>
|
||
<p class="topless"><a href="urllib.error.html"
|
||
title="下一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">urllib.error</span></code> --- urllib.request 引发的异常类</a></p>
|
||
<div role="note" aria-label="source link">
|
||
<h3>本页</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">报告 Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/3.8/Doc/library/urllib.parse.rst"
|
||
rel="nofollow">显示源代码
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
|
||
<div id="outdated-warning" style="padding: .5em; text-align: center; background-color: #FFBABA; color: #6A0E0E;">
|
||
这个文档所针对的是一个已不再受支持的 Python 旧版本。
|
||
你应当升级版本，并阅读
|
||
<a href="/3/library/urllib.parse.html"> Python 当前稳定版本的文档</a>.
|
||
</div>
|
||
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>导航</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="总目录"
|
||
accesskey="I">索引</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python 模块索引"
|
||
>模块</a> |</li>
|
||
<li class="right" >
|
||
<a href="urllib.error.html" title="urllib.error --- urllib.request 引发的异常类"
|
||
accesskey="N">下一页</a> |</li>
|
||
<li class="right" >
|
||
<a href="urllib.request.html" title="urllib.request --- 用于打开 URL 的可扩展库"
|
||
accesskey="P">上一页</a> |</li>
|
||
|
||
<li><img src="../_static/py.svg" alt="python logo" style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.8.20 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >Python 标准库</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="internet.html" accesskey="U">互联网协议和支持</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="快速搜索" aria-label="快速搜索" type="text" name="q" />
|
||
<input type="submit" value="转向" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<section id="module-urllib.parse">
|
||
<span id="urllib-parse-parse-urls-into-components"></span><h1><a class="reference internal" href="#module-urllib.parse" title="urllib.parse: Parse URLs into or assemble them from components."><code class="xref py py-mod docutils literal notranslate"><span class="pre">urllib.parse</span></code></a> 用于解析 URL<a class="headerlink" href="#module-urllib.parse" title="永久链接至标题">¶</a></h1>
|
||
<p><strong>源代码:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.8/Lib/urllib/parse.py">Lib/urllib/parse.py</a></p>
|
||
<hr class="docutils" id="index-0" />
|
||
<p>该模块定义了一个标准接口，用于URL字符串按组件(协议、网络位置、路径等)分解，或将组件组合回URL字符串，并将 "相对URL "转换为给定 "基础URL "的绝对URL。</p>
|
||
<p>The module has been designed to match the Internet RFC on Relative Uniform
|
||
Resource 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>,
|
||
<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">mailto</span></code>, <code class="docutils literal notranslate"><span class="pre">mms</span></code>,
|
||
<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">rtspu</span></code>, <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>, <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>
|
||
<p><a class="reference internal" href="#module-urllib.parse" title="urllib.parse: Parse URLs into or assemble them from components."><code class="xref py py-mod docutils literal notranslate"><span class="pre">urllib.parse</span></code></a> 模块定义的函数可分为两个主要门类: URL 解析和 URL 转码。 这些函数将在以下各节中详细说明。</p>
|
||
<section id="url-parsing">
|
||
<h2>URL 解析<a class="headerlink" href="#url-parsing" title="永久链接至标题">¶</a></h2>
|
||
<p>URL解析功能可以将一个URL字符串分割成其组件，或者将URL组件组合成一个URL字符串。</p>
|
||
<dl class="function">
|
||
<dt id="urllib.parse.urlparse">
|
||
<code class="sig-prename descclassname">urllib.parse.</code><code class="sig-name descname">urlparse</code><span class="sig-paren">(</span><em class="sig-param">urlstring</em>, <em class="sig-param">scheme=''</em>, <em class="sig-param">allow_fragments=True</em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.urlparse" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>Parse a URL into six components, returning a 6-item <a class="reference internal" href="../glossary.html#term-named-tuple"><span class="xref std std-term">named tuple</span></a>. This
|
||
corresponds to the general structure of a URL:
|
||
<code class="docutils literal notranslate"><span class="pre">scheme://netloc/path;parameters?query#fragment</span></code>.
|
||
Each tuple item is a string, possibly empty. The components are not broken up in
|
||
smaller parts (for example, the network location is a single string), and %
|
||
escapes are not expanded. The delimiters as shown above are not part of the
|
||
result, except for a leading slash in the <em>path</em> component, which is retained if
|
||
present. For example:</p>
|
||
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">urllib.parse</span> <span class="kn">import</span> <span class="n">urlparse</span>
|
||
<span class="gp">>>> </span><span class="n">o</span> <span class="o">=</span> <span class="n">urlparse</span><span class="p">(</span><span class="s1">'http://www.cwi.nl:80/</span><span class="si">%7E</span><span class="s1">guido/Python.html'</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">o</span>
|
||
<span class="go">ParseResult(scheme='http', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',</span>
|
||
<span class="go"> params='', query='', fragment='')</span>
|
||
<span class="gp">>>> </span><span class="n">o</span><span class="o">.</span><span class="n">scheme</span>
|
||
<span class="go">'http'</span>
|
||
<span class="gp">>>> </span><span class="n">o</span><span class="o">.</span><span class="n">port</span>
|
||
<span class="go">80</span>
|
||
<span class="gp">>>> </span><span class="n">o</span><span class="o">.</span><span class="n">geturl</span><span class="p">()</span>
|
||
<span class="go">'http://www.cwi.nl:80/%7Eguido/Python.html'</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>根据 <span class="target" id="index-23"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc1808.html"><strong>RFC 1808</strong></a> 中的语法规范，urlparse 仅在 netloc 前面正确地附带了 '//' 的情况下才会识别它。 否则输入会被当作是一个相对 URL 因而以路径的组成部分开头。</p>
|
||
<div class="highlight-pycon3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">urllib.parse</span> <span class="kn">import</span> <span class="n">urlparse</span>
|
||
<span class="gp">>>> </span><span class="n">urlparse</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>
|
||
<span class="go">ParseResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',</span>
|
||
<span class="go"> params='', query='', fragment='')</span>
|
||
<span class="gp">>>> </span><span class="n">urlparse</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>
|
||
<span class="go">ParseResult(scheme='', netloc='', path='www.cwi.nl/%7Eguido/Python.html',</span>
|
||
<span class="go"> params='', query='', fragment='')</span>
|
||
<span class="gp">>>> </span><span class="n">urlparse</span><span class="p">(</span><span class="s1">'help/Python.html'</span><span class="p">)</span>
|
||
<span class="go">ParseResult(scheme='', netloc='', path='help/Python.html', params='',</span>
|
||
<span class="go"> query='', fragment='')</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><em>scheme</em> 参数给出了默认的协议，只有在 URL 未指定协议的情况下才会被使用。 它应该是与 <em>urlstring</em> 相同的类型（文本或字节串），除此之外默认值 <code class="docutils literal notranslate"><span class="pre">''</span></code> 也总是被允许，并会在适当情况下自动转换为 <code class="docutils literal notranslate"><span class="pre">b''</span></code>。</p>
|
||
<p>如果 <em>allow_fragments</em> 参数为假值，则片段标识符不会被识别。 它们会被解析为路径、参数或查询部分，在返回值中 <code class="xref py py-attr docutils literal notranslate"><span class="pre">fragment</span></code> 会被设为空字符串。</p>
|
||
<p>返回值是一个 <a class="reference internal" href="../glossary.html#term-named-tuple"><span class="xref std std-term">named tuple</span></a>，这意味着它的条目可以通过索引或作为命名属性来访问，这些属性是：</p>
|
||
<table class="docutils align-default">
|
||
<colgroup>
|
||
<col style="width: 25%" />
|
||
<col style="width: 10%" />
|
||
<col style="width: 36%" />
|
||
<col style="width: 30%" />
|
||
</colgroup>
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>属性</p></th>
|
||
<th class="head"><p>索引</p></th>
|
||
<th class="head"><p>值</p></th>
|
||
<th class="head"><p>值（如果不存在）</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">scheme</span></code></p></td>
|
||
<td><p>0</p></td>
|
||
<td><p>URL方案说明符</p></td>
|
||
<td><p><em>scheme</em> parameter</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">netloc</span></code></p></td>
|
||
<td><p>1</p></td>
|
||
<td><p>网络位置部分</p></td>
|
||
<td><p>空字符串</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">path</span></code></p></td>
|
||
<td><p>2</p></td>
|
||
<td><p>分层路径</p></td>
|
||
<td><p>空字符串</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">params</span></code></p></td>
|
||
<td><p>3</p></td>
|
||
<td><p>最后路径元素的参数</p></td>
|
||
<td><p>空字符串</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">query</span></code></p></td>
|
||
<td><p>4</p></td>
|
||
<td><p>查询组件</p></td>
|
||
<td><p>空字符串</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">fragment</span></code></p></td>
|
||
<td><p>5</p></td>
|
||
<td><p>片段识别</p></td>
|
||
<td><p>空字符串</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">username</span></code></p></td>
|
||
<td></td>
|
||
<td><p>用户名</p></td>
|
||
<td><p><a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a></p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">password</span></code></p></td>
|
||
<td></td>
|
||
<td><p>密码</p></td>
|
||
<td><p><a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a></p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">hostname</span></code></p></td>
|
||
<td></td>
|
||
<td><p>主机名（小写）</p></td>
|
||
<td><p><a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a></p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">port</span></code></p></td>
|
||
<td></td>
|
||
<td><p>端口号为整数（如果存在）</p></td>
|
||
<td><p><a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a></p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>如果在 URL 中指定了无效的端口，读取 <code class="xref py py-attr docutils literal notranslate"><span class="pre">port</span></code> 属性将引发 <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>。 有关结果对象的更多信息请参阅 <a class="reference internal" href="#urlparse-result-object"><span class="std std-ref">结构化解析结果</span></a> 一节。</p>
|
||
<p>在 <code class="xref py py-attr docutils literal notranslate"><span class="pre">netloc</span></code> 属性中不匹配的方括号将引发 <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>
|
||
<p>如果 <code class="xref py py-attr docutils literal notranslate"><span class="pre">netloc</span></code> 属性中的字符在 NFKC 规范化下（如 IDNA 编码格式所使用的）被分解成 <code class="docutils literal notranslate"><span class="pre">/</span></code>, <code class="docutils literal notranslate"><span class="pre">?</span></code>, <code class="docutils literal notranslate"><span class="pre">#</span></code>, <code class="docutils literal notranslate"><span class="pre">@</span></code> 或 <code class="docutils literal notranslate"><span class="pre">:</span></code> 则将引发 <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>。 如果在解析之前 URL 就被分解，则不会引发错误。</p>
|
||
<p>与所有具名元组的情况一样，该子类还有一些特别有用的附加方法和属性。 其中一个方法是 <code class="xref py py-meth docutils literal notranslate"><span class="pre">_replace()</span></code>。 <code class="xref py py-meth docutils literal notranslate"><span class="pre">_replace()</span></code> 方法将返回一个新的 ParseResult 对象来将指定字段替换为新的值。</p>
|
||
<div class="highlight-pycon3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">urllib.parse</span> <span class="kn">import</span> <span class="n">urlparse</span>
|
||
<span class="gp">>>> </span><span class="n">u</span> <span class="o">=</span> <span class="n">urlparse</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>
|
||
<span class="gp">>>> </span><span class="n">u</span>
|
||
<span class="go">ParseResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',</span>
|
||
<span class="go"> params='', query='', fragment='')</span>
|
||
<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>
|
||
<span class="go">ParseResult(scheme='http', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',</span>
|
||
<span class="go"> params='', query='', fragment='')</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="admonition warning">
|
||
<p class="admonition-title">警告</p>
|
||
<p><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> does not perform validation. See <a class="reference internal" href="#url-parsing-security"><span class="std std-ref">URL parsing
|
||
security</span></a> for details.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.2 版更改: </span>添加了IPv6 URL解析功能。</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.3 版更改: </span>The fragment is now parsed for all URL schemes (unless <em>allow_fragment</em> is
|
||
false), in accordance with <span class="target" id="index-2"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc3986.html"><strong>RFC 3986</strong></a>. Previously, a whitelist of
|
||
schemes that support fragments existed.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.6 版更改: </span>超范围的端口号现在会引发 <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>，而不是返回 <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a>。</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.8 版更改: </span>在 NFKC 规范化下会影响 netloc 解析的字符现在将引发 <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>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="urllib.parse.parse_qs">
|
||
<code class="sig-prename descclassname">urllib.parse.</code><code class="sig-name descname">parse_qs</code><span class="sig-paren">(</span><em class="sig-param">qs</em>, <em class="sig-param">keep_blank_values=False</em>, <em class="sig-param">strict_parsing=False</em>, <em class="sig-param">encoding='utf-8'</em>, <em class="sig-param">errors='replace'</em>, <em class="sig-param">max_num_fields=None</em>, <em class="sig-param">separator='&'</em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.parse_qs" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>解析以字符串参数形式（类型为 <em class="mimetype">application/x-www-form-urlencoded</em> 的数据）给出的查询字符串。 返回字典形式的数据。 结果字典的键为唯一的查询变量名而值为每个变量名对应的值列表。</p>
|
||
<p>可选参数 <em>keep_blank_values</em> 是一个旗标，指明是否要将以百分号转码的空值作为空字符串处理。 真值表示空值应当被保留作为空字符串。 默认的假值表示空值会被忽略并将其视作未包括的值。</p>
|
||
<p>可选参数 <em>strict_parsing</em> 是一个旗标，指明要如何处理解析错误。 如为假值（默认），错误会被静默地忽略。 如为真值，错误会引发 <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>
|
||
<p>可选的 <em>encoding</em> 和 <em>errors</em> 形参指定如何将以百分号编码的序列解码为 Unicode 字符，即作为 <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> 方法所接受的数据。</p>
|
||
<p>可选参数 <em>max_num_fields</em> 是要读取的最大字段数量的。 如果设置，则如果读取的字段超过 <em>max_num_fields</em> 会引发 <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>
|
||
<p>可选参数 <em>separator</em> 是用来分隔查询参数的符号。 默认为 <code class="docutils literal notranslate"><span class="pre">&</span></code>。</p>
|
||
<p>使用 <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> 函数 (并将 <code class="docutils literal notranslate"><span class="pre">doseq</span></code> 形参设为 <code class="docutils literal notranslate"><span class="pre">True</span></code>) 将这样的字典转换为查询字符串。.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.2 版更改: </span>增加了 <em>encoding</em> 和 <em>errors</em> 形参。</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.8 版更改: </span>增加了 <em>max_num_fields</em> 形参。</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.8.8 版更改: </span>Added <em>separator</em> parameter with the default value of <code class="docutils literal notranslate"><span class="pre">&</span></code>. Python
|
||
versions earlier than Python 3.8.8 allowed using both <code class="docutils literal notranslate"><span class="pre">;</span></code> and <code class="docutils literal notranslate"><span class="pre">&</span></code> as
|
||
query parameter separator. This has been changed to allow only a single
|
||
separator key, with <code class="docutils literal notranslate"><span class="pre">&</span></code> as the default separator.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="urllib.parse.parse_qsl">
|
||
<code class="sig-prename descclassname">urllib.parse.</code><code class="sig-name descname">parse_qsl</code><span class="sig-paren">(</span><em class="sig-param">qs</em>, <em class="sig-param">keep_blank_values=False</em>, <em class="sig-param">strict_parsing=False</em>, <em class="sig-param">encoding='utf-8'</em>, <em class="sig-param">errors='replace'</em>, <em class="sig-param">max_num_fields=None</em>, <em class="sig-param">separator='&'</em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.parse_qsl" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>解析以字符串参数形式（类型为 <em class="mimetype">application/x-www-form-urlencoded</em> 的数据）给出的查询字符串。 数据以字段名和字段值对列表的形式返回。</p>
|
||
<p>可选参数 <em>keep_blank_values</em> 是一个旗标，指明是否要将以百分号转码的空值作为空字符串处理。 真值表示空值应当被保留作为空字符串。 默认的假值表示空值会被忽略并将其视作未包括的值。</p>
|
||
<p>可选参数 <em>strict_parsing</em> 是一个旗标，指明要如何处理解析错误。 如为假值（默认），错误会被静默地忽略。 如为真值，错误会引发 <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>
|
||
<p>可选的 <em>encoding</em> 和 <em>errors</em> 形参指定如何将以百分号编码的序列解码为 Unicode 字符，即作为 <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> 方法所接受的数据。</p>
|
||
<p>可选参数 <em>max_num_fields</em> 是要读取的最大字段数量的。 如果设置，则如果读取的字段超过 <em>max_num_fields</em> 会引发 <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>
|
||
<p>可选参数 <em>separator</em> 是用来分隔查询参数的符号。 默认为 <code class="docutils literal notranslate"><span class="pre">&</span></code>。</p>
|
||
<p>使用 <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> 函数将这样的名值对列表转换为查询字符串。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.2 版更改: </span>增加了 <em>encoding</em> 和 <em>errors</em> 形参。</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.8 版更改: </span>增加了 <em>max_num_fields</em> 形参。</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.8.8 版更改: </span>Added <em>separator</em> parameter with the default value of <code class="docutils literal notranslate"><span class="pre">&</span></code>. Python
|
||
versions earlier than Python 3.8.8 allowed using both <code class="docutils literal notranslate"><span class="pre">;</span></code> and <code class="docutils literal notranslate"><span class="pre">&</span></code> as
|
||
query parameter separator. This has been changed to allow only a single
|
||
separator key, with <code class="docutils literal notranslate"><span class="pre">&</span></code> as the default separator.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="urllib.parse.urlunparse">
|
||
<code class="sig-prename descclassname">urllib.parse.</code><code class="sig-name descname">urlunparse</code><span class="sig-paren">(</span><em class="sig-param">parts</em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.urlunparse" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>根据 <code class="docutils literal notranslate"><span class="pre">urlparse()</span></code> 所返回的元组来构造一个 URL。 <em>parts</em> 参数可以是任何包含六个条目的可迭代对象。 构造的结果可能是略有不同但保持等价的 URL，如果被解析的 URL 原本包含不必要的分隔符（例如，带有空查询的 <code class="docutils literal notranslate"><span class="pre">?</span></code>；RFC 已声明这是等价的）。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="urllib.parse.urlsplit">
|
||
<code class="sig-prename descclassname">urllib.parse.</code><code class="sig-name descname">urlsplit</code><span class="sig-paren">(</span><em class="sig-param">urlstring</em>, <em class="sig-param">scheme=''</em>, <em class="sig-param">allow_fragments=True</em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.urlsplit" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>此函数类似于 <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>，但不会拆分来自 URL 的参数。 此函数通常应当在需要允许将参数应用到 URL 的 <em>path</em> 部分的每个分节的较新的 URL 语法的情况下 (参见 <span class="target" id="index-24"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2396.html"><strong>RFC 2396</strong></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>。 需要使用一个拆分函数来拆分路径分节和参数。 此函数将返回包含 5 个条目的 <a class="reference internal" href="../glossary.html#term-named-tuple"><span class="xref std std-term">named tuple</span></a>:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="n">addressing</span> <span class="n">scheme</span><span class="p">,</span> <span class="n">network</span> <span class="n">location</span><span class="p">,</span> <span class="n">path</span><span class="p">,</span> <span class="n">query</span><span class="p">,</span> <span class="n">fragment</span> <span class="n">identifier</span><span class="p">)</span><span class="o">.</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>返回值是一个 <a class="reference internal" href="../glossary.html#term-named-tuple"><span class="xref std std-term">named tuple</span></a>，它的条目可以通过索引或作为命名属性来访问:</p>
|
||
<table class="docutils align-default">
|
||
<colgroup>
|
||
<col style="width: 25%" />
|
||
<col style="width: 10%" />
|
||
<col style="width: 35%" />
|
||
<col style="width: 31%" />
|
||
</colgroup>
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>属性</p></th>
|
||
<th class="head"><p>索引</p></th>
|
||
<th class="head"><p>值</p></th>
|
||
<th class="head"><p>值（如果不存在）</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">scheme</span></code></p></td>
|
||
<td><p>0</p></td>
|
||
<td><p>URL方案说明符</p></td>
|
||
<td><p><em>scheme</em> parameter</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">netloc</span></code></p></td>
|
||
<td><p>1</p></td>
|
||
<td><p>网络位置部分</p></td>
|
||
<td><p>空字符串</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">path</span></code></p></td>
|
||
<td><p>2</p></td>
|
||
<td><p>分层路径</p></td>
|
||
<td><p>空字符串</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">query</span></code></p></td>
|
||
<td><p>3</p></td>
|
||
<td><p>查询组件</p></td>
|
||
<td><p>空字符串</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">fragment</span></code></p></td>
|
||
<td><p>4</p></td>
|
||
<td><p>片段识别</p></td>
|
||
<td><p>空字符串</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">username</span></code></p></td>
|
||
<td></td>
|
||
<td><p>用户名</p></td>
|
||
<td><p><a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a></p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">password</span></code></p></td>
|
||
<td></td>
|
||
<td><p>密码</p></td>
|
||
<td><p><a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a></p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">hostname</span></code></p></td>
|
||
<td></td>
|
||
<td><p>主机名（小写）</p></td>
|
||
<td><p><a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a></p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">port</span></code></p></td>
|
||
<td></td>
|
||
<td><p>端口号为整数（如果存在）</p></td>
|
||
<td><p><a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a></p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>如果在 URL 中指定了无效的端口，读取 <code class="xref py py-attr docutils literal notranslate"><span class="pre">port</span></code> 属性将引发 <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>。 有关结果对象的更多信息请参阅 <a class="reference internal" href="#urlparse-result-object"><span class="std std-ref">结构化解析结果</span></a> 一节。</p>
|
||
<p>在 <code class="xref py py-attr docutils literal notranslate"><span class="pre">netloc</span></code> 属性中不匹配的方括号将引发 <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>
|
||
<p>如果 <code class="xref py py-attr docutils literal notranslate"><span class="pre">netloc</span></code> 属性中的字符在 NFKC 规范化下（如 IDNA 编码格式所使用的）被分解成 <code class="docutils literal notranslate"><span class="pre">/</span></code>, <code class="docutils literal notranslate"><span class="pre">?</span></code>, <code class="docutils literal notranslate"><span class="pre">#</span></code>, <code class="docutils literal notranslate"><span class="pre">@</span></code> 或 <code class="docutils literal notranslate"><span class="pre">:</span></code> 则将引发 <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>。 如果在解析之前 URL 就被分解，则不会引发错误。</p>
|
||
<p>Following some of the <a class="reference external" href="https://url.spec.whatwg.org/#concept-basic-url-parser">WHATWG spec</a> that updates RFC 3986, leading C0
|
||
control and space characters are stripped from the URL. <code class="docutils literal notranslate"><span class="pre">\n</span></code>,
|
||
<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>
|
||
<div class="admonition warning">
|
||
<p class="admonition-title">警告</p>
|
||
<p><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> does not perform validation. See <a class="reference internal" href="#url-parsing-security"><span class="std std-ref">URL parsing
|
||
security</span></a> for details.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.6 版更改: </span>超范围的端口号现在会引发 <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>，而不是返回 <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a>。</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.8 版更改: </span>在 NFKC 规范化下会影响 netloc 解析的字符现在将引发 <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>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.8.10 版更改: </span>ASCII 换行符和制表符会从 URL 中被去除。</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.8.17 版更改: </span>Leading WHATWG C0 control and space characters are stripped from the URL.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="urllib.parse.urlunsplit">
|
||
<code class="sig-prename descclassname">urllib.parse.</code><code class="sig-name descname">urlunsplit</code><span class="sig-paren">(</span><em class="sig-param">parts</em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.urlunsplit" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>将 <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> 所返回的元组中的元素合并为一个字符串形式的完整 URL。 <em>parts</em> 参数可以是任何包含五个条目的可迭代对象。 其结果可能是略有不同但保持等价的 URL，如果被解析的 URL 原本包含不必要的分隔符（例如，带有空查询的 ?；RFC 已声明这是等价的）。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="urllib.parse.urljoin">
|
||
<code class="sig-prename descclassname">urllib.parse.</code><code class="sig-name descname">urljoin</code><span class="sig-paren">(</span><em class="sig-param">base</em>, <em class="sig-param">url</em>, <em class="sig-param">allow_fragments=True</em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.urljoin" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>通过合并一个 "基准 URL" (<em>base</em>) 和另一个 URL (<em>url</em>) 来构造一个完整 ("absolute") URL。 在非正式情况下，这将使用基准 URL 的各部分，特别是地址协议、网络位置和 (一部分) 路径来提供相对 URL 中缺失的部分。 例如:</p>
|
||
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">urllib.parse</span> <span class="kn">import</span> <span class="n">urljoin</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> <span class="s1">'FAQ.html'</span><span class="p">)</span>
|
||
<span class="go">'http://www.cwi.nl/%7Eguido/FAQ.html'</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><em>allow_fragments</em> 参数具有与 <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> 中的对应参数一致的含义与默认值。</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">注解</p>
|
||
<p>If <em>url</em> is an absolute URL (that is, starting with <code class="docutils literal notranslate"><span class="pre">//</span></code> or <code class="docutils literal notranslate"><span class="pre">scheme://</span></code>),
|
||
the <em>url</em>'s host name and/or scheme will be present in the result. For example:</p>
|
||
</div>
|
||
<div class="highlight-pycon3 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>
|
||
<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>
|
||
<span class="go">'http://www.python.org/%7Eguido'</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>如果你不想要那样的行为，请使用 <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.urlunsplit" title="urllib.parse.urlunsplit"><code class="xref py py-func docutils literal notranslate"><span class="pre">urlunsplit()</span></code></a> 对 <em>url</em> 进行预处理，移除可能存在的 <em>scheme</em> 和 <em>netloc</em> 部分。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.5 版更改: </span>Behaviour updated to match the semantics defined in <span class="target" id="index-4"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc3986.html"><strong>RFC 3986</strong></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="urllib.parse.urldefrag">
|
||
<code class="sig-prename descclassname">urllib.parse.</code><code class="sig-name descname">urldefrag</code><span class="sig-paren">(</span><em class="sig-param">url</em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.urldefrag" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>如果 <em>url</em> 包含片段标识符，则返回不带片段标识符的 <em>url</em> 修改版本。 如果 <em>url</em> 中没有片段标识符，则返回未经修改的 <em>url</em> 和一个空字符串。</p>
|
||
<p>返回值是一个 <a class="reference internal" href="../glossary.html#term-named-tuple"><span class="xref std std-term">named tuple</span></a>，它的条目可以通过索引或作为命名属性来访问:</p>
|
||
<table class="docutils align-default">
|
||
<colgroup>
|
||
<col style="width: 25%" />
|
||
<col style="width: 10%" />
|
||
<col style="width: 35%" />
|
||
<col style="width: 31%" />
|
||
</colgroup>
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>属性</p></th>
|
||
<th class="head"><p>索引</p></th>
|
||
<th class="head"><p>值</p></th>
|
||
<th class="head"><p>值（如果不存在）</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">url</span></code></p></td>
|
||
<td><p>0</p></td>
|
||
<td><p>不带片段的 URL</p></td>
|
||
<td><p>空字符串</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">fragment</span></code></p></td>
|
||
<td><p>1</p></td>
|
||
<td><p>片段识别</p></td>
|
||
<td><p>空字符串</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>请参阅 <a class="reference internal" href="#urlparse-result-object"><span class="std std-ref">结构化解析结果</span></a> 一节了解有关结果对象的更多信息。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.2 版更改: </span>结果为已构造好的对象而不是一个简单的 2 元组。-tuple.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="urllib.parse.unwrap">
|
||
<code class="sig-prename descclassname">urllib.parse.</code><code class="sig-name descname">unwrap</code><span class="sig-paren">(</span><em class="sig-param">url</em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.unwrap" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>从已包装的 URL (即被格式化为 <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> 或 <code class="docutils literal notranslate"><span class="pre">scheme://host/path</span></code> 的字符串) 中提取 URL。 如果 <em>url</em> 不是一个已包装的 URL，它将被原样返回。</p>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="url-parsing-security">
|
||
<span id="id1"></span><h2>URL parsing security<a class="headerlink" href="#url-parsing-security" title="永久链接至标题">¶</a></h2>
|
||
<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> of
|
||
inputs. They may not raise errors on inputs that other applications consider
|
||
invalid. They may also succeed on some inputs that might not be considered
|
||
URLs elsewhere. Their purpose is for practical functionality rather than
|
||
purity.</p>
|
||
<p>Instead of raising an exception on unusual input, they may instead return some
|
||
component parts as empty strings. Or components may contain more than perhaps
|
||
they should.</p>
|
||
<p>We recommend that users of these APIs where the values may be used anywhere
|
||
with security implications code defensively. Do some verification within your
|
||
code before trusting a returned component part. Does that <code class="docutils literal notranslate"><span class="pre">scheme</span></code> make
|
||
sense? Is that a sensible <code class="docutils literal notranslate"><span class="pre">path</span></code>? Is there anything strange about that
|
||
<code class="docutils literal notranslate"><span class="pre">hostname</span></code>? etc.</p>
|
||
</section>
|
||
<section id="parsing-ascii-encoded-bytes">
|
||
<span id="id2"></span><h2>解析ASCII编码字节<a class="headerlink" href="#parsing-ascii-encoded-bytes" title="永久链接至标题">¶</a></h2>
|
||
<p>这些 URL 解析函数最初设计只用于操作字符串。 但在实践中，它也能够操作经过正确转码和编码的 ASCII 字节序列形式的 URL。 相应地，此模块中的 URL 解析函数既可以操作 <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> 对象也可以操作 <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> 和 <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> 对象。</p>
|
||
<p>如果传入 <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> 数据，结果将只包含 <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> 数据。 如果传入 <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> 或 <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> 数据，则结果也将只包含 <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> 数据。</p>
|
||
<p>试图在单个函数调用中混用 <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> 数据和 <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> 或 <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> 数据将导致引发 <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>，而试图传入非 ASCII 字节值则将引发 <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>
|
||
<p>为了支持结果对象在 <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> 和 <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> 之间方便地转换，所有来自 URL 解析函数的返回值都会提供 <code class="xref py py-meth docutils literal notranslate"><span class="pre">encode()</span></code> 方法 (当结果包含 <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> 数据) 或 <code class="xref py py-meth docutils literal notranslate"><span class="pre">decode()</span></code> 方法 (当结果包含 <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> 数据)。 这些方法的签名与 <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> 和 <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> 的对应方法相匹配 (不同之处在于其默认编码格式是 <code class="docutils literal notranslate"><span class="pre">'ascii'</span></code> 而非 <code class="docutils literal notranslate"><span class="pre">'utf-8'</span></code>)。 每个方法会输出包含相应类型的 <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> 数据 (对于 <code class="xref py py-meth docutils literal notranslate"><span class="pre">encode()</span></code> 方法) 或 <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> 数据 (对于 <code class="xref py py-meth docutils literal notranslate"><span class="pre">decode()</span></code> 方法) 的值。</p>
|
||
<p>对于某些需要在有可能不正确地转码的包含非 ASCII 数据的 URL 上进行操作的应用程序来说，在发起调用 URL 解析方法之前必须自行将字节串解码为字符。</p>
|
||
<p>在本节中描述的行为仅适用于 URL 解析函数。 URL 转码函数在产生和消耗字节序列时使用它们自己的规则，详情参见单独 URL 转码函数的文档。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.2 版更改: </span>URL 解析函数现在接受 ASCII 编码的字节序列</p>
|
||
</div>
|
||
</section>
|
||
<section id="structured-parse-results">
|
||
<span id="urlparse-result-object"></span><h2>结构化解析结果<a class="headerlink" href="#structured-parse-results" title="永久链接至标题">¶</a></h2>
|
||
<p><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>, <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.urldefrag" title="urllib.parse.urldefrag"><code class="xref py py-func docutils literal notranslate"><span class="pre">urldefrag()</span></code></a> 函数的结果对象是 <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> 类型的子类。 这些子类中增加了在那些函数的文档中列出的属性，之前小节中描述的编码和解码支持，以及一个附加方法:</p>
|
||
<dl class="method">
|
||
<dt id="urllib.parse.urllib.parse.SplitResult.geturl">
|
||
<code class="sig-prename descclassname">urllib.parse.SplitResult.</code><code class="sig-name descname">geturl</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.urllib.parse.SplitResult.geturl" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>以字符串形式返回原始 URL 的重合并版本。 这可能与原始 URL 有所不同，例如协议的名称可能被正规化为小写字母、空的组成部分可能被丢弃。 特别地，空的参数、查询和片段标识符将会被移除。</p>
|
||
<p>对于 <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> 的结果，只有空的片段标识符会被移除。 对于 <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> 的结果，所有被记录的改变都会被应用到此方法所返回的 URL 上。</p>
|
||
<p>如果是通过原始的解析方法传回则此方法的结果会保持不变:</p>
|
||
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">urllib.parse</span> <span class="kn">import</span> <span class="n">urlsplit</span>
|
||
<span class="gp">>>> </span><span class="n">url</span> <span class="o">=</span> <span class="s1">'HTTP://www.Python.org/doc/#'</span>
|
||
<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>
|
||
<span class="gp">>>> </span><span class="n">r1</span><span class="o">.</span><span class="n">geturl</span><span class="p">()</span>
|
||
<span class="go">'http://www.Python.org/doc/'</span>
|
||
<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>
|
||
<span class="gp">>>> </span><span class="n">r2</span><span class="o">.</span><span class="n">geturl</span><span class="p">()</span>
|
||
<span class="go">'http://www.Python.org/doc/'</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<p>下面的类提供了当在 <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>
|
||
<dl class="class">
|
||
<dt id="urllib.parse.DefragResult">
|
||
<em class="property">class </em><code class="sig-prename descclassname">urllib.parse.</code><code class="sig-name descname">DefragResult</code><span class="sig-paren">(</span><em class="sig-param">url</em>, <em class="sig-param">fragment</em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.DefragResult" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>用于 <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> 结果的实体类，包含有 <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> 数据。 <code class="xref py py-meth docutils literal notranslate"><span class="pre">encode()</span></code> 方法会返回一个 <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> 实例。</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">3.2 新版功能.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="urllib.parse.ParseResult">
|
||
<em class="property">class </em><code class="sig-prename descclassname">urllib.parse.</code><code class="sig-name descname">ParseResult</code><span class="sig-paren">(</span><em class="sig-param">scheme</em>, <em class="sig-param">netloc</em>, <em class="sig-param">path</em>, <em class="sig-param">params</em>, <em class="sig-param">query</em>, <em class="sig-param">fragment</em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.ParseResult" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>用于 <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> 结果的实体类，包含有 <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> 数据。 <code class="xref py py-meth docutils literal notranslate"><span class="pre">encode()</span></code> 方法会返回一个 <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> 实例。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="urllib.parse.SplitResult">
|
||
<em class="property">class </em><code class="sig-prename descclassname">urllib.parse.</code><code class="sig-name descname">SplitResult</code><span class="sig-paren">(</span><em class="sig-param">scheme</em>, <em class="sig-param">netloc</em>, <em class="sig-param">path</em>, <em class="sig-param">query</em>, <em class="sig-param">fragment</em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.SplitResult" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>用于 <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="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> 数据。 <code class="xref py py-meth docutils literal notranslate"><span class="pre">encode()</span></code> 方法会返回一个 <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> 实例。</p>
|
||
</dd></dl>
|
||
|
||
<p>下面的类提供了当在 <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> 或 <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> 对象上操作时对解析结果的实现:</p>
|
||
<dl class="class">
|
||
<dt id="urllib.parse.DefragResultBytes">
|
||
<em class="property">class </em><code class="sig-prename descclassname">urllib.parse.</code><code class="sig-name descname">DefragResultBytes</code><span class="sig-paren">(</span><em class="sig-param">url</em>, <em class="sig-param">fragment</em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.DefragResultBytes" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>用于 <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> 结果的实体类，包含有 <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> 数据。 <code class="xref py py-meth docutils literal notranslate"><span class="pre">decode()</span></code> 方法会返回一个 <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> 实例。</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">3.2 新版功能.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="urllib.parse.ParseResultBytes">
|
||
<em class="property">class </em><code class="sig-prename descclassname">urllib.parse.</code><code class="sig-name descname">ParseResultBytes</code><span class="sig-paren">(</span><em class="sig-param">scheme</em>, <em class="sig-param">netloc</em>, <em class="sig-param">path</em>, <em class="sig-param">params</em>, <em class="sig-param">query</em>, <em class="sig-param">fragment</em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.ParseResultBytes" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>用于 <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> 结果的实体类，包含有 <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> 数据。 <code class="xref py py-meth docutils literal notranslate"><span class="pre">decode()</span></code> 方法会返回一个 <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> 实例。</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">3.2 新版功能.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="urllib.parse.SplitResultBytes">
|
||
<em class="property">class </em><code class="sig-prename descclassname">urllib.parse.</code><code class="sig-name descname">SplitResultBytes</code><span class="sig-paren">(</span><em class="sig-param">scheme</em>, <em class="sig-param">netloc</em>, <em class="sig-param">path</em>, <em class="sig-param">query</em>, <em class="sig-param">fragment</em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.SplitResultBytes" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>用于 <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="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> 数据。 <code class="xref py py-meth docutils literal notranslate"><span class="pre">decode()</span></code> 方法会返回一个 <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> 实例。</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">3.2 新版功能.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="url-quoting">
|
||
<h2>URL 转码<a class="headerlink" href="#url-quoting" title="永久链接至标题">¶</a></h2>
|
||
<p>URL 转码函数的功能是接收程序数据并通过对特殊字符进行转码并正确编码非 ASCII 文本来将其转为可以安全地用作 URL 组成部分的形式。 它们还支持逆转此操作以便从作为 URL 组成部分的内容中重建原始数据，如果上述的 URL 解析函数还未覆盖此功能的话。</p>
|
||
<dl class="function">
|
||
<dt id="urllib.parse.quote">
|
||
<code class="sig-prename descclassname">urllib.parse.</code><code class="sig-name descname">quote</code><span class="sig-paren">(</span><em class="sig-param">string</em>, <em class="sig-param">safe='/'</em>, <em class="sig-param">encoding=None</em>, <em class="sig-param">errors=None</em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.quote" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>Replace special characters in <em>string</em> using the <code class="docutils literal notranslate"><span class="pre">%xx</span></code> escape. Letters,
|
||
digits, and the characters <code class="docutils literal notranslate"><span class="pre">'_.-~'</span></code> are never quoted. By default, this
|
||
function is intended for quoting the path section of URL. The optional <em>safe</em>
|
||
parameter specifies additional ASCII characters that should not be quoted
|
||
--- its default value is <code class="docutils literal notranslate"><span class="pre">'/'</span></code>.</p>
|
||
<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>.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.7 版更改: </span>从 <span class="target" id="index-25"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2396.html"><strong>RFC 2396</strong></a> 迁移到 <span class="target" id="index-26"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc3986.html"><strong>RFC 3986</strong></a> 以转码 URL 字符串。 "~" 现在已被包括在非保留字符集中。</p>
|
||
</div>
|
||
<p>可选的 <em>encoding</em> 和 <em>errors</em> 形参指明如何处理非 ASCII 字符，与 <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> 方法所接受的值一样。 <em>encoding</em> 默认为 <code class="docutils literal notranslate"><span class="pre">'utf-8'</span></code>。 <em>errors</em> 默认为 <code class="docutils literal notranslate"><span class="pre">'strict'</span></code>，表示不受支持的字符将引发 <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>。 如果 <em>string</em> 为 <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> 则不可提供 <em>encoding</em> 和 <em>errors</em>，否则将引发 <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>。</p>
|
||
<p>请注意 <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> 等价于 <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>
|
||
<p>例如: <code class="docutils literal notranslate"><span class="pre">quote('/El</span> <span class="pre">Niño/')</span></code> 将产生 <code class="docutils literal notranslate"><span class="pre">'/El%20Ni%C3%B1o/'</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="urllib.parse.quote_plus">
|
||
<code class="sig-prename descclassname">urllib.parse.</code><code class="sig-name descname">quote_plus</code><span class="sig-paren">(</span><em class="sig-param">string</em>, <em class="sig-param">safe=''</em>, <em class="sig-param">encoding=None</em>, <em class="sig-param">errors=None</em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.quote_plus" title="永久链接至目标">¶</a></dt>
|
||
<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 by plus signs, as required for
|
||
quoting HTML form values when building up a query string to go into a URL.
|
||
Plus signs in the original string are escaped unless they are included in
|
||
<em>safe</em>. It also does not have <em>safe</em> default to <code class="docutils literal notranslate"><span class="pre">'/'</span></code>.</p>
|
||
<p>例如: <code class="docutils literal notranslate"><span class="pre">quote_plus('/El</span> <span class="pre">Niño/')</span></code> 将产生 <code class="docutils literal notranslate"><span class="pre">'%2FEl+Ni%C3%B1o%2F'</span></code>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="urllib.parse.quote_from_bytes">
|
||
<code class="sig-prename descclassname">urllib.parse.</code><code class="sig-name descname">quote_from_bytes</code><span class="sig-paren">(</span><em class="sig-param">bytes</em>, <em class="sig-param">safe='/'</em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.quote_from_bytes" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>类似于 <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>，但是接受 <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> 对象而非 <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>
|
||
<p>例如: <code class="docutils literal notranslate"><span class="pre">quote_from_bytes(b'a&\xef')</span></code> 产生 <code class="docutils literal notranslate"><span class="pre">'a%26%EF'</span></code>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="urllib.parse.unquote">
|
||
<code class="sig-prename descclassname">urllib.parse.</code><code class="sig-name descname">unquote</code><span class="sig-paren">(</span><em class="sig-param">string</em>, <em class="sig-param">encoding='utf-8'</em>, <em class="sig-param">errors='replace'</em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.unquote" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>Replace <code class="docutils literal notranslate"><span class="pre">%xx</span></code> escapes by their single-character equivalent.
|
||
The optional <em>encoding</em> and <em>errors</em> parameters specify how to decode
|
||
percent-encoded sequences into Unicode characters, as accepted by the
|
||
<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>
|
||
<p><em>string</em> 必须为 <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>
|
||
<p><em>encoding</em> 默认为 <code class="docutils literal notranslate"><span class="pre">'utf-8'</span></code>。 <em>errors</em> 默认为 <code class="docutils literal notranslate"><span class="pre">'replace'</span></code>，表示无效的序列将被替换为占位字符。</p>
|
||
<p>例如: <code class="docutils literal notranslate"><span class="pre">unquote('/El%20Ni%C3%B1o/')</span></code> 将产生 <code class="docutils literal notranslate"><span class="pre">'/El</span> <span class="pre">Niño/'</span></code>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="urllib.parse.unquote_plus">
|
||
<code class="sig-prename descclassname">urllib.parse.</code><code class="sig-name descname">unquote_plus</code><span class="sig-paren">(</span><em class="sig-param">string</em>, <em class="sig-param">encoding='utf-8'</em>, <em class="sig-param">errors='replace'</em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.unquote_plus" title="永久链接至目标">¶</a></dt>
|
||
<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 by spaces, as required for
|
||
unquoting HTML form values.</p>
|
||
<p><em>string</em> 必须为 <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>
|
||
<p>例如: <code class="docutils literal notranslate"><span class="pre">unquote_plus('/El+Ni%C3%B1o/')</span></code> 将产生 <code class="docutils literal notranslate"><span class="pre">'/El</span> <span class="pre">Niño/'</span></code>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="urllib.parse.unquote_to_bytes">
|
||
<code class="sig-prename descclassname">urllib.parse.</code><code class="sig-name descname">unquote_to_bytes</code><span class="sig-paren">(</span><em class="sig-param">string</em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.unquote_to_bytes" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>Replace <code class="docutils literal notranslate"><span class="pre">%xx</span></code> escapes by their single-octet equivalent, and return 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>
|
||
<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>.</p>
|
||
<p>如果它是 <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>，则 <em>string</em> 中未转义的非 ASCII 字符会被编码为 UTF-8 字节串。</p>
|
||
<p>例如: <code class="docutils literal notranslate"><span class="pre">unquote_to_bytes('a%26%EF')</span></code> y将产生 <code class="docutils literal notranslate"><span class="pre">b'a&\xef'</span></code>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="urllib.parse.urlencode">
|
||
<code class="sig-prename descclassname">urllib.parse.</code><code class="sig-name descname">urlencode</code><span class="sig-paren">(</span><em class="sig-param">query</em>, <em class="sig-param">doseq=False</em>, <em class="sig-param">safe=''</em>, <em class="sig-param">encoding=None</em>, <em class="sig-param">errors=None</em>, <em class="sig-param">quote_via=quote_plus</em><span class="sig-paren">)</span><a class="headerlink" href="#urllib.parse.urlencode" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>将一个包含有 <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> 或 <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> 对象的映射对象或二元组序列转换为以百分号编码的 ASCII 文本字符串。 如果所产生的字符串要被用作 <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> 函数的 POST 操作的 <em>data</em>，则它应当被编码为字节串，否则它将导致 <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>
|
||
<p>结果字符串是一系列 <code class="docutils literal notranslate"><span class="pre">key=value</span></code> 对，由 <code class="docutils literal notranslate"><span class="pre">'&'</span></code> 字符进行分隔，其中 <em>key</em> 和 <em>value</em> 都已使用 <em>quote_via</em> 函数转码。 在默认情况下，会使用 <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> 来转码值，这意味着空格会被转码为 <code class="docutils literal notranslate"><span class="pre">'+'</span></code> 字符而 '/' 字符会被转码为 <code class="docutils literal notranslate"><span class="pre">%2F</span></code>，即遵循 GET 请求的标准 (<code class="docutils literal notranslate"><span class="pre">application/x-www-form-urlencoded</span></code>)。 另一个可以作为 <em>quote_via</em> 传入的替代函数是 <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>，它将把空格转码为 <code class="docutils literal notranslate"><span class="pre">%20</span></code> 并且不编码 '/' 字符。 为了最大程度地控制要转码的内容，请使用 <code class="docutils literal notranslate"><span class="pre">quote</span></code> 并指定 <em>safe</em> 的值。</p>
|
||
<p>When a sequence of two-element tuples is used as the <em>query</em>
|
||
argument, the first element of each tuple is a key and the second is a
|
||
value. The value element in itself can be a sequence and in that case, if
|
||
the optional parameter <em>doseq</em> is evaluates to <code class="docutils literal notranslate"><span class="pre">True</span></code>, individual
|
||
<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 of
|
||
the value sequence for the key. The order of parameters in the encoded
|
||
string will match the order of parameter tuples in the sequence.</p>
|
||
<p><em>safe</em>, <em>encoding</em> 和 <em>errors</em> 形参会被传递给 <em>quote_via</em> (<em>encoding</em> 和 <em>errors</em> 形参仅在查询元素为 <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>
|
||
<p>为了反向执行这个编码过程，此模块提供了 <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> 和 <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> 来将查询字符串解析为 Python 数据结构。</p>
|
||
<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 urlencode
|
||
method can be used for generating query string for a URL or data for POST.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.2 版更改: </span>查询参数支持字节和字符串对象。</p>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">3.5 新版功能: </span><em>quote_via</em> 参数.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<div class="admonition seealso">
|
||
<p class="admonition-title">参见</p>
|
||
<dl class="simple">
|
||
<dt><a class="reference external" href="https://url.spec.whatwg.org/">WHATWG</a> - URL 现有标准</dt><dd><p>定义 URL、域名、IP 地址、application/x-www-form-urlencoded 格式及其 API 的工作组。</p>
|
||
</dd>
|
||
<dt><span class="target" id="index-27"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc3986.html"><strong>RFC 3986</strong></a> - 统一资源标识符</dt><dd><p>这是当前的标准 (STD66)。 任何对于 urllib.parse 模块的修改都必须遵循该标准。 某些偏离也可能会出现，这大都是出于向下兼容的目的以及特定的经常存在于各主要浏览器上的实际解析需求。</p>
|
||
</dd>
|
||
<dt><span class="target" id="index-28"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2732.html"><strong>RFC 2732</strong></a> - URL 中的 IPv6 Addresses 地址显示格式。</dt><dd><p>这指明了 IPv6 URL 的解析要求。</p>
|
||
</dd>
|
||
<dt><span class="target" id="index-29"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2396.html"><strong>RFC 2396</strong></a> - 统一资源标识符（URI）：通用语法</dt><dd><p>描述统一资源名称 (URN) 和统一资源定位符 (URL) 通用语义要求的文档。</p>
|
||
</dd>
|
||
<dt><span class="target" id="index-30"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2368.html"><strong>RFC 2368</strong></a> - mailto URL 模式。</dt><dd><p>mailto URL 模式的解析要求。</p>
|
||
</dd>
|
||
<dt><span class="target" id="index-31"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc1808.html"><strong>RFC 1808</strong></a> - 相对统一资源定位符</dt><dd><p>这个请求注释包括联结绝对和相对 URL 的规则，其中包括大量控制边界情况处理的 "异常示例"。</p>
|
||
</dd>
|
||
<dt><span class="target" id="index-32"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc1738.html"><strong>RFC 1738</strong></a> - 统一资源定位符 (URL)</dt><dd><p>这指明了绝对 URL 的正式语义和句法。</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
</section>
|
||
</section>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||
<div class="sphinxsidebarwrapper">
|
||
<h3><a href="../contents.html">目录</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">urllib.parse</span></code> 用于解析 URL</a><ul>
|
||
<li><a class="reference internal" href="#url-parsing">URL 解析</a></li>
|
||
<li><a class="reference internal" href="#url-parsing-security">URL parsing security</a></li>
|
||
<li><a class="reference internal" href="#parsing-ascii-encoded-bytes">解析ASCII编码字节</a></li>
|
||
<li><a class="reference internal" href="#structured-parse-results">结构化解析结果</a></li>
|
||
<li><a class="reference internal" href="#url-quoting">URL 转码</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>上一个主题</h4>
|
||
<p class="topless"><a href="urllib.request.html"
|
||
title="上一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">urllib.request</span></code> --- 用于打开 URL 的可扩展库</a></p>
|
||
<h4>下一个主题</h4>
|
||
<p class="topless"><a href="urllib.error.html"
|
||
title="下一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">urllib.error</span></code> --- urllib.request 引发的异常类</a></p>
|
||
<div role="note" aria-label="source link">
|
||
<h3>本页</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">报告 Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/3.8/Doc/library/urllib.parse.rst"
|
||
rel="nofollow">显示源代码
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>导航</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="总目录"
|
||
>索引</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python 模块索引"
|
||
>模块</a> |</li>
|
||
<li class="right" >
|
||
<a href="urllib.error.html" title="urllib.error --- urllib.request 引发的异常类"
|
||
>下一页</a> |</li>
|
||
<li class="right" >
|
||
<a href="urllib.request.html" title="urllib.request --- 用于打开 URL 的可扩展库"
|
||
>上一页</a> |</li>
|
||
|
||
<li><img src="../_static/py.svg" alt="python logo" style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.8.20 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >Python 标准库</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="internet.html" >互联网协议和支持</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="快速搜索" aria-label="快速搜索" type="text" name="q" />
|
||
<input type="submit" value="转向" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
<div class="footer">
|
||
© <a href="../copyright.html">版权所有</a> 2001-2024, Python Software Foundation.
|
||
<br />
|
||
This page is licensed under the Python Software Foundation License Version 2.
|
||
<br />
|
||
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
|
||
<br />
|
||
|
||
<br />
|
||
|
||
The Python Software Foundation is a non-profit corporation.
|
||
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
||
<br />
|
||
<br />
|
||
|
||
最后更新于 12月 09, 2024.
|
||
<a href="https://docs.python.org/3/bugs.html">Found a bug</a>?
|
||
<br />
|
||
|
||
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 2.4.4.
|
||
</div>
|
||
|
||
</body>
|
||
</html> |