apps/piston/emitters.py

   1 from __future__ import generators
   2
   3 import decimal, re, inspect
   4 import copy
   5
   6 try:
   7     # yaml isn't standard with python.  It shouldn't be required if it
   8     # isn't used.
   9     import yaml
  10 except ImportError:
  11     yaml = None
  12
  13 # Fallback since `any` isn't in Python <2.5
  14 try:
  15     any
  16 except NameError:
  17     def any(iterable):
  18         for element in iterable:
  19             if element:
  20                 return True
  21         return False
  22
  23 from django.db.models.query import QuerySet
  24 from django.db.models import Model, permalink
  25 from django.utils import simplejson
  26 from django.utils.xmlutils import SimplerXMLGenerator
  27 from django.utils.encoding import smart_unicode
  28 from django.core.urlresolvers import reverse, NoReverseMatch
  29 from django.core.serializers.json import DateTimeAwareJSONEncoder
  30 from django.http import HttpResponse
  31 from django.core import serializers
  32
  33 from utils import HttpStatusCode, Mimer
  34
  35 try:
  36     import cStringIO as StringIO
  37 except ImportError:
  38     import StringIO
  39
  40 try:
  41     import cPickle as pickle
  42 except ImportError:
  43     import pickle
  44
  45 # Allow people to change the reverser (default `permalink`).
  46 reverser = permalink
  47
  48 class Emitter(object):
  49     """
  50     Super emitter. All other emitters should subclass
  51     this one. It has the `construct` method which
  52     conveniently returns a serialized `dict`. This is
  53     usually the only method you want to use in your
  54     emitter. See below for examples.
  55
  56     `RESERVED_FIELDS` was introduced when better resource
  57     method detection came, and we accidentially caught these
  58     as the methods on the handler. Issue58 says that's no good.
  59     """
  60     EMITTERS = { }
  61     RESERVED_FIELDS = set([ 'read', 'update', 'create',
  62                             'delete', 'model', 'anonymous',
  63                             'allowed_methods', 'fields', 'exclude' ])
  64
  65     def __init__(self, payload, typemapper, handler, fields=(), anonymous=True):
  66         self.typemapper = typemapper
  67         self.data = payload
  68         self.handler = handler
  69         self.fields = fields
  70         self.anonymous = anonymous
  71
  72         if isinstance(self.data, Exception):
  73             raise
  74
  75     def method_fields(self, handler, fields):
  76         if not handler:
  77             return { }
  78
  79         ret = dict()
  80
  81         for field in fields - Emitter.RESERVED_FIELDS:
  82             t = getattr(handler, str(field), None)
  83
  84             if t and callable(t):
  85                 ret[field] = t
  86
  87         return ret
  88
  89     def construct(self):
  90         """
  91         Recursively serialize a lot of types, and
  92         in cases where it doesn't recognize the type,
  93         it will fall back to Django's `smart_unicode`.
  94
  95         Returns `dict`.
  96         """
  97         def _any(thing, fields=()):
  98             """
  99             Dispatch, all types are routed through here.
 100             """
 101             ret = None
 102
 103             if isinstance(thing, QuerySet):
 104                 ret = _qs(thing, fields=fields)
 105             elif isinstance(thing, (tuple, list)):
 106                 ret = _list(thing)
 107             elif isinstance(thing, dict):
 108                 ret = _dict(thing)
 109             elif isinstance(thing, decimal.Decimal):
 110                 ret = str(thing)
 111             elif isinstance(thing, Model):
 112                 ret = _model(thing, fields=fields)
 113             elif isinstance(thing, HttpResponse):
 114                 raise HttpStatusCode(thing)
 115             elif inspect.isfunction(thing):
 116                 if not inspect.getargspec(thing)[0]:
 117                     ret = _any(thing())
 118             elif hasattr(thing, '__emittable__'):
 119                 f = thing.__emittable__
 120                 if inspect.ismethod(f) and len(inspect.getargspec(f)[0]) == 1:
 121                     ret = _any(f())
 122             elif repr(thing).startswith("<django.db.models.fields.related.RelatedManager"):
 123                 ret = _any(thing.all())
 124             else:
 125                 ret = smart_unicode(thing, strings_only=True)
 126
 127             return ret
 128
 129         def _fk(data, field):
 130             """
 131             Foreign keys.
 132             """
 133             return _any(getattr(data, field.name))
 134
 135         def _related(data, fields=()):
 136             """
 137             Foreign keys.
 138             """
 139             return [ _model(m, fields) for m in data.iterator() ]
 140
 141         def _m2m(data, field, fields=()):
 142             """
 143             Many to many (re-route to `_model`.)
 144             """
 145             return [ _model(m, fields) for m in getattr(data, field.name).iterator() ]
 146
 147         def _model(data, fields=()):
 148             """
 149             Models. Will respect the `fields` and/or
 150             `exclude` on the handler (see `typemapper`.)
 151             """
 152             ret = { }
 153             handler = self.in_typemapper(type(data), self.anonymous)
 154             get_absolute_uri = False
 155
 156             if handler or fields:
 157                 v = lambda f: getattr(data, f.attname)
 158
 159                 if not fields:
 160                     """
 161                     Fields was not specified, try to find teh correct
 162                     version in the typemapper we were sent.
 163                     """
 164                     mapped = self.in_typemapper(type(data), self.anonymous)
 165                     get_fields = set(mapped.fields)
 166                     exclude_fields = set(mapped.exclude).difference(get_fields)
 167
 168                     if 'absolute_uri' in get_fields:
 169                         get_absolute_uri = True
 170
 171                     if not get_fields:
 172                         get_fields = set([ f.attname.replace("_id", "", 1)
 173                             for f in data._meta.fields ])
 174
 175                     # sets can be negated.
 176                     for exclude in exclude_fields:
 177                         if isinstance(exclude, basestring):
 178                             get_fields.discard(exclude)
 179
 180                         elif isinstance(exclude, re._pattern_type):
 181                             for field in get_fields.copy():
 182                                 if exclude.match(field):
 183                                     get_fields.discard(field)
 184
 185                 else:
 186                     get_fields = set(fields)
 187
 188                 met_fields = self.method_fields(handler, get_fields)
 189
 190                 for f in data._meta.local_fields:
 191                     if f.serialize and not any([ p in met_fields for p in [ f.attname, f.name ]]):
 192                         if not f.rel:
 193                             if f.attname in get_fields:
 194                                 ret[f.attname] = _any(v(f))
 195                                 get_fields.remove(f.attname)
 196                         else:
 197                             if f.attname[:-3] in get_fields:
 198                                 ret[f.name] = _fk(data, f)
 199                                 get_fields.remove(f.name)
 200
 201                 for mf in data._meta.many_to_many:
 202                     if mf.serialize and mf.attname not in met_fields:
 203                         if mf.attname in get_fields:
 204                             ret[mf.name] = _m2m(data, mf)
 205                             get_fields.remove(mf.name)
 206
 207                 # try to get the remainder of fields
 208                 for maybe_field in get_fields:
 209                     if isinstance(maybe_field, (list, tuple)):
 210                         model, fields = maybe_field
 211                         inst = getattr(data, model, None)
 212
 213                         if inst:
 214                             if hasattr(inst, 'all'):
 215                                 ret[model] = _related(inst, fields)
 216                             elif callable(inst):
 217                                 if len(inspect.getargspec(inst)[0]) == 1:
 218                                     ret[model] = _any(inst(), fields)
 219                             else:
 220                                 ret[model] = _model(inst, fields)
 221
 222                     elif maybe_field in met_fields:
 223                         # Overriding normal field which has a "resource method"
 224                         # so you can alter the contents of certain fields without
 225                         # using different names.
 226                         ret[maybe_field] = _any(met_fields[maybe_field](data))
 227
 228                     else:
 229                         maybe = getattr(data, maybe_field, None)
 230                         if maybe:
 231                             if callable(maybe):
 232                                 if len(inspect.getargspec(maybe)[0]) == 1:
 233                                     ret[maybe_field] = _any(maybe())
 234                             else:
 235                                 ret[maybe_field] = _any(maybe)
 236                         else:
 237                             handler_f = getattr(handler or self.handler, maybe_field, None)
 238
 239                             if handler_f:
 240                                 ret[maybe_field] = _any(handler_f(data))
 241
 242             else:
 243                 for f in data._meta.fields:
 244                     ret[f.attname] = _any(getattr(data, f.attname))
 245
 246                 fields = dir(data.__class__) + ret.keys()
 247                 add_ons = [k for k in dir(data) if k not in fields]
 248
 249                 for k in add_ons:
 250                     ret[k] = _any(getattr(data, k))
 251
 252             # resouce uri
 253             if self.in_typemapper(type(data), self.anonymous):
 254                 handler = self.in_typemapper(type(data), self.anonymous)
 255                 if hasattr(handler, 'resource_uri'):
 256                     url_id, fields = handler.resource_uri(data)
 257
 258                     try:
 259                         ret['resource_uri'] = reverser( lambda: (url_id, fields) )()
 260                     except NoReverseMatch, e:
 261                         pass
 262
 263             if hasattr(data, 'get_api_url') and 'resource_uri' not in ret:
 264                 try: ret['resource_uri'] = data.get_api_url()
 265                 except: pass
 266
 267             # absolute uri
 268             if hasattr(data, 'get_absolute_url') and get_absolute_uri:
 269                 try: ret['absolute_uri'] = data.get_absolute_url()
 270                 except: pass
 271
 272             return ret
 273
 274         def _qs(data, fields=()):
 275             """
 276             Querysets.
 277             """
 278             return [ _any(v, fields) for v in data ]
 279
 280         def _list(data):
 281             """
 282             Lists.
 283             """
 284             return [ _any(v) for v in data ]
 285
 286         def _dict(data):
 287             """
 288             Dictionaries.
 289             """
 290             return dict([ (k, _any(v)) for k, v in data.iteritems() ])
 291
 292         # Kickstart the seralizin'.
 293         return _any(self.data, self.fields)
 294
 295     def in_typemapper(self, model, anonymous):
 296         for klass, (km, is_anon) in self.typemapper.iteritems():
 297             if model is km and is_anon is anonymous:
 298                 return klass
 299
 300     def render(self):
 301         """
 302         This super emitter does not implement `render`,
 303         this is a job for the specific emitter below.
 304         """
 305         raise NotImplementedError("Please implement render.")
 306
 307     def stream_render(self, request, stream=True):
 308         """
 309         Tells our patched middleware not to look
 310         at the contents, and returns a generator
 311         rather than the buffered string. Should be
 312         more memory friendly for large datasets.
 313         """
 314         yield self.render(request)
 315
 316     @classmethod
 317     def get(cls, format):
 318         """
 319         Gets an emitter, returns the class and a content-type.
 320         """
 321         if cls.EMITTERS.has_key(format):
 322             return cls.EMITTERS.get(format)
 323
 324         raise ValueError("No emitters found for type %s" % format)
 325
 326     @classmethod
 327     def register(cls, name, klass, content_type='text/plain'):
 328         """
 329         Register an emitter.
 330
 331         Parameters::
 332          - `name`: The name of the emitter ('json', 'xml', 'yaml', ...)
 333          - `klass`: The emitter class.
 334          - `content_type`: The content type to serve response as.
 335         """
 336         cls.EMITTERS[name] = (klass, content_type)
 337
 338     @classmethod
 339     def unregister(cls, name):
 340         """
 341         Remove an emitter from the registry. Useful if you don't
 342         want to provide output in one of the built-in emitters.
 343         """
 344         return cls.EMITTERS.pop(name, None)
 345
 346 class XMLEmitter(Emitter):
 347     def _to_xml(self, xml, data):
 348         if isinstance(data, (list, tuple)):
 349             for item in data:
 350                 xml.startElement("resource", {})
 351                 self._to_xml(xml, item)
 352                 xml.endElement("resource")
 353         elif isinstance(data, dict):
 354             for key, value in data.iteritems():
 355                 xml.startElement(key, {})
 356                 self._to_xml(xml, value)
 357                 xml.endElement(key)
 358         else:
 359             xml.characters(smart_unicode(data))
 360
 361     def render(self, request):
 362         stream = StringIO.StringIO()
 363
 364         xml = SimplerXMLGenerator(stream, "utf-8")
 365         xml.startDocument()
 366         xml.startElement("response", {})
 367
 368         self._to_xml(xml, self.construct())
 369
 370         xml.endElement("response")
 371         xml.endDocument()
 372
 373         return stream.getvalue()
 374
 375 Emitter.register('xml', XMLEmitter, 'text/xml; charset=utf-8')
 376 Mimer.register(lambda *a: None, ('text/xml',))
 377
 378 class JSONEmitter(Emitter):
 379     """
 380     JSON emitter, understands timestamps.
 381     """
 382     def render(self, request):
 383         cb = request.GET.get('callback')
 384         seria = simplejson.dumps(self.construct(), cls=DateTimeAwareJSONEncoder, ensure_ascii=False, indent=4)
 385
 386         # Callback
 387         if cb:
 388             return '%s(%s)' % (cb, seria)
 389
 390         return seria
 391
 392 Emitter.register('json', JSONEmitter, 'application/json; charset=utf-8')
 393 Mimer.register(simplejson.loads, ('application/json',))
 394
 395 class YAMLEmitter(Emitter):
 396     """
 397     YAML emitter, uses `safe_dump` to omit the
 398     specific types when outputting to non-Python.
 399     """
 400     def render(self, request):
 401         return yaml.safe_dump(self.construct())
 402
 403 if yaml:  # Only register yaml if it was import successfully.
 404     Emitter.register('yaml', YAMLEmitter, 'application/x-yaml; charset=utf-8')
 405     Mimer.register(lambda s: dict(yaml.load(s)), ('application/x-yaml',))
 406
 407 class PickleEmitter(Emitter):
 408     """
 409     Emitter that returns Python pickled.
 410     """
 411     def render(self, request):
 412         return pickle.dumps(self.construct())
 413
 414 Emitter.register('pickle', PickleEmitter, 'application/python-pickle')
 415
 416 """
 417 WARNING: Accepting arbitrary pickled data is a huge security concern.
 418 The unpickler has been disabled by default now, and if you want to use
 419 it, please be aware of what implications it will have.
 420
 421 Read more: http://nadiana.com/python-pickle-insecure
 422
 423 Uncomment the line below to enable it. You're doing so at your own risk.
 424 """
 425 # Mimer.register(pickle.loads, ('application/python-pickle',))
 426
 427 class DjangoEmitter(Emitter):
 428     """
 429     Emitter for the Django serialized format.
 430     """
 431     def render(self, request, format='xml'):
 432         if isinstance(self.data, HttpResponse):
 433             return self.data
 434         elif isinstance(self.data, (int, str)):
 435             response = self.data
 436         else:
 437             response = serializers.serialize(format, self.data, indent=True)
 438
 439         return response
 440
 441 Emitter.register('django', DjangoEmitter, 'text/xml; charset=utf-8')