Eliminate Utils.get_pattern() and in the process, completely revamp

subscription bans so as not to have to rely on BLOBS or pickles in the
database.

Also, be sure to include .rst files in both doctests and in the packaged
tarballs.  With the now awesome reST mode for Emacs, I plan to rename all .txt
doctest files to .rst.

1 files changed, 167 insertions, 0 deletions

diff --git a/src/mailman/app/docs/bans.rst b/src/mailman/app/docs/bans.rst
new file mode 100644
index 000000000..bb6d5902e
--- /dev/null
+++ b/src/mailman/app/docs/bans.rst
@@ -0,0 +1,167 @@
+=======================
+Banning email addresses
+=======================
+
+Email addresses can be banned from ever subscribing, either to a specific
+mailing list or globally within the Mailman system.  Both explicit email
+addresses and email address patterns can be banned.
+
+Bans are managed through the `Ban Manager`.
+
+    >>> from zope.component import getUtility
+    >>> from mailman.interfaces.bans import IBanManager
+    >>> ban_manager = getUtility(IBanManager)
+
+At first, no email addresses are banned, either globally...
+
+    >>> ban_manager.is_banned('anne@example.com')
+    False
+
+...or for a specific mailing list.
+
+    >>> ban_manager.is_banned('bart@example.com', 'test@example.com')
+    False
+
+
+Specific bans
+=============
+
+An email address can be banned from a specific mailing list by adding a ban to
+the ban manager.
+
+    >>> ban_manager.ban('cris@example.com', 'test@example.com')
+    >>> ban_manager.is_banned('cris@example.com', 'test@example.com')
+    True
+    >>> ban_manager.is_banned('bart@example.com', 'test@example.com')
+    False
+
+However, this is not a global ban.
+
+    >>> ban_manager.is_banned('cris@example.com')
+    False
+
+
+Global bans
+===========
+
+An email address can be banned globally, so that it cannot be subscribed to
+any mailing list.
+
+    >>> ban_manager.ban('dave@example.com')
+
+Dave is banned from the test mailing list...
+
+    >>> ban_manager.is_banned('dave@example.com', 'test@example.com')
+    True
+
+...and the sample mailing list.
+
+    >>> ban_manager.is_banned('dave@example.com', 'sample@example.com')
+    True
+
+Dave is also banned globally.
+
+    >>> ban_manager.is_banned('dave@example.com')
+    True
+
+Cris however is not banned globally.
+
+    >>> ban_manager.is_banned('cris@example.com')
+    False
+
+Even though Cris is not banned globally, we can add a global ban for her.
+
+    >>> ban_manager.ban('cris@example.com')
+    >>> ban_manager.is_banned('cris@example.com')
+    True
+
+Cris is obviously still banned from specific mailing lists.
+
+    >>> ban_manager.is_banned('cris@example.com', 'test@example.com')
+    True
+    >>> ban_manager.is_banned('cris@example.com', 'sample@example.com')
+    True
+
+We can remove the global ban to once again just ban her address from the test
+list.
+
+    >>> ban_manager.unban('cris@example.com')
+    >>> ban_manager.is_banned('cris@example.com', 'test@example.com')
+    True
+    >>> ban_manager.is_banned('cris@example.com', 'sample@example.com')
+    False
+
+
+Regular expression bans
+=======================
+
+Entire email address patterns can be banned, both for a specific mailing list
+and globally, just as specific addresses can be banned.  Use this for example,
+when an entire domain is a spam faucet.  When using a pattern, the email
+address must start with a caret (^).
+
+    >>> ban_manager.ban('^.*@example.org', 'test@example.com')
+
+Now, no one from example.org can subscribe to the test list.
+
+    >>> ban_manager.is_banned('elle@example.org', 'test@example.com')
+    True
+    >>> ban_manager.is_banned('eperson@example.org', 'test@example.com')
+    True
+    >>> ban_manager.is_banned('elle@example.com', 'test@example.com')
+    False
+
+They are not, however banned globally.
+
+    >>> ban_manager.is_banned('elle@example.org', 'sample@example.com')
+    False
+    >>> ban_manager.is_banned('elle@example.org')
+    False
+
+Of course, we can ban everyone from example.org globally too.
+
+    >>> ban_manager.ban('^.*@example.org')
+    >>> ban_manager.is_banned('elle@example.org', 'sample@example.com')
+    True
+    >>> ban_manager.is_banned('elle@example.org')
+    True
+
+We can remove the mailing list ban on the pattern, though the global ban will
+still be in place.
+
+    >>> ban_manager.unban('^.*@example.org', 'test@example.com')
+    >>> ban_manager.is_banned('elle@example.org', 'test@example.com')
+    True
+    >>> ban_manager.is_banned('elle@example.org', 'sample@example.com')
+    True
+    >>> ban_manager.is_banned('elle@example.org')
+    True
+
+But once the global ban is removed, everyone from example.org can subscribe to
+the mailing lists.
+
+    >>> ban_manager.unban('^.*@example.org')
+    >>> ban_manager.is_banned('elle@example.org', 'test@example.com')
+    False
+    >>> ban_manager.is_banned('elle@example.org', 'sample@example.com')
+    False
+    >>> ban_manager.is_banned('elle@example.org')
+    False
+
+
+Adding and removing bans
+========================
+
+It is not an error to add a ban more than once.  These are just ignored.
+
+    >>> ban_manager.ban('fred@example.com', 'test@example.com')
+    >>> ban_manager.ban('fred@example.com', 'test@example.com')
+    >>> ban_manager.is_banned('fred@example.com', 'test@example.com')
+    True
+
+Nor is it an error to remove a ban more than once.
+
+    >>> ban_manager.unban('fred@example.com', 'test@example.com')
+    >>> ban_manager.unban('fred@example.com', 'test@example.com')
+    >>> ban_manager.is_banned('fred@example.com', 'test@example.com')
+    False