Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update migration docs #866

Merged
merged 7 commits into from
Apr 18, 2018
+79 −72
Merged

Update migration docs #866

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
9946704
Add missing migration doc for Filter.extra
Jan 27, 2018
b140614
Group filterset migration notes
Jan 27, 2018
b0c4bf2
Move migration warnings note to top of document
Jan 27, 2018
647f8b7
Add 2.0 migration description
Jan 27, 2018
0c67097
Inline issue links to migration headers
Jan 27, 2018
c20b4e9
Add issue links for 2.x migration headers
Jan 27, 2018
0bd0738
Remove STRICTNESS settings doc
Jan 27, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
134 changes: 79 additions & 55 deletions docs/guide/migration.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,26 +2,53 @@
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
----------------

Removal of the ``Meta.together`` option
---------------------------------------
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 (`#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.

``Filter.name`` renamed to ``Filter.field_name``
------------------------------------------------

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.

FilterSet strictness has been removed
-------------------------------------
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``
Expand All @@ -31,8 +58,27 @@ 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``
---------------------------------------------------

``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
Expand All @@ -50,33 +96,10 @@ 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
--------------------------------------------------------
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``
Expand Down Expand Up @@ -110,9 +133,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
Expand All @@ -131,9 +154,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
Expand All @@ -156,9 +179,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:
Expand Down Expand Up @@ -186,9 +209,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 <ordering-filter>`. Deprecated options include:
Expand Down Expand Up @@ -221,18 +244,19 @@ 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.

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.
Expand Down
17 changes: 0 additions & 17 deletions docs/ref/settings.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <strict>`. 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