Support for case-preserving addresses. When an Address is given an email

address that is not lower cased, the original, case-preserved version is store
on the '_original' attribute.  The lower-cased version is always used as the
key and thus always stored on the 'address' attribute.  The IAddress interface
is given a new 'original_address' property which returns the case-preserved
version.

Address's __str__() and __repr__() are similarly modified.  The former always
includes the case-preserved address; the latter does too, but now also
includes the lower-cased 'key' email address (along with the object's id).

Searching for an address always does so on the lower-cased version.

Test suite is updated as necessary.  Also, I'm adding the
REPORT_ONLY_FIRST_FAILURE doctest flag so that it's easier to debug doctest
failures without having pages of problems to scroll through.

6 files changed, 108 insertions, 13 deletions

diff --git a/Mailman/database/model/address.py b/Mailman/database/model/address.py
index 897b41696..ca51af265 100644
--- a/Mailman/database/model/address.py
+++ b/Mailman/database/model/address.py
@@ -31,6 +31,7 @@ class Address(Entity):
     implements(IAddress)
 
     has_field('address',        Unicode)
+    has_field('_original',      Unicode)
     has_field('real_name',      Unicode)
     has_field('verified',       Boolean)
     has_field('registered_on',  DateTime)
@@ -41,12 +42,26 @@ class Address(Entity):
     # Options
     using_options(shortnames=True)
 
+    def __init__(self, address, real_name):
+        super(Address, self).__init__()
+        lower_case = address.lower()
+        self.address = lower_case
+        self.real_name = real_name
+        self._original = (None if lower_case == address else address)
+
     def __str__(self):
-        return formataddr((self.real_name, self.address))
+        addr = (self.address if self._original is None else self._original)
+        return formataddr((self.real_name, addr))
 
     def __repr__(self):
-        return '<Address: %s [%s]>' % (
-            str(self), ('verified' if self.verified else 'not verified'))
+        verified = ('verified' if self.verified else 'not verified')
+        address_str = str(self)
+        if self._original is None:
+            return '<Address: %s [%s] at %#x>' % (
+                address_str, verified, id(self))
+        else:
+            return '<Address: %s [%s] key: %s at %#x>' % (
+                address_str, verified, self.address, id(self))
 
     def subscribe(self, mlist, role):
         from Mailman.database.model import Member
@@ -57,3 +72,7 @@ class Address(Entity):
                         address=self)
         member.preferences = Preferences()
         return member
+
+    @property
+    def original_address(self):
+        return (self.address if self._original is None else self._original)
diff --git a/Mailman/database/usermanager.py b/Mailman/database/usermanager.py
index a37dcf60a..038427879 100644
--- a/Mailman/database/usermanager.py
+++ b/Mailman/database/usermanager.py
@@ -39,7 +39,7 @@ class UserManager(object):
         user = User()
         user.real_name = (real_name if real_name is not None else '')
         if address:
-            addrobj = Address(address=address, real_name=user.real_name)
+            addrobj = Address(address, user.real_name)
             addrobj.preferences = Preferences()
             user.link(addrobj)
         user.preferences = Preferences()
@@ -54,16 +54,16 @@ class UserManager(object):
             yield user
 
     def get_user(self, address):
-        found = Address.get_by(address=address)
+        found = Address.get_by(address=address.lower())
         return found and found.user
 
     def create_address(self, address, real_name=None):
-        found = Address.get_by(address=address)
+        found = Address.get_by(address=address.lower())
         if found:
-            raise Errors.ExistingAddressError(address)
+            raise Errors.ExistingAddressError(found.original_address)
         if real_name is None:
             real_name = ''
-        address = Address(address=address, real_name=real_name)
+        address = Address(address, real_name)
         address.preferences = Preferences()
         return address
 
@@ -75,7 +75,7 @@ class UserManager(object):
         address.delete()
 
     def get_address(self, address):
-        return Address.get_by(address=address)
+        return Address.get_by(address=address.lower())
 
     @property
     def addresses(self):
diff --git a/Mailman/docs/addresses.txt b/Mailman/docs/addresses.txt
index 774a90855..d1e83522e 100644
--- a/Mailman/docs/addresses.txt
+++ b/Mailman/docs/addresses.txt
@@ -41,6 +41,14 @@ You can also create an email address object with a real name.
     >>> sorted(address.real_name for address in mgr.addresses)
     ['', 'Ben Person']
 
+The str() of the address is the RFC 2822 preferred originator format, while
+the repr() carries more information.
+
+    >>> str(address_2)
+    'Ben Person <bperson@example.com>'
+    >>> repr(address_2)
+    '<Address: Ben Person <bperson@example.com> [not verified] at 0x...>'
+
 You can assign real names to existing addresses.
 
     >>> address_1.real_name = 'Anne Person'
@@ -156,7 +164,7 @@ subscribed, a role is specified.
              _xtext@example.com as MemberRole.member>
     >>> flush()
 
-Now that Elly is both an owner and a member of the mailing list.
+Now Elly is both an owner and a member of the mailing list.
 
     >>> sorted(mlist.owners.members)
     [<Member: Elly Person <eperson@example.com> on
@@ -174,3 +182,57 @@ Now that Elly is both an owner and a member of the mailing list.
               _xtext@example.com as MemberRole.member>]
     >>> sorted(mlist.digest_members.members)
     []
+
+
+Case-preserved addresses
+------------------------
+
+Technically speaking, email addresses are case sensitive in the local part.
+Mailman preserves the case of addresses and uses the case preserved version
+when sending the user a message, but it treats addresses that are different in
+case equivalently in all other situations.
+
+    >>> address_6 = mgr.create_address('FPERSON@example.com', 'Frank Person')
+    >>> flush()
+
+The str() of such an address prints the RFC 2822 preferred originator format
+with the original case-preserved address.  The repr() contains all the gory
+details.
+
+    >>> str(address_6)
+    'Frank Person <FPERSON@example.com>'
+    >>> repr(address_6)
+    '<Address: Frank Person <FPERSON@example.com> [not verified]
+               key: fperson@example.com at 0x...>'
+
+Both the case-insensitive version of the address and the original
+case-preserved version are available on attributes of the IAddress object.
+
+    >>> address_6.address
+    'fperson@example.com'
+    >>> address_6.original_address
+    'FPERSON@example.com'
+
+Because addresses are case-insensitive for all other purposes, you cannot
+create an address that differs only in case.
+
+    >>> mgr.create_address('fperson@example.com')
+    Traceback (most recent call last):
+    ...
+    ExistingAddressError: FPERSON@example.com
+    >>> mgr.create_address('fperson@EXAMPLE.COM')
+    Traceback (most recent call last):
+    ...
+    ExistingAddressError: FPERSON@example.com
+    >>> mgr.create_address('FPERSON@example.com')
+    Traceback (most recent call last):
+    ...
+    ExistingAddressError: FPERSON@example.com
+
+You can get the address using either the lower cased version or case-preserved
+version.  In fact, searching for an address is case insensitive.
+
+    >>> mgr.get_address('fperson@example.com').address
+    'fperson@example.com'
+    >>> mgr.get_address('FPERSON@example.com').address
+    'fperson@example.com'
diff --git a/Mailman/docs/users.txt b/Mailman/docs/users.txt
index 3dc6d11f2..eb4c9df10 100644
--- a/Mailman/docs/users.txt
+++ b/Mailman/docs/users.txt
@@ -48,9 +48,9 @@ The easiest way to link a user to an address is to just register the new
 address on a user object.
 
     >>> user_1.register('zperson@example.com', 'Zoe Person')
-    <Address: Zoe Person <zperson@example.com> [not verified]>
+    <Address: Zoe Person <zperson@example.com> [not verified] at 0x...>
     >>> user_1.register('zperson@example.org')
-    <Address: zperson@example.org [not verified]>
+    <Address: zperson@example.org [not verified] at 0x...>
     >>> flush()
     >>> sorted(address.address for address in user_1.addresses)
     ['zperson@example.com', 'zperson@example.org']
diff --git a/Mailman/interfaces/address.py b/Mailman/interfaces/address.py
index c367774c3..8a6e42c60 100644
--- a/Mailman/interfaces/address.py
+++ b/Mailman/interfaces/address.py
@@ -27,6 +27,19 @@ class IAddress(Interface):
     address = Attribute(
         """Read-only text email address.""")
 
+    original_address = Attribute(
+        """Read-only original case-preserved address.
+
+        For almost all intents and purposes, addresses in Mailman are case
+        insensitive, however because RFC 2821 allows for case sensitive local
+        parts, Mailman preserves the case of the original address when
+        emailing the user.
+
+        `original_address` will be the same as address if the original address
+        was all lower case.  Otherwise `original_address` will be the case
+        preserved address; `address` will always be lower case.
+        """)
+
     real_name = Attribute(
         """Optional real name associated with the email address.""")
 
diff --git a/Mailman/testing/test_documentation.py b/Mailman/testing/test_documentation.py
index 144e6f64b..23641d57b 100644
--- a/Mailman/testing/test_documentation.py
+++ b/Mailman/testing/test_documentation.py
@@ -67,7 +67,8 @@ def test_suite():
                 package=Mailman,
                 optionflags=(doctest.ELLIPSIS
                              | doctest.NORMALIZE_WHITESPACE
-                             | doctest.REPORT_NDIFF),
+                             | doctest.REPORT_NDIFF
+                             | doctest.REPORT_ONLY_FIRST_FAILURE),
                 tearDown=cleaning_teardown)
             suite.addTest(test)
     return suite