2 files changed, 75 insertions, 50 deletions

diff --git a/Mailman/docs/nntp.txt b/Mailman/docs/nntp.txt
new file mode 100644
index 000000000..034cb7314
--- /dev/null
+++ b/Mailman/docs/nntp.txt
@@ -0,0 +1,75 @@
+NNTP (i.e. Usenet) Gateway
+==========================
+
+Mailman has an NNTP gateway, whereby messages posted to the mailing list can
+be forwarded onto an NNTP newsgroup.  Typically this means Usenet, but since
+NNTP is to Usenet as IP is to the web, it's more general than that.
+
+    >>> from Mailman.Handlers.ToUsenet import process
+    >>> from Mailman.Message import Message
+    >>> from Mailman.Queue.Switchboard import Switchboard
+    >>> from Mailman.configuration import config
+    >>> from Mailman.database import flush
+    >>> from email import message_from_string
+    >>> mlist = config.list_manager.create('_xtest@example.com')
+    >>> mlist.preferred_language = 'en'
+    >>> flush()
+    >>> switchboard = Switchboard(config.NEWSQUEUE_DIR)
+
+Gatewaying from the mailing list to the newsgroup happens through a separate
+'nntp' queue and happen immediately when the message is posted through to the
+list.  Note that gatewaying from the newsgroup to the list happens via a
+cronjob (currently not shown).  
+
+There are several situations which prevent a message from being gatewayed to
+the newsgroup.  The feature could be disabled, as is the default.
+
+    >>> mlist.gateway_to_news = False
+    >>> flush()
+    >>> msg = message_from_string("""\
+    ... Subject: An important message
+    ...
+    ... Something of great import.
+    ... """, Message)
+    >>> process(mlist, msg, {})
+    >>> switchboard.files
+    []
+
+Even if enabled, messages that came from the newsgroup are never gated back to
+the newsgroup.
+
+    >>> mlist.gateway_to_news = True
+    >>> flush()
+    >>> process(mlist, msg, {'fromusenet': True})
+    >>> switchboard.files
+    []
+
+Neither are digests ever gated to the newsgroup.
+
+    >>> process(mlist, msg, {'isdigest': True})
+    >>> switchboard.files
+    []
+
+However, other posted messages get gated to the newsgroup via the nntp queue.
+The list owner can set the linked newsgroup and the nntp host that its
+messages are gated to.
+
+    >>> mlist.linked_newsgroup = 'comp.lang.thing'
+    >>> mlist.nntp_host = 'news.example.com'
+    >>> flush()
+    >>> process(mlist, msg, {})
+    >>> len(switchboard.files)
+    1
+    >>> filebase = switchboard.files[0]
+    >>> msg, msgdata = switchboard.dequeue(filebase)
+    >>> switchboard.finish(filebase)
+    >>> print msg.as_string()
+    Subject: An important message
+    <BLANKLINE>
+    Something of great import.
+    <BLANKLINE>
+    >>> sorted(msgdata.items())
+    [('_parsemsg', False),
+     ('listname', '_xtest@example.com'),
+     ('received_time', ...),
+     ('version', 3)]
diff --git a/Mailman/testing/test_handlers.py b/Mailman/testing/test_handlers.py
index b2f8da74e..1b1105dd9 100644
--- a/Mailman/testing/test_handlers.py
+++ b/Mailman/testing/test_handlers.py
@@ -45,7 +45,6 @@ from Mailman.Handlers import Scrubber
 from Mailman.Handlers import ToArchive
 from Mailman.Handlers import ToDigest
 from Mailman.Handlers import ToOutgoing
-from Mailman.Handlers import ToUsenet
 
 
 
@@ -431,54 +430,6 @@ It rocks!
 
 
 
-class TestToUsenet(TestBase):
-    def setUp(self):
-        TestBase.setUp(self)
-        # We're going to want to inspect this queue directory
-        self._sb = Switchboard(config.NEWSQUEUE_DIR)
-
-    def tearDown(self):
-        for f in os.listdir(config.NEWSQUEUE_DIR):
-            os.unlink(os.path.join(config.NEWSQUEUE_DIR, f))
-        TestBase.tearDown(self)
-
-    def test_short_circuit(self):
-        eq = self.assertEqual
-        mlist = self._mlist
-        mlist.gateway_to_news = 0
-        ToUsenet.process(mlist, None, {})
-        eq(len(self._sb.files()), 0)
-        mlist.gateway_to_news = 1
-        ToUsenet.process(mlist, None, {'isdigest': 1})
-        eq(len(self._sb.files()), 0)
-        ToUsenet.process(mlist, None, {'fromusenet': 1})
-        eq(len(self._sb.files()), 0)
-
-    def test_to_usenet(self):
-        # BAW: Should we, can we, test the error conditions that only log to a
-        # file instead of raising an exception?
-        eq = self.assertEqual
-        mlist = self._mlist
-        mlist.gateway_to_news = 1
-        mlist.linked_newsgroup = 'foo'
-        mlist.nntp_host = 'bar'
-        msg = email.message_from_string("""\
-Subject: About Mailman
-
-Mailman rocks!
-""")
-        ToUsenet.process(mlist, msg, {})
-        files = self._sb.files()
-        eq(len(files), 1)
-        msg2, data = self._sb.dequeue(files[0])
-        eq(msg.as_string(unixfrom=0), msg2.as_string(unixfrom=0))
-        eq(data['version'], 3)
-        eq(data['listname'], '_xtest@example.com')
-        # Clock skew makes this unreliable
-        #self.failUnless(data['received_time'] <= time.time())
-
-
-
 def test_suite():
     suite = unittest.TestSuite()
     suite.addTest(unittest.makeSuite(TestApprove))
@@ -486,5 +437,4 @@ def test_suite():
     suite.addTest(unittest.makeSuite(TestToArchive))
     suite.addTest(unittest.makeSuite(TestToDigest))
     suite.addTest(unittest.makeSuite(TestToOutgoing))
-    suite.addTest(unittest.makeSuite(TestToUsenet))
     return suite