Back to index

python3.2  3.2.2
Public Member Functions | Private Member Functions | Private Attributes
email.header.Header Class Reference

List of all members.

Public Member Functions

def __init__
def __str__
def __eq__
def __ne__
def append
def encode

Private Member Functions

def _normalize

Private Attributes

 _charset
 _continuation_ws
 _chunks
 _maxlinelen
 _headerlen

Detailed Description

Definition at line 167 of file header.py.


Constructor & Destructor Documentation

def email.header.Header.__init__ (   self,
  s = None,
  charset = None,
  maxlinelen = None,
  header_name = None,
  continuation_ws = ' ',
  errors = 'strict' 
)
Create a MIME-compliant header that can contain many character sets.

Optional s is the initial header value.  If None, the initial header
value is not set.  You can later append to the header with .append()
method calls.  s may be a byte string or a Unicode string, but see the
.append() documentation for semantics.

Optional charset serves two purposes: it has the same meaning as the
charset argument to the .append() method.  It also sets the default
character set for all subsequent .append() calls that omit the charset
argument.  If charset is not provided in the constructor, the us-ascii
charset is used both as s's initial charset and as the default for
subsequent .append() calls.

The maximum line length can be specified explicitly via maxlinelen. For
splitting the first line to a shorter value (to account for the field
header which isn't included in s, e.g. `Subject') pass in the name of
the field in header_name.  The default maxlinelen is 78 as recommended
by RFC 2822.

continuation_ws must be RFC 2822 compliant folding whitespace (usually
either a space or a hard tab) which will be prepended to continuation
lines.

errors is passed through to the .append() call.

Definition at line 170 of file header.py.

00170 
00171                  continuation_ws=' ', errors='strict'):
00172         """Create a MIME-compliant header that can contain many character sets.
00173 
00174         Optional s is the initial header value.  If None, the initial header
00175         value is not set.  You can later append to the header with .append()
00176         method calls.  s may be a byte string or a Unicode string, but see the
00177         .append() documentation for semantics.
00178 
00179         Optional charset serves two purposes: it has the same meaning as the
00180         charset argument to the .append() method.  It also sets the default
00181         character set for all subsequent .append() calls that omit the charset
00182         argument.  If charset is not provided in the constructor, the us-ascii
00183         charset is used both as s's initial charset and as the default for
00184         subsequent .append() calls.
00185 
00186         The maximum line length can be specified explicitly via maxlinelen. For
00187         splitting the first line to a shorter value (to account for the field
00188         header which isn't included in s, e.g. `Subject') pass in the name of
00189         the field in header_name.  The default maxlinelen is 78 as recommended
00190         by RFC 2822.
00191 
00192         continuation_ws must be RFC 2822 compliant folding whitespace (usually
00193         either a space or a hard tab) which will be prepended to continuation
00194         lines.
00195 
00196         errors is passed through to the .append() call.
00197         """
00198         if charset is None:
00199             charset = USASCII
00200         elif not isinstance(charset, Charset):
00201             charset = Charset(charset)
00202         self._charset = charset
00203         self._continuation_ws = continuation_ws
00204         self._chunks = []
00205         if s is not None:
00206             self.append(s, charset, errors)
00207         if maxlinelen is None:
00208             maxlinelen = MAXLINELEN
00209         self._maxlinelen = maxlinelen
00210         if header_name is None:
00211             self._headerlen = 0
00212         else:
00213             # Take the separating colon and space into account.
00214             self._headerlen = len(header_name) + 2

Here is the caller graph for this function:


Member Function Documentation

def email.header.Header.__eq__ (   self,
  other 
)

Definition at line 242 of file header.py.

00242 
00243     def __eq__(self, other):
00244         # other may be a Header or a string.  Both are fine so coerce
00245         # ourselves to a unicode (of the unencoded header value), swap the
00246         # args and do another comparison.
00247         return other == str(self)

def email.header.Header.__ne__ (   self,
  other 
)

Definition at line 248 of file header.py.

00248 
00249     def __ne__(self, other):
00250         return not self == other

Return the string value of the header.

Definition at line 215 of file header.py.

00215 
00216     def __str__(self):
00217         """Return the string value of the header."""
00218         self._normalize()
00219         uchunks = []
00220         lastcs = None
00221         for string, charset in self._chunks:
00222             # We must preserve spaces between encoded and non-encoded word
00223             # boundaries, which means for us we need to add a space when we go
00224             # from a charset to None/us-ascii, or from None/us-ascii to a
00225             # charset.  Only do this for the second and subsequent chunks.
00226             nextcs = charset
00227             if nextcs == _charset.UNKNOWN8BIT:
00228                 original_bytes = string.encode('ascii', 'surrogateescape')
00229                 string = original_bytes.decode('ascii', 'replace')
00230             if uchunks:
00231                 if lastcs not in (None, 'us-ascii'):
00232                     if nextcs in (None, 'us-ascii'):
00233                         uchunks.append(SPACE)
00234                         nextcs = None
00235                 elif nextcs not in (None, 'us-ascii'):
00236                     uchunks.append(SPACE)
00237             lastcs = nextcs
00238             uchunks.append(string)
00239         return EMPTYSTRING.join(uchunks)

Here is the call graph for this function:

def email.header.Header._normalize (   self) [private]

Definition at line 356 of file header.py.

00356 
00357     def _normalize(self):
00358         # Step 1: Normalize the chunks so that all runs of identical charsets
00359         # get collapsed into a single unicode string.
00360         chunks = []
00361         last_charset = None
00362         last_chunk = []
00363         for string, charset in self._chunks:
00364             if charset == last_charset:
00365                 last_chunk.append(string)
00366             else:
00367                 if last_charset is not None:
00368                     chunks.append((SPACE.join(last_chunk), last_charset))
00369                 last_chunk = [string]
00370                 last_charset = charset
00371         if last_chunk:
00372             chunks.append((SPACE.join(last_chunk), last_charset))
00373         self._chunks = chunks
00374 
00375 


Here is the caller graph for this function:

def email.header.Header.append (   self,
  s,
  charset = None,
  errors = 'strict' 
)
Append a string to the MIME header.

Optional charset, if given, should be a Charset instance or the name
of a character set (which will be converted to a Charset instance).  A
value of None (the default) means that the charset given in the
constructor is used.

s may be a byte string or a Unicode string.  If it is a byte string
(i.e. isinstance(s, str) is false), then charset is the encoding of
that byte string, and a UnicodeError will be raised if the string
cannot be decoded with that charset.  If s is a Unicode string, then
charset is a hint specifying the character set of the characters in
the string.  In either case, when producing an RFC 2822 compliant
header using RFC 2047 rules, the string will be encoded using the
output codec of the charset.  If the string cannot be encoded to the
output codec, a UnicodeError will be raised.

Optional `errors' is passed as the errors argument to the decode
call if s is a byte string.

Definition at line 251 of file header.py.

00251 
00252     def append(self, s, charset=None, errors='strict'):
00253         """Append a string to the MIME header.
00254 
00255         Optional charset, if given, should be a Charset instance or the name
00256         of a character set (which will be converted to a Charset instance).  A
00257         value of None (the default) means that the charset given in the
00258         constructor is used.
00259 
00260         s may be a byte string or a Unicode string.  If it is a byte string
00261         (i.e. isinstance(s, str) is false), then charset is the encoding of
00262         that byte string, and a UnicodeError will be raised if the string
00263         cannot be decoded with that charset.  If s is a Unicode string, then
00264         charset is a hint specifying the character set of the characters in
00265         the string.  In either case, when producing an RFC 2822 compliant
00266         header using RFC 2047 rules, the string will be encoded using the
00267         output codec of the charset.  If the string cannot be encoded to the
00268         output codec, a UnicodeError will be raised.
00269 
00270         Optional `errors' is passed as the errors argument to the decode
00271         call if s is a byte string.
00272         """
00273         if charset is None:
00274             charset = self._charset
00275         elif not isinstance(charset, Charset):
00276             charset = Charset(charset)
00277         if not isinstance(s, str):
00278             input_charset = charset.input_codec or 'us-ascii'
00279             if input_charset == _charset.UNKNOWN8BIT:
00280                 s = s.decode('us-ascii', 'surrogateescape')
00281             else:
00282                 s = s.decode(input_charset, errors)
00283         # Ensure that the bytes we're storing can be decoded to the output
00284         # character set, otherwise an early error is thrown.
00285         output_charset = charset.output_codec or 'us-ascii'
00286         if output_charset != _charset.UNKNOWN8BIT:
00287             s.encode(output_charset, errors)
00288         self._chunks.append((s, charset))

Here is the caller graph for this function:

def email.header.Header.encode (   self,
  splitchars = ';,
  t,
  maxlinelen = None,
  linesep = '\n' 
)

Definition at line 289 of file header.py.

00289 
00290     def encode(self, splitchars=';, \t', maxlinelen=None, linesep='\n'):
00291         r"""Encode a message header into an RFC-compliant format.
00292 
00293         There are many issues involved in converting a given string for use in
00294         an email header.  Only certain character sets are readable in most
00295         email clients, and as header strings can only contain a subset of
00296         7-bit ASCII, care must be taken to properly convert and encode (with
00297         Base64 or quoted-printable) header strings.  In addition, there is a
00298         75-character length limit on any given encoded header field, so
00299         line-wrapping must be performed, even with double-byte character sets.
00300 
00301         Optional maxlinelen specifies the maximum length of each generated
00302         line, exclusive of the linesep string.  Individual lines may be longer
00303         than maxlinelen if a folding point cannot be found.  The first line
00304         will be shorter by the length of the header name plus ": " if a header
00305         name was specified at Header construction time.  The default value for
00306         maxlinelen is determined at header construction time.
00307 
00308         Optional splitchars is a string containing characters which should be
00309         given extra weight by the splitting algorithm during normal header
00310         wrapping.  This is in very rough support of RFC 2822's `higher level
00311         syntactic breaks':  split points preceded by a splitchar are preferred
00312         during line splitting, with the characters preferred in the order in
00313         which they appear in the string.  Space and tab may be included in the
00314         string to indicate whether preference should be given to one over the
00315         other as a split point when other split chars do not appear in the line
00316         being split.  Splitchars does not affect RFC 2047 encoded lines.
00317 
00318         Optional linesep is a string to be used to separate the lines of
00319         the value.  The default value is the most useful for typical
00320         Python applications, but it can be set to \r\n to produce RFC-compliant
00321         line separators when needed.
00322         """
00323         self._normalize()
00324         if maxlinelen is None:
00325             maxlinelen = self._maxlinelen
00326         # A maxlinelen of 0 means don't wrap.  For all practical purposes,
00327         # choosing a huge number here accomplishes that and makes the
00328         # _ValueFormatter algorithm much simpler.
00329         if maxlinelen == 0:
00330             maxlinelen = 1000000
00331         formatter = _ValueFormatter(self._headerlen, maxlinelen,
00332                                     self._continuation_ws, splitchars)
00333         for string, charset in self._chunks:
00334             lines = string.splitlines()
00335             if lines:
00336                 formatter.feed('', lines[0], charset)
00337             else:
00338                 formatter.feed('', '', charset)
00339             for line in lines[1:]:
00340                 formatter.newline()
00341                 if charset.header_encoding is not None:
00342                     formatter.feed(self._continuation_ws, ' ' + line.lstrip(),
00343                                    charset)
00344                 else:
00345                     sline = line.lstrip()
00346                     fws = line[:len(line)-len(sline)]
00347                     formatter.feed(fws, sline, charset)
00348             if len(lines) > 1:
00349                 formatter.newline()
00350             formatter.add_transition()
00351         value = formatter._str(linesep)
00352         if _embeded_header.search(value):
00353             raise HeaderParseError("header value appears to contain "
00354                 "an embedded header: {!r}".format(value))
00355         return value

Here is the call graph for this function:

Here is the caller graph for this function:


Member Data Documentation

Definition at line 201 of file header.py.

Definition at line 203 of file header.py.

Definition at line 202 of file header.py.

Definition at line 210 of file header.py.

Definition at line 208 of file header.py.


The documentation for this class was generated from the following file: