apps/piston/resource.py

   1 import sys, inspect
   2
   3 from django.http import (HttpResponse, Http404, HttpResponseNotAllowed,
   4     HttpResponseForbidden, HttpResponseServerError)
   5 from django.views.debug import ExceptionReporter
   6 from django.views.decorators.vary import vary_on_headers
   7 from django.conf import settings
   8 from django.core.mail import send_mail, EmailMessage
   9 from django.db.models.query import QuerySet
  10 from django.http import Http404
  11
  12 from emitters import Emitter
  13 from handler import typemapper
  14 from doc import HandlerMethod
  15 from authentication import NoAuthentication
  16 from utils import coerce_put_post, FormValidationError, HttpStatusCode
  17 from utils import rc, format_error, translate_mime, MimerDataException
  18
  19 CHALLENGE = object()
  20
  21 class Resource(object):
  22     """
  23     Resource. Create one for your URL mappings, just
  24     like you would with Django. Takes one argument,
  25     the handler. The second argument is optional, and
  26     is an authentication handler. If not specified,
  27     `NoAuthentication` will be used by default.
  28     """
  29     callmap = { 'GET': 'read', 'POST': 'create',
  30                 'PUT': 'update', 'DELETE': 'delete' }
  31
  32     def __init__(self, handler, authentication=None):
  33         if not callable(handler):
  34             raise AttributeError, "Handler not callable."
  35
  36         self.handler = handler()
  37
  38         if not authentication:
  39             self.authentication = (NoAuthentication(),)
  40         elif isinstance(authentication, (list, tuple)):
  41             self.authentication = authentication
  42         else:
  43             self.authentication = (authentication,)
  44
  45         # Erroring
  46         self.email_errors = getattr(settings, 'PISTON_EMAIL_ERRORS', True)
  47         self.display_errors = getattr(settings, 'PISTON_DISPLAY_ERRORS', True)
  48         self.stream = getattr(settings, 'PISTON_STREAM_OUTPUT', False)
  49
  50     def determine_emitter(self, request, *args, **kwargs):
  51         """
  52         Function for determening which emitter to use
  53         for output. It lives here so you can easily subclass
  54         `Resource` in order to change how emission is detected.
  55
  56         You could also check for the `Accept` HTTP header here,
  57         since that pretty much makes sense. Refer to `Mimer` for
  58         that as well.
  59         """
  60         em = kwargs.pop('emitter_format', None)
  61
  62         if not em:
  63             em = request.GET.get('format', 'json')
  64
  65         return em
  66
  67     @property
  68     def anonymous(self):
  69         """
  70         Gets the anonymous handler. Also tries to grab a class
  71         if the `anonymous` value is a string, so that we can define
  72         anonymous handlers that aren't defined yet (like, when
  73         you're subclassing your basehandler into an anonymous one.)
  74         """
  75         if hasattr(self.handler, 'anonymous'):
  76             anon = self.handler.anonymous
  77
  78             if callable(anon):
  79                 return anon
  80
  81             for klass in typemapper.keys():
  82                 if anon == klass.__name__:
  83                     return klass
  84
  85         return None
  86
  87     def authenticate(self, request, rm):
  88         actor, anonymous = False, True
  89
  90         for authenticator in self.authentication:
  91             if not authenticator.is_authenticated(request):
  92                 if self.anonymous and \
  93                     rm in self.anonymous.allowed_methods:
  94
  95                     actor, anonymous = self.anonymous(), True
  96                 else:
  97                     actor, anonymous = authenticator.challenge, CHALLENGE
  98             else:
  99                 return self.handler, self.handler.is_anonymous
 100
 101         return actor, anonymous
 102
 103     @vary_on_headers('Authorization')
 104     def __call__(self, request, *args, **kwargs):
 105         """
 106         NB: Sends a `Vary` header so we don't cache requests
 107         that are different (OAuth stuff in `Authorization` header.)
 108         """
 109         rm = request.method.upper()
 110
 111         # Django's internal mechanism doesn't pick up
 112         # PUT request, so we trick it a little here.
 113         if rm == "PUT":
 114             coerce_put_post(request)
 115
 116         actor, anonymous = self.authenticate(request, rm)
 117
 118         if anonymous is CHALLENGE:
 119             return actor()
 120         else:
 121             handler = actor
 122
 123         # Translate nested datastructs into `request.data` here.
 124         if rm in ('POST', 'PUT'):
 125             try:
 126                 translate_mime(request)
 127             except MimerDataException:
 128                 return rc.BAD_REQUEST
 129
 130         if not rm in handler.allowed_methods:
 131             return HttpResponseNotAllowed(handler.allowed_methods)
 132
 133         meth = getattr(handler, self.callmap.get(rm), None)
 134
 135         if not meth:
 136             raise Http404
 137
 138         # Support emitter both through (?P<emitter_format>) and ?format=emitter.
 139         em_format = self.determine_emitter(request, *args, **kwargs)
 140
 141         kwargs.pop('emitter_format', None)
 142
 143         # Clean up the request object a bit, since we might
 144         # very well have `oauth_`-headers in there, and we
 145         # don't want to pass these along to the handler.
 146         request = self.cleanup_request(request)
 147
 148         try:
 149             result = meth(request, *args, **kwargs)
 150         except FormValidationError, e:
 151             resp = rc.BAD_REQUEST
 152             resp.write(' '+str(e.form.errors))
 153
 154             return resp
 155         except TypeError, e:
 156             result = rc.BAD_REQUEST
 157             hm = HandlerMethod(meth)
 158             sig = hm.signature
 159
 160             msg = 'Method signature does not match.\n\n'
 161
 162             if sig:
 163                 msg += 'Signature should be: %s' % sig
 164             else:
 165                 msg += 'Resource does not expect any parameters.'
 166
 167             if self.display_errors:
 168                 msg += '\n\nException was: %s' % str(e)
 169
 170             result.content = format_error(msg)
 171         except Http404:
 172             return rc.NOT_FOUND
 173         except HttpStatusCode, e:
 174             return e.response
 175         except Exception, e:
 176             """
 177             On errors (like code errors), we'd like to be able to
 178             give crash reports to both admins and also the calling
 179             user. There's two setting parameters for this:
 180
 181             Parameters::
 182              - `PISTON_EMAIL_ERRORS`: Will send a Django formatted
 183                error email to people in `settings.ADMINS`.
 184              - `PISTON_DISPLAY_ERRORS`: Will return a simple traceback
 185                to the caller, so he can tell you what error they got.
 186
 187             If `PISTON_DISPLAY_ERRORS` is not enabled, the caller will
 188             receive a basic "500 Internal Server Error" message.
 189             """
 190             exc_type, exc_value, tb = sys.exc_info()
 191             rep = ExceptionReporter(request, exc_type, exc_value, tb.tb_next)
 192             if self.email_errors:
 193                 self.email_exception(rep)
 194             if self.display_errors:
 195                 return HttpResponseServerError(
 196                     format_error('\n'.join(rep.format_exception())))
 197             else:
 198                 raise
 199
 200         emitter, ct = Emitter.get(em_format)
 201         fields = handler.fields
 202         if hasattr(handler, 'list_fields') and (
 203                 isinstance(result, list) or isinstance(result, QuerySet)):
 204             fields = handler.list_fields
 205
 206         srl = emitter(result, typemapper, handler, fields, anonymous)
 207
 208         try:
 209             """
 210             Decide whether or not we want a generator here,
 211             or we just want to buffer up the entire result
 212             before sending it to the client. Won't matter for
 213             smaller datasets, but larger will have an impact.
 214             """
 215             if self.stream: stream = srl.stream_render(request)
 216             else: stream = srl.render(request)
 217
 218             if not isinstance(stream, HttpResponse):
 219                 resp = HttpResponse(stream, mimetype=ct)
 220             else:
 221                 resp = stream
 222
 223             resp.streaming = self.stream
 224
 225             return resp
 226         except HttpStatusCode, e:
 227             return e.response
 228
 229     @staticmethod
 230     def cleanup_request(request):
 231         """
 232         Removes `oauth_` keys from various dicts on the
 233         request object, and returns the sanitized version.
 234         """
 235         for method_type in ('GET', 'PUT', 'POST', 'DELETE'):
 236             block = getattr(request, method_type, { })
 237
 238             if True in [ k.startswith("oauth_") for k in block.keys() ]:
 239                 sanitized = block.copy()
 240
 241                 for k in sanitized.keys():
 242                     if k.startswith("oauth_"):
 243                         sanitized.pop(k)
 244
 245                 setattr(request, method_type, sanitized)
 246
 247         return request
 248
 249     # --
 250
 251     def email_exception(self, reporter):
 252         subject = "Piston crash report"
 253         html = reporter.get_traceback_html()
 254
 255         message = EmailMessage(settings.EMAIL_SUBJECT_PREFIX+subject,
 256                                 html, settings.SERVER_EMAIL,
 257                                 [ admin[1] for admin in settings.ADMINS ])
 258
 259         message.content_subtype = 'html'
 260         message.send(fail_silently=True)