added Contact.message and Connection.message helpers.

it's a very common request to be able to send a message directly to
a contact. there are already many ways, but this seems cleaner and
more discoverable.

lib/rapidsms/errors.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python
+# vim: ai ts=4 sts=4 et sw=4
+
+
+class MessageSendingError(StandardError):
+    """
+    This exception is raised when an outgoing message cannot be sent.
+    Where possible, a more specific exception should be raised, along
+    with a descriptive message.
+    """
+
+
+class NoRouterError(MessageSendingError):
+    """
+    This exception is raised when no Router is available to send an
+    outgoing message. This usually means that it is being sent from the
+    webui process(es), which is not currently possible in RapidSMS.
+    """
+
+
+class NoConnectionError(MessageSendingError):
+    """
+    This execption is raised when a Contact cannot be messaged because
+    they do not have any Connections.
+    """

lib/rapidsms/messages/outgoing.py

@@ -5,6 +5,7 @@
 from datetime import datetime
 from django.utils.translation.trans_real import translation
 from .base import MessageBase
+from ..errors import NoRouterError
 from ..conf import settings
 
 
@@ -71,12 +72,19 @@ def send(self):
         phase (giving any app the opportunity to modify or cancel it).
         Return True if the message was sent successfully.
 
+        If the router is not running (as is usually the case outside of
+        the ``runrouter`` process), NoRouterError is raised.
+
         Warning: This method blocks the current thread until the backend
         accepts or rejects the message, which takes as long as it takes.
         There is currently no way to send messages asynchronously.
         """
 
         from rapidsms.router import router
+
+        if not router.running:
+            raise NoRouterError()
+
         return router.outgoing(self)
 
 

lib/rapidsms/models.py

@@ -5,6 +5,7 @@
 from datetime import datetime
 from django.db import models
 from .utils.modules import try_import, get_classes
+from .errors import NoConnectionError, MessageSendingError
 from .conf import settings
 
 
@@ -115,6 +116,28 @@ def default_connection(self):
             return self.connection_set.all()[0]
         return None
 
+    def message(self, template, **kwargs):
+        """
+        Attempt to send a message to this contact via their default
+        connection. Like any outgoing message, it may be aborted during
+        the ``outgoing`` phase, or be rejected by the backend. In these
+        cases, MessageSendingError is raised. If no default connection
+        exists, NoConnectionError is raised.
+        """
+
+        if self.default_connection is None:
+            raise NoConnectionError()
+
+        was_sent = self.default_connection.message(
+            template, **kwargs)
+
+        if not was_sent:
+            raise MessageSendingError()
+
+        return True
+
+
+
 class Contact(ContactBase):
     __metaclass__ = ExtensibleModelBase
 
@@ -135,6 +158,28 @@ def __repr__(self):
         return '<%s: %s>' %\
             (type(self).__name__, self)
 
+    def message(self, template, **kwargs):
+        """
+        Attempt to send a message to this connection. Like any outgoing
+        message, it may be aborted during the ``outgoing`` phase, or be
+        rejected by the backend. In these cases, MessageSendingError is
+        raised. (There is currently no way to know *why* the message was
+        not sent, so we raise a generic error.)
+
+        This method can only be called in the ``runrouter`` process,
+        since the router is currently not accessible from the webui
+        process(es). If no router is running, NoRouterError is raised
+        (by the ``OutgoingMessage.send`` method).
+        """
+
+        from .messages.outgoing import OutgoingMessage
+        was_sent = OutgoingMessage(self, template, **kwargs).send()
+
+        if not was_sent:
+            raise MessageSendingError()
+
+        return True
+
 
 class Connection(ConnectionBase):
     """