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

370 lines
45 KiB
HTML
Raw Permalink Blame History

<!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.generator: 生成 MIME 文档 &#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.policy: Policy 对象" href="email.policy.html" />
<link rel="prev" title="email.parser: 解析电子邮件信息" href="email.parser.html" />
<link rel="canonical" href="https://docs.python.org/3/library/email.generator.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.parser.html"
title="上一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.parser</span></code>: 解析电子邮件信息</a></p>
<h4>下一个主题</h4>
<p class="topless"><a href="email.policy.html"
title="下一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.policy</span></code>: Policy 对象</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.generator.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.generator.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.policy.html" title="email.policy: Policy 对象"
accesskey="N">下一页</a> |</li>
<li class="right" >
<a href="email.parser.html" title="email.parser: 解析电子邮件信息"
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.generator">
<span id="email-generator-generating-mime-documents"></span><h1><a class="reference internal" href="#module-email.generator" title="email.generator: Generate flat text email messages from a message structure."><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.generator</span></code></a>: 生成 MIME 文档<a class="headerlink" href="#module-email.generator" title="永久链接至标题"></a></h1>
<p><strong>源代码:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.8/Lib/email/generator.py">Lib/email/generator.py</a></p>
<hr class="docutils" />
<p>最普通的一种任务是生成由消息对象结构体表示的电子邮件消息的扁平（序列化）版本。 如果你想通过 <a class="reference internal" href="smtplib.html#smtplib.SMTP.sendmail" title="smtplib.SMTP.sendmail"><code class="xref py py-meth docutils literal notranslate"><span class="pre">smtplib.SMTP.sendmail()</span></code></a> 或 <a class="reference internal" href="nntplib.html#module-nntplib" title="nntplib: NNTP protocol client (requires sockets)."><code class="xref py py-mod docutils literal notranslate"><span class="pre">nntplib</span></code></a> 模块来发送你的消息或是将消息打印到控制台就将需要这样做。 接受一个消息对象结构体并生成其序列化表示就是这些生成器类的工作。</p>
<p>与 <a class="reference internal" href="email.parser.html#module-email.parser" title="email.parser: Parse flat text email messages to produce a message object structure."><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.parser</span></code></a> 模块一样，你并不会受限于已捆绑生成器的功能；你可以自己从头写一个。 不过，已捆绑生成器知道如何以符合标准的方式来生成大多数电子邮件，应该能够很好地处理 MIME 和非 MIME 电子邮件消息，并且被设计为面向字节的解析和生成操作是互逆的，它假定两者都使用同样的非转换型 <a class="reference internal" href="email.policy.html#module-email.policy" title="email.policy: Controlling the parsing and generating of messages"><code class="xref py py-mod docutils literal notranslate"><span class="pre">policy</span></code></a>。 也就是说，通过 <a class="reference internal" href="email.parser.html#email.parser.BytesParser" title="email.parser.BytesParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesParser</span></code></a> 类来解析序列化字节流然后再使用 <a class="reference internal" href="#email.generator.BytesGenerator" title="email.generator.BytesGenerator"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesGenerator</span></code></a> 来重新生成序列化字节流应当得到与输入相同的结果 <a class="footnote-reference brackets" href="#id3" id="id1">1</a>。 （而另一方面，在由程序所构造的 <a class="reference internal" href="email.message.html#email.message.EmailMessage" title="email.message.EmailMessage"><code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code></a> 上使用生成器可能导致对默认填入的 <a class="reference internal" href="email.message.html#email.message.EmailMessage" title="email.message.EmailMessage"><code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code></a> 对象的改变。。）</p>
<p>可以使用 <a class="reference internal" href="#email.generator.Generator" title="email.generator.Generator"><code class="xref py py-class docutils literal notranslate"><span class="pre">Generator</span></code></a> 类将消息扁平化为文本（而非二进制数据）的序列化表示形式，但是由于 Unicode 无法直接表示二进制数据，因此消息有必要被转换为仅包含 ASCII 字符的数据，这将使用标准电子邮件 RFC 内容传输编码格式技术来编码电子邮件消息以便通过非 “8 比特位兼容”的信道来传输。</p>
<p>为了适应 SMIME 签名消息的可重现处理过程，<a class="reference internal" href="#email.generator.Generator" title="email.generator.Generator"><code class="xref py py-class docutils literal notranslate"><span class="pre">Generator</span></code></a> 禁用了针对 <code class="docutils literal notranslate"><span class="pre">multipart/signed</span></code> 类型的消息部分及所有子部分的标头折叠。</p>
<dl class="class">
<dt id="email.generator.BytesGenerator">
<em class="property">class </em><code class="sig-prename descclassname">email.generator.</code><code class="sig-name descname">BytesGenerator</code><span class="sig-paren">(</span><em class="sig-param">outfp</em>, <em class="sig-param">mangle_from_=None</em>, <em class="sig-param">maxheaderlen=None</em>, <em class="sig-param">*</em>, <em class="sig-param">policy=None</em><span class="sig-paren">)</span><a class="headerlink" href="#email.generator.BytesGenerator" title="永久链接至目标"></a></dt>
<dd><p>返回一个 <a class="reference internal" href="#email.generator.BytesGenerator" title="email.generator.BytesGenerator"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesGenerator</span></code></a> 对象，该对象将把提供给 <a class="reference internal" href="#email.generator.BytesGenerator.flatten" title="email.generator.BytesGenerator.flatten"><code class="xref py py-meth docutils literal notranslate"><span class="pre">flatten()</span></code></a> 方法的任何消息或者提供给 <a class="reference internal" href="#email.generator.BytesGenerator.write" title="email.generator.BytesGenerator.write"><code class="xref py py-meth docutils literal notranslate"><span class="pre">write()</span></code></a> 方法的任何经过代理转义编码的文本写入到 <a class="reference internal" href="../glossary.html#term-file-like-object"><span class="xref std std-term">file-like object</span></a> <em>outfp</em>。 <em>outfp</em> 必须支持接受二进制数据的 <code class="docutils literal notranslate"><span class="pre">write</span></code> 方法。</p>
<p>如果可选的 <em>mangle_from_</em> 为 <code class="docutils literal notranslate"><span class="pre">True</span></code>，则会将一个 <code class="docutils literal notranslate"><span class="pre">&gt;</span></code> 字符放到恰好以字符串 <code class="docutils literal notranslate"><span class="pre">&quot;From</span> <span class="pre">&quot;</span></code> 打头，即开头文本为 <code class="docutils literal notranslate"><span class="pre">From</span></code> 加一个空格的的行前面。 <em>mangle_from_</em> 默认为 <em>policy</em> 的 <a class="reference internal" href="email.policy.html#email.policy.Policy.mangle_from_" title="email.policy.Policy.mangle_from_"><code class="xref py py-attr docutils literal notranslate"><span class="pre">mangle_from_</span></code></a> 设置值 (对于 <a class="reference internal" href="email.policy.html#email.policy.compat32" title="email.policy.compat32"><code class="xref py py-data docutils literal notranslate"><span class="pre">compat32</span></code></a> 策略为 <code class="docutils literal notranslate"><span class="pre">True</span></code>，对于所有其他策略则为 <code class="docutils literal notranslate"><span class="pre">False</span></code>)。 <em>mangle_from_</em> 被设计为在当消息以 unix mbox 格式存储时使用 (参见 <a class="reference internal" href="mailbox.html#module-mailbox" title="mailbox: Manipulate mailboxes in various formats"><code class="xref py py-mod docutils literal notranslate"><span class="pre">mailbox</span></code></a> 和 <a class="reference external" href="https://www.jwz.org/doc/content-length.html">WHY THE CONTENT-LENGTH FORMAT IS BAD</a>)。</p>
<p>如果 <em>maxheaderlen</em> 不为 <code class="docutils literal notranslate"><span class="pre">None</span></code>，则重新折叠任何长于 <em>maxheaderlen</em> 的标头行，或者如果为 <code class="docutils literal notranslate"><span class="pre">0</span></code>，则不重新包装任何标头。 如果 <em>manheaderlen</em> 为 <code class="docutils literal notranslate"><span class="pre">None</span></code> (默认值)，则根据 <em>policy</em> 设置包装标头和其他消息行。</p>
<p>如果指定了 <em>policy</em>，则使用该策略来控制消息的生成。 如果 <em>policy</em> 为 <code class="docutils literal notranslate"><span class="pre">None</span></code> (默认值)，则使用与传递给 <code class="docutils literal notranslate"><span class="pre">flatten</span></code> 的 <a class="reference internal" href="email.compat32-message.html#email.message.Message" title="email.message.Message"><code class="xref py py-class docutils literal notranslate"><span class="pre">Message</span></code></a> 或 <a class="reference internal" href="email.message.html#email.message.EmailMessage" title="email.message.EmailMessage"><code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code></a> 对象相关联的策略来控制消息的生成。 请参阅 <a class="reference internal" href="email.policy.html#module-email.policy" title="email.policy: Controlling the parsing and generating of messages"><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.policy</span></code></a> 了解有关 <em>policy</em> 所控制内容的详情。</p>
<div class="versionadded">
<p><span class="versionmodified added">3.2 新版功能.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.3 版更改: </span>添加了*policy*关键字。</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.6 版更改: </span><em>mangle_from_</em> 和 <em>maxheaderlen</em> 形参的默认行为是遵循策略。</p>
</div>
<dl class="method">
<dt id="email.generator.BytesGenerator.flatten">
<code class="sig-name descname">flatten</code><span class="sig-paren">(</span><em class="sig-param">msg</em>, <em class="sig-param">unixfrom=False</em>, <em class="sig-param">linesep=None</em><span class="sig-paren">)</span><a class="headerlink" href="#email.generator.BytesGenerator.flatten" title="永久链接至目标"></a></dt>
<dd><p>将将以 <em>msg</em> 为根的消息对象结构体的文本表示形式打印到创建 <a class="reference internal" href="#email.generator.BytesGenerator" title="email.generator.BytesGenerator"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesGenerator</span></code></a> 实例时指定的输出文件。</p>
<p>如果 <a class="reference internal" href="email.policy.html#module-email.policy" title="email.policy: Controlling the parsing and generating of messages"><code class="xref py py-mod docutils literal notranslate"><span class="pre">policy</span></code></a> 选项 <a class="reference internal" href="email.policy.html#email.policy.Policy.cte_type" title="email.policy.Policy.cte_type"><code class="xref py py-attr docutils literal notranslate"><span class="pre">cte_type</span></code></a> 为 <code class="docutils literal notranslate"><span class="pre">8bit</span></code> (默认值)，则会将未被修改的原始已解析消息中的任何标头拷贝到输出，其中会重新生成与原始数据相同的高比特位组字节数据，并保留具有它们的任何消息体部分的非 ASCII <em class="mailheader">Content-Transfer-Encoding</em>。 如果 <code class="docutils literal notranslate"><span class="pre">cte_type</span></code> 为 <code class="docutils literal notranslate"><span class="pre">7bit</span></code>，则会根据需要使用兼容 ASCII 的 <em class="mailheader">Content-Transfer-Encoding</em> 来转换高比特位组字节数据。 也就是说，将具有非 ASCII <em class="mailheader">Content-Transfer-Encoding</em> (<em class="mailheader">Content-Transfer-Encoding: 8bit</em>) 的部分转换为兼容 ASCII 的 <em class="mailheader">Content-Transfer-Encoding</em>，并使用 MIME <code class="docutils literal notranslate"><span class="pre">unknown-8bit</span></code> 字符集来编码标头中不符合 RFC 的非 ASCII 字节数据，以使其符合 RFC。</p>
<p>如果 <em>unixfrom</em> 为 <code class="docutils literal notranslate"><span class="pre">True</span></code>，则会在根消息对象的第一个 <span class="target" id="index-4"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc5322.html"><strong>RFC 5322</strong></a> 标头之前打印 Unix mailbox 格式 (参见 <a class="reference internal" href="mailbox.html#module-mailbox" title="mailbox: Manipulate mailboxes in various formats"><code class="xref py py-mod docutils literal notranslate"><span class="pre">mailbox</span></code></a>) 所使用的封包标头分隔符。 如果根对象没有封包标头，则会创建一个标准标头。 默认值为 <code class="docutils literal notranslate"><span class="pre">False</span></code>。 请注意对于子部分来说，不会打印任何封包标头。</p>
<p>如果 <em>linesep</em> 不为 <code class="docutils literal notranslate"><span class="pre">None</span></code>，则会将其用作扁平化消息的所有行之间的分隔符。 如果 <em>linesep</em> 为 <code class="docutils literal notranslate"><span class="pre">None</span></code> (默认值)，则使用在 <em>policy</em> 中指定的值。</p>
</dd></dl>
<dl class="method">
<dt id="email.generator.BytesGenerator.clone">
<code class="sig-name descname">clone</code><span class="sig-paren">(</span><em class="sig-param">fp</em><span class="sig-paren">)</span><a class="headerlink" href="#email.generator.BytesGenerator.clone" title="永久链接至目标"></a></dt>
<dd><p>返回此Return an independent clone of this <a class="reference internal" href="#email.generator.BytesGenerator" title="email.generator.BytesGenerator"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesGenerator</span></code></a> 实例的独立克隆，具有完全相同的选项设置，而 <em>fp</em> 为新的 <em>outfp</em>。</p>
</dd></dl>
<dl class="method">
<dt id="email.generator.BytesGenerator.write">
<code class="sig-name descname">write</code><span class="sig-paren">(</span><em class="sig-param">s</em><span class="sig-paren">)</span><a class="headerlink" href="#email.generator.BytesGenerator.write" title="永久链接至目标"></a></dt>
<dd><p>使用 <code class="docutils literal notranslate"><span class="pre">ASCII</span></code> 编解码器和 <code class="docutils literal notranslate"><span class="pre">surrogateescape</span></code> 错误处理程序编码 <em>s</em>，并将其传递给传入到 <a class="reference internal" href="#email.generator.BytesGenerator" title="email.generator.BytesGenerator"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesGenerator</span></code></a> 的构造器的 <em>outfp</em> 的 <em>write</em> 方法 。</p>
</dd></dl>
</dd></dl>
<p>作为一个便捷工具，<a class="reference internal" href="email.message.html#email.message.EmailMessage" title="email.message.EmailMessage"><code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code></a> 提供了 <a class="reference internal" href="email.message.html#email.message.EmailMessage.as_bytes" title="email.message.EmailMessage.as_bytes"><code class="xref py py-meth docutils literal notranslate"><span class="pre">as_bytes()</span></code></a> 和 <code class="docutils literal notranslate"><span class="pre">bytes(aMessage)</span></code> (即 <a class="reference internal" href="email.message.html#email.message.EmailMessage.__bytes__" title="email.message.EmailMessage.__bytes__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__bytes__()</span></code></a>) 等方法，它们简单地生成一个消息对象的序列化二进制表示形式。 更多细节请参阅 <a class="reference internal" href="email.message.html#module-email.message" title="email.message: The base class representing email messages."><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.message</span></code></a>。</p>
<p>因为字符串无法表示二进制数据，<a class="reference internal" href="#email.generator.Generator" title="email.generator.Generator"><code class="xref py py-class docutils literal notranslate"><span class="pre">Generator</span></code></a> 类必须将任何消息中扁平化的任何二进制数据转换为兼容 ASCII 的格式，具体将其转换为兼容 ASCII 的 <em class="mailheader">Content-Transfer_Encoding</em>。 使用电子邮件 RFC 的术语，你可以将其视作 <a class="reference internal" href="#email.generator.Generator" title="email.generator.Generator"><code class="xref py py-class docutils literal notranslate"><span class="pre">Generator</span></code></a> 序列化为不 &quot;支持 8 比特&quot; 的 I/O 流。 换句话说，大部分应用程序将需要使用 <a class="reference internal" href="#email.generator.BytesGenerator" title="email.generator.BytesGenerator"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesGenerator</span></code></a>，而非 <a class="reference internal" href="#email.generator.Generator" title="email.generator.Generator"><code class="xref py py-class docutils literal notranslate"><span class="pre">Generator</span></code></a>。</p>
<dl class="class">
<dt id="email.generator.Generator">
<em class="property">class </em><code class="sig-prename descclassname">email.generator.</code><code class="sig-name descname">Generator</code><span class="sig-paren">(</span><em class="sig-param">outfp</em>, <em class="sig-param">mangle_from_=None</em>, <em class="sig-param">maxheaderlen=None</em>, <em class="sig-param">*</em>, <em class="sig-param">policy=None</em><span class="sig-paren">)</span><a class="headerlink" href="#email.generator.Generator" title="永久链接至目标"></a></dt>
<dd><p>返回一个 <a class="reference internal" href="#email.generator.Generator" title="email.generator.Generator"><code class="xref py py-class docutils literal notranslate"><span class="pre">Generator</span></code></a>，它将把提供给 <a class="reference internal" href="#email.generator.Generator.flatten" title="email.generator.Generator.flatten"><code class="xref py py-meth docutils literal notranslate"><span class="pre">flatten()</span></code></a> 方法的任何消息，或者提供给 <a class="reference internal" href="#email.generator.Generator.write" title="email.generator.Generator.write"><code class="xref py py-meth docutils literal notranslate"><span class="pre">write()</span></code></a> 方法的任何文本写入到 <a class="reference internal" href="../glossary.html#term-file-like-object"><span class="xref std std-term">file-like object</span></a> <em>outfp</em>。 <em>outfp</em> 必须支持接受字符串数据的 <code class="docutils literal notranslate"><span class="pre">write</span></code> 方法。</p>
<p>如果可选的 <em>mangle_from_</em> 为 <code class="docutils literal notranslate"><span class="pre">True</span></code>，则会将一个 <code class="docutils literal notranslate"><span class="pre">&gt;</span></code> 字符放到恰好以字符串 <code class="docutils literal notranslate"><span class="pre">&quot;From</span> <span class="pre">&quot;</span></code> 打头，即开头文本为 <code class="docutils literal notranslate"><span class="pre">From</span></code> 加一个空格的的行前面。 <em>mangle_from_</em> 默认为 <em>policy</em> 的 <a class="reference internal" href="email.policy.html#email.policy.Policy.mangle_from_" title="email.policy.Policy.mangle_from_"><code class="xref py py-attr docutils literal notranslate"><span class="pre">mangle_from_</span></code></a> 设置值 (对于 <a class="reference internal" href="email.policy.html#email.policy.compat32" title="email.policy.compat32"><code class="xref py py-data docutils literal notranslate"><span class="pre">compat32</span></code></a> 策略为 <code class="docutils literal notranslate"><span class="pre">True</span></code>，对于所有其他策略则为 <code class="docutils literal notranslate"><span class="pre">False</span></code>)。 <em>mangle_from_</em> 被设计为在当消息以 unix mbox 格式存储时使用 (参见 <a class="reference internal" href="mailbox.html#module-mailbox" title="mailbox: Manipulate mailboxes in various formats"><code class="xref py py-mod docutils literal notranslate"><span class="pre">mailbox</span></code></a> 和 <a class="reference external" href="https://www.jwz.org/doc/content-length.html">WHY THE CONTENT-LENGTH FORMAT IS BAD</a>)。</p>
<p>如果 <em>maxheaderlen</em> 不为 <code class="docutils literal notranslate"><span class="pre">None</span></code>，则重新折叠任何长于 <em>maxheaderlen</em> 的标头行，或者如果为 <code class="docutils literal notranslate"><span class="pre">0</span></code>，则不重新包装任何标头。 如果 <em>manheaderlen</em> 为 <code class="docutils literal notranslate"><span class="pre">None</span></code> (默认值)，则根据 <em>policy</em> 设置包装标头和其他消息行。</p>
<p>如果指定了 <em>policy</em>，则使用该策略来控制消息的生成。 如果 <em>policy</em> 为 <code class="docutils literal notranslate"><span class="pre">None</span></code> (默认值)，则使用与传递给 <code class="docutils literal notranslate"><span class="pre">flatten</span></code> 的 <a class="reference internal" href="email.compat32-message.html#email.message.Message" title="email.message.Message"><code class="xref py py-class docutils literal notranslate"><span class="pre">Message</span></code></a> 或 <a class="reference internal" href="email.message.html#email.message.EmailMessage" title="email.message.EmailMessage"><code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code></a> 对象相关联的策略来控制消息的生成。 请参阅 <a class="reference internal" href="email.policy.html#module-email.policy" title="email.policy: Controlling the parsing and generating of messages"><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.policy</span></code></a> 了解有关 <em>policy</em> 所控制内容的详情。</p>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.3 版更改: </span>添加了*policy*关键字。</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.6 版更改: </span><em>mangle_from_</em> 和 <em>maxheaderlen</em> 形参的默认行为是遵循策略。</p>
</div>
<dl class="method">
<dt id="email.generator.Generator.flatten">
<code class="sig-name descname">flatten</code><span class="sig-paren">(</span><em class="sig-param">msg</em>, <em class="sig-param">unixfrom=False</em>, <em class="sig-param">linesep=None</em><span class="sig-paren">)</span><a class="headerlink" href="#email.generator.Generator.flatten" title="永久链接至目标"></a></dt>
<dd><p>将以 <em>msg</em> 为根的消息对象结构体的文本表示形式打印到当 <a class="reference internal" href="#email.generator.Generator" title="email.generator.Generator"><code class="xref py py-class docutils literal notranslate"><span class="pre">Generator</span></code></a> 实例被创建时所指定的输出文件。</p>
<p>如果 <a class="reference internal" href="email.policy.html#module-email.policy" title="email.policy: Controlling the parsing and generating of messages"><code class="xref py py-mod docutils literal notranslate"><span class="pre">policy</span></code></a> 选项 <a class="reference internal" href="email.policy.html#email.policy.Policy.cte_type" title="email.policy.Policy.cte_type"><code class="xref py py-attr docutils literal notranslate"><span class="pre">cte_type</span></code></a> 为 <code class="docutils literal notranslate"><span class="pre">8bit</span></code>，则视同选项被设为 <code class="docutils literal notranslate"><span class="pre">7bit</span></code> 来生成消息。 （这是必需的，因为字符串无法表示非 ASCII 字节数据。） 将使用兼容 ASCII 的 <em class="mailheader">Content-Transfer-Encoding</em> 按需转换任何具有高比特位组的字节数据。 也就是说，将具有非 ASCII <em class="mailheader">Content-Transfer-Encoding</em> (<em class="mailheader">Content-Transfer-Encoding: 8bit</em>) 的部分转换为兼容 ASCII 的 <em class="mailheader">Content-Transfer-Encoding</em>，并使用 MIME <code class="docutils literal notranslate"><span class="pre">unknown-8bit</span></code> 字符集来编码标头中不符合 RFC 的非 ASCII 字节数据，以使其符合 RFC。</p>
<p>如果 <em>unixfrom</em> 为 <code class="docutils literal notranslate"><span class="pre">True</span></code>，则会在根消息对象的第一个 <span class="target" id="index-5"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc5322.html"><strong>RFC 5322</strong></a> 标头之前打印 Unix mailbox 格式 (参见 <a class="reference internal" href="mailbox.html#module-mailbox" title="mailbox: Manipulate mailboxes in various formats"><code class="xref py py-mod docutils literal notranslate"><span class="pre">mailbox</span></code></a>) 所使用的封包标头分隔符。 如果根对象没有封包标头，则会创建一个标准标头。 默认值为 <code class="docutils literal notranslate"><span class="pre">False</span></code>。 请注意对于子部分来说，不会打印任何封包标头。</p>
<p>如果 <em>linesep</em> 不为 <code class="docutils literal notranslate"><span class="pre">None</span></code>，则会将其用作扁平化消息的所有行之间的分隔符。 如果 <em>linesep</em> 为 <code class="docutils literal notranslate"><span class="pre">None</span></code> (默认值)，则使用在 <em>policy</em> 中指定的值。</p>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.2 版更改: </span>添加了对重编码 <code class="docutils literal notranslate"><span class="pre">8bit</span></code> 消息体的支持，以及 <em>linesep</em> 参数。</p>
</div>
</dd></dl>
<dl class="method">
<dt id="email.generator.Generator.clone">
<code class="sig-name descname">clone</code><span class="sig-paren">(</span><em class="sig-param">fp</em><span class="sig-paren">)</span><a class="headerlink" href="#email.generator.Generator.clone" title="永久链接至目标"></a></dt>
<dd><p>返回此 <a class="reference internal" href="#email.generator.Generator" title="email.generator.Generator"><code class="xref py py-class docutils literal notranslate"><span class="pre">Generator</span></code></a> 实例的独立克隆，具有完全相同的选项设置，而 <em>fp</em> 为新的 <em>outfp</em>。</p>
</dd></dl>
<dl class="method">
<dt id="email.generator.Generator.write">
<code class="sig-name descname">write</code><span class="sig-paren">(</span><em class="sig-param">s</em><span class="sig-paren">)</span><a class="headerlink" href="#email.generator.Generator.write" title="永久链接至目标"></a></dt>
<dd><p>将 <em>s</em> 写入到传给 <a class="reference internal" href="#email.generator.Generator" title="email.generator.Generator"><code class="xref py py-class docutils literal notranslate"><span class="pre">Generator</span></code></a> 的构造器的 <em>outfp</em> 的 <em>write</em> 方法。 这足够为 <a class="reference internal" href="#email.generator.Generator" title="email.generator.Generator"><code class="xref py py-class docutils literal notranslate"><span class="pre">Generator</span></code></a> 实际提供可用于 <a class="reference internal" href="functions.html#print" title="print"><code class="xref py py-func docutils literal notranslate"><span class="pre">print()</span></code></a> 函数的文件类 API。</p>
</dd></dl>
</dd></dl>
<p>作为一个便捷工具，<a class="reference internal" href="email.message.html#email.message.EmailMessage" title="email.message.EmailMessage"><code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code></a> 提供了 <a class="reference internal" href="email.message.html#email.message.EmailMessage.as_string" title="email.message.EmailMessage.as_string"><code class="xref py py-meth docutils literal notranslate"><span class="pre">as_string()</span></code></a> 和 <code class="docutils literal notranslate"><span class="pre">str(aMessage)</span></code> (即 <a class="reference internal" href="email.message.html#email.message.EmailMessage.__str__" title="email.message.EmailMessage.__str__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__str__()</span></code></a>) 等方法，它们简单地生成一个消息对象的已格式化字符串表示形式。 更多细节请参阅 <a class="reference internal" href="email.message.html#module-email.message" title="email.message: The base class representing email messages."><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.message</span></code></a>。</p>
<p><a class="reference internal" href="#module-email.generator" title="email.generator: Generate flat text email messages from a message structure."><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.generator</span></code></a> 模块还提供了一个派生类 <a class="reference internal" href="#email.generator.DecodedGenerator" title="email.generator.DecodedGenerator"><code class="xref py py-class docutils literal notranslate"><span class="pre">DecodedGenerator</span></code></a>，它类似于 <a class="reference internal" href="#email.generator.Generator" title="email.generator.Generator"><code class="xref py py-class docutils literal notranslate"><span class="pre">Generator</span></code></a> 基类，不同之处在于非 <em class="mimetype">text</em> 部分不会被序列化，而是被表示为 基于模板并填写了有关该部分的信息的字符串输出流的形式。</p>
<dl class="class">
<dt id="email.generator.DecodedGenerator">
<em class="property">class </em><code class="sig-prename descclassname">email.generator.</code><code class="sig-name descname">DecodedGenerator</code><span class="sig-paren">(</span><em class="sig-param">outfp</em>, <em class="sig-param">mangle_from_=None</em>, <em class="sig-param">maxheaderlen=None</em>, <em class="sig-param">fmt=None</em>, <em class="sig-param">*</em>, <em class="sig-param">policy=None</em><span class="sig-paren">)</span><a class="headerlink" href="#email.generator.DecodedGenerator" title="永久链接至目标"></a></dt>
<dd><p>行为类似于 <a class="reference internal" href="#email.generator.Generator" title="email.generator.Generator"><code class="xref py py-class docutils literal notranslate"><span class="pre">Generator</span></code></a>，不同之处在于对传给 <a class="reference internal" href="#email.generator.Generator.flatten" title="email.generator.Generator.flatten"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Generator.flatten()</span></code></a> 的消息的任何子部分，如果该子部分的主类型为 <em class="mimetype">text</em>，则打印该子部分的已解码载荷，而如果其主类型不为 <em class="mimetype">text</em>，则不直接打印它而是使用来自该部分的信息填入字符串 <em>fmt</em> 并将填写完成的字符串打印出来。</p>
<p>要填入 <em>fmt</em>，则执行 <code class="docutils literal notranslate"><span class="pre">fmt</span> <span class="pre">%</span> <span class="pre">part_info</span></code>，其中 <code class="docutils literal notranslate"><span class="pre">part_info</span></code> 是由下列键和值组成的字典:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">type</span></code> -- 非 <em class="mimetype">text</em> 部分的完整 MIME 类型</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">maintype</span></code> -- 非 <em class="mimetype">text</em> 部分的主 MIME 类型</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">subtype</span></code> -- 非 <em class="mimetype">text</em> 部分的子 MIME 类型</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">filename</span></code> -- 非 <em class="mimetype">text</em> 部分的文件名</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">description</span></code> -- 与非 <em class="mimetype">text</em> 部分相关联的描述</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">encoding</span></code> -- 非 <em class="mimetype">text</em> 部分的内容转换编码格式</p></li>
</ul>
<p>如果 <em>fmt</em> 为 <code class="docutils literal notranslate"><span class="pre">None</span></code>，则使用下列默认 <em>fmt</em>:</p>
<blockquote>
<div><p>&quot;[忽略消息的非文本 (%(type)s) 部分，文件名 %(filename)s]&quot;</p>
</div></blockquote>
<p>可选的 <em>_mangle_from_</em> 和 <em>maxheaderlen</em> 与 <a class="reference internal" href="#email.generator.Generator" title="email.generator.Generator"><code class="xref py py-class docutils literal notranslate"><span class="pre">Generator</span></code></a> 基类的相同。</p>
</dd></dl>
<p class="rubric">备注</p>
<dl class="footnote brackets">
<dt class="label" id="id3"><span class="brackets"><a class="fn-backref" href="#id1">1</a></span></dt>
<dd><p>此语句假定你使用了正确的 <code class="docutils literal notranslate"><span class="pre">unixfrom</span></code> 设置，并且没有用于自动调整的 <code class="xref py py-mod docutils literal notranslate"><span class="pre">policy</span></code> 设置调用（例如 <code class="xref py py-attr docutils literal notranslate"><span class="pre">refold_source</span></code> 必须为 <code class="docutils literal notranslate"><span class="pre">none</span></code>，这 <em>不是</em> 默认值）。 这也不是 100% 为真，因为如果消息不遵循 RFC 标准则有时实际原始文本的信息会在解析错误恢复时丢失。 它的目标是在可能的情况下修复这些后续边缘情况。</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.parser.html"
title="上一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.parser</span></code>: 解析电子邮件信息</a></p>
<h4>下一个主题</h4>
<p class="topless"><a href="email.policy.html"
title="下一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.policy</span></code>: Policy 对象</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.generator.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.policy.html" title="email.policy: Policy 对象"
>下一页</a> |</li>
<li class="right" >
<a href="email.parser.html" title="email.parser: 解析电子邮件信息"
>上一页</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