move code to inner directory, another pass at README.

README.md

@@ -1,21 +1,83 @@
-django_ratchet - Django notifier for Ratchet.io
------------------------------------------------
+django_ratchet - Django notifier for [Ratchet.io](http://ratchet.io)
+====================================================================
 
-Configuration:
-Add this to MIDDLEWARE_CLASSES in settings.py:
-    'django_ratchet.middleware.RatchetNotifierMiddleware',
+django_ratchet is a simple middleware for reporting errors from Django apps to [Ratchet.io](http://ratchet.io).
 
-Add the bare minimum ratchet configuration to settings.py:
+
+Requirements
+------------
+django_ratchet requires:
+
+- Python 2.6 or 2.7
+- Django 1.4+
+- requests 0.13.1+
+- a [Ratchet.io](http://ratchet.io) account
+
+
+Installation
+------------
+abcdefg
+
+
+Configuration
+-------------
+Basic configuration requires two changes in your `settings.py`.
+
+1. Add `'django_ratchet.middleware.RatchetNotifierMiddleware'` as the last item in `MIDDLEWARE_CLASSES`:
 
-    RATCHET = {
-        'access_token': '32charactertokengoeshere'
-    }
-
-Additional config variables:
-    endpoint
-    timeout
-    branch
-    environment
-    github.account
-    github.repo
+        MIDDLEWARE_CLASSES = (
+            # ... other middleware classes ...
+            'django_ratchet.middleware.RatchetNotifierMiddleware',
+        )
+
+2. Add the `RATCHET` settings dictionary somewhere in `settings.py`. The bare minimum is:
+
+        RATCHET = {
+            'access_token': '32charactertokengoeshere',
+        }
+
+    Most users will want a few extra settings to take advantage of more features:
+
+        RATCHET = {
+            'access_token': '32charactertokengoeshere',
+            'github.user': 'brianr',
+            'github.repo': 'django_ratchet',
+            'branch': 'master',
+            'root': '/absolute/path/to/code/root',
+        }
+
+Here's the full list of configuration variables:
+
+<dl class="dl-horizontal">
+  <dt>access_token</dt>
+    <dd>Access token from your Ratchet.io project</dd>
+  <dt>endpoint</dt>
+    <dd>URL items are posted to.<br>
+        <b>default:</b> <code>http://submit.ratchet.io/api/item/</code>
+    </dd>
+  <dt>handler</dt>
+    <dd>Currently only one choice, <code>blocking</code>.<br>
+        <b>default:</b> <code>blocking</code>
+    </dd>
+  <dt>timeout</dt>
+    <dd>Request timeout (in seconds) when posting to Ratchet.<br>
+        <b>default:</b> <code>1</code>
+    </dd>
+  <dt>environment</dt>
+    <dd>Environment name; should be <code>production</code>, <code>staging</code>, or <code>development</code><br>
+        <b>default:</b> <code>development</code> if settings.DEBUG is True, <code>production</code> otherwise
+    </dd>
+  <dt>root</dt>
+    <dd>Absolute path to the root of your application, not including the final <code>/</code>. If your manage.py is in <code>/home/brian/www/coolapp/manage.py</code>, then this should be set to <code>/home/brian/www/coolapp</code> . Required for Github integration.</dd>
+  <dt>github.user</dt>
+    <dd>Github username for your github repo. Required for Github integration.</dd>
+  <dt>github.repo</dt>
+    <dd>Github repo name. Required for Github integration.</dd>
+  <dt>branch</dt>
+    <dd>Name of the checked-out branch. Required for Github integration.</dd>
+</dl>
+
 
+Caveats
+-------
+There is currently only one handler, 'blocking', which makes and blocks on an HTTP POST to report each error. More handlers are coming soon (or fork and write your own).

middleware.py → django_ratchet/middleware.py

@@ -1,5 +1,14 @@
 """
-The django-ratchet middleware
+django-ratchet middleware
+
+To install, add the following in your settings.py:
+1. add 'django_ratchet.middleware.RatchetNotifierMiddleware' to MIDDLEWARE_CLASSES 
+2. add a section like this:
+RATCHET = {
+    'access_token': 'tokengoeshere',
+}
+
+See README.md for full installation and configuration instructions.
 """
 
 import json
@@ -19,10 +28,10 @@
 
 
 DEFAULTS = {
-    #'endpoint': 'http://submit.ratchet.io/api/item/',
-    'endpoint': 'http://localhost:6943/api/item/',
+    'endpoint': 'http://submit.ratchet.io/api/item/',
+    'enabled': True,
+    'handler': 'blocking',
     'timeout': 1,
-    'notify_while_debug': False,
     'environment': lambda: 'development' if settings.DEBUG else 'production',
 }
 
@@ -36,20 +45,29 @@ def _extract_user_ip(request):
     if forwarded_for:
         return forwarded_for
     return request.environ['REMOTE_ADDR']
- 
+
 
 class RatchetNotifierMiddleware(object):
     def __init__(self):
         self.settings = getattr(settings, 'RATCHET', {})
         if not self.settings.get('access_token'):
             raise MiddlewareNotUsed
-        
-        if settings.DEBUG and not self._get_setting('notify_while_debug'):
+
+        if not self._get_setting('enabled'):
             raise MiddlewareNotUsed
 
+        # basic settings
         self.endpoint = self._get_setting('endpoint')
         self.timeout = self._get_setting('timeout')
+        self.handler_name = self._get_setting('handler')
+        try:
+            self.handler = getattr(self, '_handler_%s' % self.handler_name)
+        except AttributeError:
+            self.handler_name = DEFAULTS['handler']
+            print "Unknown handler name, defaulting to %s" % self.handler_name
+            self.handler = getattr(self, '_handler_%s' % self.handler_name)
 
+        # cache settings/environment variables that won't change across requests
         self.server_host = socket.gethostname()
         self.server_environment = self._get_setting('environment')
         self.server_branch = self._get_setting('branch')
@@ -115,4 +133,17 @@ def _process_exception(self, request, exc):
 
         payload['params'] = json.dumps(params)
 
-        requests.post(self.endpoint, data=payload, timeout=self.timeout)
+        self.handler(payload)
+
+    def _handler_blocking(self, payload):
+        """
+        Send the payload immediately, and block until the request completes.
+        If self.timeout is nonzero, use it as the timeout (in seconds).
+        """
+        kw = {'data': payload}
+        if self.timeout:
+            kw['timeout'] = self.timeout
+
+        requests.post(self.endpoint, **kw)
+
+