Skip to main content

Django-refinery is a reusable Django application for allowing users to filter queryset dynamically.

Project description

Allows users to filter down a queryset based on a model’s fields, similar to the Django admin’s list_filter interface. A FilterTool helper class is provided, which will (by default) map filters to model fields and create a form for queryset manipulation. The helper class supports an interface which will feel familiar to anyone who’s used a Django ModelForm.


Jacob Radford



Example usage

Given a Product model you could create a FilterTool for it with:

import refinery

class ProductFilterTool(refinery.FilterTool):
    class Meta:
        model = Product
        fields = ['name', 'price']

And then in your view you could do:

def product_list(request):
    filtertool = ProductFilterTool(request.GET or None)
    return render_to_response('product/product_list.html',
        {'filtertool': filtertool})

And then in your template:

<form action="" method="get">
    {{ filtertool.form.as_p }}
    <input type="submit" />
  {% for obj in filtertool %}
      <li>{{ }} - ${{ obj.price }}</li>
  {% endfor %}

For more complex usage or custom needs, refer to the project documentation.


  • Python 2.5+

  • Django 1.3+


  • pip install -U django-refinery

  • Add refinery to your INSTALLED_APPS

To install the in-development version of django-refinery, run pip install django-refinery==dev.


See the docs folder or read it on readthedocs for expanded information on:

  • Usage examples

  • Contributing

  • Integration with other apps

  • Project background

  • Low-level API

  • Creating custom filters


If you want to help out with the development of django-refinery, by posting detailed bug reports, proposing new features, or suggesting documentation improvements, use the issue tracker. If you want to fix it yourself, thank you! Fork the project, make changes and send a pull request. Please do create an issue to discuss your plans.


Django-refinery is based on django-filter, an application created by Alex Gaynor. For a complete project history and list of contributors, see the project documentation.


  • Overhaul and expand documentation

  • Overhaul and expand test suite

  • Refactor generic class view (look into pagination of ListView)

  • Allow integration of django-floppyforms

  • Allow integration of django-crispy-forms

  • Allow filters on non-required fields with choices to provide option of filtering the records that are unset. (i.e. FK is null)

  • Allow abstraction of ordering values used to avoid passing internal information in GET params (i.e. user__username)

  • Look into adapting LinkWidget and overall behavior to support filtering like django-easyfilters or maybe drop the widget?


Project details

Release history Release notifications | RSS feed

This version


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django-refinery-0.1.tar.gz (23.0 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page