From 4b26a080cec0b6636aa38749a5733737134ef723 Mon Sep 17 00:00:00 2001 From: Oliver Sauder Date: Thu, 3 Oct 2019 15:37:46 +0400 Subject: [PATCH] Use extra requires to separate optional features Fixes #674 Currently only django-filter and django-polymorphic use the extra_requires definition. --- CHANGELOG.md | 9 +++++++++ README.rst | 3 +++ docs/getting-started.md | 3 +++ docs/usage.md | 31 +++++++++++++++++-------------- setup.py | 4 ++++ 5 files changed, 36 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4ac200cd..3e967fc7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,15 @@ This release is not backwards compatible. For easy migration best upgrade first * Add support for Django REST framework 3.10. * Add code from ErrorDetail into the JSON:API error object +### Changed + +* Moved dependency definition for `django-polymorphic` and `django-filter` into extra requires. + Hence dependencies of each optional module can be installed with pip using + ``` + pip install djangorestframework-jsonapi['django-polymorphic'] + pip install djangorestframework-jsonapi['django-filter']` + ``` + ### Removed * Removed support for Python 2.7 and 3.4. diff --git a/README.rst b/README.rst index 4f3d8aaa..2a53723c 100644 --- a/README.rst +++ b/README.rst @@ -101,6 +101,9 @@ From PyPI :: $ pip install djangorestframework-jsonapi + $ # for optional package integrations + $ pip install djangorestframework-jsonapi['django-filter'] + $ pip install djangorestframework-jsonapi['django-polymorphic'] From Source diff --git a/docs/getting-started.md b/docs/getting-started.md index 93096d79..d89eb248 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -60,6 +60,9 @@ like the following: From PyPI pip install djangorestframework-jsonapi + # for optional package integrations + pip install djangorestframework-jsonapi['django-filter'] + pip install djangorestframework-jsonapi['django-polymorphic'] From Source diff --git a/docs/usage.md b/docs/usage.md index a655687a..fc8e2895 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -4,7 +4,7 @@ The DJA package implements a custom renderer, parser, exception handler, query filter backends, and pagination. To get started enable the pieces in `settings.py` that you want to use. -Many features of the [JSON:API](http://jsonapi.org/format) format standard have been implemented using +Many features of the [JSON:API](http://jsonapi.org/format) format standard have been implemented using Mixin classes in `serializers.py`. The easiest way to make use of those features is to import ModelSerializer variants from `rest_framework_json_api` instead of the usual `rest_framework` @@ -108,7 +108,8 @@ class MyLimitPagination(JsonApiLimitOffsetPagination): Following are descriptions of JSON:API-specific filter backends and documentation on suggested usage for a standard DRF keyword-search filter backend that makes it consistent with JSON:API. -#### `QueryParameterValidationFilter` +#### QueryParameterValidationFilter + `QueryParameterValidationFilter` validates query parameters to be one of the defined JSON:API query parameters (sort, include, filter, fields, page) and returns a `400 Bad Request` if a non-matching query parameter is used. This can help the client identify misspelled query parameters, for example. @@ -131,7 +132,8 @@ class MyQPValidator(QueryValidationFilter): If you don't care if non-JSON:API query parameters are allowed (and potentially silently ignored), simply don't use this filter backend. -#### `OrderingFilter` +#### OrderingFilter + `OrderingFilter` implements the [JSON:API `sort`](http://jsonapi.org/format/#fetching-sorting) and uses DRF's [ordering filter](http://django-rest-framework.readthedocs.io/en/latest/api-guide/filtering/#orderingfilter). @@ -155,7 +157,8 @@ field name and the other two are not valid: If you want to silently ignore bad sort fields, just use `rest_framework.filters.OrderingFilter` and set `ordering_param` to `sort`. -#### `DjangoFilterBackend` +#### DjangoFilterBackend + `DjangoFilterBackend` implements a Django ORM-style [JSON:API `filter`](http://jsonapi.org/format/#fetching-filtering) using the [django-filter](https://django-filter.readthedocs.io/) package. @@ -178,13 +181,6 @@ Filters can be: - A related resource path can be used: `?filter[inventory.item.partNum]=123456` (where `inventory.item` is the relationship path) -If you are also using [`SearchFilter`](#searchfilter) -(which performs single parameter searches across multiple fields) you'll want to customize the name of the query -parameter for searching to make sure it doesn't conflict with a field name defined in the filterset. -The recommended value is: `search_param="filter[search]"` but just make sure it's -`filter[_something_]` to comply with the JSON:API spec requirement to use the filter -keyword. The default is `REST_FRAMEWORK['SEARCH_PARAM']` unless overriden. - The filter returns a `400 Bad Request` error for invalid filter query parameters as in this example for `GET http://127.0.0.1:8000/nopage-entries?filter[bad]=1`: ```json @@ -201,7 +197,11 @@ for `GET http://127.0.0.1:8000/nopage-entries?filter[bad]=1`: } ``` -#### `SearchFilter` +As this feature depends on `django-filter` you need to run + + pip install djangorestframework-jsonapi['django-filter'] + +#### SearchFilter To comply with JSON:API query parameter naming standards, DRF's [SearchFilter](https://django-rest-framework.readthedocs.io/en/latest/api-guide/filtering/#searchfilter) should @@ -211,12 +211,11 @@ adding the `.search_param` attribute to a custom class derived from `SearchFilte use [`DjangoFilterBackend`](#djangofilterbackend), make sure you set the same values for both classes. - #### Configuring Filter Backends You can configure the filter backends either by setting the `REST_FRAMEWORK['DEFAULT_FILTER_BACKENDS']` as shown in the [example settings](#configuration) or individually add them as `.filter_backends` View attributes: - + ```python from rest_framework_json_api import filters from rest_framework_json_api import django_filters @@ -699,6 +698,10 @@ DJA tests its polymorphic support against [django-polymorphic](https://django-po The polymorphic feature should also work with other popular libraries like django-polymodels or django-typed-models. +As this feature depends on `django-polymorphic` you need to run + + pip install djangorestframework-jsonapi['django-polymorphic'] + #### Writing polymorphic resources A polymorphic endpoint can be set up if associated with a polymorphic serializer. diff --git a/setup.py b/setup.py index d9c1c926..7181beb0 100755 --- a/setup.py +++ b/setup.py @@ -90,6 +90,10 @@ def get_package_data(package): 'djangorestframework>=3.10', 'django>=1.11', ], + extras_require={ + 'django-polymorphic': ['django-polymorphic>=2.0'], + 'django-filter': ['django-filter>=2.0'] + }, python_requires=">=3.5", zip_safe=False, ) pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy