klarkxy/hustoj
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
hustoj/web/python-docs/library/email.utils.html
klarkxy 723430cade 增加python文档
2025-03-09 17:10:56 +08:00

409 lines
37 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!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>email.utils: 其他工具 &#8212; 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="email.iterators: 迭代器" href="email.iterators.html" />
<link rel="prev" title="email.encoders: 编码器" href="email.encoders.html" />
<link rel="canonical" href="https://docs.python.org/3/library/email.utils.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>
<h4>上一个主题</h4>
<p class="topless"><a href="email.encoders.html"
title="上一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.encoders</span></code>: 编码器</a></p>
<h4>下一个主题</h4>
<p class="topless"><a href="email.iterators.html"
title="下一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.iterators</span></code>: 迭代器</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/email.utils.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/email.utils.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="email.iterators.html" title="email.iterators: 迭代器"
accesskey="N">下一页</a> |</li>
<li class="right" >
<a href="email.encoders.html" title="email.encoders: 编码器"
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> &#187;</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> &#187;
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python 标准库</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="netdata.html" >互联网数据处理</a> &#187;</li>
<li class="nav-item nav-item-3"><a href="email.html" accesskey="U"><code class="xref py py-mod docutils literal notranslate"><span class="pre">email</span></code> --- 电子邮件与 MIME 处理包</a> &#187;</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-email.utils">
<span id="email-utils-miscellaneous-utilities"></span><h1><a class="reference internal" href="#module-email.utils" title="email.utils: Miscellaneous email package utilities."><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.utils</span></code></a>: 其他工具<a class="headerlink" href="#module-email.utils" title="永久链接至标题"></a></h1>
<p><strong>源代码:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.8/Lib/email/utils.py">Lib/email/utils.py</a></p>
<hr class="docutils" />
<p><a class="reference internal" href="#module-email.utils" title="email.utils: Miscellaneous email package utilities."><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.utils</span></code></a> 模块提供如下几个工具</p>
<dl class="function">
<dt id="email.utils.localtime">
<code class="sig-prename descclassname">email.utils.</code><code class="sig-name descname">localtime</code><span class="sig-paren">(</span><em class="sig-param">dt=None</em><span class="sig-paren">)</span><a class="headerlink" href="#email.utils.localtime" title="永久链接至目标"></a></dt>
<dd><p>以感知型 datetime 对象返回当地时间。 如果调用时参数为空，则返回当前时间。 否则 <em>dt</em> 参数应该是一个 <a class="reference internal" href="datetime.html#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a> 实例，并根据系统时区数据库转换为当地时区。 如果 <em>dt</em> 是简单型的 （即 <code class="docutils literal notranslate"><span class="pre">dt.tzinfo</span></code> 是 <code class="docutils literal notranslate"><span class="pre">None</span></code> )，则假定为当地时间。 在这种情况下，为正值或零的 <em>isdst</em> 会使 <code class="docutils literal notranslate"><span class="pre">localtime</span></code> 假定夏季时间（例如，夏令时）对指定时间（分别）生效或不生效。 负值 <em>isdst</em> 会使 <code class="docutils literal notranslate"><span class="pre">localtime</span></code> 预测夏季时间对指定时间是否生效。</p>
<div class="versionadded">
<p><span class="versionmodified added">3.3 新版功能.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="email.utils.make_msgid">
<code class="sig-prename descclassname">email.utils.</code><code class="sig-name descname">make_msgid</code><span class="sig-paren">(</span><em class="sig-param">idstring=None</em>, <em class="sig-param">domain=None</em><span class="sig-paren">)</span><a class="headerlink" href="#email.utils.make_msgid" title="永久链接至目标"></a></dt>
<dd><p>返回一个适合作为兼容 <span class="target" id="index-22"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2822.html"><strong>RFC 2822</strong></a> 的 <em class="mailheader">Message-ID</em> 标头的字符串。可选参数 <em>idstring</em> 可传入一字符串以增强该消息 ID 的唯一性。可选参数 <em>domain</em> 可用于提供消息 ID 中字符 '&#64;' 之后的部分，其默认值是本机的主机名。正常情况下无需覆盖此默认值，但在特定情况下覆盖默认值可能会有用，比如构建一个分布式系统，在多台主机上采用一致的域名。</p>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.2 版更改: </span>增加了关键字 <em>domain</em></p>
</div>
</dd></dl>
<p>下列函数是旧（<code class="docutils literal notranslate"><span class="pre">Compat32</span></code>）电子邮件 API 的一部分。新 API 提供的解析和格式化在标头解析机制中已经被自动完成，故在使用新 API 时没有必要直接使用它们函数。</p>
<dl class="function">
<dt id="email.utils.quote">
<code class="sig-prename descclassname">email.utils.</code><code class="sig-name descname">quote</code><span class="sig-paren">(</span><em class="sig-param">str</em><span class="sig-paren">)</span><a class="headerlink" href="#email.utils.quote" title="永久链接至目标"></a></dt>
<dd><p>返回一个新的字符串， <em>str</em> 中的反斜杠被替换为两个反斜杠，并且双引号被替换为反斜杠加双引号。</p>
</dd></dl>
<dl class="function">
<dt id="email.utils.unquote">
<code class="sig-prename descclassname">email.utils.</code><code class="sig-name descname">unquote</code><span class="sig-paren">(</span><em class="sig-param">str</em><span class="sig-paren">)</span><a class="headerlink" href="#email.utils.unquote" title="永久链接至目标"></a></dt>
<dd><p>返回 <em>str</em> 被去除引用版本的字符串。如果 <em>str</em> 开头和结尾均是双引号，则这对双引号被去除。类似地，如果 <em>str</em> 开头和结尾都是尖角括号，这对尖角括号会被去除。</p>
</dd></dl>
<dl class="function">
<dt id="email.utils.parseaddr">
<code class="sig-prename descclassname">email.utils.</code><code class="sig-name descname">parseaddr</code><span class="sig-paren">(</span><em class="sig-param">address</em>, <em class="sig-param">*</em>, <em class="sig-param">strict=True</em><span class="sig-paren">)</span><a class="headerlink" href="#email.utils.parseaddr" title="永久链接至目标"></a></dt>
<dd><p>将地址（应为诸如 <em class="mailheader">To</em> 或者 <em class="mailheader">Cc</em> 之类包含地址的字段值）解析为构成之的 <em>真实名字</em> 和 <em>电子邮件地址</em> 部分。返回包含这两个信息的一个元组；如若解析失败，则返回一个二元组 <code class="docutils literal notranslate"><span class="pre">('',</span> <span class="pre">'')</span></code> 。</p>
<p>如果 <em>strict</em> 为真值，将使用拒绝错误形式输入的严格解析器。</p>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.8.20 版更改: </span>增加了 <em>strict</em> 可选形参并将默认拒绝错误形式输入。</p>
</div>
</dd></dl>
<dl class="function">
<dt id="email.utils.formataddr">
<code class="sig-prename descclassname">email.utils.</code><code class="sig-name descname">formataddr</code><span class="sig-paren">(</span><em class="sig-param">pair</em>, <em class="sig-param">charset='utf-8'</em><span class="sig-paren">)</span><a class="headerlink" href="#email.utils.formataddr" title="永久链接至目标"></a></dt>
<dd><p>是 <a class="reference internal" href="#email.utils.parseaddr" title="email.utils.parseaddr"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parseaddr()</span></code></a> 的逆操作，接受一个 <code class="docutils literal notranslate"><span class="pre">(真实名字,</span> <span class="pre">电子邮件地址)</span></code> 的二元组，并返回适合于 <em class="mailheader">To</em> or <em class="mailheader">Cc</em> 标头的字符串。如果第一个元素为假性值，则第二个元素将被原样返回。</p>
<p>可选地，如果指定 <em>charset</em>，则被视为一符合 <span class="target" id="index-23"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2047.html"><strong>RFC 2047</strong></a> 的编码字符集，用于编码 <code class="docutils literal notranslate"><span class="pre">真实名字</span></code> 中的非 ASCII 字符。可以是一个 <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="email.charset.html#email.charset.Charset" title="email.charset.Charset"><code class="xref py py-class docutils literal notranslate"><span class="pre">Charset</span></code></a> 类。默认为 <code class="docutils literal notranslate"><span class="pre">utf-8</span></code> 。</p>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.3 版更改: </span>添加了 <em>charset</em> 选项。</p>
</div>
</dd></dl>
<dl class="function">
<dt id="email.utils.getaddresses">
<code class="sig-prename descclassname">email.utils.</code><code class="sig-name descname">getaddresses</code><span class="sig-paren">(</span><em class="sig-param">fieldvalues</em>, <em class="sig-param">*</em>, <em class="sig-param">strict=True</em><span class="sig-paren">)</span><a class="headerlink" href="#email.utils.getaddresses" title="永久链接至目标"></a></dt>
<dd><p>该方法返回一个与 <code class="docutils literal notranslate"><span class="pre">parseaddr()</span></code> 返回值形式相同的 2 元组。 <em>fieldvalues</em> 是与 <a class="reference internal" href="email.compat32-message.html#email.message.Message.get_all" title="email.message.Message.get_all"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Message.get_all</span></code></a> 返回值形式相同的由标头字段值组成的序列。</p>
<p>如果 <em>strict</em> 为真值，将使用拒绝错误形式输入的严格解析器。</p>
<p>下面简单示例可获取一条消息的所有接收方:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">email.utils</span> <span class="kn">import</span> <span class="n">getaddresses</span>
<span class="n">tos</span> <span class="o">=</span> <span class="n">msg</span><span class="o">.</span><span class="n">get_all</span><span class="p">(</span><span class="s1">&#39;to&#39;</span><span class="p">,</span> <span class="p">[])</span>
<span class="n">ccs</span> <span class="o">=</span> <span class="n">msg</span><span class="o">.</span><span class="n">get_all</span><span class="p">(</span><span class="s1">&#39;cc&#39;</span><span class="p">,</span> <span class="p">[])</span>
<span class="n">resent_tos</span> <span class="o">=</span> <span class="n">msg</span><span class="o">.</span><span class="n">get_all</span><span class="p">(</span><span class="s1">&#39;resent-to&#39;</span><span class="p">,</span> <span class="p">[])</span>
<span class="n">resent_ccs</span> <span class="o">=</span> <span class="n">msg</span><span class="o">.</span><span class="n">get_all</span><span class="p">(</span><span class="s1">&#39;resent-cc&#39;</span><span class="p">,</span> <span class="p">[])</span>
<span class="n">all_recipients</span> <span class="o">=</span> <span class="n">getaddresses</span><span class="p">(</span><span class="n">tos</span> <span class="o">+</span> <span class="n">ccs</span> <span class="o">+</span> <span class="n">resent_tos</span> <span class="o">+</span> <span class="n">resent_ccs</span><span class="p">)</span>
</pre></div>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.8.20 版更改: </span>增加了 <em>strict</em> 可选形参并将默认拒绝错误形式输入。</p>
</div>
</dd></dl>
<dl class="function">
<dt id="email.utils.parsedate">
<code class="sig-prename descclassname">email.utils.</code><code class="sig-name descname">parsedate</code><span class="sig-paren">(</span><em class="sig-param">date</em><span class="sig-paren">)</span><a class="headerlink" href="#email.utils.parsedate" title="永久链接至目标"></a></dt>
<dd><p>尝试根据 <span class="target" id="index-24"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2822.html"><strong>RFC 2822</strong></a> 的规则解析一个日期。然而，有些寄信人不严格遵守这一格式，所以这种情况下 <a class="reference internal" href="#email.utils.parsedate" title="email.utils.parsedate"><code class="xref py py-func docutils literal notranslate"><span class="pre">parsedate()</span></code></a> 会尝试猜测其形式。<em>date</em> 是一个字符串包含了一个形如 <code class="docutils literal notranslate"><span class="pre">&quot;Mon,</span> <span class="pre">20</span> <span class="pre">Nov</span> <span class="pre">1995</span> <span class="pre">19:12:08</span> <span class="pre">-0500&quot;</span></code> 的 <span class="target" id="index-25"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2822.html"><strong>RFC 2822</strong></a> 格式日期。如果日期解析成功， <a class="reference internal" href="#email.utils.parsedate" title="email.utils.parsedate"><code class="xref py py-func docutils literal notranslate"><span class="pre">parsedate()</span></code></a> 将返回一个九元组，可直接传递给 <a class="reference internal" href="time.html#time.mktime" title="time.mktime"><code class="xref py py-func docutils literal notranslate"><span class="pre">time.mktime()</span></code></a>；否则返回 <code class="docutils literal notranslate"><span class="pre">None</span></code>。注意返回的元组中下标为 6、7、8 的部分是无用的。</p>
</dd></dl>
<dl class="function">
<dt id="email.utils.parsedate_tz">
<code class="sig-prename descclassname">email.utils.</code><code class="sig-name descname">parsedate_tz</code><span class="sig-paren">(</span><em class="sig-param">date</em><span class="sig-paren">)</span><a class="headerlink" href="#email.utils.parsedate_tz" title="永久链接至目标"></a></dt>
<dd><p>执行与 <a class="reference internal" href="#email.utils.parsedate" title="email.utils.parsedate"><code class="xref py py-func docutils literal notranslate"><span class="pre">parsedate()</span></code></a> 相同的功能，但会返回 <code class="docutils literal notranslate"><span class="pre">None</span></code> 或是一个 10 元组；前 9 个元素构成一个可以直接传给 <a class="reference internal" href="time.html#time.mktime" title="time.mktime"><code class="xref py py-func docutils literal notranslate"><span class="pre">time.mktime()</span></code></a> 的元组，而第十个元素则是该日期的时区与 UTC (格林威治平均时 GMT 的正式名称) <a class="footnote-reference brackets" href="#id2" id="id1">1</a> 的时差。 如果输入字符串不带时区，则所返回元组的最后一个元素将为 <code class="docutils literal notranslate"><span class="pre">0</span></code>，这表示 UTC。 请注意结果元组的索引号 6, 7 和 8 是不可用的。</p>
</dd></dl>
<dl class="function">
<dt id="email.utils.parsedate_to_datetime">
<code class="sig-prename descclassname">email.utils.</code><code class="sig-name descname">parsedate_to_datetime</code><span class="sig-paren">(</span><em class="sig-param">date</em><span class="sig-paren">)</span><a class="headerlink" href="#email.utils.parsedate_to_datetime" title="永久链接至目标"></a></dt>
<dd><p><a class="reference internal" href="#email.utils.format_datetime" title="email.utils.format_datetime"><code class="xref py py-func docutils literal notranslate"><span class="pre">format_datetime()</span></code></a> 的逆操作。 执行与 <a class="reference internal" href="#email.utils.parsedate" title="email.utils.parsedate"><code class="xref py py-func docutils literal notranslate"><span class="pre">parsedate()</span></code></a> 相同的功能，但会在成功时返回一个 <a class="reference internal" href="datetime.html#datetime.datetime" title="datetime.datetime"><code class="xref py py-mod docutils literal notranslate"><span class="pre">datetime</span></code></a>。 如果输入日期的时区值为 <code class="docutils literal notranslate"><span class="pre">-0000</span></code>，则 <code class="docutils literal notranslate"><span class="pre">datetime</span></code> 将为一个简单型 <code class="docutils literal notranslate"><span class="pre">datetime</span></code>，而如果日期符合 RFC 标准则它将代表一个 UTC 时间，但是并不指明日期所在消息的实际源时区。 如果输入日期具有任何其他有效的时区差值，则 <code class="docutils literal notranslate"><span class="pre">datetime</span></code> 将为一个感知型 <code class="docutils literal notranslate"><span class="pre">datetime</span></code> 并与 <a class="reference internal" href="datetime.html#datetime.timezone" title="datetime.timezone"><code class="xref py py-class docutils literal notranslate"><span class="pre">timezone</span></code></a> <a class="reference internal" href="datetime.html#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">tzinfo</span></code></a> 相对应。</p>
<div class="versionadded">
<p><span class="versionmodified added">3.3 新版功能.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="email.utils.mktime_tz">
<code class="sig-prename descclassname">email.utils.</code><code class="sig-name descname">mktime_tz</code><span class="sig-paren">(</span><em class="sig-param">tuple</em><span class="sig-paren">)</span><a class="headerlink" href="#email.utils.mktime_tz" title="永久链接至目标"></a></dt>
<dd><p>将 <a class="reference internal" href="#email.utils.parsedate_tz" title="email.utils.parsedate_tz"><code class="xref py py-func docutils literal notranslate"><span class="pre">parsedate_tz()</span></code></a> 所返回的 10 元组转换为一个 UTC 时间戳（相距 Epoch 纪元初始的秒数）。 如果元组中的时区项为 <code class="docutils literal notranslate"><span class="pre">None</span></code>，则视为当地时间。</p>
</dd></dl>
<dl class="function">
<dt id="email.utils.formatdate">
<code class="sig-prename descclassname">email.utils.</code><code class="sig-name descname">formatdate</code><span class="sig-paren">(</span><em class="sig-param">timeval=None</em>, <em class="sig-param">localtime=False</em>, <em class="sig-param">usegmt=False</em><span class="sig-paren">)</span><a class="headerlink" href="#email.utils.formatdate" title="永久链接至目标"></a></dt>
<dd><p>返回 <span class="target" id="index-26"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2822.html"><strong>RFC 2822</strong></a> 标准的日期字符串，例如:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">Fri</span><span class="p">,</span> <span class="mi">09</span> <span class="n">Nov</span> <span class="mi">2001</span> <span class="mi">01</span><span class="p">:</span><span class="mi">08</span><span class="p">:</span><span class="mi">47</span> <span class="o">-</span><span class="mi">0000</span>
</pre></div>
</div>
<p>可选的 <em>timeval</em> 如果给出，则是一个可被 <a class="reference internal" href="time.html#time.gmtime" title="time.gmtime"><code class="xref py py-func docutils literal notranslate"><span class="pre">time.gmtime()</span></code></a> 和 <a class="reference internal" href="time.html#time.localtime" title="time.localtime"><code class="xref py py-func docutils literal notranslate"><span class="pre">time.localtime()</span></code></a> 接受的浮点数时间值，否则会使用当前时间。</p>
<p>可选的 <em>localtime</em> 是一个旗标，当为 <code class="docutils literal notranslate"><span class="pre">True</span></code> 时，将会解析 <em>timeval</em>，并返回一个相对于当地时区而非 UTC 的日期值，并会适当地考虑夏令时。 默认值 <code class="docutils literal notranslate"><span class="pre">False</span></code> 表示使用 UTC。</p>
<p>可选的 <em>usegmt</em> 是一个旗标，当为 <code class="docutils literal notranslate"><span class="pre">True</span></code> 时，将会输出一个日期字符串，其中时区表示为 ascii 字符串 <code class="docutils literal notranslate"><span class="pre">GMT</span></code> 而非数字形式的 <code class="docutils literal notranslate"><span class="pre">-0000</span></code>。 这对某些协议（例如 HTTP）来说是必要的。 这仅在 <em>localtime</em> 为 <code class="docutils literal notranslate"><span class="pre">False</span></code> 时应用。 默认值为 <code class="docutils literal notranslate"><span class="pre">False</span></code>。</p>
</dd></dl>
<dl class="function">
<dt id="email.utils.format_datetime">
<code class="sig-prename descclassname">email.utils.</code><code class="sig-name descname">format_datetime</code><span class="sig-paren">(</span><em class="sig-param">dt</em>, <em class="sig-param">usegmt=False</em><span class="sig-paren">)</span><a class="headerlink" href="#email.utils.format_datetime" title="永久链接至目标"></a></dt>
<dd><p>类似于 <code class="docutils literal notranslate"><span class="pre">formatdate</span></code>，但输入的是一个 <a class="reference internal" href="datetime.html#module-datetime" title="datetime: Basic date and time types."><code class="xref py py-mod docutils literal notranslate"><span class="pre">datetime</span></code></a> 实例。 如果实例是一个简单型 datetime，它会被视为 &quot;不带源时区信息的 UTC&quot;，并且使用传统的 <code class="docutils literal notranslate"><span class="pre">-0000</span></code> 作为时区。 如果实例是一个感知型 <code class="docutils literal notranslate"><span class="pre">datetime</span></code>，则会使用数字形式的时区时差。 如果实例是感知型且时区时差为零，则 <em>usegmt</em> 可能会被设为 <code class="docutils literal notranslate"><span class="pre">True</span></code>，在这种情况下将使用字符串 <code class="docutils literal notranslate"><span class="pre">GMT</span></code> 而非数字形式的时区时差。 这提供了一种生成符合标准 HTTP 日期标头的方式。</p>
<div class="versionadded">
<p><span class="versionmodified added">3.3 新版功能.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="email.utils.decode_rfc2231">
<code class="sig-prename descclassname">email.utils.</code><code class="sig-name descname">decode_rfc2231</code><span class="sig-paren">(</span><em class="sig-param">s</em><span class="sig-paren">)</span><a class="headerlink" href="#email.utils.decode_rfc2231" title="永久链接至目标"></a></dt>
<dd><p>根据 <span class="target" id="index-27"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2231.html"><strong>RFC 2231</strong></a> 解码字符串 <em>s</em>。</p>
</dd></dl>
<dl class="function">
<dt id="email.utils.encode_rfc2231">
<code class="sig-prename descclassname">email.utils.</code><code class="sig-name descname">encode_rfc2231</code><span class="sig-paren">(</span><em class="sig-param">s</em>, <em class="sig-param">charset=None</em>, <em class="sig-param">language=None</em><span class="sig-paren">)</span><a class="headerlink" href="#email.utils.encode_rfc2231" title="永久链接至目标"></a></dt>
<dd><p>根据 <span class="target" id="index-28"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2231.html"><strong>RFC 2231</strong></a> 对字符串 <em>s</em> 进行编码。 可选的 <em>charset</em> 和 <em>language</em> 如果给出，则为指明要使用的字符集名称和语言名称。 如果两者均未给出，则会原样返回 <em>s</em>。 如果给出 <em>charset</em> 但未给出 <em>language</em>，则会使用空字符串作为 <em>language</em> 值来对字符串进行编码。</p>
</dd></dl>
<dl class="function">
<dt id="email.utils.collapse_rfc2231_value">
<code class="sig-prename descclassname">email.utils.</code><code class="sig-name descname">collapse_rfc2231_value</code><span class="sig-paren">(</span><em class="sig-param">value</em>, <em class="sig-param">errors='replace'</em>, <em class="sig-param">fallback_charset='us-ascii'</em><span class="sig-paren">)</span><a class="headerlink" href="#email.utils.collapse_rfc2231_value" title="永久链接至目标"></a></dt>
<dd><p>当以 <span class="target" id="index-29"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2231.html"><strong>RFC 2231</strong></a> 格式来编码标头形参时，<a class="reference internal" href="email.compat32-message.html#email.message.Message.get_param" title="email.message.Message.get_param"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Message.get_param</span></code></a> 可能返回一个包含字符集、语言和值的 3 元组。 <a class="reference internal" href="#email.utils.collapse_rfc2231_value" title="email.utils.collapse_rfc2231_value"><code class="xref py py-func docutils literal notranslate"><span class="pre">collapse_rfc2231_value()</span></code></a> 会将此返回为一个 unicode 字符串。 可选的 <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> 的 <a class="reference internal" href="stdtypes.html#str.encode" title="str.encode"><code class="xref py py-func docutils literal notranslate"><span class="pre">encode()</span></code></a> 方法的 <em>errors</em> 参数；它的默认值为 <code class="docutils literal notranslate"><span class="pre">'replace'</span></code>。 可选的 <em>fallback_charset</em> 指定当 <span class="target" id="index-30"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2231.html"><strong>RFC 2231</strong></a> 标头中的字符集无法被 Python 识别时要使用的字符集；它的默认值为 <code class="docutils literal notranslate"><span class="pre">'us-ascii'</span></code>。</p>
<p>为方便起见，如果传给 <a class="reference internal" href="#email.utils.collapse_rfc2231_value" title="email.utils.collapse_rfc2231_value"><code class="xref py py-func docutils literal notranslate"><span class="pre">collapse_rfc2231_value()</span></code></a> 的 <em>value</em> 不是一个元组，则应为一个字符串并会将其原样返回。</p>
</dd></dl>
<dl class="function">
<dt id="email.utils.decode_params">
<code class="sig-prename descclassname">email.utils.</code><code class="sig-name descname">decode_params</code><span class="sig-paren">(</span><em class="sig-param">params</em><span class="sig-paren">)</span><a class="headerlink" href="#email.utils.decode_params" title="永久链接至目标"></a></dt>
<dd><p>根据 <span class="target" id="index-31"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2231.html"><strong>RFC 2231</strong></a> 解码参数列表。 <em>params</em> 是一个包含 <code class="docutils literal notranslate"><span class="pre">(content-type,</span> <span class="pre">string-value)</span></code> 形式的元素的 2 元组的序列。</p>
</dd></dl>
<p class="rubric">备注</p>
<dl class="footnote brackets">
<dt class="label" id="id2"><span class="brackets"><a class="fn-backref" href="#id1">1</a></span></dt>
<dd><p>请注意时区时差的符号与同一时区的 <code class="docutils literal notranslate"><span class="pre">time.timezone</span></code> 变量的符号相反；后者遵循 POSIX 标准而此模块遵循 <span class="target" id="index-32"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2822.html"><strong>RFC 2822</strong></a>。</p>
</dd>
</dl>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>上一个主题</h4>
<p class="topless"><a href="email.encoders.html"
title="上一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.encoders</span></code>: 编码器</a></p>
<h4>下一个主题</h4>
<p class="topless"><a href="email.iterators.html"
title="下一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.iterators</span></code>: 迭代器</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/email.utils.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="email.iterators.html" title="email.iterators: 迭代器"
>下一页</a> |</li>
<li class="right" >
<a href="email.encoders.html" title="email.encoders: 编码器"
>上一页</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> &#187;</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> &#187;
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python 标准库</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="netdata.html" >互联网数据处理</a> &#187;</li>
<li class="nav-item nav-item-3"><a href="email.html" ><code class="xref py py-mod docutils literal notranslate"><span class="pre">email</span></code> --- 电子邮件与 MIME 处理包</a> &#187;</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">
&copy; <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>
Reference in New Issue View Git Blame Copy Permalink