Allow use of an API key instead of the deprecated per-instance login

PopIt is migrating from having a single username / password for each
instance to having site-wide logins for the web interface and API
keys for programmatic use.  This commit introduces support for API
keys, without breaking old code that uses the legacy per-instance login
system.

README.rst

@@ -22,15 +22,22 @@ First, you'll need to get the PopIt binding object. Make sure PopIt as running a
                 hostname='127-0-0-1.org.uk',
                 port=3000,
                 api_version='v0.1',
-                user='test@test.co.uk',
-                password='tJo1zBum')
+                api_key='f093903b7a1aa9688b36241502beadc7')
 
 * ``instance`` Name of the instance you created. There can be more than one for one installation.
 * ``hostname`` The hostname of the PopIt server.
 * ``api_version`` The version of the PopIt API. Since there may be changes in the way you access the data in PopIt you want to have a stable API version. We recommend that you use the latest version, if possible.
 * ``port`` The port that PopIt is listening on. This probably is ``80`` or ``3000``. ``80`` is the default.
-* ``user`` Your username. You will not be able to write anything if you haven't provided your username and password.
-* ``password`` The password for the user.
+* ``api_key`` This is the API key you can request by clicking
+  'Get API key' in the PopIt web interface for your instance, as
+  `described in the documentation <http://popit.poplus.org/docs/api/#authentication>`_.
+
+If you're still using an older PopIt instance and have not upgraded
+your account for the new, more secure authentication system, instead
+of ``api_key`` you can supply ``user`` and ``password``:
+
+* ``user`` Your username, the email address that you created the instance with
+* ``password`` The password you were emailed when creating the instance
 
 …create something?
 ~~~~~~~~~~~~~~~~~~

popit_api.py

@@ -4,6 +4,7 @@
 import slumber
 import logging
 from pprint import pprint
+from requests.auth import AuthBase
 from requests.exceptions import *
 from slumber.exceptions import *
 
@@ -14,6 +15,13 @@
     logging.basicConfig(level = logging.DEBUG, format=FORMAT)
     log.setLevel(logging.DEBUG)
 
+class PopItApiKeyAuth(AuthBase):
+    def __init__(self, api_key):
+        self.api_key = api_key
+    def __call__(self, r):
+        r.headers['Apikey'] = str(self.api_key)
+        return r
+
 class SchemaError(NameError):
     def __init__(self, value):
         self.value = value
@@ -40,7 +48,8 @@ def set_up(self, **args):
             'port': 80,
             'api_version': 'v0.1',
             'user': None,
-            'password': None
+            'password': None,
+            'api_key': None,
         }
         defaults.update(args)
         self.__dict__.update(defaults)
@@ -103,8 +112,12 @@ def __api(self):
 
     def __slumber_api(self):
         url = self.__url()
+        if self.api_key:
+            auth = PopItApiKeyAuth(api_key=self.api_key)
+        else:
+            auth = (self.user, self.password)
         return slumber.API(url,
-                           auth=(self.user, self.password),
+                           auth=auth,
                            append_slash=False)
 
     def __url(self):