apps/api/handlers.py

   1 # -*- coding: utf-8 -*-
   2 # This file is part of Wolnelektury, licensed under GNU Affero GPLv3 or later.
   3 # Copyright © Fundacja Nowoczesna Polska. See NOTICE for more information.
   4
   5 from datetime import datetime, timedelta
   6 import json
   7
   8 from django.conf import settings
   9 from django.contrib.sites.models import Site
  10 from django.core.cache import get_cache
  11 from django.core.urlresolvers import reverse
  12 from piston.handler import AnonymousBaseHandler, BaseHandler
  13 from piston.utils import rc
  14
  15 from api.helpers import timestamp
  16 from api.models import Deleted
  17 from catalogue.forms import BookImportForm
  18 from catalogue.models import Book, Tag, BookMedia, Fragment
  19 from picture.models import Picture
  20 from picture.forms import PictureImportForm
  21
  22 from stats.utils import piwik_track
  23
  24 API_BASE = WL_BASE = MEDIA_BASE = 'http://' + Site.objects.get_current().domain
  25
  26
  27 category_singular = {
  28     'authors': 'author',
  29     'kinds': 'kind',
  30     'genres': 'genre',
  31     'epochs': 'epoch',
  32     'themes': 'theme',
  33     'books': 'book',
  34 }
  35 category_plural={}
  36 for k, v in category_singular.items():
  37     category_plural[v] = k
  38
  39 book_tag_categories = ['author', 'epoch', 'kind', 'genre']
  40
  41
  42
  43 def read_tags(tags, allowed):
  44     """ Reads a path of filtering tags.
  45
  46     :param str tags: a path of category and slug pairs, like: authors/an-author/...
  47     :returns: list of Tag objects
  48     :raises: ValueError when tags can't be found
  49     """
  50     if not tags:
  51         return []
  52
  53     tags = tags.strip('/').split('/')
  54     real_tags = []
  55     while tags:
  56         category = tags.pop(0)
  57         slug = tags.pop(0)
  58
  59         try:
  60             category = category_singular[category]
  61         except KeyError:
  62             raise ValueError('Unknown category.')
  63
  64         if not category in allowed:
  65             raise ValueError('Category not allowed.')
  66
  67         # !^%@#$^#!
  68         if category == 'book':
  69             slug = 'l-' + slug
  70
  71         try:
  72             real_tags.append(Tag.objects.get(category=category, slug=slug))
  73         except Tag.DoesNotExist:
  74             raise ValueError('Tag not found')
  75     return real_tags
  76
  77
  78 # RESTful handlers
  79
  80
  81 class BookMediaHandler(BaseHandler):
  82     """ Responsible for representing media in Books. """
  83
  84     model = BookMedia
  85     fields = ['name', 'type', 'url']
  86
  87     @classmethod
  88     def url(cls, media):
  89         """ Link to media on site. """
  90
  91         return MEDIA_BASE + media.file.url
  92
  93
  94 class BookDetails(object):
  95     """Custom fields used for representing Books."""
  96
  97     @classmethod
  98     def author(cls, book):
  99         return ", ".join(t.name for t in book.tags.filter(category='author'))
 100
 101     @classmethod
 102     def href(cls, book):
 103         """ Returns an URI for a Book in the API. """
 104         return API_BASE + reverse("api_book", args=[book.slug])
 105
 106     @classmethod
 107     def url(cls, book):
 108         """ Returns Book's URL on the site. """
 109
 110         return WL_BASE + book.get_absolute_url()
 111
 112     @classmethod
 113     def children(cls, book):
 114         """ Returns all media for a book. """
 115
 116         return book.children.all()
 117
 118     @classmethod
 119     def media(cls, book):
 120         """ Returns all media for a book. """
 121
 122         return book.media.all()
 123
 124
 125
 126 class BookDetailHandler(BaseHandler, BookDetails):
 127     """ Main handler for Book objects.
 128
 129     Responsible for single Book details.
 130     """
 131     allowed_methods = ['GET']
 132     fields = ['title', 'parent', 'children'] + Book.formats + [
 133         'media', 'url'] + book_tag_categories
 134
 135     @piwik_track
 136     def read(self, request, book):
 137         """ Returns details of a book, identified by a slug and lang. """
 138         try:
 139             return Book.objects.get(slug=book)
 140         except Book.DoesNotExist:
 141             return rc.NOT_FOUND
 142
 143
 144 class AnonymousBooksHandler(AnonymousBaseHandler, BookDetails):
 145     """ Main handler for Book objects.
 146
 147     Responsible for lists of Book objects.
 148     """
 149     allowed_methods = ('GET',)
 150     model = Book
 151     fields = ['author', 'href', 'title', 'url']
 152
 153     @piwik_track
 154     def read(self, request, tags, top_level=False):
 155         """ Lists all books with given tags.
 156
 157         :param tags: filtering tags; should be a path of categories
 158              and slugs, i.e.: authors/an-author/epoch/an-epoch/
 159         :param top_level: if True and a book is included in the results,
 160              it's children are aren't. By default all books matching the tags
 161              are returned.
 162         """
 163         try:
 164             tags = read_tags(tags, allowed=book_tag_categories)
 165         except ValueError:
 166             return rc.NOT_FOUND
 167
 168         if tags:
 169             if top_level:
 170                 books = Book.tagged_top_level(tags)
 171                 return books if books else rc.NOT_FOUND
 172             else:
 173                 books = Book.tagged.with_all(tags)
 174         elif top_level:
 175             books = Book.objects.filter(parent=None)
 176         else:
 177             books = Book.objects.all()
 178
 179         if books.exists():
 180             return books
 181         else:
 182             return rc.NOT_FOUND
 183
 184     def create(self, request, tags, top_level=False):
 185         return rc.FORBIDDEN
 186
 187
 188 class BooksHandler(BookDetailHandler):
 189     model = Book
 190     fields = ['author', 'href', 'title', 'url']
 191     anonymous = AnonymousBooksHandler
 192
 193     def create(self, request, tags, top_level=False):
 194         if not request.user.has_perm('catalogue.add_book'):
 195             return rc.FORBIDDEN
 196
 197         data = json.loads(request.POST.get('data'))
 198         form = BookImportForm(data)
 199         if form.is_valid():
 200             form.save()
 201             return rc.CREATED
 202         else:
 203             return rc.NOT_FOUND
 204
 205
 206 # add categorized tags fields for Book
 207 def _tags_getter(category):
 208     @classmethod
 209     def get_tags(cls, book):
 210         return book.tags.filter(category=category)
 211     return get_tags
 212 for plural, singular in category_singular.items():
 213     setattr(BookDetails, plural, _tags_getter(singular))
 214
 215 # add fields for files in Book
 216 def _file_getter(format):
 217     field = "%s_file" % format
 218     @classmethod
 219     def get_file(cls, book):
 220         f = getattr(book, field)
 221         if f:
 222             return MEDIA_BASE + f.url
 223         else:
 224             return ''
 225     return get_file
 226 for format in Book.formats:
 227     setattr(BookDetails, format, _file_getter(format))
 228
 229
 230 class TagDetails(object):
 231     """Custom Tag fields."""
 232
 233     @classmethod
 234     def href(cls, tag):
 235         """ Returns URI in the API for the tag. """
 236
 237         return API_BASE + reverse("api_tag", args=[category_plural[tag.category], tag.slug])
 238
 239     @classmethod
 240     def url(cls, tag):
 241         """ Returns URL on the site. """
 242
 243         return WL_BASE + tag.get_absolute_url()
 244
 245
 246 class TagDetailHandler(BaseHandler, TagDetails):
 247     """ Responsible for details of a single Tag object. """
 248
 249     fields = ['name', 'url', 'sort_key', 'description']
 250
 251     @piwik_track
 252     def read(self, request, category, slug):
 253         """ Returns details of a tag, identified by category and slug. """
 254
 255         try:
 256             category_sng = category_singular[category]
 257         except KeyError, e:
 258             return rc.NOT_FOUND
 259
 260         try:
 261             return Tag.objects.get(category=category_sng, slug=slug)
 262         except Tag.DoesNotExist:
 263             return rc.NOT_FOUND
 264
 265
 266 class TagsHandler(BaseHandler, TagDetails):
 267     """ Main handler for Tag objects.
 268
 269     Responsible for lists of Tag objects
 270     and fields used for representing Tags.
 271
 272     """
 273     allowed_methods = ('GET',)
 274     model = Tag
 275     fields = ['name', 'href', 'url']
 276
 277     @piwik_track
 278     def read(self, request, category):
 279         """ Lists all tags in the category (eg. all themes). """
 280
 281         try:
 282             category_sng = category_singular[category]
 283         except KeyError, e:
 284             return rc.NOT_FOUND
 285
 286         tags = Tag.objects.filter(category=category_sng).exclude(book_count=0)
 287         if tags.exists():
 288             return tags
 289         else:
 290             return rc.NOT_FOUND
 291
 292
 293 class FragmentDetails(object):
 294     """Custom Fragment fields."""
 295
 296     @classmethod
 297     def href(cls, fragment):
 298         """ Returns URI in the API for the fragment. """
 299
 300         return API_BASE + reverse("api_fragment",
 301             args=[fragment.book.slug, fragment.anchor])
 302
 303     @classmethod
 304     def url(cls, fragment):
 305         """ Returns URL on the site for the fragment. """
 306
 307         return WL_BASE + fragment.get_absolute_url()
 308
 309     @classmethod
 310     def themes(cls, fragment):
 311         """ Returns a list of theme tags for the fragment. """
 312
 313         return fragment.tags.filter(category='theme')
 314
 315
 316 class FragmentDetailHandler(BaseHandler, FragmentDetails):
 317     fields = ['book', 'anchor', 'text', 'url', 'themes']
 318
 319     @piwik_track
 320     def read(self, request, book, anchor):
 321         """ Returns details of a fragment, identified by book slug and anchor. """
 322         try:
 323             return Fragment.objects.get(book__slug=book, anchor=anchor)
 324         except Fragment.DoesNotExist:
 325             return rc.NOT_FOUND
 326
 327
 328 class FragmentsHandler(BaseHandler, FragmentDetails):
 329     """ Main handler for Fragments.
 330
 331     Responsible for lists of Fragment objects
 332     and fields used for representing Fragments.
 333
 334     """
 335     model = Fragment
 336     fields = ['book', 'url', 'anchor', 'href']
 337     allowed_methods = ('GET',)
 338
 339     categories = set(['author', 'epoch', 'kind', 'genre', 'book', 'theme'])
 340
 341     @piwik_track
 342     def read(self, request, tags):
 343         """ Lists all fragments with given book, tags, themes.
 344
 345         :param tags: should be a path of categories and slugs, i.e.:
 346              books/book-slug/authors/an-author/themes/a-theme/
 347
 348         """
 349         try:
 350             tags = read_tags(tags, allowed=self.categories)
 351         except ValueError:
 352             return rc.NOT_FOUND
 353         fragments = Fragment.tagged.with_all(tags).select_related('book')
 354         if fragments.exists():
 355             return fragments
 356         else:
 357             return rc.NOT_FOUND
 358
 359
 360
 361 # Changes handlers
 362
 363 class CatalogueHandler(BaseHandler):
 364
 365     @staticmethod
 366     def fields(request, name):
 367         fields_str = request.GET.get(name) if request is not None else None
 368         return fields_str.split(',') if fields_str is not None else None
 369
 370     @staticmethod
 371     def until(t=None):
 372         """ Returns time suitable for use as upper time boundary for check.
 373
 374             Used to avoid issues with time between setting the change stamp
 375             and actually saving the model in database.
 376             Cuts the microsecond part to avoid issues with DBs where time has
 377             more precision.
 378
 379             :param datetime t: manually sets the upper boundary
 380
 381         """
 382         # set to five minutes ago, to avoid concurrency issues
 383         if t is None:
 384             t = datetime.now() - timedelta(seconds=settings.API_WAIT)
 385         # set to whole second in case DB supports something smaller
 386         return t.replace(microsecond=0)
 387
 388     @staticmethod
 389     def book_dict(book, fields=None):
 390         all_fields = ['url', 'title', 'description',
 391                       'gazeta_link', 'wiki_link',
 392                       ] + Book.formats + BookMedia.formats + [
 393                       'parent', 'parent_number',
 394                       'tags',
 395                       'license', 'license_description', 'source_name',
 396                       'technical_editors', 'editors',
 397                       'author', 'sort_key',
 398                      ]
 399         if fields:
 400             fields = (f for f in fields if f in all_fields)
 401         else:
 402             fields = all_fields
 403
 404         extra_info = book.get_extra_info_value()
 405
 406         obj = {}
 407         for field in fields:
 408
 409             if field in Book.formats:
 410                 f = getattr(book, field+'_file')
 411                 if f:
 412                     obj[field] = {
 413                         'url': f.url,
 414                         'size': f.size,
 415                     }
 416
 417             elif field in BookMedia.formats:
 418                 media = []
 419                 for m in book.media.filter(type=field):
 420                     media.append({
 421                         'url': m.file.url,
 422                         'size': m.file.size,
 423                     })
 424                 if media:
 425                     obj[field] = media
 426
 427             elif field == 'url':
 428                 obj[field] = book.get_absolute_url()
 429
 430             elif field == 'tags':
 431                 obj[field] = [t.id for t in book.tags.exclude(category__in=('book', 'set'))]
 432
 433             elif field == 'author':
 434                 obj[field] = ", ".join(t.name for t in book.tags.filter(category='author'))
 435
 436             elif field == 'parent':
 437                 obj[field] = book.parent_id
 438
 439             elif field in ('license', 'license_description', 'source_name',
 440                       'technical_editors', 'editors'):
 441                 f = extra_info.get(field)
 442                 if f:
 443                     obj[field] = f
 444
 445             else:
 446                 f = getattr(book, field)
 447                 if f:
 448                     obj[field] = f
 449
 450         obj['id'] = book.id
 451         return obj
 452
 453     @classmethod
 454     def book_changes(cls, request=None, since=0, until=None, fields=None):
 455         since = datetime.fromtimestamp(int(since))
 456         until = cls.until(until)
 457
 458         changes = {
 459             'time_checked': timestamp(until)
 460         }
 461
 462         if not fields:
 463             fields = cls.fields(request, 'book_fields')
 464
 465         added = []
 466         updated = []
 467         deleted = []
 468
 469         last_change = since
 470         for book in Book.objects.filter(changed_at__gte=since,
 471                     changed_at__lt=until):
 472             book_d = cls.book_dict(book, fields)
 473             updated.append(book_d)
 474         if updated:
 475             changes['updated'] = updated
 476
 477         for book in Deleted.objects.filter(content_type=Book,
 478                     deleted_at__gte=since,
 479                     deleted_at__lt=until,
 480                     created_at__lt=since):
 481             deleted.append(book.id)
 482         if deleted:
 483             changes['deleted'] = deleted
 484
 485         return changes
 486
 487     @staticmethod
 488     def tag_dict(tag, fields=None):
 489         all_fields = ('name', 'category', 'sort_key', 'description',
 490                       'gazeta_link', 'wiki_link',
 491                       'url', 'books',
 492                      )
 493
 494         if fields:
 495             fields = (f for f in fields if f in all_fields)
 496         else:
 497             fields = all_fields
 498
 499         obj = {}
 500         for field in fields:
 501
 502             if field == 'url':
 503                 obj[field] = tag.get_absolute_url()
 504
 505             elif field == 'books':
 506                 obj[field] = [b.id for b in Book.tagged_top_level([tag])]
 507
 508             elif field == 'sort_key':
 509                 obj[field] = tag.sort_key
 510
 511             else:
 512                 f = getattr(tag, field)
 513                 if f:
 514                     obj[field] = f
 515
 516         obj['id'] = tag.id
 517         return obj
 518
 519     @classmethod
 520     def tag_changes(cls, request=None, since=0, until=None, fields=None, categories=None):
 521         since = datetime.fromtimestamp(int(since))
 522         until = cls.until(until)
 523
 524         changes = {
 525             'time_checked': timestamp(until)
 526         }
 527
 528         if not fields:
 529             fields = cls.fields(request, 'tag_fields')
 530         if not categories:
 531             categories = cls.fields(request, 'tag_categories')
 532
 533         all_categories = ('author', 'epoch', 'kind', 'genre')
 534         if categories:
 535             categories = (c for c in categories if c in all_categories)
 536         else:
 537             categories = all_categories
 538
 539         updated = []
 540         deleted = []
 541
 542         for tag in Tag.objects.filter(category__in=categories,
 543                     changed_at__gte=since,
 544                     changed_at__lt=until):
 545             # only serve non-empty tags
 546             if tag.book_count:
 547                 tag_d = cls.tag_dict(tag, fields)
 548                 updated.append(tag_d)
 549             elif tag.created_at < since:
 550                 deleted.append(tag.id)
 551         if updated:
 552             changes['updated'] = updated
 553
 554         for tag in Deleted.objects.filter(category__in=categories,
 555                 content_type=Tag,
 556                     deleted_at__gte=since,
 557                     deleted_at__lt=until,
 558                     created_at__lt=since):
 559             deleted.append(tag.id)
 560         if deleted:
 561             changes['deleted'] = deleted
 562
 563         return changes
 564
 565     @classmethod
 566     def changes(cls, request=None, since=0, until=None, book_fields=None,
 567                 tag_fields=None, tag_categories=None):
 568         until = cls.until(until)
 569         since = int(since)
 570
 571         if not since:
 572             cache = get_cache('api')
 573             key = hash((book_fields, tag_fields, tag_categories,
 574                     tuple(sorted(request.GET.items()))
 575                   ))
 576             value = cache.get(key)
 577             if value is not None:
 578                 return value
 579
 580         changes = {
 581             'time_checked': timestamp(until)
 582         }
 583
 584         changes_by_type = {
 585             'books': cls.book_changes(request, since, until, book_fields),
 586             'tags': cls.tag_changes(request, since, until, tag_fields, tag_categories),
 587         }
 588
 589         for model in changes_by_type:
 590             for field in changes_by_type[model]:
 591                 if field == 'time_checked':
 592                     continue
 593                 changes.setdefault(field, {})[model] = changes_by_type[model][field]
 594
 595         if not since:
 596             cache.set(key, changes)
 597
 598         return changes
 599
 600
 601 class BookChangesHandler(CatalogueHandler):
 602     allowed_methods = ('GET',)
 603
 604     @piwik_track
 605     def read(self, request, since):
 606         return self.book_changes(request, since)
 607
 608
 609 class TagChangesHandler(CatalogueHandler):
 610     allowed_methods = ('GET',)
 611
 612     @piwik_track
 613     def read(self, request, since):
 614         return self.tag_changes(request, since)
 615
 616
 617 class ChangesHandler(CatalogueHandler):
 618     allowed_methods = ('GET',)
 619
 620     @piwik_track
 621     def read(self, request, since):
 622         return self.changes(request, since)
 623
 624
 625 class PictureHandler(BaseHandler):
 626     model = Picture
 627     fields = ('slug', 'title')
 628     allowed_methods = ('POST',)
 629
 630     def create(self, request):
 631         if not request.user.has_perm('picture.add_picture'):
 632             return rc.FORBIDDEN
 633
 634         data = json.loads(request.POST.get('data'))
 635         form = PictureImportForm(data)
 636         if form.is_valid():
 637             form.save()
 638             return rc.CREATED
 639         else:
 640             return rc.NOT_FOUND