SQLAlchemy support

HISTORY.rst

@@ -3,6 +3,25 @@
 History
 -------
 
+0.2.0 (2015-09-12)
+~~~~~~~~~~~~~~~~~~
+
+* Added `SQLAlchemy <http://www.sqlalchemy.org/>`_ support.
+* ``FilterSet`` instances have much more useful ``__repr__`` which
+  shows all filters at a glance. For example::
+
+    >>> PlaceFilterSet()
+    PlaceFilterSet()
+      address = Filter(form_field=CharField, lookups=ALL, default_lookup="exact", is_default=False)
+      id = Filter(form_field=IntegerField, lookups=ALL, default_lookup="exact", is_default=True)
+      name = Filter(form_field=CharField, lookups=ALL, default_lookup="exact", is_default=False)
+      restaurant = RestaurantFilterSet()
+        serves_hot_dogs = Filter(form_field=BooleanField, lookups=ALL, default_lookup="exact", is_default=False)
+        serves_pizza = Filter(form_field=BooleanField, lookups=ALL, default_lookup="exact", is_default=False)
+        waiter = WaiterFilterSet()
+          id = Filter(form_field=IntegerField, lookups=ALL, default_lookup="exact", is_default=True)
+          name = Filter(form_field=CharField, lookups=ALL, default_lookup="exact", is_default=False)
+
 0.1.1 (2015-09-06)
 ~~~~~~~~~~~~~~~~~~
 

docs/api/url_filter.backends.base.rst

@@ -0,0 +1,7 @@
+url_filter.backends.base module
+===============================
+
+.. automodule:: url_filter.backends.base
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/api/url_filter.backends.rst

@@ -11,5 +11,7 @@ Submodules
 
 .. toctree::
 
+   url_filter.backends.base
    url_filter.backends.django
+   url_filter.backends.sqlalchemy
 

docs/api/url_filter.backends.sqlalchemy.rst

@@ -0,0 +1,7 @@
+url_filter.backends.sqlalchemy module
+=====================================
+
+.. automodule:: url_filter.backends.sqlalchemy
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/api/url_filter.filtersets.rst

@@ -13,4 +13,5 @@ Submodules
 
    url_filter.filtersets.base
    url_filter.filtersets.django
+   url_filter.filtersets.sqlalchemy
 

docs/api/url_filter.filtersets.sqlalchemy.rst

@@ -0,0 +1,7 @@
+url_filter.filtersets.sqlalchemy module
+=======================================
+
+.. automodule:: url_filter.filtersets.sqlalchemy
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/big_picture.rst

@@ -94,16 +94,16 @@ Filtering
 +++++++++
 
 Since filtering is decoupled from the ``FilterSet``, the filtering honors
-all full on a specified filter backend. The backend is very simple.
+all go to a specified filter backend. The backend is very simple.
 It takes a list of filter specifications and a data to filter and its
 job is to filter that data as specified in the specifications.
 
 .. note::
-  Currently we only support Django ORM filter backend but you can imagine
-  that any backend can be implemented. We plan to add support for SQLAlchemy
-  since, well, why not add it? Eventually filter backends can be added
-  for flat data-structures like filtering a vanilla Python lists or
-  filtering from exotic data-source like Mongo.
+  Currently we only support Django ORM and SQLAlchemy filter backends
+  but you can imagine that any backend can be implemented.
+  Eventually filter backends can be added for flat data-structures
+  like filtering a vanilla Python lists or even more exotic sources
+  like Mongo, Redis, etc.
 
 Steps
 -----

docs/history.rst

@@ -0,0 +1 @@
+.. include:: ../HISTORY.rst

docs/index.rst

@@ -10,6 +10,7 @@ Contents
 
    usage
    big_picture
+   history
    api/modules
 
 .. include:: ../README.rst

docs/usage.rst

@@ -67,6 +67,35 @@ Notable things:
             model = User
             fields = ['username', 'email', 'joined', 'profile']
 
+SQLAlchemy
+----------
+
+`SQLAlchemy <http://www.sqlalchemy.org/>`_ works very similar to how Django
+backend works. For example::
+
+    from django import forms
+    from url_filter.backend.sqlalchemy import SQLAlchemyFilterBackend
+    from url_filter.filtersets.sqlalchemy import SQLAlchemyModelFilterSet
+
+    class UserFilterSet(SQLAlchemyModelFilterSet):
+        filter_backend_class = SQLAlchemyFilterBackend
+
+        class Meta(object):
+            model = User  # this model should be SQLAlchemy model
+            fields = ['username', 'email', 'joined', 'profile']
+
+    fs = UserFilterSet(data=QueryDict(), queryset=session.query(User))
+    fs.filter()
+
+Notable things:
+
+* this works exactly same as ``ModelFitlerSet`` so refer above for some of
+  general options.
+* ``filter_backend_class`` **must** be provided since otherwise
+  ``DjangoFilterBackend`` will be used which will obviously not work
+  with SQLAlchemy models.
+* ``queryset`` given to the queryset should be SQLAlchemy query object.
+
 Integrations
 ------------
 

requirements-dev.txt

@@ -1,6 +1,4 @@
 -r requirements.txt
-Sphinx
-Werkzeug
 coverage
 django-extensions
 djangorestframework
@@ -10,7 +8,10 @@ mock
 pytest
 pytest-cov
 pytest-django
+sphinx
 sphinx-autobuild
 sphinx-rtd-theme
+sqlalchemy
 tox
 watchdog
+werkzeug

test_project/alchemy.py

@@ -0,0 +1,7 @@
+# -*- coding: utf-8 -*-
+from __future__ import absolute_import, print_function, unicode_literals
+
+from sqlalchemy.ext.declarative import declarative_base
+
+
+Base = declarative_base()

test_project/many_to_many/alchemy.py

@@ -0,0 +1,44 @@
+# -*- coding: utf-8 -*-
+from __future__ import absolute_import, print_function, unicode_literals
+
+from sqlalchemy import Column, Integer, String
+from sqlalchemy.orm import backref, relationship
+from sqlalchemy.schema import ForeignKey, Table
+
+from ..alchemy import Base
+
+
+class Publication(Base):
+    __tablename__ = 'many_to_many_publication'
+    id = Column(Integer, primary_key=True)
+    title = Column(String(30))
+
+    @property
+    def pk(self):
+        return self.id
+
+
+publication_article_association_table = Table(
+    'many_to_many_article_publications',
+    Base.metadata,
+    Column('id', Integer),
+    Column('publication_id', Integer, ForeignKey('many_to_many_publication.id')),
+    Column('article_id', Integer, ForeignKey('many_to_many_article.id')),
+)
+
+
+class Article(Base):
+    __tablename__ = 'many_to_many_article'
+    id = Column(Integer, primary_key=True)
+    headline = Column(String(100))
+
+    publications = relationship(
+        Publication,
+        secondary=publication_article_association_table,
+        backref=backref('articles', uselist=True),
+        uselist=True,
+    )
+
+    @property
+    def pk(self):
+        return self.id

test_project/many_to_many/api.py

@@ -2,10 +2,13 @@
 from __future__ import print_function, unicode_literals
 
 from rest_framework.serializers import ModelSerializer
-from rest_framework.viewsets import ModelViewSet
+from rest_framework.viewsets import ReadOnlyModelViewSet
 
+from url_filter.backends.sqlalchemy import SQLAlchemyFilterBackend
 from url_filter.filtersets import ModelFilterSet
+from url_filter.filtersets.sqlalchemy import SQLAlchemyModelFilterSet
 
+from . import alchemy
 from .models import Article, Publication
 
 
@@ -39,18 +42,48 @@ class Meta(object):
         model = Publication
 
 
-class PublicationViewSet(ModelViewSet):
-    queryset = Publication.objects.all()
-    serializer_class = PublicationNestedSerializer
-    filter_class = PublicationFilterSet
+class SQLAlchemyPublicationFilterSet(SQLAlchemyModelFilterSet):
+    filter_backend_class = SQLAlchemyFilterBackend
+
+    class Meta(object):
+        model = alchemy.Publication
 
 
 class ArticleFilterSet(ModelFilterSet):
     class Meta(object):
         model = Article
 
 
-class ArticleViewSet(ModelViewSet):
+class SQLAlchemyArticleFilterSet(SQLAlchemyModelFilterSet):
+    filter_backend_class = SQLAlchemyFilterBackend
+
+    class Meta(object):
+        model = alchemy.Article
+
+
+class PublicationViewSet(ReadOnlyModelViewSet):
+    queryset = Publication.objects.all()
+    serializer_class = PublicationNestedSerializer
+    filter_class = PublicationFilterSet
+
+
+class SQLAlchemyPublicationViewSet(ReadOnlyModelViewSet):
+    serializer_class = PublicationNestedSerializer
+    filter_class = SQLAlchemyPublicationFilterSet
+
+    def get_queryset(self):
+        return self.request.alchemy_session.query(alchemy.Publication)
+
+
+class ArticleViewSet(ReadOnlyModelViewSet):
     queryset = Article.objects.all()
     serializer_class = ArticleNestedSerializer
     filter_class = ArticleFilterSet
+
+
+class SQLAlchemyArticleViewSet(ReadOnlyModelViewSet):
+    serializer_class = ArticleNestedSerializer
+    filter_class = SQLAlchemyArticleFilterSet
+
+    def get_queryset(self):
+        return self.request.alchemy_session.query(alchemy.Article)

test_project/many_to_one/alchemy.py

@@ -0,0 +1,39 @@
+# -*- coding: utf-8 -*-
+from __future__ import absolute_import, print_function, unicode_literals
+
+from sqlalchemy import Column, Date, Integer, String
+from sqlalchemy.orm import backref, relationship
+
+from ..alchemy import Base
+
+
+class Reporter(Base):
+    __tablename__ = 'many_to_one_reporter'
+    id = Column(Integer, primary_key=True)
+    first_name = Column(String(30))
+    last_name = Column(String(30))
+    email = Column(String(254))
+
+    @property
+    def pk(self):
+        return self.id
+
+
+class Article(Base):
+    __tablename__ = 'many_to_one_article'
+    id = Column(Integer, primary_key=True)
+    reporter_id = Column(Integer)
+    headline = Column(String(100))
+    pub_date = Column(Date)
+
+    reporter = relationship(
+        Reporter,
+        backref=backref('articles', uselist=True),
+        uselist=False,
+        primaryjoin='test_project.many_to_one.alchemy.Article.reporter_id == Reporter.id',
+        foreign_keys=reporter_id,
+    )
+
+    @property
+    def pk(self):
+        return self.id

test_project/many_to_one/api.py

@@ -2,10 +2,13 @@
 from __future__ import print_function, unicode_literals
 
 from rest_framework.serializers import ModelSerializer
-from rest_framework.viewsets import ModelViewSet
+from rest_framework.viewsets import ReadOnlyModelViewSet
 
+from url_filter.backends.sqlalchemy import SQLAlchemyFilterBackend
 from url_filter.filtersets import ModelFilterSet
+from url_filter.filtersets.sqlalchemy import SQLAlchemyModelFilterSet
 
+from . import alchemy
 from .models import Article, Reporter
 
 
@@ -39,18 +42,48 @@ class Meta(object):
         model = Reporter
 
 
+class SQLAlchemyReporterFilterSet(SQLAlchemyModelFilterSet):
+    filter_backend_class = SQLAlchemyFilterBackend
+
+    class Meta(object):
+        model = alchemy.Reporter
+
+
 class ArticleFilterSet(ModelFilterSet):
     class Meta(object):
         model = Article
 
 
-class ReporterViewSet(ModelViewSet):
+class SQLAlchemyArticleFilterSet(SQLAlchemyModelFilterSet):
+    filter_backend_class = SQLAlchemyFilterBackend
+
+    class Meta(object):
+        model = alchemy.Article
+
+
+class ReporterViewSet(ReadOnlyModelViewSet):
     queryset = Reporter.objects.all()
     serializer_class = ReporterNestedSerializer
     filter_class = ReporterFilterSet
 
 
-class ArticleViewSet(ModelViewSet):
+class SQLAlchemyReporterViewSet(ReadOnlyModelViewSet):
+    serializer_class = ReporterNestedSerializer
+    filter_class = SQLAlchemyReporterFilterSet
+
+    def get_queryset(self):
+        return self.request.alchemy_session.query(alchemy.Reporter)
+
+
+class ArticleViewSet(ReadOnlyModelViewSet):
     queryset = Article.objects.all()
     serializer_class = ArticleNestedSerializer
     filter_class = ArticleFilterSet
+
+
+class SQLAlchemyArticleViewSet(ReadOnlyModelViewSet):
+    serializer_class = ArticleNestedSerializer
+    filter_class = SQLAlchemyArticleFilterSet
+
+    def get_queryset(self):
+        return self.request.alchemy_session.query(alchemy.Article)

test_project/middleware.py

@@ -0,0 +1,17 @@
+# -*- coding: utf-8 -*-
+from __future__ import print_function, unicode_literals
+
+from django.conf import settings
+from sqlalchemy.orm import sessionmaker
+
+
+Session = sessionmaker(bind=settings.SQLALCHEMY_ENGINE)
+
+
+class SQLAlchemySessionMiddleware(object):
+    def process_request(self, request):
+        request.alchemy_session = Session()
+
+    def process_response(self, request, response):
+        request.alchemy_session.close()
+        return response