Update docs

Author: moggers87

docs/getting_started.rst

@@ -102,7 +102,7 @@ By deafult, all configuration happens in ``config/``
 ^^^^^^^^^^^
 
 This file is used by Salmon during start-up to configure the daemon with
-various things, such as starting the ``LMTPReceiver``. It's a bit like the
+various things, such as starting the ``AsyncLMTPReceiver``. It's a bit like the
 ``wsgi.py`` file that Python web apps have. If you want to use a different boot
 module, you can specify it with the ``--boot`` argument. E.g. to use
 ``myapp/othermodule.py``, do:
@@ -144,18 +144,18 @@ much in the same way as you host a WSGI application behind Apache or Nginx.
 
 As seen above, a new Salmon project will start a LMTP server that listens on
 ``localhost:8823``. You can go into ``config/settings.py`` and change the host
-and port Salmon uses. You can also switch out ``LMTPReceiver`` for
-``SMTPReceiver`` if you require Salmon to use SMTP instead.
+and port Salmon uses. You can also switch out ``AsyncLMTPReceiver`` for
+``AsyncSMTPReceiver`` if you require Salmon to use SMTP instead.
 
 .. warning::
 
     Due to the way Salmon has been implemented it is better suited as a LMTP
-    server than a SMTP server. ``SMTPReceiver`` is unable to handle multiple
+    server than a SMTP server. ``AsyncSMTPReceiver`` is unable to handle multiple
     recipients in one transaction as it doesn't implement the nessessary
     features to properly implement this part of the SMTP protocol. This is a
-    compromise ``SMTPReceiver`` makes in order to allow users more freedom in
+    compromise ``AsyncSMTPReceiver`` makes in order to allow users more freedom in
     what they do in their handlers.
 
 
-    ``LMTPReceiver`` is unaffected by this issue and implements the LMTP
+    ``AsyncLMTPReceiver`` is unaffected by this issue and implements the LMTP
     protocol fully.

docs/index.rst

@@ -20,6 +20,7 @@ Contents:
     routing
     relaying
     mail_objects
+    receivers
     commandline
     Salmon API guide <salmon>
 

docs/receivers.rst

@@ -0,0 +1,41 @@
+Receivers
+=========
+
+Salmon comes with a number of receivers
+
+Asyncio based receivers
+-----------------------
+
+Salmon's default receivers based on `aiosmtpd <https://github.com/aio-libs/aiosmtpd>`__.
+
+.. note::
+   Although these receivers use Asyncio, your handlers are executed in a
+   separate thread to allow them to use synchronous code that is easier to
+   write and maintain.
+
+:class:`~salmon.server.AsyncLMTPReceiver`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:class:`~salmon.server.AsyncSMTPReceiver`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Asyncore based receivers
+------------------------
+
+Salmon's original receivers based on Python's ``smtpd`` library.
+
+:class:`~salmon.server.LMTPReceiver`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:class:`~salmon.server.SMTPReceiver`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. warning::
+   This receiver is not suitable for use on an Internet facing port. Try
+   `AsyncSMTPReceiver`_ instead.
+
+Other receivers
+---------------
+
+:class:`~salmon.server.QueueReceiver`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

salmon/data/prototype/config/boot.py

@@ -2,7 +2,7 @@
 
 from salmon import queue
 from salmon.routing import Router
-from salmon.server import LMTPReceiver, Relay
+from salmon.server import AsyncLMTPReceiver, Relay
 
 from . import settings
 
@@ -13,8 +13,8 @@
                        port=settings.relay_config['port'], debug=1)
 
 # where to listen for incoming messages
-settings.receiver = LMTPReceiver(settings.receiver_config['host'],
-                                 settings.receiver_config['port'])
+settings.receiver = AsyncLMTPReceiver(hostname=settings.receiver_config['host'],
+                                      port=settings.receiver_config['port'])
 
 Router.defaults(**settings.router_defaults)
 Router.load(settings.handlers)

salmon/server.py

@@ -175,8 +175,6 @@ def _deliver(receiver, Peer, From, To, Data, **kwargs):
 
 
 class SMTPChannel(smtpd.SMTPChannel):
-    """Replaces the standard SMTPChannel with one that rejects more than one recipient"""
-
     def smtp_RCPT(self, arg):
         if self.__rcpttos:
             # We can't properly handle multiple RCPT TOs in SMTPReceiver
@@ -202,7 +200,11 @@ def smtp_RCPT(self, arg):
 
 
 class SMTPReceiver(smtpd.SMTPServer):
-    """Receives emails and hands it to the Router for further processing."""
+    """Receives emails and hands it to the Router for further processing.
+
+
+    This Receiver is based on Python's asyncore module. Consider using AsyncSMTPReceiver.
+    """
 
     def __init__(self, host='127.0.0.1', port=8825):
         """
@@ -245,7 +247,10 @@ def process_message(self, Peer, From, To, Data, **kwargs):
 
 
 class LMTPReceiver(lmtpd.LMTPServer):
-    """Receives emails and hands it to the Router for further processing."""
+    """Receives emails and hands it to the Router for further processing.
+
+    This Receiver is based on Python's asyncore module. Consider using AsyncLMTPReceiver.
+    """
 
     def __init__(self, host='127.0.0.1', port=8824, socket=None):
         """

salmon/utils.py

@@ -94,7 +94,7 @@ def make_fake_settings(host, port):
         logging.basicConfig(filename="logs/logger.log", level=logging.DEBUG)
         routing.Router.load(['salmon.handlers.log', 'salmon.handlers.queue'])
         settings = imp.new_module('settings')
-        settings.receiver = server.SMTPReceiver(host, port)
+        settings.receiver = server.AsyncSMTPReceiver(hostname=host, port=port)
         settings.relay = None
         logging.info("Logging mode enabled, will not send email to anyone, just log.")