Wow. Put domains into the database.

Add an IDomainManager and a global domain manager which can be gotten by
adapting the global config object.

Add an IDomainCollection interface for exposing the domain manager onto the
API.

3 files changed, 136 insertions, 73 deletions

diff --git a/src/mailman/docs/addresses.txt b/src/mailman/docs/addresses.txt
index a8ae24840..1621afa90 100644
--- a/src/mailman/docs/addresses.txt
+++ b/src/mailman/docs/addresses.txt
@@ -1,3 +1,4 @@
+===============
 Email addresses
 ===============
 
@@ -10,7 +11,7 @@ about.  Addresses are subscribed to mailing lists though members.
 
 
 Creating addresses
-------------------
+==================
 
 Addresses are created directly through the user manager, which starts out with
 no addresses.
@@ -82,7 +83,7 @@ And now you can find the associated user.
 
 
 Deleting addresses
-------------------
+==================
 
 You can remove an unlinked address from the user manager.
 
@@ -110,7 +111,7 @@ address from the user.
 
 
 Registration and validation
----------------------------
+===========================
 
 Addresses have two dates, the date the address was registered on and the date
 the address was validated on.  Neither date is set by default.
@@ -141,7 +142,7 @@ And of course, you can also set the validation date.
 
 
 Subscriptions
--------------
+=============
 
 Addresses get subscribed to mailing lists, not users.  When the address is
 subscribed, a role is specified.
@@ -179,7 +180,7 @@ Now Elly is both an owner and a member of the mailing list.
 
 
 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
diff --git a/src/mailman/docs/domains.txt b/src/mailman/docs/domains.txt
index b71689520..bd7ff5791 100644
--- a/src/mailman/docs/domains.txt
+++ b/src/mailman/docs/domains.txt
@@ -1,46 +1,122 @@
+=======
 Domains
 =======
 
+    # The test framework starts out with an example domain, so let's delete
+    # that first.
+    >>> from mailman.interfaces.domain import IDomainManager
+    >>> manager = IDomainManager(config)
+    >>> manager.remove(u'example.com')
+    <Domain example.com...>
+
 Domains are how Mailman interacts with email host names and web host names.
-Generally, new domains are registered in the mailman.cfg configuration file.
-We simulate that here by pushing new configurations.
 
-    >>> config.push('example.org', """
-    ... [domain.example_dot_org]
-    ... email_host: example.org
-    ... base_url: https://mail.example.org
-    ... description: The example domain
-    ... contact_address: postmaster@mail.example.org
-    ... """)
+    >>> from operator import attrgetter
+    >>> def show_domains():
+    ...     if len(manager) == 0:
+    ...         print 'no domains'
+    ...         return
+    ...     for domain in sorted(manager, key=attrgetter('email_host')):
+    ...         print domain
 
-    >>> domain = config.domains['example.org']
-    >>> print domain.email_host
-    example.org
-    >>> print domain.base_url
-    https://mail.example.org
-    >>> print domain.description
-    The example domain
-    >>> print domain.contact_address
-    postmaster@mail.example.org
-    >>> print domain.url_host
-    mail.example.org
+    >>> show_domains()
+    no domains
 
+Adding a domain requires some basic information, of which the email host name
+is the only required piece.  The other parts are inferred from that.
 
-Confirmation tokens
--------------------
+    >>> manager.add(u'example.org')
+    <Domain example.org, base_url: http://example.org,
+            contact_address: postmaster@example.org>
+    >>> show_domains()
+    <Domain example.org, base_url: http://example.org,
+            contact_address: postmaster@example.org>
 
-Confirmation tokens can be added to either the email confirmation address...
+We can remove domains too.
 
-    >>> print domain.confirm_address('xyz')
-    confirm-xyz@example.org
+    >>> manager.remove(u'example.org')
+    <Domain example.org, base_url: http://example.org,
+            contact_address: postmaster@example.org>
+    >>> show_domains()
+    no domains
 
-...or the confirmation url.
+Sometimes the email host name is different than the base url for hitting the
+web interface for the domain.
+
+    >>> manager.add(u'example.com', base_url=u'https://mail.example.com')
+    <Domain example.com, base_url: https://mail.example.com,
+            contact_address: postmaster@example.com>
+    >>> show_domains()
+    <Domain example.com, base_url: https://mail.example.com,
+            contact_address: postmaster@example.com>
+
+Domains can have explicit descriptions and contact addresses.
+
+    >>> manager.add(
+    ...     u'example.net',
+    ...     base_url=u'http://lists.example.net',
+    ...     contact_address=u'postmaster@example.com',
+    ...     description=u'The example domain')
+    <Domain example.net, The example domain,
+            base_url: http://lists.example.net,
+            contact_address: postmaster@example.com>
+
+    >>> show_domains()
+    <Domain example.com, base_url: https://mail.example.com,
+            contact_address: postmaster@example.com>
+    <Domain example.net, The example domain,
+            base_url: http://lists.example.net,
+            contact_address: postmaster@example.com>
+
+In the global domain manager, domains are indexed by their email host name.
+
+    >>> for domain in sorted(manager, key=attrgetter('email_host')):
+    ...     print domain.email_host
+    example.com
+    example.net
+
+    >>> print manager[u'example.net']
+    <Domain example.net, The example domain,
+            base_url: http://lists.example.net,
+            contact_address: postmaster@example.com>
 
-    >>> print domain.confirm_url('abc')
-    https://mail.example.org/confirm/abc
+    >>> print manager[u'doesnotexist.com']
+    Traceback (most recent call last):
+    ...
+    KeyError: u'doesnotexist.com'
 
+As with a dictionary, you can also get the domain.  If the domain does not
+exist, None or a default is returned.
 
-Clean up
---------
+    >>> print manager.get(u'example.net')
+    <Domain example.net, The example domain,
+            base_url: http://lists.example.net,
+            contact_address: postmaster@example.com>
+
+    >>> print manager.get(u'doesnotexist.com')
+    None
+
+    >>> print manager.get(u'doesnotexist.com', u'blahdeblah')
+    blahdeblah
+
+Non-existent domains cannot be removed.
+
+    >>> manager.remove(u'doesnotexist.com')
+    Traceback (most recent call last):
+    ...
+    KeyError: u'doesnotexist.com'
+
+
+Confirmation tokens
+===================
+
+Confirmation tokens can be added to either the email confirmation address...
+
+    >>> domain = manager[u'example.net']
+    >>> print domain.confirm_address(u'xyz')
+    confirm-xyz@example.net
+
+...or the confirmation url.
 
-    >>> config.pop('example.org')
+    >>> print domain.confirm_url(u'abc')
+    http://lists.example.net/confirm/abc
diff --git a/src/mailman/docs/registration.txt b/src/mailman/docs/registration.txt
index c1b29fd05..519b81ba8 100644
--- a/src/mailman/docs/registration.txt
+++ b/src/mailman/docs/registration.txt
@@ -1,11 +1,11 @@
+====================
 Address registration
 ====================
 
-When a user wants to join a mailing list -- any mailing list -- in the running
-instance, he or she must first register with Mailman.  The only thing they
-must supply is an email address, although there is additional information they
-may supply.  All registered email addresses must be verified before Mailman
-will send them any list traffic.
+Before users can join a mailing list, they must first register with Mailman.
+The only thing they must supply is an email address, although there is
+additional information they may supply.  All registered email addresses must
+be verified before Mailman will send them any list traffic.
 
     >>> from mailman.app.registrar import Registrar
     >>> from mailman.interfaces.registrar import IRegistrar
@@ -15,19 +15,11 @@ Specifically, it does not handle verifications, email address syntax validity
 checks, etc.  The IRegistrar is the interface to the object handling all this
 stuff.
 
-Add a domain, which will provide the context for the verification email
-message.
-
-    >>> config.push('mail', """
-    ... [domain.mail_example_dot_com]
-    ... email_host: mail.example.com
-    ... base_url: http://mail.example.com
-    ... contact_address: postmaster@mail.example.com
-    ... """)
-
-    >>> domain = config.domains['mail.example.com']
+    >>> from mailman.interfaces.domain import IDomainManager
+    >>> manager = IDomainManager(config)
+    >>> domain = manager[u'example.com']
 
-Get a registrar by adapting a context to the interface.
+Get a registrar by adapting a domain.
 
     >>> from zope.interface.verify import verifyObject
     >>> registrar = IRegistrar(domain)
@@ -45,14 +37,14 @@ Here is a helper function to check the token strings.
 Here is a helper function to extract tokens from confirmation messages.
 
     >>> import re
-    >>> cre = re.compile('http://mail.example.com/confirm/(.*)')
+    >>> cre = re.compile('http://lists.example.com/confirm/(.*)')
     >>> def extract_token(msg):
     ...     mo = cre.search(qmsg.get_payload())
     ...     return mo.group(1)
 
 
 Invalid email addresses
------------------------
+=======================
 
 The only piece of information you need to register is the email address.
 Some amount of sanity checks are performed on the email address, although
@@ -86,7 +78,7 @@ addresses are rejected outright.
 
 
 Register an email address
--------------------------
+=========================
 
 Registration of an unknown address creates nothing until the confirmation step
 is complete.  No IUser or IAddress is created at registration time, but a
@@ -115,7 +107,7 @@ But this address is waiting for confirmation.
 
 
 Verification by email
----------------------
+=====================
 
 There is also a verification email sitting in the virgin queue now.  This
 message is sent to the user in order to verify the registered address.
@@ -131,7 +123,7 @@ message is sent to the user in order to verify the registered address.
     Content-Type: text/plain; charset="us-ascii"
     Content-Transfer-Encoding: 7bit
     Subject: confirm ...
-    From: confirm-...@mail.example.com
+    From: confirm-...@example.com
     To: aperson@example.com
     Message-ID: <...>
     Date: ...
@@ -139,7 +131,7 @@ message is sent to the user in order to verify the registered address.
     <BLANKLINE>
     Email Address Registration Confirmation
     <BLANKLINE>
-    Hello, this is the GNU Mailman server at mail.example.com.
+    Hello, this is the GNU Mailman server at example.com.
     <BLANKLINE>
     We have received a registration request for the email address
     <BLANKLINE>
@@ -150,13 +142,13 @@ message is sent to the user in order to verify the registered address.
     this message, keeping the Subject header intact.  Or you can visit this
     web page
     <BLANKLINE>
-        http://mail.example.com/confirm/...
+        http://lists.example.com/confirm/...
     <BLANKLINE>
     If you do not wish to register this email address simply disregard this
     message.  If you think you are being maliciously subscribed to the list,
     or have any other questions, you may contact
     <BLANKLINE>
-        postmaster@mail.example.com
+        postmaster@example.com
     <BLANKLINE>
     >>> dump_msgdata(qdata)
     _parsemsg           : False
@@ -175,7 +167,7 @@ appear in a URL in the body of the message.
 
 The same token will appear in the From header.
 
-    >>> qmsg['from'] == 'confirm-' + token + '@mail.example.com'
+    >>> qmsg['from'] == 'confirm-' + token + '@example.com'
     True
 
 It will also appear in the Subject header.
@@ -207,7 +199,7 @@ IUser linked to this address.  The IAddress is verified.
 
 
 Non-standard registrations
---------------------------
+==========================
 
 If you try to confirm a registration token twice, of course only the first one
 will work.  The second one is ignored.
@@ -254,7 +246,7 @@ registration sends a confirmation.
 
 
 Discarding
-----------
+==========
 
 A confirmation token can also be discarded, say if the user changes his or her
 mind about registering.  When discarded, no IAddress or IUser is created.
@@ -272,7 +264,7 @@ mind about registering.  When discarded, no IAddress or IUser is created.
 
 
 Registering a new address for an existing user
-----------------------------------------------
+==============================================
 
 When a new address for an existing user is registered, there isn't too much
 different except that the new address will still need to be verified before it
@@ -306,7 +298,7 @@ can be used.
 
 
 Corner cases
-------------
+============
 
 If you try to confirm a token that doesn't exist in the pending database, the
 confirm method will just return None.
@@ -332,7 +324,7 @@ pending even matched with that token will still be removed.
 
 
 Registration and subscription
------------------------------
+=============================
 
 Fred registers with Mailman at the same time that he subscribes to a mailing
 list.
@@ -353,9 +345,3 @@ But after confirmation, he is.
     >>> print mlist.members.get_member(u'fred.person@example.com')
     <Member: Fred Person <fred.person@example.com>
              on alpha@example.com as MemberRole.member>
-
-
-Clean up
---------
-
-    >>> config.pop('mail')