path: root/devdocs/python~3.12/library%2Femail.utils.html

 <span id="email-utils-miscellaneous-utilities"></span><h1>email.utils: Miscellaneous utilities</h1> <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/email/utils.py">Lib/email/utils.py</a></p>  <p>There are a couple of useful utilities provided in the <a class="reference internal" href="#module-email.utils" title="email.utils: Miscellaneous email package utilities."><code>email.utils</code></a> module:</p> <dl class="py function"> <dt class="sig sig-object py" id="email.utils.localtime">
<code>email.utils.localtime(dt=None)</code> </dt> <dd>
<p>Return local time as an aware datetime object. If called without arguments, return current time. Otherwise <em>dt</em> argument should be a <a class="reference internal" href="datetime#datetime.datetime" title="datetime.datetime"><code>datetime</code></a> instance, and it is converted to the local time zone according to the system time zone database. If <em>dt</em> is naive (that is, <code>dt.tzinfo</code> is <code>None</code>), it is assumed to be in local time. The <em>isdst</em> parameter is ignored.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.3.</span></p> </div> <div class="deprecated-removed"> <p><span class="versionmodified">Deprecated since version 3.12, will be removed in version 3.14: </span>The <em>isdst</em> parameter.</p> </div> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="email.utils.make_msgid">
<code>email.utils.make_msgid(idstring=None, domain=None)</code> </dt> <dd>
<p>Returns a string suitable for an <span class="target" id="index-0"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2822.html"><strong>RFC 2822</strong></a>-compliant <em class="mailheader">Message-ID</em> header. Optional <em>idstring</em> if given, is a string used to strengthen the uniqueness of the message id. Optional <em>domain</em> if given provides the portion of the msgid after the ‘@’. The default is the local hostname. It is not normally necessary to override this default, but may be useful certain cases, such as a constructing distributed system that uses a consistent domain name across multiple hosts.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.2: </span>Added the <em>domain</em> keyword.</p> </div> </dd>
</dl> <p>The remaining functions are part of the legacy (<code>Compat32</code>) email API. There is no need to directly use these with the new API, since the parsing and formatting they provide is done automatically by the header parsing machinery of the new API.</p> <dl class="py function"> <dt class="sig sig-object py" id="email.utils.quote">
<code>email.utils.quote(str)</code> </dt> <dd>
<p>Return a new string with backslashes in <em>str</em> replaced by two backslashes, and double quotes replaced by backslash-double quote.</p> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="email.utils.unquote">
<code>email.utils.unquote(str)</code> </dt> <dd>
<p>Return a new string which is an <em>unquoted</em> version of <em>str</em>. If <em>str</em> ends and begins with double quotes, they are stripped off. Likewise if <em>str</em> ends and begins with angle brackets, they are stripped off.</p> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="email.utils.parseaddr">
<code>email.utils.parseaddr(address)</code> </dt> <dd>
<p>Parse address – which should be the value of some address-containing field such as <em class="mailheader">To</em> or <em class="mailheader">Cc</em> – into its constituent <em>realname</em> and <em>email address</em> parts. Returns a tuple of that information, unless the parse fails, in which case a 2-tuple of <code>('', '')</code> is returned.</p> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="email.utils.formataddr">
<code>email.utils.formataddr(pair, charset='utf-8')</code> </dt> <dd>
<p>The inverse of <a class="reference internal" href="#email.utils.parseaddr" title="email.utils.parseaddr"><code>parseaddr()</code></a>, this takes a 2-tuple of the form <code>(realname,
email_address)</code> and returns the string value suitable for a <em class="mailheader">To</em> or <em class="mailheader">Cc</em> header. If the first element of <em>pair</em> is false, then the second element is returned unmodified.</p> <p>Optional <em>charset</em> is the character set that will be used in the <span class="target" id="index-1"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2047.html"><strong>RFC 2047</strong></a> encoding of the <code>realname</code> if the <code>realname</code> contains non-ASCII characters. Can be an instance of <a class="reference internal" href="stdtypes#str" title="str"><code>str</code></a> or a <a class="reference internal" href="email.charset#email.charset.Charset" title="email.charset.Charset"><code>Charset</code></a>. Defaults to <code>utf-8</code>.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.3: </span>Added the <em>charset</em> option.</p> </div> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="email.utils.getaddresses">
<code>email.utils.getaddresses(fieldvalues)</code> </dt> <dd>
<p>This method returns a list of 2-tuples of the form returned by <code>parseaddr()</code>. <em>fieldvalues</em> is a sequence of header field values as might be returned by <a class="reference internal" href="email.compat32-message#email.message.Message.get_all" title="email.message.Message.get_all"><code>Message.get_all</code></a>. Here’s a simple example that gets all the recipients of a message:</p> <pre data-language="python">from email.utils import getaddresses

tos = msg.get_all('to', [])
ccs = msg.get_all('cc', [])
resent_tos = msg.get_all('resent-to', [])
resent_ccs = msg.get_all('resent-cc', [])
all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs)
</pre> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="email.utils.parsedate">
<code>email.utils.parsedate(date)</code> </dt> <dd>
<p>Attempts to parse a date according to the rules in <span class="target" id="index-2"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2822.html"><strong>RFC 2822</strong></a>. however, some mailers don’t follow that format as specified, so <a class="reference internal" href="#email.utils.parsedate" title="email.utils.parsedate"><code>parsedate()</code></a> tries to guess correctly in such cases. <em>date</em> is a string containing an <span class="target" id="index-3"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2822.html"><strong>RFC 2822</strong></a> date, such as <code>"Mon, 20 Nov 1995 19:12:08 -0500"</code>. If it succeeds in parsing the date, <a class="reference internal" href="#email.utils.parsedate" title="email.utils.parsedate"><code>parsedate()</code></a> returns a 9-tuple that can be passed directly to <a class="reference internal" href="time#time.mktime" title="time.mktime"><code>time.mktime()</code></a>; otherwise <code>None</code> will be returned. Note that indexes 6, 7, and 8 of the result tuple are not usable.</p> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="email.utils.parsedate_tz">
<code>email.utils.parsedate_tz(date)</code> </dt> <dd>
<p>Performs the same function as <a class="reference internal" href="#email.utils.parsedate" title="email.utils.parsedate"><code>parsedate()</code></a>, but returns either <code>None</code> or a 10-tuple; the first 9 elements make up a tuple that can be passed directly to <a class="reference internal" href="time#time.mktime" title="time.mktime"><code>time.mktime()</code></a>, and the tenth is the offset of the date’s timezone from UTC (which is the official term for Greenwich Mean Time) <a class="footnote-reference brackets" href="#id2" id="id1">1</a>. If the input string has no timezone, the last element of the tuple returned is <code>0</code>, which represents UTC. Note that indexes 6, 7, and 8 of the result tuple are not usable.</p> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="email.utils.parsedate_to_datetime">
<code>email.utils.parsedate_to_datetime(date)</code> </dt> <dd>
<p>The inverse of <a class="reference internal" href="#email.utils.format_datetime" title="email.utils.format_datetime"><code>format_datetime()</code></a>. Performs the same function as <a class="reference internal" href="#email.utils.parsedate" title="email.utils.parsedate"><code>parsedate()</code></a>, but on success returns a <a class="reference internal" href="datetime#datetime.datetime" title="datetime.datetime"><code>datetime</code></a>; otherwise <code>ValueError</code> is raised if <em>date</em> contains an invalid value such as an hour greater than 23 or a timezone offset not between -24 and 24 hours. If the input date has a timezone of <code>-0000</code>, the <code>datetime</code> will be a naive <code>datetime</code>, and if the date is conforming to the RFCs it will represent a time in UTC but with no indication of the actual source timezone of the message the date comes from. If the input date has any other valid timezone offset, the <code>datetime</code> will be an aware <code>datetime</code> with the corresponding a <a class="reference internal" href="datetime#datetime.timezone" title="datetime.timezone"><code>timezone</code></a> <a class="reference internal" href="datetime#datetime.tzinfo" title="datetime.tzinfo"><code>tzinfo</code></a>.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.3.</span></p> </div> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="email.utils.mktime_tz">
<code>email.utils.mktime_tz(tuple)</code> </dt> <dd>
<p>Turn a 10-tuple as returned by <a class="reference internal" href="#email.utils.parsedate_tz" title="email.utils.parsedate_tz"><code>parsedate_tz()</code></a> into a UTC timestamp (seconds since the Epoch). If the timezone item in the tuple is <code>None</code>, assume local time.</p> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="email.utils.formatdate">
<code>email.utils.formatdate(timeval=None, localtime=False, usegmt=False)</code> </dt> <dd>
<p>Returns a date string as per <span class="target" id="index-4"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2822.html"><strong>RFC 2822</strong></a>, e.g.:</p> <pre data-language="python">Fri, 09 Nov 2001 01:08:47 -0000
</pre> <p>Optional <em>timeval</em> if given is a floating point time value as accepted by <a class="reference internal" href="time#time.gmtime" title="time.gmtime"><code>time.gmtime()</code></a> and <a class="reference internal" href="time#time.localtime" title="time.localtime"><code>time.localtime()</code></a>, otherwise the current time is used.</p> <p>Optional <em>localtime</em> is a flag that when <code>True</code>, interprets <em>timeval</em>, and returns a date relative to the local timezone instead of UTC, properly taking daylight savings time into account. The default is <code>False</code> meaning UTC is used.</p> <p>Optional <em>usegmt</em> is a flag that when <code>True</code>, outputs a date string with the timezone as an ascii string <code>GMT</code>, rather than a numeric <code>-0000</code>. This is needed for some protocols (such as HTTP). This only applies when <em>localtime</em> is <code>False</code>. The default is <code>False</code>.</p> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="email.utils.format_datetime">
<code>email.utils.format_datetime(dt, usegmt=False)</code> </dt> <dd>
<p>Like <code>formatdate</code>, but the input is a <a class="reference internal" href="datetime#module-datetime" title="datetime: Basic date and time types."><code>datetime</code></a> instance. If it is a naive datetime, it is assumed to be “UTC with no information about the source timezone”, and the conventional <code>-0000</code> is used for the timezone. If it is an aware <code>datetime</code>, then the numeric timezone offset is used. If it is an aware timezone with offset zero, then <em>usegmt</em> may be set to <code>True</code>, in which case the string <code>GMT</code> is used instead of the numeric timezone offset. This provides a way to generate standards conformant HTTP date headers.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.3.</span></p> </div> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="email.utils.decode_rfc2231">
<code>email.utils.decode_rfc2231(s)</code> </dt> <dd>
<p>Decode the string <em>s</em> according to <span class="target" id="index-5"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2231.html"><strong>RFC 2231</strong></a>.</p> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="email.utils.encode_rfc2231">
<code>email.utils.encode_rfc2231(s, charset=None, language=None)</code> </dt> <dd>
<p>Encode the string <em>s</em> according to <span class="target" id="index-6"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2231.html"><strong>RFC 2231</strong></a>. Optional <em>charset</em> and <em>language</em>, if given is the character set name and language name to use. If neither is given, <em>s</em> is returned as-is. If <em>charset</em> is given but <em>language</em> is not, the string is encoded using the empty string for <em>language</em>.</p> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="email.utils.collapse_rfc2231_value">
<code>email.utils.collapse_rfc2231_value(value, errors='replace', fallback_charset='us-ascii')</code> </dt> <dd>
<p>When a header parameter is encoded in <span class="target" id="index-7"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2231.html"><strong>RFC 2231</strong></a> format, <a class="reference internal" href="email.compat32-message#email.message.Message.get_param" title="email.message.Message.get_param"><code>Message.get_param</code></a> may return a 3-tuple containing the character set, language, and value. <a class="reference internal" href="#email.utils.collapse_rfc2231_value" title="email.utils.collapse_rfc2231_value"><code>collapse_rfc2231_value()</code></a> turns this into a unicode string. Optional <em>errors</em> is passed to the <em>errors</em> argument of <a class="reference internal" href="stdtypes#str" title="str"><code>str</code></a>’s <a class="reference internal" href="stdtypes#str.encode" title="str.encode"><code>encode()</code></a> method; it defaults to <code>'replace'</code>. Optional <em>fallback_charset</em> specifies the character set to use if the one in the <span class="target" id="index-8"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2231.html"><strong>RFC 2231</strong></a> header is not known by Python; it defaults to <code>'us-ascii'</code>.</p> <p>For convenience, if the <em>value</em> passed to <a class="reference internal" href="#email.utils.collapse_rfc2231_value" title="email.utils.collapse_rfc2231_value"><code>collapse_rfc2231_value()</code></a> is not a tuple, it should be a string and it is returned unquoted.</p> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="email.utils.decode_params">
<code>email.utils.decode_params(params)</code> </dt> <dd>
<p>Decode parameters list according to <span class="target" id="index-9"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2231.html"><strong>RFC 2231</strong></a>. <em>params</em> is a sequence of 2-tuples containing elements of the form <code>(content-type, string-value)</code>.</p> </dd>
</dl> <h4 class="rubric">Footnotes</h4> <dl class="footnote brackets"> <dt class="label" id="id2">
<code>1</code> </dt> <dd>
<p>Note that the sign of the timezone offset is the opposite of the sign of the <code>time.timezone</code> variable for the same timezone; the latter variable follows the POSIX standard while this module follows <span class="target" id="index-10"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2822.html"><strong>RFC 2822</strong></a>.</p> </dd> </dl> <div class="_attribution">
  <p class="_attribution-p">
    &copy; 2001&ndash;2023 Python Software Foundation<br>Licensed under the PSF License.<br>
    <a href="https://docs.python.org/3.12/library/email.utils.html" class="_attribution-link">https://docs.python.org/3.12/library/email.utils.html</a>
  </p>
</div>