first working beta

.travis.yml

@@ -0,0 +1,5 @@
+language: python
+python:
+  - 2.7
+install: pip install -q --use-mirrors tox
+script: tox

LICENSE.rst

@@ -0,0 +1,23 @@
+License
+-------
+
+The source code can be found at `Github <https://github.com/miki725/django-rest-framework-bulk>`_.
+
+This library is licensed with `MIT License <http://opensource.org/licenses/MIT>`_::
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights to
+    use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+    the Software, and to permit persons to whom the Software is furnished to do so,
+    subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+    INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+    PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+    HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+    OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+    SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

MANIFEST.in

@@ -0,0 +1,2 @@
+include *.rst
+recursive-include tests *.sh *.py

README.rst

@@ -0,0 +1,139 @@
+Django REST Framework Bulk
+==========================
+
+.. image:: https://badge.fury.io/py/djangorestframework-bulk.png
+   :target: http://badge.fury.io/py/djangorestframework-bulk
+
+.. image:: https://d2weczhvl823v0.cloudfront.net/miki725/django-rest-framework-bulk/trend.png
+   :alt: Bitdeli badge
+   :target: https://bitdeli.com/free
+
+Django REST Framework bulk CRUD view mixins.
+
+Overview
+--------
+
+Django REST Framework comes with many generic views however none
+of them allow to do bulk operations such as create, update and delete.
+To keep the core of Django REST Framework simple, its maintainer
+suggested to create a separate project to allow for bulk operations
+within the framework. That is the purpose of this project.
+
+Requirements
+------------
+
+* Python (2.6, 2.7 and 3.3)
+* Django 1.3+
+* Django REST Framework >= 2.2.5 (when bulk features were added to serializers)
+
+Installing
+----------
+
+Using pip::
+
+    $ pip install djangorestframework-bulk
+
+or from source code::
+
+    $ pip install -r git+http://github.com/miki725/django-rest-framework-bulk#egg=djangorestframework-bulk
+
+Example
+-------
+
+The bulk views (and mixins) are very similar to Django REST Framework's own
+generic views (and mixins)::
+
+    from rest_framework_bulk import ListBulkCreateUpdateDestroyAPIView
+    class FooView(ListBulkCreateUpdateDestroyAPIView):
+        model = FooModel
+
+The above will allow to create the following queries
+
+::
+
+    # list queryset
+    GET
+
+::
+
+    # create single resource
+    POST
+    {"field":"value","field2":"value2"}     <- json object in request data
+
+::
+
+    # create multiple resources
+    POST
+    [{"field":"value","field2":"value2"}]
+
+::
+
+    # update multiple resources (requires all fields)
+    PUT
+    [{"field":"value","field2":"value2"}]   <- json list of objects in data
+
+::
+
+    # partial update multiple resources
+    PATCH
+    [{"field":"value"}]                     <- json list of objects in data
+
+::
+
+    # delete queryset (see notes)
+    DELETE
+
+Notes
+-----
+
+Most API urls have two URL levels for each resource:
+
+1. ``url(r'foo/', ...)``
+2. ``url(r'foo/(?P<pk>\d+)/', ...)``
+
+The second url however is not applicable for bulk operations because
+the url directly maps to a single resource. Therefore all bulk
+generic views only apply to the first url.
+
+There are multiple generic view classes in case only a certail
+bulk functionality is required. For example ``ListBulkCreateAPIView``
+will only do bulk operations for creating resources.
+For a complete list of available generic view classes, please
+take a look at the source code at ``generics.py`` as it is mostly
+self-explanatory.
+
+Most bulk operations are pretty safe in terms of how they operate,
+that is you excplicitly describe all requests. For example, if you
+need to update 3 specific resources, you have to explicitly identify
+those resources in the request's ``PUT`` or ``PATCH`` data.
+The only exception to this is bulk delete. Conside a ``DELETE``
+request to the first url. That can potentially delete all resources
+without any special confirmation. To try to account for this, bulk delete
+mixin allows to implement a hook to determine if the bulk delete
+request should be allowed::
+
+    class FooView(BulkDestroyAPIView):
+        def allow_bulk_destroy(self, qs, filtered):
+            # custom logic here
+
+            # default checks if the qs was filtered
+            # qs comes from self.get_queryset()
+            # filtered comes from self.filter_queryset(qs)
+            return qs is not filtered
+
+By default it checks if the queryset was filtered and if not will not
+allow the bulk delete to complete. The logic here is that if the request
+is filtered to only get certain resources, more attention was payed hence
+the action is less likely to be accidental. On how to filter requests,
+please refer to Django REST
+`docs <http://www.django-rest-framework.org/api-guide/filtering>`_.
+Either way, please use bulk deletes with extreme causion since they
+can be dangerous.
+
+Credits
+-------
+
+Current maintainers:
+
+* Miroslav Shubernetskiy - miroslav@miki725.com
+

requirements.txt

@@ -0,0 +1,6 @@
+coverage
+django
+django-nose
+djangorestframework
+mock
+tox

rest_framework_bulk/__init__.py

@@ -0,0 +1,8 @@
+__version__ = '0.1'
+__author__ = 'Miroslav Shubernetskiy'
+
+try:
+    from .generics import *
+    from .mixins import *
+except Exception:
+    pass

rest_framework_bulk/generics.py

@@ -0,0 +1,116 @@
+from __future__ import unicode_literals, print_function
+from rest_framework import mixins
+from rest_framework.generics import GenericAPIView
+from . import mixins as bulk_mixins
+
+
+##########################################################
+### Concrete view classes that provide method handlers ###
+### by composing the mixin classes with the base view. ###
+##########################################################
+
+class BulkCreateAPIView(bulk_mixins.BulkCreateModelMixin,
+                        GenericAPIView):
+    def post(self, request, *args, **kwargs):
+        return self.create(request, *args, **kwargs)
+
+
+class BulkUpdateAPIView(bulk_mixins.BulkUpdateModelMixin,
+                        GenericAPIView):
+    def put(self, request, *args, **kwargs):
+        return self.bulk_update(request, *args, **kwargs)
+
+    def patch(self, request, *args, **kwargs):
+        return self.partial_bulk_update(request, *args, **kwargs)
+
+
+class BulkDestroyAPIView(bulk_mixins.BulkDestroyModelMixin,
+                         GenericAPIView):
+    def delete(self, request, *args, **kwargs):
+        return self.bulk_destroy(request, *args, **kwargs)
+
+
+class ListBulkCreateAPIView(mixins.ListModelMixin,
+                            bulk_mixins.BulkCreateModelMixin,
+                            GenericAPIView):
+    def get(self, request, *args, **kwargs):
+        return self.list(request, *args, **kwargs)
+
+    def post(self, request, *args, **kwargs):
+        return self.create(request, *args, **kwargs)
+
+
+class ListCreateBulkUpdateAPIView(mixins.ListModelMixin,
+                                  mixins.CreateModelMixin,
+                                  bulk_mixins.BulkUpdateModelMixin,
+                                  GenericAPIView):
+    def get(self, request, *args, **kwargs):
+        return self.list(request, *args, **kwargs)
+
+    def post(self, request, *args, **kwargs):
+        return self.create(request, *args, **kwargs)
+
+    def put(self, request, *args, **kwargs):
+        return self.bulk_update(request, *args, **kwargs)
+
+    def patch(self, request, *args, **kwargs):
+        return self.partial_bulk_update(request, *args, **kwargs)
+
+
+class ListCreateBulkUpdateDestroyAPIView(mixins.ListModelMixin,
+                                         mixins.CreateModelMixin,
+                                         bulk_mixins.BulkUpdateModelMixin,
+                                         bulk_mixins.BulkDestroyModelMixin,
+                                         GenericAPIView):
+    def get(self, request, *args, **kwargs):
+        return self.list(request, *args, **kwargs)
+
+    def post(self, request, *args, **kwargs):
+        return self.create(request, *args, **kwargs)
+
+    def put(self, request, *args, **kwargs):
+        return self.bulk_update(request, *args, **kwargs)
+
+    def patch(self, request, *args, **kwargs):
+        return self.partial_bulk_update(request, *args, **kwargs)
+
+    def delete(self, request, *args, **kwargs):
+        return self.bulk_destroy(request, *args, **kwargs)
+
+
+class ListBulkCreateUpdateAPIView(mixins.ListModelMixin,
+                                  bulk_mixins.BulkCreateModelMixin,
+                                  bulk_mixins.BulkUpdateModelMixin,
+                                  GenericAPIView):
+    def get(self, request, *args, **kwargs):
+        return self.list(request, *args, **kwargs)
+
+    def post(self, request, *args, **kwargs):
+        return self.create(request, *args, **kwargs)
+
+    def put(self, request, *args, **kwargs):
+        return self.bulk_update(request, *args, **kwargs)
+
+    def patch(self, request, *args, **kwargs):
+        return self.partial_bulk_update(request, *args, **kwargs)
+
+
+class ListBulkCreateUpdateDestroyAPIView(mixins.ListModelMixin,
+                                         bulk_mixins.BulkCreateModelMixin,
+                                         bulk_mixins.BulkUpdateModelMixin,
+                                         bulk_mixins.BulkDestroyModelMixin,
+                                         GenericAPIView):
+    def get(self, request, *args, **kwargs):
+        return self.list(request, *args, **kwargs)
+
+    def post(self, request, *args, **kwargs):
+        return self.create(request, *args, **kwargs)
+
+    def put(self, request, *args, **kwargs):
+        return self.bulk_update(request, *args, **kwargs)
+
+    def patch(self, request, *args, **kwargs):
+        return self.partial_bulk_update(request, *args, **kwargs)
+
+    def delete(self, request, *args, **kwargs):
+        return self.bulk_destroy(request, *args, **kwargs)

rest_framework_bulk/mixins.py

@@ -0,0 +1,93 @@
+from __future__ import unicode_literals, print_function
+from django.core.exceptions import ValidationError
+from rest_framework import status
+from rest_framework.mixins import CreateModelMixin
+from rest_framework.response import Response
+
+
+class BulkCreateModelMixin(CreateModelMixin):
+    """
+    Either create a single or many model instances in bulk by using the
+    Serializer's ``many=True`` ability from Django REST >= 2.2.5.
+
+    .. note::
+        This mixin uses the same method to create model instances
+        as ``CreateModelMixin`` because both non-bulk and bulk
+        requests will use ``POST`` request method.
+    """
+
+    def create(self, request, *args, **kwargs):
+        bulk = isinstance(request.DATA, list)
+
+        if not bulk:
+            return super(BulkCreateModelMixin, self).create(request, *args, **kwargs)
+
+        else:
+            serializer = self.get_serializer(data=request.DATA, many=True)
+            if serializer.is_valid():
+                [self.pre_save(obj) for obj in serializer.object]
+                self.object = serializer.save(force_insert=True)
+                [self.post_save(obj) for obj in self.object]
+                return Response(serializer.data, status=status.HTTP_201_CREATED)
+
+        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)
+
+
+class BulkUpdateModelMixin(object):
+    """
+    Update model instances in bulk by using the Serializer's
+    ``many=True`` ability from Django REST >= 2.2.5.
+    """
+
+    def bulk_update(self, request, *args, **kwargs):
+        partial = kwargs.pop('partial', False)
+
+        # restrict the update to the filtered queryset
+        serializer = self.get_serializer(self.filter_queryset(self.get_queryset()),
+                                         data=request.DATA,
+                                         many=True,
+                                         partial=partial)
+
+        if serializer.is_valid():
+            try:
+                self.pre_save(serializer.object)
+            except ValidationError as err:
+                # full_clean on model instances may be called in pre_save
+                # so we have to handle eventual errors.
+                return Response(err.message_dict, status=status.HTTP_400_BAD_REQUEST)
+            self.object = serializer.save(force_update=True)
+            [self.post_save(obj, created=False) for obj in self.object]
+            return Response(serializer.data, status=status.HTTP_200_OK)
+
+        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)
+
+    def partial_bulk_update(self, request, *args, **kwargs):
+        kwargs['partial'] = True
+        return self.bulk_update(request, *args, **kwargs)
+
+
+class BulkDestroyModelMixin(object):
+    """
+    Destroy model instances.
+    """
+
+    def allow_bulk_destroy(self, qs, filtered):
+        """
+        Hook to ensure that the bulk destroy should be allowed.
+
+        By default this checks that the destroy is only applied to
+        filtered querysets.
+        """
+        return qs is not filtered
+
+    def bulk_destroy(self, request, *args, **kwargs):
+        qs = self.get_queryset()
+        filtered = self.filter_queryset(qs)
+        if not self.allow_bulk_destroy(qs, filtered):
+            return Response(status=status.HTTP_400_BAD_REQUEST)
+
+        for obj in filtered:
+            self.pre_delete(obj)
+            obj.delete()
+            self.post_delete(obj)
+        return Response(status=status.HTTP_204_NO_CONTENT)

setup.py

@@ -0,0 +1,65 @@
+"""
+Based on Django REST Framework's ``setup.py``.
+"""
+import os
+from setuptools import setup
+from rest_framework_bulk import __version__, __author__
+
+
+def get_packages(package):
+    """
+    Return root package and all sub-packages.
+    """
+    return [dirpath
+            for dirpath, dirnames, filenames in os.walk(package)
+            if os.path.exists(os.path.join(dirpath, '__init__.py'))]
+
+
+def get_package_data(package):
+    """
+    Return all files under the root package, that are not in a
+    package themselves.
+    """
+    walk = [(dirpath.replace(package + os.sep, '', 1), filenames)
+            for dirpath, dirnames, filenames in os.walk(package)
+            if not os.path.exists(os.path.join(dirpath, '__init__.py'))]
+
+    filepaths = []
+    for base, filenames in walk:
+        filepaths.extend([os.path.join(base, filename)
+                          for filename in filenames])
+    return {package: filepaths}
+
+
+def read(fname):
+    return open(os.path.join(os.path.dirname(__file__), fname)).read()
+
+
+setup(
+    name='djangorestframework-bulk',
+    version=__version__,
+    author=__author__,
+    author_email='miroslav@miki725.com',
+    description='Django REST Framework bulk CRUD view mixins',
+    long_description=read('README.rst') + read('LICENSE.rst'),
+    url='https://github.com/miki725/django-rest-framework-bulk',
+    license='MIT',
+    keywords='django',
+    packages=get_packages('rest_framework_bulk'),
+    data_files=get_package_data('rest_framework_bulk'),
+    install_requires=[
+        'django',
+        'djangorestframework',
+    ],
+    classifiers=[
+        'Development Status :: 3 - Alpha',
+        'Framework :: Django',
+        'Intended Audience :: Developers',
+        'Operating System :: OS Independent',
+        'Programming Language :: Python',
+        'Programming Language :: Python :: 3',
+        'Topic :: Utilities',
+        'Topic :: Internet :: WWW/HTTP',
+        'License :: OSI Approved :: MIT License',
+    ],
+)

tests/manage.py

@@ -0,0 +1,12 @@
+#!/usr/bin/env python
+import os
+import sys
+
+sys.path.append(os.path.abspath(os.path.join(__file__, '..', '..')))
+
+if __name__ == "__main__":
+    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "settings")
+
+    from django.core.management import execute_from_command_line
+
+    execute_from_command_line(sys.argv)

tests/runtests.sh

@@ -0,0 +1,6 @@
+#!/bin/sh
+
+export DJANGO_MANAGE=manage.py
+export args="$@"
+
+python $DJANGO_MANAGE test rest_framework_bulk "$args"

tests/settings.py

@@ -0,0 +1,26 @@
+# Bare ``settings.py`` for running tests for rest_framework_bulk
+
+DEBUG = True
+
+DATABASES = {
+    'default': {
+        'ENGINE': 'django.db.backends.sqlite3',
+        'NAME': 'rest_framework_bulk.sqlite'
+    }
+}
+
+INSTALLED_APPS = (
+    'django_nose',
+    'rest_framework_bulk',
+)
+
+TEST_RUNNER = 'django_nose.NoseTestSuiteRunner'
+NOSE_ARGS = (
+    '--all-modules',
+    '--with-doctest',
+    '--with-coverage',
+    '--cover-package=rest_framework_bulk',
+)
+
+STATIC_URL = '/static/'
+SECRET_KEY = 'foo'

tox.ini

@@ -0,0 +1,26 @@
+[tox]
+envlist =
+    py26, py27, py33, docs
+
+[testenv]
+downloadcache = {toxworkdir}/_download/
+commands =
+    ./runtests.sh
+changedir =
+    {toxinidir}/tests
+deps =
+    coverage
+    django
+    django-nose
+    djangorestframework
+    mock
+    six
+
+[testenv:py26]
+basepython = python2.6
+
+[testenv:py27]
+basepython = python2.7
+
+[testenv:py33]
+basepython = python3.3