Merge pull request carltongibson#554 from rpkilby/docs-changes

Documentation updates

Author: Carlton Gibson

README.rst

@@ -12,9 +12,9 @@ Full documentation on `read the docs`_.
 Requirements
 ------------
 
-* Python 2.7, 3.3, 3.4, 3.5
-* Django 1.8, 1.9, 1.10
-* DRF 3.3 (Django 1.8 only), 3.4
+* **Python**: 2.7, 3.3, 3.4, 3.5
+* **Django**: 1.8, 1.9, 1.10
+* **DRF**: 3.4, 3.5
 
 Installation
 ------------

docs/img/form.png renamed to docs/assets/form.png

@@ -0,0 +1,67 @@
+======================
+Running the Test Suite
+======================
+
+The easiest way to run the django-filter tests is to check out the source
+code and create a virtualenv where you can install the test dependencies.
+Django-filter uses a custom test runner to configure the environment, so a
+wrapper script is available to set up and run the test suite.
+
+.. note::
+
+    The following assumes you have `virtualenv`__ and `git`__ installed.
+
+__ https://virtualenv.pypa.io/en/stable/
+__ https://git-scm.com
+
+Clone the repository
+--------------------
+
+Get the source code using the following command:
+
+.. code-block:: bash
+
+    $ git clone https://github.com/carltongibson/django-filter.git
+
+Switch to the django-filter directory:
+
+.. code-block:: bash
+
+    $ cd django-filter
+
+Set up the virtualenv
+---------------------
+
+Create a new virtualenv to run the test suite in:
+
+.. code-block:: bash
+
+    $ virtualenv venv
+
+Then activate the virtualenv and install the test requirements:
+
+.. code-block:: bash
+
+    $ source venv/bin/activate
+    $ pip install -r requirements/test.txt
+
+Execute the test runner
+-----------------------
+
+Run the tests with the runner script:
+
+.. code-block:: bash
+
+    $ python runtests.py
+
+
+Test all supported versions
+---------------------------
+
+You can also use the excellent tox testing tool to run the tests against all
+supported versions of Python and Django. Install tox, and then simply run:
+
+.. code-block:: bash
+
+    $ pip install tox
+    $ tox

docs/dev/tests.txt

@@ -0,0 +1,33 @@
+============
+Installation
+============
+
+Django-filter can be installed from PyPI with tools like ``pip``:
+
+.. code-block:: bash
+
+    $ pip install django-filter
+
+Then add ``'django_filters'`` to your ``INSTALLED_APPS``.
+
+.. note::
+
+    django-filter provides *some* localization for *some* languages. If you do
+    not need these translations (or would rather provide your own), then it is
+    unnecessary to add django-filter to the ``INSTALLED_APPS`` setting.
+
+
+Requirements
+------------
+
+Django-filter is tested against all supported versions of Python and `Django`__,
+as well as the latest versions of Django REST Framework (`DRF`__).
+
+__ https://www.djangoproject.com/download/
+__ http://www.django-rest-framework.org/
+
+
+
+* **Python**: 2.7, 3.3, 3.4, 3.5
+* **Django**: 1.8, 1.9, 1.10
+* **DRF**: 3.4, 3.5

docs/guide/install.txt

@@ -1,3 +1,4 @@
+================
 Migrating to 1.0
 ================
 

docs/migration.txt renamed to docs/guide/migration.txt

@@ -1,5 +1,6 @@
-Django Rest Framework
-=====================
+====================
+Integration with DRF
+====================
 
 Integration with `Django Rest Framework`__ is provided through a DRF-specific ``FilterSet`` and a `filter backend`__. These may be found in the ``rest_framework`` sub-package.
 
@@ -72,8 +73,8 @@ To enable filtering with a ``FilterSet``, add it to the ``filter_class`` paramet
         filter_class = ProductFilter
 
 
-Specifying ``filter_fields``
-----------------------------
+Using the ``filter_fields`` shortcut
+------------------------------------
 
 You may bypass creating a ``FilterSet`` by instead adding ``filter_fields`` to your view class. This is equivalent to creating a FilterSet with just :ref:`Meta.fields <fields>`.
 
@@ -168,4 +169,4 @@ If you are using DRF's browsable API or admin API you may also want to install `
 
 With crispy forms installed and added to Django's ``INSTALLED_APPS``, the browsable API will present a filtering control for ``DjangoFilterBackend``, like so:
 
-.. image:: img/form.png
+.. image:: ../assets/form.png

docs/rest_framework.txt renamed to docs/guide/rest_framework.txt

@@ -0,0 +1,215 @@
+==================
+Tips and Solutions
+==================
+
+Common problems for declared filters
+------------------------------------
+
+Below are some of the common problem that occur when declaring filters. It is
+recommended that you read this as it provides a more complete understanding of
+how filters work.
+
+
+Filter ``name`` and ``lookup_expr`` not configured
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+While ``name`` and ``lookup_expr`` are optional, it is recommended that you specify
+them. By default, if ``name`` is not specified, the filter's name on the
+filterset class will be used. Additionally, ``lookup_expr`` defaults to
+``exact``. The following is an example of a misconfigured price filter:
+
+.. code-block:: python
+
+    class ProductFilter(django_filters.FilterSet):
+        price__gt = django_filters.NumberFilter()
+
+The filter instance will have a field name of ``price__gt`` and an ``exact``
+lookup type. Under the hood, this will incorrectly be resolved as:
+
+.. code-block:: python
+
+    Produce.objects.filter(price__gt__exact=value)
+
+The above will most likely generate a ``FieldError``. The correct configuration
+would be:
+
+.. code-block:: python
+
+    class ProductFilter(django_filters.FilterSet):
+        price__gt = django_filters.NumberFilter(name='price', lookup_expr='gt')
+
+
+Missing ``lookup_expr`` for text search filters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It's quite common to forget to set the lookup expression for :code:`CharField`
+and :code:`TextField` and wonder why a search for "foo" does not return results
+for "foobar". This is because the default lookup type is ``exact``, but you
+probably want to perform  an ``icontains`` lookup.
+
+
+Filter and lookup expression mismatch (in, range, isnull)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It's not always appropriate to directly match a filter to its model field's
+type, as some lookups expect different types of values. This is a commonly
+found issue with ``in``, ``range``, and ``isnull`` lookups. Let's look
+at the following product model:
+
+.. code-block:: python
+
+    class Product(models.Model):
+        category = models.ForeignKey(Category, null=True)
+
+Given that ``category`` is optional, it's reasonable to want to enable a search
+for uncategorized products. The following is an incorrectly configured
+``isnull`` filter:
+
+.. code-block:: python
+
+    class ProductFilter(django_filters.FilterSet):
+        uncategorized = django_filters.NumberFilter(name='category', lookup_expr='isnull')
+
+So what's the issue? While the underlying column type for ``category`` is an
+integer, ``isnull`` lookups expect a boolean value. A ``NumberFilter`` however
+only validates numbers. Filters are not `'expression aware'` and won't change
+behavior based on their ``lookup_expr``. You should use filters that match the
+data type of the lookup expression `instead` of the data type underlying the
+model field. The following would correctly allow you to search for both
+uncategorized products and products for a set of categories:
+
+.. code-block:: python
+
+    class NumberInFilter(django_filters.BaseInFilter, django_filters.NumberFilter):
+        pass
+
+    class ProductFilter(django_filters.FilterSet):
+        categories = NumberInFilter(name='category', lookup_expr='in')
+        uncategorized = django_filters.BooleanFilter(name='category', lookup_expr='isnull')
+
+More info on constructing ``in`` and ``range`` csv :ref:`filters <base-in-filter>`.
+
+
+Filtering by empty values
+-------------------------
+
+There are a number of cases where you may need to filter by empty or null
+values. The following are some common solutions to these problems:
+
+
+Filtering by null values
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+As explained in the above "Filter and lookup expression mismatch" section, a
+common problem is how to correctly filter by null values on a field.
+
+Solution 1: Using a ``BooleanFilter`` with ``isnull``
+"""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+Using ``BooleanFilter`` with an ``isnull`` lookup is a builtin solution used by
+the FilterSet's automatic filter generation. To do this manually, simply add:
+
+.. code-block:: python
+
+    class ProductFilter(django_filters.FilterSet):
+        uncategorized = django_filters.BooleanFilter(name='category', lookup_expr='isnull')
+
+.. note::
+
+    Remember that the filter class is validating the input value. The underlying
+    type of the mode field is not relevant here.
+
+You may also reverse the logic with the ``exclude`` parameter.
+
+.. code-block:: python
+
+    class ProductFilter(django_filters.FilterSet):
+        has_category = django_filters.BooleanFilter(name='category', lookup_expr='isnull', exclude=True)
+
+Solution 2: Using ``ChoiceFilter``'s null choice
+""""""""""""""""""""""""""""""""""""""""""""""""
+
+If you're using a ChoiceFilter, you may also filter by null values by enabling
+the ``null_label`` parameter. More details in the ``ChoiceFilter`` reference
+:ref:`docs <choice-filter>`.
+
+.. code-block:: python
+
+    class ProductFilter(django_filters.FilterSet):
+        category = django_filters.ModelChoiceFilter(
+            name='category', lookup_expr='isnull',
+            null_label='Uncategorized',
+            queryset=Category.objects.all(),
+        )
+
+Solution 3: Combining fields w/ ``MultiValueField``
+""""""""""""""""""""""""""""""""""""""""""""""""""
+
+An alternative approach is to use Django's ``MultiValueField`` to manually add
+in a ``BooleanField`` to handle null values. Proof of concept:
+https://github.com/carltongibson/django-filter/issues/446
+
+
+Filtering by an empty string
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It's not currently possible to filter by an empty string, since empty values are
+interpreted as a skipped filter.
+
+.. code-block:: http
+
+    GET http://localhost/api/my-model?myfield=
+
+Solution 1: Magic values
+""""""""""""""""""""""""
+
+You can override the ``filter()`` method of a filter class to specifically check
+for magic values. This is similar to the ``ChoiceFilter``'s null value handling.
+
+.. code-block:: http
+
+    GET http://localhost/api/my-model?myfield=EMPTY
+
+.. code-block:: python
+
+    class MyCharFilter(filters.CharFilter):
+        empty_value = 'EMPTY'
+
+        def filter(self, qs, value):
+            if value != self.empty_value:
+                return super(MyCharFilter, self).filter(qs, value)
+
+            qs = self.get_method(qs)(**{'%s__%s' % (self.name, self.lookup_expr): ""})
+            return qs.distinct() if self.distinct else qs
+
+
+Solution 2: Empty string filter
+"""""""""""""""""""""""""""""""
+
+It would also be possible to create an empty value filter that exhibits the same
+behavior as an ``isnull`` filter.
+
+.. code-block:: http
+
+    GET http://localhost/api/my-model?myfield__isempty=false
+
+.. code-block:: python
+
+    from django.core.validators import EMPTY_VALUES
+
+    class EmptyStringFilter(filters.BooleanFilter):
+        def filter(self, qs, value):
+            if value in EMPTY_VALUES:
+                return qs
+
+            exclude = self.exclude ^ (value is False)
+            method = qs.exclude if exclude else qs.filter
+
+            return method(**{self.name: ""})
+
+
+    class MyFilterSet(filters.FilterSet):
+        myfield__isempty = EmptyStringFilter(name='myfield')
+
+        class Meta:
+            model = MyModel