From 99467046a912f2fb48ce17ef03461a93fc2ad69b Mon Sep 17 00:00:00 2001 From: Ryan P Kilby Date: Sat, 27 Jan 2018 02:26:12 -0500 Subject: [PATCH 1/7] Add missing migration doc for Filter.extra --- docs/guide/migration.txt | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/guide/migration.txt b/docs/guide/migration.txt index 1a799696d..bebc890b9 100644 --- a/docs/guide/migration.txt +++ b/docs/guide/migration.txt @@ -20,6 +20,12 @@ 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 +------------------------------------------------- + +The filter class no longer directly stores arguments passed to its form field. +All arguments are located in the filter's ``.extra`` dict. + FilterSet strictness has been removed ------------------------------------- From b140614133eceaf2b899bad75be276a1536584ff Mon Sep 17 00:00:00 2001 From: Ryan P Kilby Date: Sat, 27 Jan 2018 02:32:25 -0500 Subject: [PATCH 2/7] Group filterset migration notes --- docs/guide/migration.txt | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/guide/migration.txt b/docs/guide/migration.txt index bebc890b9..39fc01ca5 100644 --- a/docs/guide/migration.txt +++ b/docs/guide/migration.txt @@ -6,13 +6,24 @@ Migration Guide Migrating to 2.0 ---------------- -Removal of the ``Meta.together`` option ---------------------------------------- +FilterSet ``Meta.together`` option removed +------------------------------------------ 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" secion in future docs. +FilterSet "strictness" handling moved to view +--------------------------------------------- + +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`` ------------------------------------------------ @@ -26,17 +37,6 @@ for filtering purposes. The filter class no longer directly stores arguments passed to its form field. All arguments are located in the filter's ``.extra`` dict. -FilterSet strictness has been removed -------------------------------------- - -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. - ``MultiWidget`` replaced by ``SuffixedMultiWidget`` --------------------------------------------------- From b0c4bf21bdf25270f2a60bac7998edc0c39ccd1f Mon Sep 17 00:00:00 2001 From: Ryan P Kilby Date: Sat, 27 Jan 2018 02:35:50 -0500 Subject: [PATCH 3/7] Move migration warnings note to top of document --- docs/guide/migration.txt | 47 ++++++++++++++++++++-------------------- 1 file changed, 24 insertions(+), 23 deletions(-) diff --git a/docs/guide/migration.txt b/docs/guide/migration.txt index 39fc01ca5..3475b035b 100644 --- a/docs/guide/migration.txt +++ b/docs/guide/migration.txt @@ -2,6 +2,30 @@ 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 ---------------- @@ -56,29 +80,6 @@ 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. -Enabling warnings ------------------ - -To view the 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 - MethodFilter and Filter.action replaced by Filter.method -------------------------------------------------------- From 647f8b7946e414f0c571b69e6de0a54a5b61d008 Mon Sep 17 00:00:00 2001 From: Ryan P Kilby Date: Sat, 27 Jan 2018 04:08:41 -0500 Subject: [PATCH 4/7] Add 2.0 migration description --- docs/guide/migration.txt | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/guide/migration.txt b/docs/guide/migration.txt index 3475b035b..1466591e4 100644 --- a/docs/guide/migration.txt +++ b/docs/guide/migration.txt @@ -30,6 +30,13 @@ __ 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 forards-compatible migration release. Please review the below list of +changes and update your code accordingly. + + FilterSet ``Meta.together`` option removed ------------------------------------------ From 0c6709750a73909419c3f6f86d213239f12b7b56 Mon Sep 17 00:00:00 2001 From: Ryan P Kilby Date: Sat, 27 Jan 2018 04:18:18 -0500 Subject: [PATCH 5/7] Inline issue links to migration headers --- docs/guide/migration.txt | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/guide/migration.txt b/docs/guide/migration.txt index 1466591e4..c7e86d81a 100644 --- a/docs/guide/migration.txt +++ b/docs/guide/migration.txt @@ -88,9 +88,9 @@ 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 --------------------------------------------------------- -Details: https://github.com/carltongibson/django-filter/pull/382 +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`` @@ -124,9 +124,9 @@ instead of the raw value. return qs.filter(**{name: value}) -QuerySet methods are no longer proxied --------------------------------------- -Details: https://github.com/carltongibson/django-filter/pull/440 +QuerySet methods are no longer proxied (`#440`__) +------------------------------------------------- +__ https://github.com/carltongibson/django-filter/pull/440 The ``__iter__()``, ``__len__()``, ``__getitem__()``, ``count()`` methods are no longer proxied from the queryset. To fix this, call the methods on the @@ -145,9 +145,9 @@ no longer proxied from the queryset. To fix this, call the methods on the ... -Filters no longer autogenerated when Meta.fields is not specified ------------------------------------------------------------------ -Details: https://github.com/carltongibson/django-filter/pull/450 +Filters no longer autogenerated when Meta.fields is not specified (`#450`__) +---------------------------------------------------------------------------- +__ https://github.com/carltongibson/django-filter/pull/450 FilterSets had an undocumented behavior of autogenerating filters for all model fields when either ``Meta.fields`` was not specified or when set to @@ -170,9 +170,9 @@ the ``Meta.exclude`` attribute. exclude = ['password'] -Move FilterSet options to Meta class ------------------------------------- -Details: https://github.com/carltongibson/django-filter/issues/430 +Move FilterSet options to Meta class (`#430`__) +----------------------------------------------- +__ https://github.com/carltongibson/django-filter/issues/430 Several ``FilterSet`` options have been moved to the ``Meta`` class to prevent potential conflicts with declared filter names. This includes: @@ -200,9 +200,9 @@ potential conflicts with declared filter names. This includes: order_by_field = 'order' -FilterSet ordering replaced by OrderingFilter ---------------------------------------------- -Details: https://github.com/carltongibson/django-filter/pull/472 +FilterSet ordering replaced by OrderingFilter (`#472`__) +-------------------------------------------------------- +__ https://github.com/carltongibson/django-filter/pull/472 The FilterSet ordering options and methods have been deprecated and replaced by :ref:`OrderingFilter `. Deprecated options include: @@ -235,9 +235,9 @@ To fix this, simply remove the methods from your class. You can subclass ``OrderingFilter`` to migrate any custom logic. -Deprecated ``FILTERS_HELP_TEXT_FILTER`` and ``FILTERS_HELP_TEXT_EXCLUDE`` -------------------------------------------------------------------------- -Details: https://github.com/carltongibson/django-filter/pull/437 +Deprecated ``FILTERS_HELP_TEXT_FILTER`` and ``FILTERS_HELP_TEXT_EXCLUDE`` (`#437`__) +------------------------------------------------------------------------------------ +__ https://github.com/carltongibson/django-filter/pull/437 Generated filter labels in 1.0 will be more descriptive, including humanized text about the lookup being performed and if the filter is an exclusion filter. From c20b4e9c98afedd02ca19725aa94fdde35705718 Mon Sep 17 00:00:00 2001 From: Ryan P Kilby Date: Sat, 27 Jan 2018 05:24:56 -0500 Subject: [PATCH 6/7] Add issue links for 2.x migration headers --- docs/guide/migration.txt | 34 ++++++++++++++++++++++------------ 1 file changed, 22 insertions(+), 12 deletions(-) diff --git a/docs/guide/migration.txt b/docs/guide/migration.txt index c7e86d81a..bee013b9c 100644 --- a/docs/guide/migration.txt +++ b/docs/guide/migration.txt @@ -37,15 +37,18 @@ a fully forards-compatible migration release. Please review the below list of changes and update your code accordingly. -FilterSet ``Meta.together`` option removed ------------------------------------------- +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" secion in future docs. -FilterSet "strictness" handling moved to view ---------------------------------------------- + +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`` @@ -55,21 +58,27 @@ 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`` ------------------------------------------------- + +``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 -------------------------------------------------- + +``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`` ---------------------------------------------------- + +``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 @@ -245,8 +254,9 @@ text about the lookup being performed and if the filter is an exclusion filter. These settings will no longer have an effect and will be removed in the 1.0 release. -DRF filter backend raises ``TemplateDoesNotExist`` exception ------------------------------------------------------------- +DRF filter backend raises ``TemplateDoesNotExist`` exception (`#562`__) +----------------------------------------------------------------------- +__ https://github.com/carltongibson/django-filter/issues/562 Templates are now provided by django-filter. If you are receiving this error, you may need to add ``'django_filters'`` to your ``INSTALLED_APPS`` setting. From 0bd07383dd5d06b7001a504280f82c87d7ff3b63 Mon Sep 17 00:00:00 2001 From: Ryan P Kilby Date: Sat, 27 Jan 2018 05:25:28 -0500 Subject: [PATCH 7/7] Remove STRICTNESS settings doc --- docs/ref/settings.txt | 17 ----------------- 1 file changed, 17 deletions(-) diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index 8bf68634d..856b35739 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -87,20 +87,3 @@ For example, you could add verbose output for "exact" lookups. 'exact': 'is equal to', }) return verbose_lookups - - -FILTERS_STRICTNESS ------------------- - -Default: ``STRICTNESS.RETURN_NO_RESULTS`` - -Set the global default for FilterSet :ref:`strictness `. If ``strict`` is not -provided to the filterset, it will default to this setting. You can change the setting -like so: - -.. code-block:: python - - # settings.py - from django_filters import STRICTNESS - - FILTERS_STRICTNESS = STRICTNESS.RETURN_NO_RESULTS