Doc/lib/emailheaders.tex

   1 \declaremodule{standard}{email.Header}
   2 \modulesynopsis{Representing non-ASCII headers}
   3
   4 \rfc{2822} is the base standard that describes the format of email
   5 messages.  It derives from the older \rfc{822} standard which came
   6 into widespread use at a time when most email was composed of \ASCII{}
   7 characters only.  \rfc{2822} is a specification written assuming email
   8 contains only 7-bit \ASCII{} characters.
   9
  10 Of course, as email has been deployed worldwide, it has become
  11 internationalized, such that language specific character sets can now
  12 be used in email messages.  The base standard still requires email
  13 messages to be transferred using only 7-bit \ASCII{} characters, so a
  14 slew of RFCs have been written describing how to encode email
  15 containing non-\ASCII{} characters into \rfc{2822}-compliant format.
  16 These RFCs include \rfc{2045}, \rfc{2046}, \rfc{2047}, and \rfc{2231}.
  17 The \module{email} package supports these standards in its
  18 \module{email.Header} and \module{email.Charset} modules.
  19
  20 If you want to include non-\ASCII{} characters in your email headers,
  21 say in the \mailheader{Subject} or \mailheader{To} fields, you should
  22 use the \class{Header} class and assign the field in the
  23 \class{Message} object to an instance of \class{Header} instead of
  24 using a string for the header value.  For example:
  25
  26 \begin{verbatim}
  27 >>> from email.Message import Message
  28 >>> from email.Header import Header
  29 >>> msg = Message()
  30 >>> h = Header('p\xf6stal', 'iso-8859-1')
  31 >>> msg['Subject'] = h
  32 >>> print msg.as_string()
  33 Subject: =?iso-8859-1?q?p=F6stal?=
  34
  35
  36 \end{verbatim}
  37
  38 Notice here how we wanted the \mailheader{Subject} field to contain a
  39 non-\ASCII{} character?  We did this by creating a \class{Header}
  40 instance and passing in the character set that the byte string was
  41 encoded in.  When the subsequent \class{Message} instance was
  42 flattened, the \mailheader{Subject} field was properly \rfc{2047}
  43 encoded.  MIME-aware mail readers would show this header using the
  44 embedded ISO-8859-1 character.
  45
  46 \versionadded{2.2.2}
  47
  48 Here is the \class{Header} class description:
  49
  50 \begin{classdesc}{Header}{\optional{s\optional{, charset\optional{,
  51     maxlinelen\optional{, header_name\optional{, continuation_ws\optional{,
  52     errors}}}}}}}
  53 Create a MIME-compliant header that can contain strings in different
  54 character sets.
  55
  56 Optional \var{s} is the initial header value.  If \code{None} (the
  57 default), the initial header value is not set.  You can later append
  58 to the header with \method{append()} method calls.  \var{s} may be a
  59 byte string or a Unicode string, but see the \method{append()}
  60 documentation for semantics.
  61
  62 Optional \var{charset} serves two purposes: it has the same meaning as
  63 the \var{charset} argument to the \method{append()} method.  It also
  64 sets the default character set for all subsequent \method{append()}
  65 calls that omit the \var{charset} argument.  If \var{charset} is not
  66 provided in the constructor (the default), the \code{us-ascii}
  67 character set is used both as \var{s}'s initial charset and as the
  68 default for subsequent \method{append()} calls.
  69
  70 The maximum line length can be specified explicit via
  71 \var{maxlinelen}.  For splitting the first line to a shorter value (to
  72 account for the field header which isn't included in \var{s},
  73 e.g. \mailheader{Subject}) pass in the name of the field in
  74 \var{header_name}.  The default \var{maxlinelen} is 76, and the
  75 default value for \var{header_name} is \code{None}, meaning it is not
  76 taken into account for the first line of a long, split header.
  77
  78 Optional \var{continuation_ws} must be \rfc{2822}-compliant folding
  79 whitespace, and is usually either a space or a hard tab character.
  80 This character will be prepended to continuation lines.
  81 \end{classdesc}
  82
  83 Optional \var{errors} is passed straight through to the
  84 \method{append()} method.
  85
  86 \begin{methoddesc}[Header]{append}{s\optional{, charset\optional{, errors}}}
  87 Append the string \var{s} to the MIME header.
  88
  89 Optional \var{charset}, if given, should be a \class{Charset} instance
  90 (see \refmodule{email.Charset}) or the name of a character set, which
  91 will be converted to a \class{Charset} instance.  A value of
  92 \code{None} (the default) means that the \var{charset} given in the
  93 constructor is used.
  94
  95 \var{s} may be a byte string or a Unicode string.  If it is a byte
  96 string (i.e. \code{isinstance(s, str)} is true), then
  97 \var{charset} is the encoding of that byte string, and a
  98 \exception{UnicodeError} will be raised if the string cannot be
  99 decoded with that character set.
 100
 101 If \var{s} is a Unicode string, then \var{charset} is a hint
 102 specifying the character set of the characters in the string.  In this
 103 case, when producing an \rfc{2822}-compliant header using \rfc{2047}
 104 rules, the Unicode string will be encoded using the following charsets
 105 in order: \code{us-ascii}, the \var{charset} hint, \code{utf-8}.  The
 106 first character set to not provoke a \exception{UnicodeError} is used.
 107
 108 Optional \var{errors} is passed through to any \function{unicode()} or
 109 \function{ustr.encode()} call, and defaults to ``strict''.
 110 \end{methoddesc}
 111
 112 \begin{methoddesc}[Header]{encode}{\optional{splitchars}}
 113 Encode a message header into an RFC-compliant format, possibly
 114 wrapping long lines and encapsulating non-\ASCII{} parts in base64 or
 115 quoted-printable encodings.  Optional \var{splitchars} is a string
 116 containing characters to split long ASCII lines on, in rough support
 117 of \rfc{2822}'s \emph{highest level syntactic breaks}.  This doesn't
 118 affect \rfc{2047} encoded lines.
 119 \end{methoddesc}
 120
 121 The \class{Header} class also provides a number of methods to support
 122 standard operators and built-in functions.
 123
 124 \begin{methoddesc}[Header]{__str__}{}
 125 A synonym for \method{Header.encode()}.  Useful for
 126 \code{str(aHeader)}.
 127 \end{methoddesc}
 128
 129 \begin{methoddesc}[Header]{__unicode__}{}
 130 A helper for the built-in \function{unicode()} function.  Returns the
 131 header as a Unicode string.
 132 \end{methoddesc}
 133
 134 \begin{methoddesc}[Header]{__eq__}{other}
 135 This method allows you to compare two \class{Header} instances for equality.
 136 \end{methoddesc}
 137
 138 \begin{methoddesc}[Header]{__ne__}{other}
 139 This method allows you to compare two \class{Header} instances for inequality.
 140 \end{methoddesc}
 141
 142 The \module{email.Header} module also provides the following
 143 convenient functions.
 144
 145 \begin{funcdesc}{decode_header}{header}
 146 Decode a message header value without converting the character set.
 147 The header value is in \var{header}.
 148
 149 This function returns a list of \code{(decoded_string, charset)} pairs
 150 containing each of the decoded parts of the header.  \var{charset} is
 151 \code{None} for non-encoded parts of the header, otherwise a lower
 152 case string containing the name of the character set specified in the
 153 encoded string.
 154
 155 Here's an example:
 156
 157 \begin{verbatim}
 158 >>> from email.Header import decode_header
 159 >>> decode_header('=?iso-8859-1?q?p=F6stal?=')
 160 [('p\xf6stal', 'iso-8859-1')]
 161 \end{verbatim}
 162 \end{funcdesc}
 163
 164 \begin{funcdesc}{make_header}{decoded_seq\optional{, maxlinelen\optional{,
 165     header_name\optional{, continuation_ws}}}}
 166 Create a \class{Header} instance from a sequence of pairs as returned
 167 by \function{decode_header()}.
 168
 169 \function{decode_header()} takes a header value string and returns a
 170 sequence of pairs of the format \code{(decoded_string, charset)} where
 171 \var{charset} is the name of the character set.
 172
 173 This function takes one of those sequence of pairs and returns a
 174 \class{Header} instance.  Optional \var{maxlinelen},
 175 \var{header_name}, and \var{continuation_ws} are as in the
 176 \class{Header} constructor.
 177 \end{funcdesc}