[Python-checkins] python/dist/src/Lib/email Header.py,1.11,1.12
barry@users.sourceforge.net
barry@users.sourceforge.net
Mon, 30 Sep 2002 08:51:34 -0700
Update of /cvsroot/python/python/dist/src/Lib/email
In directory usw-pr-cvs1:/tmp/cvs-serv24752
Modified Files:
Header.py
Log Message:
With help from Martin v. Loewis, clarification is added for the
semantics of header chunks using byte and Unicode strings.
Specifically,
append(): When the given string is a byte string, charset (whether
specified explicitly in the argument list or implicitly via the
constructor default) is the encoding of the 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 this case, when
producing an RFC 2822 compliant header using RFC 2047 rules, the
Unicode string will be encoded using the following charsets in order:
us-ascii, the charset hint, utf-8.
__init__(): Use the global USASCII Charset instance when the charset
argument is None. Also, clarification in the docstring.
Also, use True/False where appropriate.
Index: Header.py
===================================================================
RCS file: /cvsroot/python/python/dist/src/Lib/email/Header.py,v
retrieving revision 1.11
retrieving revision 1.12
diff -C2 -d -r1.11 -r1.12
*** Header.py 10 Sep 2002 15:57:29 -0000 1.11
--- Header.py 30 Sep 2002 15:51:31 -0000 1.12
***************
*** 1,8 ****
# Copyright (C) 2002 Python Software Foundation
! # Author: che@debian.org (Ben Gertzfield)
"""Header encoding and decoding functionality."""
import re
import email.quopriMIME
import email.base64MIME
--- 1,10 ----
# Copyright (C) 2002 Python Software Foundation
! # Author: che@debian.org (Ben Gertzfield), barry@zope.com (Barry Warsaw)
"""Header encoding and decoding functionality."""
import re
+ from types import StringType, UnicodeType
+
import email.quopriMIME
import email.base64MIME
***************
*** 15,18 ****
--- 17,26 ----
from email._compat21 import _floordiv
+ try:
+ True, False
+ except NameError:
+ True = 1
+ False = 0
+
CRLFSPACE = '\r\n '
CRLF = '\r\n'
***************
*** 26,29 ****
--- 34,40 ----
DECODE = 2
+ USASCII = Charset('us-ascii')
+ UTF8 = Charset('utf-8')
+
# Match encoded-word strings in the form =?charset?q?Hello_World?=
ecre = re.compile(r'''
***************
*** 118,136 ****
def __init__(self, s=None, charset=None, maxlinelen=None, header_name=None,
continuation_ws=' '):
! """Create a MIME-compliant header that can contain many languages.
!
! Specify the initial header value in s. If None, the initial header
! value is not set.
! Specify both s's character set, and the default character set by
! setting the charset argument to a Charset object (not a character set
! name string!). If None, a us-ascii Charset is used as both s's
! initial charset and as the default character set for subsequent
! .append() calls.
! You can later append to the header with append(s, charset) below;
! charset does not have to be the same as the one initially specified
! here. In fact, it's optional, and if not given, defaults to the
! charset specified in the constructor.
The maximum line length can be specified explicit via maxlinelen. For
--- 129,145 ----
def __init__(self, s=None, charset=None, maxlinelen=None, header_name=None,
continuation_ws=' '):
! """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 explicit via maxlinelen. For
***************
*** 144,148 ****
"""
if charset is None:
! charset = Charset()
self._charset = charset
self._continuation_ws = continuation_ws
--- 153,157 ----
"""
if charset is None:
! charset = USASCII
self._charset = charset
self._continuation_ws = continuation_ws
***************
*** 187,196 ****
def append(self, s, charset=None):
! """Append string s with Charset charset to the MIME header.
! If charset is given, it 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 charset is the one given in the
! class constructor.
"""
if charset is None:
--- 196,214 ----
def append(self, s, charset=None):
! """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, StringType) is true), 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 this case, when producing an RFC 2822 compliant header
! using RFC 2047 rules, the Unicode string will be encoded using the
! following charsets in order: us-ascii, the charset hint, utf-8.
"""
if charset is None:
***************
*** 198,204 ****
elif not isinstance(charset, Charset):
charset = Charset(charset)
self._chunks.append((s, charset))
! def _split(self, s, charset, firstline=0):
# Split up a header safely for use with encode_chunks. BAW: this
# appears to be a private convenience method.
--- 216,236 ----
elif not isinstance(charset, Charset):
charset = Charset(charset)
+ # Normalize and check the string
+ if isinstance(s, StringType):
+ # Possibly raise UnicodeError if it can't e encoded
+ unicode(s, charset.get_output_charset())
+ elif isinstance(s, UnicodeType):
+ # Convert Unicode to byte string for later concatenation
+ for charset in USASCII, charset, UTF8:
+ try:
+ s = s.encode(charset.get_output_charset())
+ break
+ except UnicodeError:
+ pass
+ else:
+ assert False, 'Could not encode to utf-8'
self._chunks.append((s, charset))
! def _split(self, s, charset, firstline=False):
# Split up a header safely for use with encode_chunks. BAW: this
# appears to be a private convenience method.
***************
*** 228,238 ****
# encoding won't change the size of the string
splitpnt = self._maxlinelen
! first = charset.from_splittable(splittable[:splitpnt], 0)
! last = charset.from_splittable(splittable[splitpnt:], 0)
else:
# Divide and conquer.
halfway = _floordiv(len(splittable), 2)
! first = charset.from_splittable(splittable[:halfway], 0)
! last = charset.from_splittable(splittable[halfway:], 0)
# Do the split
return self._split(first, charset, firstline) + \
--- 260,270 ----
# encoding won't change the size of the string
splitpnt = self._maxlinelen
! first = charset.from_splittable(splittable[:splitpnt], False)
! last = charset.from_splittable(splittable[splitpnt:], False)
else:
# Divide and conquer.
halfway = _floordiv(len(splittable), 2)
! first = charset.from_splittable(splittable[:halfway], False)
! last = charset.from_splittable(splittable[halfway:], False)
# Do the split
return self._split(first, charset, firstline) + \
***************
*** 249,253 ****
if firstline:
maxlinelen = self._firstlinelen
! firstline = 0
else:
#line = line.lstrip()
--- 281,285 ----
if firstline:
maxlinelen = self._firstlinelen
! firstline = False
else:
#line = line.lstrip()
***************
*** 339,343 ****
_max_append(chunks, header, self._maxlinelen)
else:
! _max_append(chunks, charset.header_encode(header, 0),
self._maxlinelen, ' ')
joiner = NL + self._continuation_ws
--- 371,375 ----
_max_append(chunks, header, self._maxlinelen)
else:
! _max_append(chunks, charset.header_encode(header),
self._maxlinelen, ' ')
joiner = NL + self._continuation_ws
***************
*** 364,368 ****
newchunks = []
for s, charset in self._chunks:
! newchunks += self._split(s, charset, 1)
self._chunks = newchunks
return self._encode_chunks()
--- 396,400 ----
newchunks = []
for s, charset in self._chunks:
! newchunks += self._split(s, charset, True)
self._chunks = newchunks
return self._encode_chunks()