Baoding-FenShuaJiang
/
Green_GoodERP18_FSJ_Standard
Observar 1
Favorito 0
Wiki 捐赠
gooderp18绿色标准版
Você não pode selecionar mais de 25 tópicos Os tópicos devem começar com uma letra ou um número, podem incluir traços ('-') e podem ter até 35 caracteres.
Tag: 0f75e31513
Branches Tags
${ item.name }
Criar branch ${ searchTerm }
de 0f75e31513
${ noResults }
Green_GoodERP18_FSJ_Standard/python/Doc/html/library/email.policy.html

935 linhas
85KB
Original Anotar Histórico 

  1. <!DOCTYPE html>

  2. 

  3. <html lang="en" data-content_root="../">

  4.   <head>

  5.     <meta charset="utf-8" />

  6.     <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  7. <meta property="og:title" content="email.policy: Policy Objects" />

  8. <meta property="og:type" content="website" />

  9. <meta property="og:url" content="https://docs.python.org/3/library/email.policy.html" />

  10. <meta property="og:site_name" content="Python documentation" />

  11. <meta property="og:description" content="Source code: Lib/email/policy.py The email package’s prime focus is the handling of email messages as described by the various email and MIME RFCs. However, the general format of email messages (a ..." />

  12. <meta property="og:image" content="https://docs.python.org/3/_static/og-image.png" />

  13. <meta property="og:image:alt" content="Python documentation" />

  14. <meta name="description" content="Source code: Lib/email/policy.py The email package’s prime focus is the handling of email messages as described by the various email and MIME RFCs. However, the general format of email messages (a ..." />

  15. <meta property="og:image:width" content="200" />

  16. <meta property="og:image:height" content="200" />

  17. <meta name="theme-color" content="#3776ab" />

  18. 

  19.     <title>email.policy: Policy Objects &#8212; Python 3.12.3 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">

  20.     

  21.     <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />

  22.     <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=bb723527" />

  23.     <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=b20cc3f5" />

  24.     

  25.     <script src="../_static/documentation_options.js?v=2c828074"></script>

  26.     <script src="../_static/doctools.js?v=888ff710"></script>

  27.     <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>

  28.     

  29.     <script src="../_static/sidebar.js"></script>

  30.     

  31.     <link rel="search" type="application/opensearchdescription+xml"

  32.           title="Search within Python 3.12.3 documentation"

  33.           href="../_static/opensearch.xml"/>

  34.     <link rel="author" title="About these documents" href="../about.html" />

  35.     <link rel="index" title="Index" href="../genindex.html" />

  36.     <link rel="search" title="Search" href="../search.html" />

  37.     <link rel="copyright" title="Copyright" href="../copyright.html" />

  38.     <link rel="next" title="email.errors: Exception and Defect classes" href="email.errors.html" />

  39.     <link rel="prev" title="email.generator: Generating MIME documents" href="email.generator.html" />

  40.     <link rel="canonical" href="https://docs.python.org/3/library/email.policy.html" />

  41.     

  42.       

  43.     

  44. 

  45.     

  46.     <style>

  47.       @media only screen {

  48.         table.full-width-table {

  49.             width: 100%;

  50.         }

  51.       }

  52.     </style>

  53. <link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">

  54.     <link rel="shortcut icon" type="image/png" href="../_static/py.svg" />

  55.             <script type="text/javascript" src="../_static/copybutton.js"></script>

  56.             <script type="text/javascript" src="../_static/menu.js"></script>

  57.             <script type="text/javascript" src="../_static/search-focus.js"></script>

  58.             <script type="text/javascript" src="../_static/themetoggle.js"></script> 

  59. 

  60.   </head>

  61. <body>

  62. <div class="mobile-nav">

  63.     <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"

  64.            aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />

  65.     <nav class="nav-content" role="navigation">

  66.         <label for="menuToggler" class="toggler__label">

  67.             <span></span>

  68.         </label>

  69.         <span class="nav-items-wrapper">

  70.             <a href="https://www.python.org/" class="nav-logo">

  71.                 <img src="../_static/py.svg" alt="Python logo"/>

  72.             </a>

  73.             <span class="version_switcher_placeholder"></span>

  74.             <form role="search" class="search" action="../search.html" method="get">

  75.                 <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">

  76.                     <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>

  77.                 </svg>

  78.                 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" />

  79.                 <input type="submit" value="Go"/>

  80.             </form>

  81.         </span>

  82.     </nav>

  83.     <div class="menu-wrapper">

  84.         <nav class="menu" role="navigation" aria-label="main navigation">

  85.             <div class="language_switcher_placeholder"></div>

  86.             

  87. <label class="theme-selector-label">

  88.     Theme

  89.     <select class="theme-selector" oninput="activateTheme(this.value)">

  90.         <option value="auto" selected>Auto</option>

  91.         <option value="light">Light</option>

  92.         <option value="dark">Dark</option>

  93.     </select>

  94. </label>

  95.   <div>

  96.     <h4>Previous topic</h4>

  97.     <p class="topless"><a href="email.generator.html"

  98.                           title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.generator</span></code>: Generating MIME documents</a></p>

  99.   </div>

  100.   <div>

  101.     <h4>Next topic</h4>

  102.     <p class="topless"><a href="email.errors.html"

  103.                           title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.errors</span></code>: Exception and Defect classes</a></p>

  104.   </div>

  105.   <div role="note" aria-label="source link">

  106.     <h3>This Page</h3>

  107.     <ul class="this-page-menu">

  108.       <li><a href="../bugs.html">Report a Bug</a></li>

  109.       <li>

  110.         <a href="https://github.com/python/cpython/blob/main/Doc/library/email.policy.rst"

  111.             rel="nofollow">Show Source

  112.         </a>

  113.       </li>

  114.     </ul>

  115.   </div>

  116.         </nav>

  117.     </div>

  118. </div>

  119. 

  120.   

  121.     <div class="related" role="navigation" aria-label="related navigation">

  122.       <h3>Navigation</h3>

  123.       <ul>

  124.         <li class="right" style="margin-right: 10px">

  125.           <a href="../genindex.html" title="General Index"

  126.              accesskey="I">index</a></li>

  127.         <li class="right" >

  128.           <a href="../py-modindex.html" title="Python Module Index"

  129.              >modules</a> |</li>

  130.         <li class="right" >

  131.           <a href="email.errors.html" title="email.errors: Exception and Defect classes"

  132.              accesskey="N">next</a> |</li>

  133.         <li class="right" >

  134.           <a href="email.generator.html" title="email.generator: Generating MIME documents"

  135.              accesskey="P">previous</a> |</li>

  136. 

  137.           <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>

  138.           <li><a href="https://www.python.org/">Python</a> &#187;</li>

  139.           <li class="switchers">

  140.             <div class="language_switcher_placeholder"></div>

  141.             <div class="version_switcher_placeholder"></div>

  142.           </li>

  143.           <li>

  144.               

  145.           </li>

  146.     <li id="cpython-language-and-version">

  147.       <a href="../index.html">3.12.3 Documentation</a> &#187;

  148.     </li>

  149. 

  150.           <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>

  151.           <li class="nav-item nav-item-2"><a href="netdata.html" >Internet Data Handling</a> &#187;</li>

  152.           <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> — An email and MIME handling package</a> &#187;</li>

  153.         <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.policy</span></code>: Policy Objects</a></li>

  154.                 <li class="right">

  155.                     

  156. 

  157.     <div class="inline-search" role="search">

  158.         <form class="inline-search" action="../search.html" method="get">

  159.           <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />

  160.           <input type="submit" value="Go" />

  161.         </form>

  162.     </div>

  163.                      |

  164.                 </li>

  165.             <li class="right">

  166. <label class="theme-selector-label">

  167.     Theme

  168.     <select class="theme-selector" oninput="activateTheme(this.value)">

  169.         <option value="auto" selected>Auto</option>

  170.         <option value="light">Light</option>

  171.         <option value="dark">Dark</option>

  172.     </select>

  173. </label> |</li>

  174.             

  175.       </ul>

  176.     </div>    

  177. 

  178.     <div class="document">

  179.       <div class="documentwrapper">

  180.         <div class="bodywrapper">

  181.           <div class="body" role="main">

  182.             

  183.   <section id="module-email.policy">

  184. <span id="email-policy-policy-objects"></span><h1><a class="reference internal" href="#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>: Policy Objects<a class="headerlink" href="#module-email.policy" title="Link to this heading">¶</a></h1>

  185. <div class="versionadded">

  186. <p><span class="versionmodified added">New in version 3.3.</span></p>

  187. </div>

  188. <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/email/policy.py">Lib/email/policy.py</a></p>

  189. <hr class="docutils" />

  190. <p>The <a class="reference internal" href="email.html#module-email" title="email: Package supporting the parsing, manipulating, and generating email messages."><code class="xref py py-mod docutils literal notranslate"><span class="pre">email</span></code></a> package’s prime focus is the handling of email messages as

  191. described by the various email and MIME RFCs.  However, the general format of

  192. email messages (a block of header fields each consisting of a name followed by

  193. a colon followed by a value, the whole block followed by a blank line and an

  194. arbitrary ‘body’), is a format that has found utility outside of the realm of

  195. email.  Some of these uses conform fairly closely to the main email RFCs, some

  196. do not.  Even when working with email, there are times when it is desirable to

  197. break strict compliance with the RFCs, such as generating emails that

  198. interoperate with email servers that do not themselves follow the standards, or

  199. that implement extensions you want to use in ways that violate the

  200. standards.</p>

  201. <p>Policy objects give the email package the flexibility to handle all these

  202. disparate use cases.</p>

  203. <p>A <a class="reference internal" href="#email.policy.Policy" title="email.policy.Policy"><code class="xref py py-class docutils literal notranslate"><span class="pre">Policy</span></code></a> object encapsulates a set of attributes and methods that

  204. control the behavior of various components of the email package during use.

  205. <a class="reference internal" href="#email.policy.Policy" title="email.policy.Policy"><code class="xref py py-class docutils literal notranslate"><span class="pre">Policy</span></code></a> instances can be passed to various classes and methods in the

  206. email package to alter the default behavior.  The settable values and their

  207. defaults are described below.</p>

  208. <p>There is a default policy used by all classes in the email package.  For all of

  209. the <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">parser</span></code></a> classes and the related convenience functions, and for

  210. the <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> class, this is the <a class="reference internal" href="#email.policy.Compat32" title="email.policy.Compat32"><code class="xref py py-class docutils literal notranslate"><span class="pre">Compat32</span></code></a>

  211. policy, via its corresponding pre-defined instance <a class="reference internal" href="#email.policy.compat32" title="email.policy.compat32"><code class="xref py py-const docutils literal notranslate"><span class="pre">compat32</span></code></a>.  This

  212. policy provides for complete backward compatibility (in some cases, including

  213. bug compatibility) with the pre-Python3.3 version of the email package.</p>

  214. <p>This default value for the <em>policy</em> keyword to

  215. <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> is the <a class="reference internal" href="#email.policy.EmailPolicy" title="email.policy.EmailPolicy"><code class="xref py py-class docutils literal notranslate"><span class="pre">EmailPolicy</span></code></a> policy, via

  216. its pre-defined instance <a class="reference internal" href="#email.policy.default" title="email.policy.default"><code class="xref py py-data docutils literal notranslate"><span class="pre">default</span></code></a>.</p>

  217. <p>When a <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> or <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>

  218. object is created, it acquires a policy.  If the message is created by a

  219. <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">parser</span></code></a>, a policy passed to the parser will be the policy used by

  220. the message it creates.  If the message is created by the program, then the

  221. policy can be specified when it is created.  When a message is passed to a

  222. <a class="reference internal" href="email.generator.html#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">generator</span></code></a>, the generator uses the policy from the message by

  223. default, but you can also pass a specific policy to the generator that will

  224. override the one stored on the message object.</p>

  225. <p>The default value for the <em>policy</em> keyword for the <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> classes

  226. and the parser convenience functions <strong>will be changing</strong> in a future version of

  227. Python.  Therefore you should <strong>always specify explicitly which policy you want

  228. to use</strong> when calling any of the classes and functions described in the

  229. <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">parser</span></code></a> module.</p>

  230. <p>The first part of this documentation covers the features of <a class="reference internal" href="#email.policy.Policy" title="email.policy.Policy"><code class="xref py py-class docutils literal notranslate"><span class="pre">Policy</span></code></a>, an

  231. <a class="reference internal" href="../glossary.html#term-abstract-base-class"><span class="xref std std-term">abstract base class</span></a> that defines the features that are common to all

  232. policy objects, including <a class="reference internal" href="#email.policy.compat32" title="email.policy.compat32"><code class="xref py py-const docutils literal notranslate"><span class="pre">compat32</span></code></a>.  This includes certain hook

  233. methods that are called internally by the email package, which a custom policy

  234. could override to obtain different behavior.  The second part describes the

  235. concrete classes <a class="reference internal" href="#email.policy.EmailPolicy" title="email.policy.EmailPolicy"><code class="xref py py-class docutils literal notranslate"><span class="pre">EmailPolicy</span></code></a> and <a class="reference internal" href="#email.policy.Compat32" title="email.policy.Compat32"><code class="xref py py-class docutils literal notranslate"><span class="pre">Compat32</span></code></a>, which implement

  236. the hooks that provide the standard behavior and the backward compatible

  237. behavior and features, respectively.</p>

  238. <p><a class="reference internal" href="#email.policy.Policy" title="email.policy.Policy"><code class="xref py py-class docutils literal notranslate"><span class="pre">Policy</span></code></a> instances are immutable, but they can be cloned, accepting the

  239. same keyword arguments as the class constructor and returning a new

  240. <a class="reference internal" href="#email.policy.Policy" title="email.policy.Policy"><code class="xref py py-class docutils literal notranslate"><span class="pre">Policy</span></code></a> instance that is a copy of the original but with the specified

  241. attributes values changed.</p>

  242. <p>As an example, the following code could be used to read an email message from a

  243. file on disk and pass it to the system <code class="docutils literal notranslate"><span class="pre">sendmail</span></code> program on a Unix system:</p>

  244. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">email</span> <span class="kn">import</span> <span class="n">message_from_binary_file</span>

  245. <span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">email.generator</span> <span class="kn">import</span> <span class="n">BytesGenerator</span>

  246. <span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">email</span> <span class="kn">import</span> <span class="n">policy</span>

  247. <span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">subprocess</span> <span class="kn">import</span> <span class="n">Popen</span><span class="p">,</span> <span class="n">PIPE</span>

  248. <span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">&#39;mymsg.txt&#39;</span><span class="p">,</span> <span class="s1">&#39;rb&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>

  249. <span class="gp">... </span>    <span class="n">msg</span> <span class="o">=</span> <span class="n">message_from_binary_file</span><span class="p">(</span><span class="n">f</span><span class="p">,</span> <span class="n">policy</span><span class="o">=</span><span class="n">policy</span><span class="o">.</span><span class="n">default</span><span class="p">)</span>

  250. <span class="gp">...</span>

  251. <span class="gp">&gt;&gt;&gt; </span><span class="n">p</span> <span class="o">=</span> <span class="n">Popen</span><span class="p">([</span><span class="s1">&#39;sendmail&#39;</span><span class="p">,</span> <span class="n">msg</span><span class="p">[</span><span class="s1">&#39;To&#39;</span><span class="p">]</span><span class="o">.</span><span class="n">addresses</span><span class="p">[</span><span class="mi">0</span><span class="p">]],</span> <span class="n">stdin</span><span class="o">=</span><span class="n">PIPE</span><span class="p">)</span>

  252. <span class="gp">&gt;&gt;&gt; </span><span class="n">g</span> <span class="o">=</span> <span class="n">BytesGenerator</span><span class="p">(</span><span class="n">p</span><span class="o">.</span><span class="n">stdin</span><span class="p">,</span> <span class="n">policy</span><span class="o">=</span><span class="n">msg</span><span class="o">.</span><span class="n">policy</span><span class="o">.</span><span class="n">clone</span><span class="p">(</span><span class="n">linesep</span><span class="o">=</span><span class="s1">&#39;</span><span class="se">\r\n</span><span class="s1">&#39;</span><span class="p">))</span>

  253. <span class="gp">&gt;&gt;&gt; </span><span class="n">g</span><span class="o">.</span><span class="n">flatten</span><span class="p">(</span><span class="n">msg</span><span class="p">)</span>

  254. <span class="gp">&gt;&gt;&gt; </span><span class="n">p</span><span class="o">.</span><span class="n">stdin</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>

  255. <span class="gp">&gt;&gt;&gt; </span><span class="n">rc</span> <span class="o">=</span> <span class="n">p</span><span class="o">.</span><span class="n">wait</span><span class="p">()</span>

  256. </pre></div>

  257. </div>

  258. <p>Here we are telling <a class="reference internal" href="email.generator.html#email.generator.BytesGenerator" title="email.generator.BytesGenerator"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesGenerator</span></code></a> to use the RFC

  259. correct line separator characters when creating the binary string to feed into

  260. <code class="docutils literal notranslate"><span class="pre">sendmail's</span></code> <code class="docutils literal notranslate"><span class="pre">stdin</span></code>, where the default policy would use <code class="docutils literal notranslate"><span class="pre">\n</span></code> line

  261. separators.</p>

  262. <p>Some email package methods accept a <em>policy</em> keyword argument, allowing the

  263. policy to be overridden for that method.  For example, the following code uses

  264. the <a class="reference internal" href="email.compat32-message.html#email.message.Message.as_bytes" title="email.message.Message.as_bytes"><code class="xref py py-meth docutils literal notranslate"><span class="pre">as_bytes()</span></code></a> method of the <em>msg</em> object from

  265. the previous example and writes the message to a file using the native line

  266. separators for the platform on which it is running:</p>

  267. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">os</span>

  268. <span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">&#39;converted.txt&#39;</span><span class="p">,</span> <span class="s1">&#39;wb&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>

  269. <span class="gp">... </span>    <span class="n">f</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">msg</span><span class="o">.</span><span class="n">as_bytes</span><span class="p">(</span><span class="n">policy</span><span class="o">=</span><span class="n">msg</span><span class="o">.</span><span class="n">policy</span><span class="o">.</span><span class="n">clone</span><span class="p">(</span><span class="n">linesep</span><span class="o">=</span><span class="n">os</span><span class="o">.</span><span class="n">linesep</span><span class="p">)))</span>

  270. <span class="go">17</span>

  271. </pre></div>

  272. </div>

  273. <p>Policy objects can also be combined using the addition operator, producing a

  274. policy object whose settings are a combination of the non-default values of the

  275. summed objects:</p>

  276. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">compat_SMTP</span> <span class="o">=</span> <span class="n">policy</span><span class="o">.</span><span class="n">compat32</span><span class="o">.</span><span class="n">clone</span><span class="p">(</span><span class="n">linesep</span><span class="o">=</span><span class="s1">&#39;</span><span class="se">\r\n</span><span class="s1">&#39;</span><span class="p">)</span>

  277. <span class="gp">&gt;&gt;&gt; </span><span class="n">compat_strict</span> <span class="o">=</span> <span class="n">policy</span><span class="o">.</span><span class="n">compat32</span><span class="o">.</span><span class="n">clone</span><span class="p">(</span><span class="n">raise_on_defect</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>

  278. <span class="gp">&gt;&gt;&gt; </span><span class="n">compat_strict_SMTP</span> <span class="o">=</span> <span class="n">compat_SMTP</span> <span class="o">+</span> <span class="n">compat_strict</span>

  279. </pre></div>

  280. </div>

  281. <p>This operation is not commutative; that is, the order in which the objects are

  282. added matters.  To illustrate:</p>

  283. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">policy100</span> <span class="o">=</span> <span class="n">policy</span><span class="o">.</span><span class="n">compat32</span><span class="o">.</span><span class="n">clone</span><span class="p">(</span><span class="n">max_line_length</span><span class="o">=</span><span class="mi">100</span><span class="p">)</span>

  284. <span class="gp">&gt;&gt;&gt; </span><span class="n">policy80</span> <span class="o">=</span> <span class="n">policy</span><span class="o">.</span><span class="n">compat32</span><span class="o">.</span><span class="n">clone</span><span class="p">(</span><span class="n">max_line_length</span><span class="o">=</span><span class="mi">80</span><span class="p">)</span>

  285. <span class="gp">&gt;&gt;&gt; </span><span class="n">apolicy</span> <span class="o">=</span> <span class="n">policy100</span> <span class="o">+</span> <span class="n">policy80</span>

  286. <span class="gp">&gt;&gt;&gt; </span><span class="n">apolicy</span><span class="o">.</span><span class="n">max_line_length</span>

  287. <span class="go">80</span>

  288. <span class="gp">&gt;&gt;&gt; </span><span class="n">apolicy</span> <span class="o">=</span> <span class="n">policy80</span> <span class="o">+</span> <span class="n">policy100</span>

  289. <span class="gp">&gt;&gt;&gt; </span><span class="n">apolicy</span><span class="o">.</span><span class="n">max_line_length</span>

  290. <span class="go">100</span>

  291. </pre></div>

  292. </div>

  293. <dl class="py class">

  294. <dt class="sig sig-object py" id="email.policy.Policy">

  295. <em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">email.policy.</span></span><span class="sig-name descname"><span class="pre">Policy</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kw</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.policy.Policy" title="Link to this definition">¶</a></dt>

  296. <dd><p>This is the <a class="reference internal" href="../glossary.html#term-abstract-base-class"><span class="xref std std-term">abstract base class</span></a> for all policy classes.  It provides

  297. default implementations for a couple of trivial methods, as well as the

  298. implementation of the immutability property, the <a class="reference internal" href="#email.policy.Policy.clone" title="email.policy.Policy.clone"><code class="xref py py-meth docutils literal notranslate"><span class="pre">clone()</span></code></a> method, and

  299. the constructor semantics.</p>

  300. <p>The constructor of a policy class can be passed various keyword arguments.

  301. The arguments that may be specified are any non-method properties on this

  302. class, plus any additional non-method properties on the concrete class.  A

  303. value specified in the constructor will override the default value for the

  304. corresponding attribute.</p>

  305. <p>This class defines the following properties, and thus values for the

  306. following may be passed in the constructor of any policy class:</p>

  307. <dl class="py attribute">

  308. <dt class="sig sig-object py" id="email.policy.Policy.max_line_length">

  309. <span class="sig-name descname"><span class="pre">max_line_length</span></span><a class="headerlink" href="#email.policy.Policy.max_line_length" title="Link to this definition">¶</a></dt>

  310. <dd><p>The maximum length of any line in the serialized output, not counting the

  311. end of line character(s).  Default is 78, per <span class="target" id="index-0"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc5322.html"><strong>RFC 5322</strong></a>.  A value of

  312. <code class="docutils literal notranslate"><span class="pre">0</span></code> or <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> indicates that no line wrapping should be

  313. done at all.</p>

  314. </dd></dl>

  315. 

  316. <dl class="py attribute">

  317. <dt class="sig sig-object py" id="email.policy.Policy.linesep">

  318. <span class="sig-name descname"><span class="pre">linesep</span></span><a class="headerlink" href="#email.policy.Policy.linesep" title="Link to this definition">¶</a></dt>

  319. <dd><p>The string to be used to terminate lines in serialized output.  The

  320. default is <code class="docutils literal notranslate"><span class="pre">\n</span></code> because that’s the internal end-of-line discipline used

  321. by Python, though <code class="docutils literal notranslate"><span class="pre">\r\n</span></code> is required by the RFCs.</p>

  322. </dd></dl>

  323. 

  324. <dl class="py attribute">

  325. <dt class="sig sig-object py" id="email.policy.Policy.cte_type">

  326. <span class="sig-name descname"><span class="pre">cte_type</span></span><a class="headerlink" href="#email.policy.Policy.cte_type" title="Link to this definition">¶</a></dt>

  327. <dd><p>Controls the type of Content Transfer Encodings that may be or are

  328. required to be used.  The possible values are:</p>

  329. <table class="docutils align-default">

  330. <tbody>

  331. <tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">7bit</span></code></p></td>

  332. <td><p>all data must be “7 bit clean” (ASCII-only).  This means that

  333. where necessary data will be encoded using either

  334. quoted-printable or base64 encoding.</p></td>

  335. </tr>

  336. <tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">8bit</span></code></p></td>

  337. <td><p>data is not constrained to be 7 bit clean.  Data in headers is

  338. still required to be ASCII-only and so will be encoded (see

  339. <a class="reference internal" href="#email.policy.Policy.fold_binary" title="email.policy.Policy.fold_binary"><code class="xref py py-meth docutils literal notranslate"><span class="pre">fold_binary()</span></code></a> and <a class="reference internal" href="#email.policy.EmailPolicy.utf8" title="email.policy.EmailPolicy.utf8"><code class="xref py py-attr docutils literal notranslate"><span class="pre">utf8</span></code></a> below for

  340. exceptions), but body parts may use the <code class="docutils literal notranslate"><span class="pre">8bit</span></code> CTE.</p></td>

  341. </tr>

  342. </tbody>

  343. </table>

  344. <p>A <code class="docutils literal notranslate"><span class="pre">cte_type</span></code> value of <code class="docutils literal notranslate"><span class="pre">8bit</span></code> only works with <code class="docutils literal notranslate"><span class="pre">BytesGenerator</span></code>, not

  345. <code class="docutils literal notranslate"><span class="pre">Generator</span></code>, because strings cannot contain binary data.  If a

  346. <code class="docutils literal notranslate"><span class="pre">Generator</span></code> is operating under a policy that specifies

  347. <code class="docutils literal notranslate"><span class="pre">cte_type=8bit</span></code>, it will act as if <code class="docutils literal notranslate"><span class="pre">cte_type</span></code> is <code class="docutils literal notranslate"><span class="pre">7bit</span></code>.</p>

  348. </dd></dl>

  349. 

  350. <dl class="py attribute">

  351. <dt class="sig sig-object py" id="email.policy.Policy.raise_on_defect">

  352. <span class="sig-name descname"><span class="pre">raise_on_defect</span></span><a class="headerlink" href="#email.policy.Policy.raise_on_defect" title="Link to this definition">¶</a></dt>

  353. <dd><p>If <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>, any defects encountered will be raised as errors.  If

  354. <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a> (the default), defects will be passed to the

  355. <a class="reference internal" href="#email.policy.Policy.register_defect" title="email.policy.Policy.register_defect"><code class="xref py py-meth docutils literal notranslate"><span class="pre">register_defect()</span></code></a> method.</p>

  356. </dd></dl>

  357. 

  358. <dl class="py attribute">

  359. <dt class="sig sig-object py" id="email.policy.Policy.mangle_from_">

  360. <span class="sig-name descname"><span class="pre">mangle_from_</span></span><a class="headerlink" href="#email.policy.Policy.mangle_from_" title="Link to this definition">¶</a></dt>

  361. <dd><p>If <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>, lines starting with <em>“From “</em> in the body are

  362. escaped by putting a <code class="docutils literal notranslate"><span class="pre">&gt;</span></code> in front of them. This parameter is used when

  363. the message is being serialized by a generator.

  364. Default: <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a>.</p>

  365. <div class="versionadded">

  366. <p><span class="versionmodified added">New in version 3.5.</span></p>

  367. </div>

  368. </dd></dl>

  369. 

  370. <dl class="py attribute">

  371. <dt class="sig sig-object py" id="email.policy.Policy.message_factory">

  372. <span class="sig-name descname"><span class="pre">message_factory</span></span><a class="headerlink" href="#email.policy.Policy.message_factory" title="Link to this definition">¶</a></dt>

  373. <dd><p>A factory function for constructing a new empty message object.  Used

  374. by the parser when building messages.  Defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code>, in

  375. which case <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> is used.</p>

  376. <div class="versionadded">

  377. <p><span class="versionmodified added">New in version 3.6.</span></p>

  378. </div>

  379. </dd></dl>

  380. 

  381. <p>The following <a class="reference internal" href="#email.policy.Policy" title="email.policy.Policy"><code class="xref py py-class docutils literal notranslate"><span class="pre">Policy</span></code></a> method is intended to be called by code using

  382. the email library to create policy instances with custom settings:</p>

  383. <dl class="py method">

  384. <dt class="sig sig-object py" id="email.policy.Policy.clone">

  385. <span class="sig-name descname"><span class="pre">clone</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kw</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.policy.Policy.clone" title="Link to this definition">¶</a></dt>

  386. <dd><p>Return a new <a class="reference internal" href="#email.policy.Policy" title="email.policy.Policy"><code class="xref py py-class docutils literal notranslate"><span class="pre">Policy</span></code></a> instance whose attributes have the same

  387. values as the current instance, except where those attributes are

  388. given new values by the keyword arguments.</p>

  389. </dd></dl>

  390. 

  391. <p>The remaining <a class="reference internal" href="#email.policy.Policy" title="email.policy.Policy"><code class="xref py py-class docutils literal notranslate"><span class="pre">Policy</span></code></a> methods are called by the email package code,

  392. and are not intended to be called by an application using the email package.

  393. A custom policy must implement all of these methods.</p>

  394. <dl class="py method">

  395. <dt class="sig sig-object py" id="email.policy.Policy.handle_defect">

  396. <span class="sig-name descname"><span class="pre">handle_defect</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">obj</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">defect</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.policy.Policy.handle_defect" title="Link to this definition">¶</a></dt>

  397. <dd><p>Handle a <em>defect</em> found on <em>obj</em>.  When the email package calls this

  398. method, <em>defect</em> will always be a subclass of

  399. <code class="xref py py-class docutils literal notranslate"><span class="pre">Defect</span></code>.</p>

  400. <p>The default implementation checks the <a class="reference internal" href="#email.policy.Policy.raise_on_defect" title="email.policy.Policy.raise_on_defect"><code class="xref py py-attr docutils literal notranslate"><span class="pre">raise_on_defect</span></code></a> flag.  If

  401. it is <code class="docutils literal notranslate"><span class="pre">True</span></code>, <em>defect</em> is raised as an exception.  If it is <code class="docutils literal notranslate"><span class="pre">False</span></code>

  402. (the default), <em>obj</em> and <em>defect</em> are passed to <a class="reference internal" href="#email.policy.Policy.register_defect" title="email.policy.Policy.register_defect"><code class="xref py py-meth docutils literal notranslate"><span class="pre">register_defect()</span></code></a>.</p>

  403. </dd></dl>

  404. 

  405. <dl class="py method">

  406. <dt class="sig sig-object py" id="email.policy.Policy.register_defect">

  407. <span class="sig-name descname"><span class="pre">register_defect</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">obj</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">defect</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.policy.Policy.register_defect" title="Link to this definition">¶</a></dt>

  408. <dd><p>Register a <em>defect</em> on <em>obj</em>.  In the email package, <em>defect</em> will always

  409. be a subclass of <code class="xref py py-class docutils literal notranslate"><span class="pre">Defect</span></code>.</p>

  410. <p>The default implementation calls the <code class="docutils literal notranslate"><span class="pre">append</span></code> method of the <code class="docutils literal notranslate"><span class="pre">defects</span></code>

  411. attribute of <em>obj</em>.  When the email package calls <a class="reference internal" href="#email.policy.Policy.handle_defect" title="email.policy.Policy.handle_defect"><code class="xref py py-attr docutils literal notranslate"><span class="pre">handle_defect</span></code></a>,

  412. <em>obj</em> will normally have a <code class="docutils literal notranslate"><span class="pre">defects</span></code> attribute that has an <code class="docutils literal notranslate"><span class="pre">append</span></code>

  413. method.  Custom object types used with the email package (for example,

  414. custom <code class="docutils literal notranslate"><span class="pre">Message</span></code> objects) should also provide such an attribute,

  415. otherwise defects in parsed messages will raise unexpected errors.</p>

  416. </dd></dl>

  417. 

  418. <dl class="py method">

  419. <dt class="sig sig-object py" id="email.policy.Policy.header_max_count">

  420. <span class="sig-name descname"><span class="pre">header_max_count</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.policy.Policy.header_max_count" title="Link to this definition">¶</a></dt>

  421. <dd><p>Return the maximum allowed number of headers named <em>name</em>.</p>

  422. <p>Called when a header is added to an <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>

  423. or <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> object.  If the returned value is not

  424. <code class="docutils literal notranslate"><span class="pre">0</span></code> or <code class="docutils literal notranslate"><span class="pre">None</span></code>, and there are already a number of headers with the

  425. name <em>name</em> greater than or equal to the value returned, a

  426. <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> is raised.</p>

  427. <p>Because the default behavior of <code class="docutils literal notranslate"><span class="pre">Message.__setitem__</span></code> is to append the

  428. value to the list of headers, it is easy to create duplicate headers

  429. without realizing it.  This method allows certain headers to be limited

  430. in the number of instances of that header that may be added to a

  431. <code class="docutils literal notranslate"><span class="pre">Message</span></code> programmatically.  (The limit is not observed by the parser,

  432. which will faithfully produce as many headers as exist in the message

  433. being parsed.)</p>

  434. <p>The default implementation returns <code class="docutils literal notranslate"><span class="pre">None</span></code> for all header names.</p>

  435. </dd></dl>

  436. 

  437. <dl class="py method">

  438. <dt class="sig sig-object py" id="email.policy.Policy.header_source_parse">

  439. <span class="sig-name descname"><span class="pre">header_source_parse</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">sourcelines</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.policy.Policy.header_source_parse" title="Link to this definition">¶</a></dt>

  440. <dd><p>The email package calls this method with a list of strings, each string

  441. ending with the line separation characters found in the source being

  442. parsed.  The first line includes the field header name and separator.

  443. All whitespace in the source is preserved.  The method should return the

  444. <code class="docutils literal notranslate"><span class="pre">(name,</span> <span class="pre">value)</span></code> tuple that is to be stored in the <code class="docutils literal notranslate"><span class="pre">Message</span></code> to

  445. represent the parsed header.</p>

  446. <p>If an implementation wishes to retain compatibility with the existing

  447. email package policies, <em>name</em> should be the case preserved name (all

  448. characters up to the ‘<code class="docutils literal notranslate"><span class="pre">:</span></code>’ separator), while <em>value</em> should be the

  449. unfolded value (all line separator characters removed, but whitespace

  450. kept intact), stripped of leading whitespace.</p>

  451. <p><em>sourcelines</em> may contain surrogateescaped binary data.</p>

  452. <p>There is no default implementation</p>

  453. </dd></dl>

  454. 

  455. <dl class="py method">

  456. <dt class="sig sig-object py" id="email.policy.Policy.header_store_parse">

  457. <span class="sig-name descname"><span class="pre">header_store_parse</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">value</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.policy.Policy.header_store_parse" title="Link to this definition">¶</a></dt>

  458. <dd><p>The email package calls this method with the name and value provided by

  459. the application program when the application program is modifying a

  460. <code class="docutils literal notranslate"><span class="pre">Message</span></code> programmatically (as opposed to a <code class="docutils literal notranslate"><span class="pre">Message</span></code> created by a

  461. parser).  The method should return the <code class="docutils literal notranslate"><span class="pre">(name,</span> <span class="pre">value)</span></code> tuple that is to

  462. be stored in the <code class="docutils literal notranslate"><span class="pre">Message</span></code> to represent the header.</p>

  463. <p>If an implementation wishes to retain compatibility with the existing

  464. email package policies, the <em>name</em> and <em>value</em> should be strings or

  465. string subclasses that do not change the content of the passed in

  466. arguments.</p>

  467. <p>There is no default implementation</p>

  468. </dd></dl>

  469. 

  470. <dl class="py method">

  471. <dt class="sig sig-object py" id="email.policy.Policy.header_fetch_parse">

  472. <span class="sig-name descname"><span class="pre">header_fetch_parse</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">value</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.policy.Policy.header_fetch_parse" title="Link to this definition">¶</a></dt>

  473. <dd><p>The email package calls this method with the <em>name</em> and <em>value</em> currently

  474. stored in the <code class="docutils literal notranslate"><span class="pre">Message</span></code> when that header is requested by the

  475. application program, and whatever the method returns is what is passed

  476. back to the application as the value of the header being retrieved.

  477. Note that there may be more than one header with the same name stored in

  478. the <code class="docutils literal notranslate"><span class="pre">Message</span></code>; the method is passed the specific name and value of the

  479. header destined to be returned to the application.</p>

  480. <p><em>value</em> may contain surrogateescaped binary data.  There should be no

  481. surrogateescaped binary data in the value returned by the method.</p>

  482. <p>There is no default implementation</p>

  483. </dd></dl>

  484. 

  485. <dl class="py method">

  486. <dt class="sig sig-object py" id="email.policy.Policy.fold">

  487. <span class="sig-name descname"><span class="pre">fold</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">value</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.policy.Policy.fold" title="Link to this definition">¶</a></dt>

  488. <dd><p>The email package calls this method with the <em>name</em> and <em>value</em> currently

  489. stored in the <code class="docutils literal notranslate"><span class="pre">Message</span></code> for a given header.  The method should return a

  490. string that represents that header “folded” correctly (according to the

  491. policy settings) by composing the <em>name</em> with the <em>value</em> and inserting

  492. <a class="reference internal" href="#email.policy.Policy.linesep" title="email.policy.Policy.linesep"><code class="xref py py-attr docutils literal notranslate"><span class="pre">linesep</span></code></a> characters at the appropriate places.  See <span class="target" id="index-1"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc5322.html"><strong>RFC 5322</strong></a>

  493. for a discussion of the rules for folding email headers.</p>

  494. <p><em>value</em> may contain surrogateescaped binary data.  There should be no

  495. surrogateescaped binary data in the string returned by the method.</p>

  496. </dd></dl>

  497. 

  498. <dl class="py method">

  499. <dt class="sig sig-object py" id="email.policy.Policy.fold_binary">

  500. <span class="sig-name descname"><span class="pre">fold_binary</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">value</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.policy.Policy.fold_binary" title="Link to this definition">¶</a></dt>

  501. <dd><p>The same as <a class="reference internal" href="#email.policy.Policy.fold" title="email.policy.Policy.fold"><code class="xref py py-meth docutils literal notranslate"><span class="pre">fold()</span></code></a>, except that the returned value should be a

  502. bytes object rather than a string.</p>

  503. <p><em>value</em> may contain surrogateescaped binary data.  These could be

  504. converted back into binary data in the returned bytes object.</p>

  505. </dd></dl>

  506. 

  507. </dd></dl>

  508. 

  509. <dl class="py class">

  510. <dt class="sig sig-object py" id="email.policy.EmailPolicy">

  511. <em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">email.policy.</span></span><span class="sig-name descname"><span class="pre">EmailPolicy</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kw</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.policy.EmailPolicy" title="Link to this definition">¶</a></dt>

  512. <dd><p>This concrete <a class="reference internal" href="#email.policy.Policy" title="email.policy.Policy"><code class="xref py py-class docutils literal notranslate"><span class="pre">Policy</span></code></a> provides behavior that is intended to be fully

  513. compliant with the current email RFCs.  These include (but are not limited

  514. to) <span class="target" id="index-2"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc5322.html"><strong>RFC 5322</strong></a>, <span class="target" id="index-3"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2047.html"><strong>RFC 2047</strong></a>, and the current MIME RFCs.</p>

  515. <p>This policy adds new header parsing and folding algorithms.  Instead of

  516. simple strings, headers are <code class="docutils literal notranslate"><span class="pre">str</span></code> subclasses with attributes that depend

  517. on the type of the field.  The parsing and folding algorithm fully implement

  518. <span class="target" id="index-4"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2047.html"><strong>RFC 2047</strong></a> and <span class="target" id="index-5"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc5322.html"><strong>RFC 5322</strong></a>.</p>

  519. <p>The default value for the <a class="reference internal" href="#email.policy.Policy.message_factory" title="email.policy.Policy.message_factory"><code class="xref py py-attr docutils literal notranslate"><span class="pre">message_factory</span></code></a>

  520. attribute is <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>

  521. <p>In addition to the settable attributes listed above that apply to all

  522. policies, this policy adds the following additional attributes:</p>

  523. <div class="versionadded">

  524. <p><span class="versionmodified added">New in version 3.6: </span><a class="footnote-reference brackets" href="#id2" id="id1" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a></p>

  525. </div>

  526. <dl class="py attribute">

  527. <dt class="sig sig-object py" id="email.policy.EmailPolicy.utf8">

  528. <span class="sig-name descname"><span class="pre">utf8</span></span><a class="headerlink" href="#email.policy.EmailPolicy.utf8" title="Link to this definition">¶</a></dt>

  529. <dd><p>If <code class="docutils literal notranslate"><span class="pre">False</span></code>, follow <span class="target" id="index-6"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc5322.html"><strong>RFC 5322</strong></a>, supporting non-ASCII characters in

  530. headers by encoding them as “encoded words”.  If <code class="docutils literal notranslate"><span class="pre">True</span></code>, follow

  531. <span class="target" id="index-7"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc6532.html"><strong>RFC 6532</strong></a> and use <code class="docutils literal notranslate"><span class="pre">utf-8</span></code> encoding for headers.  Messages

  532. formatted in this way may be passed to SMTP servers that support

  533. the <code class="docutils literal notranslate"><span class="pre">SMTPUTF8</span></code> extension (<span class="target" id="index-8"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc6531.html"><strong>RFC 6531</strong></a>).</p>

  534. </dd></dl>

  535. 

  536. <dl class="py attribute">

  537. <dt class="sig sig-object py" id="email.policy.EmailPolicy.refold_source">

  538. <span class="sig-name descname"><span class="pre">refold_source</span></span><a class="headerlink" href="#email.policy.EmailPolicy.refold_source" title="Link to this definition">¶</a></dt>

  539. <dd><p>If the value for a header in the <code class="docutils literal notranslate"><span class="pre">Message</span></code> object originated from a

  540. <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">parser</span></code></a> (as opposed to being set by a program), this

  541. attribute indicates whether or not a generator should refold that value

  542. when transforming the message back into serialized form.  The possible

  543. values are:</p>

  544. <table class="docutils align-default">

  545. <tbody>

  546. <tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">none</span></code></p></td>

  547. <td><p>all source values use original folding</p></td>

  548. </tr>

  549. <tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">long</span></code></p></td>

  550. <td><p>source values that have any line that is longer than

  551. <code class="docutils literal notranslate"><span class="pre">max_line_length</span></code> will be refolded</p></td>

  552. </tr>

  553. <tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">all</span></code></p></td>

  554. <td><p>all values are refolded.</p></td>

  555. </tr>

  556. </tbody>

  557. </table>

  558. <p>The default is <code class="docutils literal notranslate"><span class="pre">long</span></code>.</p>

  559. </dd></dl>

  560. 

  561. <dl class="py attribute">

  562. <dt class="sig sig-object py" id="email.policy.EmailPolicy.header_factory">

  563. <span class="sig-name descname"><span class="pre">header_factory</span></span><a class="headerlink" href="#email.policy.EmailPolicy.header_factory" title="Link to this definition">¶</a></dt>

  564. <dd><p>A callable that takes two arguments, <code class="docutils literal notranslate"><span class="pre">name</span></code> and <code class="docutils literal notranslate"><span class="pre">value</span></code>, where

  565. <code class="docutils literal notranslate"><span class="pre">name</span></code> is a header field name and <code class="docutils literal notranslate"><span class="pre">value</span></code> is an unfolded header field

  566. value, and returns a string subclass that represents that header.  A

  567. default <code class="docutils literal notranslate"><span class="pre">header_factory</span></code> (see <a class="reference internal" href="email.headerregistry.html#module-email.headerregistry" title="email.headerregistry: Automatic Parsing of headers based on the field name"><code class="xref py py-mod docutils literal notranslate"><span class="pre">headerregistry</span></code></a>) is provided

  568. that supports custom parsing for the various address and date <span class="target" id="index-9"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc5322.html"><strong>RFC 5322</strong></a>

  569. header field types, and the major MIME header field stypes.  Support for

  570. additional custom parsing will be added in the future.</p>

  571. </dd></dl>

  572. 

  573. <dl class="py attribute">

  574. <dt class="sig sig-object py" id="email.policy.EmailPolicy.content_manager">

  575. <span class="sig-name descname"><span class="pre">content_manager</span></span><a class="headerlink" href="#email.policy.EmailPolicy.content_manager" title="Link to this definition">¶</a></dt>

  576. <dd><p>An object with at least two methods: get_content and set_content.  When

  577. the <a class="reference internal" href="email.message.html#email.message.EmailMessage.get_content" title="email.message.EmailMessage.get_content"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_content()</span></code></a> or

  578. <a class="reference internal" href="email.message.html#email.message.EmailMessage.set_content" title="email.message.EmailMessage.set_content"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_content()</span></code></a> method of an

  579. <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> object is called, it calls the

  580. corresponding method of this object, passing it the message object as its

  581. first argument, and any arguments or keywords that were passed to it as

  582. additional arguments.  By default <code class="docutils literal notranslate"><span class="pre">content_manager</span></code> is set to

  583. <a class="reference internal" href="email.contentmanager.html#email.contentmanager.raw_data_manager" title="email.contentmanager.raw_data_manager"><code class="xref py py-data docutils literal notranslate"><span class="pre">raw_data_manager</span></code></a>.</p>

  584. <div class="versionadded">

  585. <p><span class="versionmodified added">New in version 3.4.</span></p>

  586. </div>

  587. </dd></dl>

  588. 

  589. <p>The class provides the following concrete implementations of the abstract

  590. methods of <a class="reference internal" href="#email.policy.Policy" title="email.policy.Policy"><code class="xref py py-class docutils literal notranslate"><span class="pre">Policy</span></code></a>:</p>

  591. <dl class="py method">

  592. <dt class="sig sig-object py" id="email.policy.EmailPolicy.header_max_count">

  593. <span class="sig-name descname"><span class="pre">header_max_count</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.policy.EmailPolicy.header_max_count" title="Link to this definition">¶</a></dt>

  594. <dd><p>Returns the value of the

  595. <a class="reference internal" href="email.headerregistry.html#email.headerregistry.BaseHeader.max_count" title="email.headerregistry.BaseHeader.max_count"><code class="xref py py-attr docutils literal notranslate"><span class="pre">max_count</span></code></a> attribute of the

  596. specialized class used to represent the header with the given name.</p>

  597. </dd></dl>

  598. 

  599. <dl class="py method">

  600. <dt class="sig sig-object py" id="email.policy.EmailPolicy.header_source_parse">

  601. <span class="sig-name descname"><span class="pre">header_source_parse</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">sourcelines</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.policy.EmailPolicy.header_source_parse" title="Link to this definition">¶</a></dt>

  602. <dd><p>The name is parsed as everything up to the ‘<code class="docutils literal notranslate"><span class="pre">:</span></code>’ and returned

  603. unmodified.  The value is determined by stripping leading whitespace off

  604. the remainder of the first line, joining all subsequent lines together,

  605. and stripping any trailing carriage return or linefeed characters.</p>

  606. </dd></dl>

  607. 

  608. <dl class="py method">

  609. <dt class="sig sig-object py" id="email.policy.EmailPolicy.header_store_parse">

  610. <span class="sig-name descname"><span class="pre">header_store_parse</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">value</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.policy.EmailPolicy.header_store_parse" title="Link to this definition">¶</a></dt>

  611. <dd><p>The name is returned unchanged.  If the input value has a <code class="docutils literal notranslate"><span class="pre">name</span></code>

  612. attribute and it matches <em>name</em> ignoring case, the value is returned

  613. unchanged.  Otherwise the <em>name</em> and <em>value</em> are passed to

  614. <code class="docutils literal notranslate"><span class="pre">header_factory</span></code>, and the resulting header object is returned as

  615. the value.  In this case a <code class="docutils literal notranslate"><span class="pre">ValueError</span></code> is raised if the input value

  616. contains CR or LF characters.</p>

  617. </dd></dl>

  618. 

  619. <dl class="py method">

  620. <dt class="sig sig-object py" id="email.policy.EmailPolicy.header_fetch_parse">

  621. <span class="sig-name descname"><span class="pre">header_fetch_parse</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">value</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.policy.EmailPolicy.header_fetch_parse" title="Link to this definition">¶</a></dt>

  622. <dd><p>If the value has a <code class="docutils literal notranslate"><span class="pre">name</span></code> attribute, it is returned to unmodified.

  623. Otherwise the <em>name</em>, and the <em>value</em> with any CR or LF characters

  624. removed, are passed to the <code class="docutils literal notranslate"><span class="pre">header_factory</span></code>, and the resulting

  625. header object is returned.  Any surrogateescaped bytes get turned into

  626. the unicode unknown-character glyph.</p>

  627. </dd></dl>

  628. 

  629. <dl class="py method">

  630. <dt class="sig sig-object py" id="email.policy.EmailPolicy.fold">

  631. <span class="sig-name descname"><span class="pre">fold</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">value</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.policy.EmailPolicy.fold" title="Link to this definition">¶</a></dt>

  632. <dd><p>Header folding is controlled by the <a class="reference internal" href="#email.policy.EmailPolicy.refold_source" title="email.policy.EmailPolicy.refold_source"><code class="xref py py-attr docutils literal notranslate"><span class="pre">refold_source</span></code></a> policy setting.

  633. A value is considered to be a ‘source value’ if and only if it does not

  634. have a <code class="docutils literal notranslate"><span class="pre">name</span></code> attribute (having a <code class="docutils literal notranslate"><span class="pre">name</span></code> attribute means it is a

  635. header object of some sort).  If a source value needs to be refolded

  636. according to the policy, it is converted into a header object by

  637. passing the <em>name</em> and the <em>value</em> with any CR and LF characters removed

  638. to the <code class="docutils literal notranslate"><span class="pre">header_factory</span></code>.  Folding of a header object is done by

  639. calling its <code class="docutils literal notranslate"><span class="pre">fold</span></code> method with the current policy.</p>

  640. <p>Source values are split into lines using <a class="reference internal" href="stdtypes.html#str.splitlines" title="str.splitlines"><code class="xref py py-meth docutils literal notranslate"><span class="pre">splitlines()</span></code></a>.  If

  641. the value is not to be refolded, the lines are rejoined using the

  642. <code class="docutils literal notranslate"><span class="pre">linesep</span></code> from the policy and returned.  The exception is lines

  643. containing non-ascii binary data.  In that case the value is refolded

  644. regardless of the <code class="docutils literal notranslate"><span class="pre">refold_source</span></code> setting, which causes the binary data

  645. to be CTE encoded using the <code class="docutils literal notranslate"><span class="pre">unknown-8bit</span></code> charset.</p>

  646. </dd></dl>

  647. 

  648. <dl class="py method">

  649. <dt class="sig sig-object py" id="email.policy.EmailPolicy.fold_binary">

  650. <span class="sig-name descname"><span class="pre">fold_binary</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">value</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.policy.EmailPolicy.fold_binary" title="Link to this definition">¶</a></dt>

  651. <dd><p>The same as <a class="reference internal" href="#email.policy.EmailPolicy.fold" title="email.policy.EmailPolicy.fold"><code class="xref py py-meth docutils literal notranslate"><span class="pre">fold()</span></code></a> if <a class="reference internal" href="#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> is <code class="docutils literal notranslate"><span class="pre">7bit</span></code>, except

  652. that the returned value is bytes.</p>

  653. <p>If <a class="reference internal" href="#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> is <code class="docutils literal notranslate"><span class="pre">8bit</span></code>, non-ASCII binary data is

  654. converted back

  655. into bytes.  Headers with binary data are not refolded, regardless of the

  656. <code class="docutils literal notranslate"><span class="pre">refold_header</span></code> setting, since there is no way to know whether the

  657. binary data consists of single byte characters or multibyte characters.</p>

  658. </dd></dl>

  659. 

  660. </dd></dl>

  661. 

  662. <p>The following instances of <a class="reference internal" href="#email.policy.EmailPolicy" title="email.policy.EmailPolicy"><code class="xref py py-class docutils literal notranslate"><span class="pre">EmailPolicy</span></code></a> provide defaults suitable for

  663. specific application domains.  Note that in the future the behavior of these

  664. instances (in particular the <code class="docutils literal notranslate"><span class="pre">HTTP</span></code> instance) may be adjusted to conform even

  665. more closely to the RFCs relevant to their domains.</p>

  666. <dl class="py data">

  667. <dt class="sig sig-object py" id="email.policy.default">

  668. <span class="sig-prename descclassname"><span class="pre">email.policy.</span></span><span class="sig-name descname"><span class="pre">default</span></span><a class="headerlink" href="#email.policy.default" title="Link to this definition">¶</a></dt>

  669. <dd><p>An instance of <code class="docutils literal notranslate"><span class="pre">EmailPolicy</span></code> with all defaults unchanged.  This policy

  670. uses the standard Python <code class="docutils literal notranslate"><span class="pre">\n</span></code> line endings rather than the RFC-correct

  671. <code class="docutils literal notranslate"><span class="pre">\r\n</span></code>.</p>

  672. </dd></dl>

  673. 

  674. <dl class="py data">

  675. <dt class="sig sig-object py" id="email.policy.SMTP">

  676. <span class="sig-prename descclassname"><span class="pre">email.policy.</span></span><span class="sig-name descname"><span class="pre">SMTP</span></span><a class="headerlink" href="#email.policy.SMTP" title="Link to this definition">¶</a></dt>

  677. <dd><p>Suitable for serializing messages in conformance with the email RFCs.

  678. Like <code class="docutils literal notranslate"><span class="pre">default</span></code>, but with <code class="docutils literal notranslate"><span class="pre">linesep</span></code> set to <code class="docutils literal notranslate"><span class="pre">\r\n</span></code>, which is RFC

  679. compliant.</p>

  680. </dd></dl>

  681. 

  682. <dl class="py data">

  683. <dt class="sig sig-object py" id="email.policy.SMTPUTF8">

  684. <span class="sig-prename descclassname"><span class="pre">email.policy.</span></span><span class="sig-name descname"><span class="pre">SMTPUTF8</span></span><a class="headerlink" href="#email.policy.SMTPUTF8" title="Link to this definition">¶</a></dt>

  685. <dd><p>The same as <code class="docutils literal notranslate"><span class="pre">SMTP</span></code> except that <a class="reference internal" href="#email.policy.EmailPolicy.utf8" title="email.policy.EmailPolicy.utf8"><code class="xref py py-attr docutils literal notranslate"><span class="pre">utf8</span></code></a> is <code class="docutils literal notranslate"><span class="pre">True</span></code>.

  686. Useful for serializing messages to a message store without using encoded

  687. words in the headers.  Should only be used for SMTP transmission if the

  688. sender or recipient addresses have non-ASCII characters (the

  689. <a class="reference internal" href="smtplib.html#smtplib.SMTP.send_message" title="smtplib.SMTP.send_message"><code class="xref py py-meth docutils literal notranslate"><span class="pre">smtplib.SMTP.send_message()</span></code></a> method handles this automatically).</p>

  690. </dd></dl>

  691. 

  692. <dl class="py data">

  693. <dt class="sig sig-object py" id="email.policy.HTTP">

  694. <span class="sig-prename descclassname"><span class="pre">email.policy.</span></span><span class="sig-name descname"><span class="pre">HTTP</span></span><a class="headerlink" href="#email.policy.HTTP" title="Link to this definition">¶</a></dt>

  695. <dd><p>Suitable for serializing headers with for use in HTTP traffic.  Like

  696. <code class="docutils literal notranslate"><span class="pre">SMTP</span></code> except that <code class="docutils literal notranslate"><span class="pre">max_line_length</span></code> is set to <code class="docutils literal notranslate"><span class="pre">None</span></code> (unlimited).</p>

  697. </dd></dl>

  698. 

  699. <dl class="py data">

  700. <dt class="sig sig-object py" id="email.policy.strict">

  701. <span class="sig-prename descclassname"><span class="pre">email.policy.</span></span><span class="sig-name descname"><span class="pre">strict</span></span><a class="headerlink" href="#email.policy.strict" title="Link to this definition">¶</a></dt>

  702. <dd><p>Convenience instance.  The same as <code class="docutils literal notranslate"><span class="pre">default</span></code> except that

  703. <code class="docutils literal notranslate"><span class="pre">raise_on_defect</span></code> is set to <code class="docutils literal notranslate"><span class="pre">True</span></code>.  This allows any policy to be made

  704. strict by writing:</p>

  705. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">somepolicy</span> <span class="o">+</span> <span class="n">policy</span><span class="o">.</span><span class="n">strict</span>

  706. </pre></div>

  707. </div>

  708. </dd></dl>

  709. 

  710. <p>With all of these <a class="reference internal" href="#email.policy.EmailPolicy" title="email.policy.EmailPolicy"><code class="xref py py-class docutils literal notranslate"><span class="pre">EmailPolicies</span></code></a>, the effective API of

  711. the email package is changed from the Python 3.2 API in the following ways:</p>

  712. <ul class="simple">

  713. <li><p>Setting a header on a <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> results in that

  714. header being parsed and a header object created.</p></li>

  715. <li><p>Fetching a header value from a <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> results

  716. in that header being parsed and a header object created and

  717. returned.</p></li>

  718. <li><p>Any header object, or any header that is refolded due to the

  719. policy settings, is folded using an algorithm that fully implements the

  720. RFC folding algorithms, including knowing where encoded words are required

  721. and allowed.</p></li>

  722. </ul>

  723. <p>From the application view, this means that any header obtained through the

  724. <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> is a header object with extra

  725. attributes, whose string value is the fully decoded unicode value of the

  726. header.  Likewise, a header may be assigned a new value, or a new header

  727. created, using a unicode string, and the policy will take care of converting

  728. the unicode string into the correct RFC encoded form.</p>

  729. <p>The header objects and their attributes are described in

  730. <a class="reference internal" href="email.headerregistry.html#module-email.headerregistry" title="email.headerregistry: Automatic Parsing of headers based on the field name"><code class="xref py py-mod docutils literal notranslate"><span class="pre">headerregistry</span></code></a>.</p>

  731. <dl class="py class">

  732. <dt class="sig sig-object py" id="email.policy.Compat32">

  733. <em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">email.policy.</span></span><span class="sig-name descname"><span class="pre">Compat32</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kw</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.policy.Compat32" title="Link to this definition">¶</a></dt>

  734. <dd><p>This concrete <a class="reference internal" href="#email.policy.Policy" title="email.policy.Policy"><code class="xref py py-class docutils literal notranslate"><span class="pre">Policy</span></code></a> is the backward compatibility policy.  It

  735. replicates the behavior of the email package in Python 3.2.  The

  736. <a class="reference internal" href="#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> module also defines an instance of this class,

  737. <a class="reference internal" href="#email.policy.compat32" title="email.policy.compat32"><code class="xref py py-const docutils literal notranslate"><span class="pre">compat32</span></code></a>, that is used as the default policy.  Thus the default

  738. behavior of the email package is to maintain compatibility with Python 3.2.</p>

  739. <p>The following attributes have values that are different from the

  740. <a class="reference internal" href="#email.policy.Policy" title="email.policy.Policy"><code class="xref py py-class docutils literal notranslate"><span class="pre">Policy</span></code></a> default:</p>

  741. <dl class="py attribute">

  742. <dt class="sig sig-object py" id="email.policy.Compat32.mangle_from_">

  743. <span class="sig-name descname"><span class="pre">mangle_from_</span></span><a class="headerlink" href="#email.policy.Compat32.mangle_from_" title="Link to this definition">¶</a></dt>

  744. <dd><p>The default is <code class="docutils literal notranslate"><span class="pre">True</span></code>.</p>

  745. </dd></dl>

  746. 

  747. <p>The class provides the following concrete implementations of the

  748. abstract methods of <a class="reference internal" href="#email.policy.Policy" title="email.policy.Policy"><code class="xref py py-class docutils literal notranslate"><span class="pre">Policy</span></code></a>:</p>

  749. <dl class="py method">

  750. <dt class="sig sig-object py" id="email.policy.Compat32.header_source_parse">

  751. <span class="sig-name descname"><span class="pre">header_source_parse</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">sourcelines</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.policy.Compat32.header_source_parse" title="Link to this definition">¶</a></dt>

  752. <dd><p>The name is parsed as everything up to the ‘<code class="docutils literal notranslate"><span class="pre">:</span></code>’ and returned

  753. unmodified.  The value is determined by stripping leading whitespace off

  754. the remainder of the first line, joining all subsequent lines together,

  755. and stripping any trailing carriage return or linefeed characters.</p>

  756. </dd></dl>

  757. 

  758. <dl class="py method">

  759. <dt class="sig sig-object py" id="email.policy.Compat32.header_store_parse">

  760. <span class="sig-name descname"><span class="pre">header_store_parse</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">value</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.policy.Compat32.header_store_parse" title="Link to this definition">¶</a></dt>

  761. <dd><p>The name and value are returned unmodified.</p>

  762. </dd></dl>

  763. 

  764. <dl class="py method">

  765. <dt class="sig sig-object py" id="email.policy.Compat32.header_fetch_parse">

  766. <span class="sig-name descname"><span class="pre">header_fetch_parse</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">value</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.policy.Compat32.header_fetch_parse" title="Link to this definition">¶</a></dt>

  767. <dd><p>If the value contains binary data, it is converted into a

  768. <a class="reference internal" href="email.header.html#email.header.Header" title="email.header.Header"><code class="xref py py-class docutils literal notranslate"><span class="pre">Header</span></code></a> object using the <code class="docutils literal notranslate"><span class="pre">unknown-8bit</span></code> charset.

  769. Otherwise it is returned unmodified.</p>

  770. </dd></dl>

  771. 

  772. <dl class="py method">

  773. <dt class="sig sig-object py" id="email.policy.Compat32.fold">

  774. <span class="sig-name descname"><span class="pre">fold</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">value</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.policy.Compat32.fold" title="Link to this definition">¶</a></dt>

  775. <dd><p>Headers are folded using the <a class="reference internal" href="email.header.html#email.header.Header" title="email.header.Header"><code class="xref py py-class docutils literal notranslate"><span class="pre">Header</span></code></a> folding

  776. algorithm, which preserves existing line breaks in the value, and wraps

  777. each resulting line to the <code class="docutils literal notranslate"><span class="pre">max_line_length</span></code>.  Non-ASCII binary data are

  778. CTE encoded using the <code class="docutils literal notranslate"><span class="pre">unknown-8bit</span></code> charset.</p>

  779. </dd></dl>

  780. 

  781. <dl class="py method">

  782. <dt class="sig sig-object py" id="email.policy.Compat32.fold_binary">

  783. <span class="sig-name descname"><span class="pre">fold_binary</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">value</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.policy.Compat32.fold_binary" title="Link to this definition">¶</a></dt>

  784. <dd><p>Headers are folded using the <a class="reference internal" href="email.header.html#email.header.Header" title="email.header.Header"><code class="xref py py-class docutils literal notranslate"><span class="pre">Header</span></code></a> folding

  785. algorithm, which preserves existing line breaks in the value, and wraps

  786. each resulting line to the <code class="docutils literal notranslate"><span class="pre">max_line_length</span></code>.  If <code class="docutils literal notranslate"><span class="pre">cte_type</span></code> is

  787. <code class="docutils literal notranslate"><span class="pre">7bit</span></code>, non-ascii binary data is CTE encoded using the <code class="docutils literal notranslate"><span class="pre">unknown-8bit</span></code>

  788. charset.  Otherwise the original source header is used, with its existing

  789. line breaks and any (RFC invalid) binary data it may contain.</p>

  790. </dd></dl>

  791. 

  792. </dd></dl>

  793. 

  794. <dl class="py data">

  795. <dt class="sig sig-object py" id="email.policy.compat32">

  796. <span class="sig-prename descclassname"><span class="pre">email.policy.</span></span><span class="sig-name descname"><span class="pre">compat32</span></span><a class="headerlink" href="#email.policy.compat32" title="Link to this definition">¶</a></dt>

  797. <dd><p>An instance of <a class="reference internal" href="#email.policy.Compat32" title="email.policy.Compat32"><code class="xref py py-class docutils literal notranslate"><span class="pre">Compat32</span></code></a>, providing  backward compatibility with the

  798. behavior of the email package in Python 3.2.</p>

  799. </dd></dl>

  800. 

  801. <p class="rubric">Footnotes</p>

  802. <aside class="footnote-list brackets">

  803. <aside class="footnote brackets" id="id2" role="doc-footnote">

  804. <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id1">1</a><span class="fn-bracket">]</span></span>

  805. <p>Originally added in 3.3 as a <a class="reference internal" href="../glossary.html#term-provisional-package"><span class="xref std std-term">provisional feature</span></a>.</p>

  806. </aside>

  807. </aside>

  808. </section>

  809. 

  810. 

  811.             <div class="clearer"></div>

  812.           </div>

  813.         </div>

  814.       </div>

  815.       <div class="sphinxsidebar" role="navigation" aria-label="main navigation">

  816.         <div class="sphinxsidebarwrapper">

  817.   <div>

  818.     <h4>Previous topic</h4>

  819.     <p class="topless"><a href="email.generator.html"

  820.                           title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.generator</span></code>: Generating MIME documents</a></p>

  821.   </div>

  822.   <div>

  823.     <h4>Next topic</h4>

  824.     <p class="topless"><a href="email.errors.html"

  825.                           title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.errors</span></code>: Exception and Defect classes</a></p>

  826.   </div>

  827.   <div role="note" aria-label="source link">

  828.     <h3>This Page</h3>

  829.     <ul class="this-page-menu">

  830.       <li><a href="../bugs.html">Report a Bug</a></li>

  831.       <li>

  832.         <a href="https://github.com/python/cpython/blob/main/Doc/library/email.policy.rst"

  833.             rel="nofollow">Show Source

  834.         </a>

  835.       </li>

  836.     </ul>

  837.   </div>

  838.         </div>

  839. <div id="sidebarbutton" title="Collapse sidebar">

  840. <span>«</span>

  841. </div>

  842. 

  843.       </div>

  844.       <div class="clearer"></div>

  845.     </div>  

  846.     <div class="related" role="navigation" aria-label="related navigation">

  847.       <h3>Navigation</h3>

  848.       <ul>

  849.         <li class="right" style="margin-right: 10px">

  850.           <a href="../genindex.html" title="General Index"

  851.              >index</a></li>

  852.         <li class="right" >

  853.           <a href="../py-modindex.html" title="Python Module Index"

  854.              >modules</a> |</li>

  855.         <li class="right" >

  856.           <a href="email.errors.html" title="email.errors: Exception and Defect classes"

  857.              >next</a> |</li>

  858.         <li class="right" >

  859.           <a href="email.generator.html" title="email.generator: Generating MIME documents"

  860.              >previous</a> |</li>

  861. 

  862.           <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>

  863.           <li><a href="https://www.python.org/">Python</a> &#187;</li>

  864.           <li class="switchers">

  865.             <div class="language_switcher_placeholder"></div>

  866.             <div class="version_switcher_placeholder"></div>

  867.           </li>

  868.           <li>

  869.               

  870.           </li>

  871.     <li id="cpython-language-and-version">

  872.       <a href="../index.html">3.12.3 Documentation</a> &#187;

  873.     </li>

  874. 

  875.           <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>

  876.           <li class="nav-item nav-item-2"><a href="netdata.html" >Internet Data Handling</a> &#187;</li>

  877.           <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> — An email and MIME handling package</a> &#187;</li>

  878.         <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.policy</span></code>: Policy Objects</a></li>

  879.                 <li class="right">

  880.                     

  881. 

  882.     <div class="inline-search" role="search">

  883.         <form class="inline-search" action="../search.html" method="get">

  884.           <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />

  885.           <input type="submit" value="Go" />

  886.         </form>

  887.     </div>

  888.                      |

  889.                 </li>

  890.             <li class="right">

  891. <label class="theme-selector-label">

  892.     Theme

  893.     <select class="theme-selector" oninput="activateTheme(this.value)">

  894.         <option value="auto" selected>Auto</option>

  895.         <option value="light">Light</option>

  896.         <option value="dark">Dark</option>

  897.     </select>

  898. </label> |</li>

  899.             

  900.       </ul>

  901.     </div>  

  902.     <div class="footer">

  903.     &copy; 

  904.       <a href="../copyright.html">

  905.     

  906.     Copyright

  907.     

  908.       </a>

  909.      2001-2024, Python Software Foundation.

  910.     <br />

  911.     This page is licensed under the Python Software Foundation License Version 2.

  912.     <br />

  913.     Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.

  914.     <br />

  915.     

  916.       See <a href="/license.html">History and License</a> for more information.<br />

  917.     

  918.     

  919.     <br />

  920. 

  921.     The Python Software Foundation is a non-profit corporation.

  922. <a href="https://www.python.org/psf/donations/">Please donate.</a>

  923. <br />

  924.     <br />

  925.       Last updated on Apr 09, 2024 (13:47 UTC).

  926.     

  927.       <a href="/bugs.html">Found a bug</a>?

  928.     

  929.     <br />

  930. 

  931.     Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.2.6.

  932.     </div>

  933. 

  934.   </body>

  935. </html>
上海开阖软件有限公司 沪ICP备12045867号-1