skip to navigation
skip to content

Not Logged In

django-url-filter 0.1

Generic Django filter system with easy URL interface. Useful for APIs such as http://django-rest-framework.org/.

Build Status Bitdeli badge

Generic Django filtering system with easy URL interface. Useful for APIs such as Django REST.

Overview

The main goal of Django URL Filter is to provide an easy URL interface for filtering querysets. It allows the user to safely filter by model attributes and also allows to specify the lookup type for each filter (very much like Django's filtering system). For example the following will retrieve all items where the id is 5 and title contains "foo":

GET http://example.com/listview/?id=5&title__contains=foo

In addition to basic lookup types, Django URL Filter allows to use more sophisticated filters such as in or year. For example:

GET http://example.com/listview/?id__in=1,2,3&created__year=2013

Documentation

Documentation can be found at Read The Docs.

Requirements

  • Python (2.6, 2.7 and 3.3)
  • Django 1+ (no specific Django features are used so should even work even on <1.3)

Installing

Since this package is still in development, no stable version has been uploaded to PYPI yet. You can however install it as a developer version:

$ pip install django-url-filter==dev

Example

Using Django URL Filter with Django REST is just a matter of changing the filter backend:

from django.contrib.auth.models import User
from url_filter.backend import URLDjangoFilterBackend

class ListView(generics.ListAPIView):
    model = User
    filter_backends = (URLDjangoFilterBackend,)
    filter_fields = ('id', 'email', 'is_active', 'date_joined')

Assuming the previous view is enabled via /users/ url, the following queries become possible:

GET /users/?id=5                          # id is equal to 5
GET /users/?id__in=1,2,3                  # id either 1, 2 or 3
GET /users/?id__!exact=1                  # id not 1
GET /users/?is_active=true                # active users
GET /users/?is_active__isnull=false       # active state is defined
GET /users/?date_joined__gte=2013-11-06   # joined on or after Nov 11, 2013
                                          # (Django 1.6 release date)
GET /users/?date_joined__range=2013-02-26,2013-11-06
                                          # joined between Feb 26, 2013 and Nov 11, 2013
                                          # (Django 1.5 and 1.6 release dates)

Credits

Current maintainers:

Inspiration libs:

  • django-filters was a strong inspiration for creating this library so huge thanks for all the smart people involved there. I did use it for a while however some features I wanted django-filters to have were either hard to accomplish or required monkey patching (e.g. the URL interface) or were not possible at all due to design constrains of the library. For more details about the differences you can look in the docs.
  • django-rest-framework-chain also served as inspiration. Even though this library enables better URL interface, it still relies on django-filters hence similar constrains apply.

Future

Some of the things on the todo roadmap

  • Relation filters

    Currently the library only works with non-relation model fields which means you can't filter against table joins like Django querysets allow.

License

The source code can be found at Github.

This library is licensed with MIT License:

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.
 
  • Downloads (All Versions):
  • 0 downloads in the last day
  • 0 downloads in the last week
  • 0 downloads in the last month