Rework ordering

[rpkilby]

Hey @carltongibson, I wanted to submit this PR internally to the label improvements branch, due to the growing scope creep of the original PR (label improvements, reworked ordering, deprecations, docs, etc...). Want to keep that PR from becoming un-reviewable. This makes the label improvements branch fully compatible with the existing ordering features, except for get_order_by and get_ordering_field (refactored, no longer invoked).

The objective is to completely deprecate the ordering features on the FilterSet, instead encouraging the use of an explicitly declared ordering filter. In theory, order_by and the refactored get_ordering_filter could be kept, however I think it's better to remove it. The existing behavior of order_by is just not compatible with too many use cases. Maybe the deprecation could become a behavior change to order_by?

Details: In short, this completely reworks ordering into two ordering filters.

• OrderingFilter is the base filter that allows backwards compatibility with the existing feature set.
  • works like a ChoiceFilter and a CSVFilter
  • a fields argument allows users to alias the underlying field names. eg, account => username
• AutoOrderingFilter builds on OrderingFilter to reduce some verbosity.
  • automatically adds descending options to choices
  • can build default choices from the fields map

Changes:

• Add OrderingFilter and AutoOrderingFilter
• Deprecate Meta.order_by and order_by_field.
• Refactor get_ordering_field into get_ordering_filter. While now deprecated, the behavior for Meta.order_by is completely backwards compatible with the caveat that it only works for the Meta.fields list syntax.
• Add assertion error to get_ordering_filter that prevents undefined behavior from occurring when using the Meta.fields dict syntax with Meta.order_by.
• Add assertion errors for get_order_by and get_ordering_field.
• Add deprecation warnings

Notes:

• Deprecations are forwards compatible
• For get_order_by and get_ordering_field, assertions were chosen over deprecation warnings because those changes are forwards incompatible. The best that can be done is to warn the user that the behavior has changed. Otherwise, the behavior would silently change after upgrading, as those methods are no longer invoked.

TODO:

• [ ] wait for 459, which contains the strict and order_by_field moves.
• [ ] docs, generally speaking
• [ ] document deprecations
  • [ ] Meta.order_by deprecation
  • [ ] Ordering methods deprecation (get_order_by, get_ordering_field, etc...)
  • [ ] Document all of the deprecations, including the lack or default ordering
  • [ ] Default qs ordering when no ordering param has been removed. (Not possible to emulate? See removed: test_filterset.FilterSetOrderingTests.test_ordering_when_unbound)

[rpkilby]

Hey @carltongibson - this has been reworked into a separate PR that is not dependent on the label/form improvements. It would be great to get it merged into the 0.15 release, as it also has a number of deprecations.