<commit_before>===============
Migration Guide
===============

-----------------
Enabling warnings
-----------------

To view deprecations, you may need to enable warnings within python. This
can be achieved with either the ``-W`` `flag`__, or with  ``PYTHONWARNINGS``
`environment variable`__. For example, you could run your test suite like so:

.. code-block:: bash

    $ python -W once manage.py test

The above would print all warnings once when they first occur. This is useful
to know what violations exist in your code (or occasionally in third party
code). However, it only prints the last line of the stack trace. You can use
the following to raise the full exception instead:

.. code-block:: bash

    $ python -W error manage.py test

__ https://docs.python.org/3.6/using/cmdline.html#cmdoption-W
__ https://docs.python.org/3.6/using/cmdline.html#envvar-PYTHONWARNINGS

----------------
Migrating to 2.0
----------------

This release contains several changes that break forwards compatibility. This
includes removed features, renamed attributes and arguments, and some reworked
features. Due to the nature of these changes, it is not feasible to release
a fully forwards-compatible migration release. Please review the below list of
changes and update your code accordingly.


``Filter.lookup_expr`` list form removed (`#851`__)
---------------------------------------------------
__ https://github.com/carltongibson/django-filter/pull/851

The ``Filter.lookup_expr`` argument no longer accepts ``None`` or a list of
expressions. Use the :ref:`LookupChoiceFilter <lookup-choice-filter>` instead.


FilterSet ``filter_for_reverse_field`` removed (`#915`__)
---------------------------------------------------------
__ https://github.com/carltongibson/django-filter/pull/915

The ``filter_for_field`` method now generates filters for reverse relationships,
removing  the need for ``filter_for_reverse_field``. As a result, reverse
relationships now also obey ``Meta.filter_overrides``.


View attributes renamed (`#867`__)
----------------------------------
__ https://github.com/carltongibson/django-filter/pull/867

Several view-related attributes have been renamed to improve consistency with
other parts of the library. The following classes are affected:

* DRF ``ViewSet.filter_class`` => ``filterset_class``
* DRF ``ViewSet.filter_fields`` => ``filterset_fields``
* ``DjangoFilterBackend.default_filter_set`` => ``filterset_base``
* ``DjangoFilterBackend.get_filter_class()`` => ``get_filterset_class()``
* ``FilterMixin.filter_fields`` => ``filterset_fields``


FilterSet ``Meta.together`` option removed (`#791`__)
-----------------------------------------------------
__ https://github.com/carltongibson/django-filter/pull/791

The ``Meta.together`` has been deprecated in favor of userland implementations
that override the ``clean`` method of the ``Meta.form`` class. An example will
be provided in a "recipes" section in future docs.


FilterSet "strictness" handling moved to view (`#788`__)
--------------------------------------------------------
__ https://github.com/carltongibson/django-filter/pull/788

Strictness handling has been removed from the ``FilterSet`` and added to the
view layer. As a result, the ``FILTERS_STRICTNESS`` setting, ``Meta.strict``
option, and ``strict`` argument for the ``FilterSet`` initializer have all
been removed.

To alter strictness behavior, the appropriate view code should be overridden.
More details will be provided in future docs.


``Filter.name`` renamed to ``Filter.field_name`` (`#792`__)
-----------------------------------------------------------
__ https://github.com/carltongibson/django-filter/pull/792

The filter ``name`` has been renamed to ``field_name`` as a way to disambiguate
the filter's attribute name on its FilterSet class from the ``field_name`` used
for filtering purposes.


``Filter.widget`` and ``Filter.required`` removed (`#734`__)
------------------------------------------------------------
__ https://github.com/carltongibson/django-filter/pull/734

The filter class no longer directly stores arguments passed to its form field.
All arguments are located in the filter's ``.extra`` dict.


``MultiWidget`` replaced by ``SuffixedMultiWidget`` (`#770`__)
--------------------------------------------------------------
__ https://github.com/carltongibson/django-filter/pull/770

``RangeWidget``, ``DateRangeWidget``, and ``LookupTypeWidget`` now inherit from
``SuffixedMultiWidget``, changing the suffixes of their query param names. For
example, ``RangeWidget`` now has ``_min`` and ``_max`` suffixes instead of
``_0`` and ``_1``.


----------------
Migrating to 1.0
----------------

The 1.0 release of django-filter introduces several API changes and refinements
that break forwards compatibility. Below is a list of deprecations and
instructions on how to migrate to the 1.0 release. A forwards-compatible 0.15
release has also been created to help with migration. It is compatible with
both the existing and new APIs and will raise warnings for deprecated behavior.


MethodFilter and Filter.action replaced by Filter.method (`#382`__)
-------------------------------------------------------------------
__ https://github.com/carltongibson/django-filter/pull/382

The functionality of ``MethodFilter`` and ``Filter.action`` has been merged
together and replaced by the ``Filter.method`` parameter. The ``method``
parameter takes either a callable or the name of a ``FilterSet`` method. The
signature now takes an additional ``name`` argument that is the name of the
model field to be filtered on.

Since ``method`` is now a parameter of all filters, inputs are validated and
cleaned by its ``field_class``. The function will receive the cleaned value
instead of the raw value.
<commit_msg>Add range filters to Migration Guide (#1038)<commit_after>===============
Migration Guide
===============

-----------------
Enabling warnings
-----------------

To view deprecations, you may need to enable warnings within python. This
can be achieved with either the ``-W`` `flag`__, or with  ``PYTHONWARNINGS``
`environment variable`__. For example, you could run your test suite like so:

.. code-block:: bash

    $ python -W once manage.py test

The above would print all warnings once when they first occur. This is useful
to know what violations exist in your code (or occasionally in third party
code). However, it only prints the last line of the stack trace. You can use
the following to raise the full exception instead:

.. code-block:: bash

    $ python -W error manage.py test

__ https://docs.python.org/3.6/using/cmdline.html#cmdoption-W
__ https://docs.python.org/3.6/using/cmdline.html#envvar-PYTHONWARNINGS

----------------
Migrating to 2.0
----------------

This release contains several changes that break forwards compatibility. This
includes removed features, renamed attributes and arguments, and some reworked
features. Due to the nature of these changes, it is not feasible to release
a fully forwards-compatible migration release. Please review the below list of
changes and update your code accordingly.


``Filter.lookup_expr`` list form removed (`#851`__)
---------------------------------------------------
__ https://github.com/carltongibson/django-filter/pull/851

The ``Filter.lookup_expr`` argument no longer accepts ``None`` or a list of
expressions. Use the :ref:`LookupChoiceFilter <lookup-choice-filter>` instead.


FilterSet ``filter_for_reverse_field`` removed (`#915`__)
---------------------------------------------------------
__ https://github.com/carltongibson/django-filter/pull/915

The ``filter_for_field`` method now generates filters for reverse relationships,
removing  the need for ``filter_for_reverse_field``. As a result, reverse
relationships now also obey ``Meta.filter_overrides``.


View attributes renamed (`#867`__)
----------------------------------
__ https://github.com/carltongibson/django-filter/pull/867

Several view-related attributes have been renamed to improve consistency with
other parts of the library. The following classes are affected:

* DRF ``ViewSet.filter_class`` => ``filterset_class``
* DRF ``ViewSet.filter_fields`` => ``filterset_fields``
* ``DjangoFilterBackend.default_filter_set`` => ``filterset_base``
* ``DjangoFilterBackend.get_filter_class()`` => ``get_filterset_class()``
* ``FilterMixin.filter_fields`` => ``filterset_fields``


FilterSet ``Meta.together`` option removed (`#791`__)
-----------------------------------------------------
__ https://github.com/carltongibson/django-filter/pull/791

The ``Meta.together`` has been deprecated in favor of userland implementations
that override the ``clean`` method of the ``Meta.form`` class. An example will
be provided in a "recipes" section in future docs.


FilterSet "strictness" handling moved to view (`#788`__)
--------------------------------------------------------
__ https://github.com/carltongibson/django-filter/pull/788

Strictness handling has been removed from the ``FilterSet`` and added to the
view layer. As a result, the ``FILTERS_STRICTNESS`` setting, ``Meta.strict``
option, and ``strict`` argument for the ``FilterSet`` initializer have all
been removed.

To alter strictness behavior, the appropriate view code should be overridden.
More details will be provided in future docs.


``Filter.name`` renamed to ``Filter.field_name`` (`#792`__)
-----------------------------------------------------------
__ https://github.com/carltongibson/django-filter/pull/792

The filter ``name`` has been renamed to ``field_name`` as a way to disambiguate
the filter's attribute name on its FilterSet class from the ``field_name`` used
for filtering purposes.


``Filter.widget`` and ``Filter.required`` removed (`#734`__)
------------------------------------------------------------
__ https://github.com/carltongibson/django-filter/pull/734

The filter class no longer directly stores arguments passed to its form field.
All arguments are located in the filter's ``.extra`` dict.


``MultiWidget`` replaced by ``SuffixedMultiWidget`` (`#770`__)
--------------------------------------------------------------
__ https://github.com/carltongibson/django-filter/pull/770

``RangeWidget``, ``DateRangeWidget``, and ``LookupTypeWidget`` now inherit from
``SuffixedMultiWidget``, changing the suffixes of their query param names. For
example, ``RangeWidget`` now has ``_min`` and ``_max`` suffixes instead of
``_0`` and ``_1``.


Filters like ``RangeFilter, DateRangeFilter, DateTimeFromToRangeFilter...`` (`#770`__)
--------------------------------------------------------------------------------------
__ https://github.com/carltongibson/django-filter/pull/770

As they depend on ``MultiWidget``, they need to be adjusted. In 1.0 release
 parameters were provided using ``_0`` and ``_1`` as suffix``. For example,
 a parameter ``creation_date`` using``DateRangeFilter`` will expect
 ``creation_date_after`` and ``creation_date_before`` instead of
 ``creation_date_0`` and ``creation_date_1``.


----------------
Migrating to 1.0
----------------

The 1.0 release of django-filter introduces several API changes and refinements
that break forwards compatibility. Below is a list of deprecations and
instructions on how to migrate to the 1.0 release. A forwards-compatible 0.15
release has also been created to help with migration. It is compatible with
both the existing and new APIs and will raise warnings for deprecated behavior.


MethodFilter and Filter.action replaced by Filter.method (`#382`__)
-------------------------------------------------------------------
__ https://github.com/carltongibson/django-filter/pull/382

The functionality of ``MethodFilter`` and ``Filter.action`` has been merged
together and replaced by the ``Filter.method`` parameter. The ``method``
parameter takes either a callable or the name of a ``FilterSet`` method. The
signature now takes an additional ``name`` argument that is the name of the
model field to be filtered on.

Since ``method`` is now a parameter of all filters, inputs are validated and
cleaned by its ``field_class``. The function will receive the cleaned value
instead of the raw value.

{'fraction_non_alphanumeric': 0.2, 'fraction_numerical': 0.012961443806398687, 'mean_word_length': 2.973598435462842, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 15, 'https://': 23, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '204724', 'n_tokens_mistral': 3228, 'n_tokens_neox': 3013, 'n_words': 1237}