Return local time as an aware datetime object. If called without
arguments, return current time. Otherwise dt argument should be a
datetime instance, and it is converted to the local time
zone according to the system time zone database. If dt is naive (that
is, dt.tzinfo is None), it is assumed to be in local time. In this
case, a positive or zero value for isdst causes localtime to presume
initially that summer time (for example, Daylight Saving Time) is or is not
(respectively) in effect for the specified time. A negative value for
isdst causes the localtime to attempt to divine whether summer time
is in effect for the specified time.

Returns a string suitable for an RFC 2822-compliant
Message-ID header. Optional idstring if given, is a string
used to strengthen the uniqueness of the message id. Optional domain 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.

Changed in version 3.2: Added the domain keyword.

The remaining functions are part of the legacy (Compat32) 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.

Parse address – which should be the value of some address-containing field such
as To or Cc – into its constituent realname and
email address parts. Returns a tuple of that information, unless the parse
fails, in which case a 2-tuple of ('','') is returned.

The inverse of parseaddr(), this takes a 2-tuple of the form (realname,email_address) and returns the string value suitable for a To or
Cc header. If the first element of pair is false, then the
second element is returned unmodified.

Optional charset is the character set that will be used in the RFC 2047
encoding of the realname if the realname contains non-ASCII
characters. Can be an instance of str or a
Charset. Defaults to utf-8.

This method returns a list of 2-tuples of the form returned by parseaddr().
fieldvalues is a sequence of header field values as might be returned by
Message.get_all. Here’s a simple
example that gets all the recipients of a message:

Attempts to parse a date according to the rules in RFC 2822. however, some
mailers don’t follow that format as specified, so parsedate() tries to
guess correctly in such cases. date is a string containing an RFC 2822
date, such as "Mon,20Nov199519:12:08-0500". If it succeeds in parsing
the date, parsedate() returns a 9-tuple that can be passed directly to
time.mktime(); otherwise None will be returned. Note that indexes 6,
7, and 8 of the result tuple are not usable.

Performs the same function as parsedate(), but returns either None or
a 10-tuple; the first 9 elements make up a tuple that can be passed directly to
time.mktime(), and the tenth is the offset of the date’s timezone from UTC
(which is the official term for Greenwich Mean Time) [1]. If the input string
has no timezone, the last element of the tuple returned is None. Note that
indexes 6, 7, and 8 of the result tuple are not usable.

The inverse of format_datetime(). Performs the same function as
parsedate(), but on success returns a datetime. If
the input date has a timezone of -0000, the datetime will be a naive
datetime, 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 datetime will be an aware datetime with the
corresponding a timezonetzinfo.

Optional localtime is a flag that when True, interprets timeval, and
returns a date relative to the local timezone instead of UTC, properly taking
daylight savings time into account. The default is False meaning UTC is
used.

Optional usegmt is a flag that when True, outputs a date string with the
timezone as an ascii string GMT, rather than a numeric -0000. This is
needed for some protocols (such as HTTP). This only applies when localtime is
False. The default is False.

Like formatdate, but the input is a datetime instance. If it is
a naive datetime, it is assumed to be “UTC with no information about the
source timezone”, and the conventional -0000 is used for the timezone.
If it is an aware datetime, then the numeric timezone offset is used.
If it is an aware timezone with offset zero, then usegmt may be set to
True, in which case the string GMT is used instead of the numeric
timezone offset. This provides a way to generate standards conformant HTTP
date headers.

Encode the string s according to RFC 2231. Optional charset and
language, if given is the character set name and language name to use. If
neither is given, s is returned as-is. If charset is given but language
is not, the string is encoded using the empty string for language.

When a header parameter is encoded in RFC 2231 format,
Message.get_param may return a
3-tuple containing the character set,
language, and value. collapse_rfc2231_value() turns this into a unicode
string. Optional errors is passed to the errors argument of str’s
encode() method; it defaults to 'replace'. Optional
fallback_charset specifies the character set to use if the one in the
RFC 2231 header is not known by Python; it defaults to 'us-ascii'.

For convenience, if the value passed to collapse_rfc2231_value() is not
a tuple, it should be a string and it is returned unquoted.

Note that the sign of the timezone offset is the opposite of the sign of the
time.timezone variable for the same timezone; the latter variable follows
the POSIX standard while this module follows RFC 2822.