<p align="center">
<img width="64" src="https://avatars2.githubusercontent.com/u/22204821?s=200&v=4" alt="Rehive Logo">
<h1 align="center">DRF Rehive Extras</h1>
<p align="center">Extra utilities for using Django REST Framework.</p>
</p>
## Features
- Python >= 3.6
- Django >= 3.0
- Generic views and mixins for all CRUD.
- Custom pagination that supports cursor and page based pagination.
- Integrated support for flex fields and django filters.
- Base serializers.
- Metadata, timestamp, and enum serializer fields.
- Schema generation support via drf-spectacular.
## Getting started
1. Install the package:
```sh
pip install drf-rehive-extras
```
2. Add "drf_rehive_extras" to your `INSTALLED_APPS` settings like this:
```python
INSTALLED_APPS = [
# ...
'drf_rehive_extras',
]
```
## Usage
### Schema generation
This library allows you to use `drf-spectacular` to generate Open API schemas that match the Rehive eveloped request/response format as defined by the `drf-rehive-extras` views/serializers.
To use schema generation, install `drf-spectacular` (in addition to `drf-rehive-extras` as described above):
```sh
pip install drf-spectacular[sidecar]
```
And add the following to the `INSTALLED_APPS` settings:
```python
INSTALLED_APPS = [
# ...
'drf_spectacular',
'drf_spectacular_sidecar',
]
```
Finally, configure the `REST_FRAMEWORK` settings with:
```python
REST_FRAMEWORK = {
'DEFAULT_SCHEMA_CLASS': 'drf_rehive_extras.schema.BaseAutoSchema',
}
```
The `schema.BaseAutoSchema` class also includes functionality to attach
additional documentation to the schema via yaml files.
To generate additional documentation, create a `docs.yaml` file in a `docs` folder in your Django app. The file should be formatted like this:
```yaml
app.views.ExampleView:
GET:
operationId:
summary:
description:
x-code-samples:
- lang:
label:
source: >
- lang: Python
label: Python SDK
source: >
```
Then, in your `settings` file specify the above directory using the `ADDITIONAL_DOCS_DIRS` settings:
```python
import os
ADDITIONAL_DOCS_DIRS = [
"/root/app/docs/",
]
```
### Pagination
This library adds extra pagination via `PageNumberPagination` and `CursorPagination` that can be used to generate paginated lists that return the results in the Rehive eveloped request/response format.
You can use them like this:
```python
from drf_rehive_extras.pagination import PageNumberPagination
class ExampleView(ListAPIView)
pagination_class = PageNumberPagination
```
These pagination classes will be automatically applied to any views that inherit from the `drf-rehive-extras` generics and mixins.
### Serializers
This library includes base serializers that can be used to ensure all serializers share the same Rehive base:
- `BaseModelSerializer` : A DRF `ModelSerializer` that includes `rest_flex_fields` functionality.
- `ActionResponseSerializer` : A serializer that can be used to generate action responses.
### Serializers fields
This library adds extra serializer fields that can be used in DRF serializers:
- `MetadataField`
- `TimestampField`
- `EnumField`
These fields can be used like normal serializer fields.
### Views
This library includes a collection of generic views and mixins that can be used to ensure all views follow the same Rehive standard.
The generic views can be used like this:
```python
from drf_rehive_extras.generics import ListAPIView
class ListExampleModelView(ListAPIView):
serializer_class = ExampleModelSerializer
def get_queryset(self):
if getattr(self, 'swagger_fake_view', False):
return ExampleModel.objects.none()
return ExampleModel.objects.all().order_by('-created')
```
The generic views allow for the customization of the serializer based on the method. This can be done by adding a `serializer_classes` attribute to the view:
```python
# Single shared request/response serializer.
serializer_classes = {
"POST": ExampleModelRequestSerializer
}
# Multiple serializers, the first for the request and the second for the response.
serializer_classes = {
"POST": (ExampleModelRequestSerializer, ExampleModelResponseSerializer,)
}
```
The generic views also support explicitly modifying the response status for a given method. This can be done via the `response_status_codes` attribute.
```python
response_status_codes = {"POST": status.HTTP_202_ACCEPTED}
```
If possible, all generic views will attempt to add a `_resource` and `_resource_id` to the request object. This will only be done if there is a single model instance and the instance contains a `RESOURCE` and/or `RESOURCE_ID` attribute.
Finally, in addition to the normal DRF generic views, the library contains an extra `ActionAPIView` that can be used for simple actions. These actions will default to a 200 response and will only ever return a `{"status": "success"}` response.
Usage is as follows:
```python
from drf_rehive_extras.generics import ActionAPIView
from drf_rehive_extras.serializers import ActionResponseSerializer
class ExampleActionView(ActionAPIView):
serializer_class = ExampleActionSerializer
serializer_classes = {
"POST": (ExampleActionSerializer, ActionResponseSerializer,)
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/rehive/drf-rehive-extras",
"name": "drf-rehive-extras",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "Rehive",
"author_email": "info@rehive.com",
"download_url": "https://files.pythonhosted.org/packages/50/e3/7218d4979bdf4d9bc66f39b2e8fd19c51363b60339e889cfea3feda763f1/drf-rehive-extras-2.2.3.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img width=\"64\" src=\"https://avatars2.githubusercontent.com/u/22204821?s=200&v=4\" alt=\"Rehive Logo\">\n <h1 align=\"center\">DRF Rehive Extras</h1>\n <p align=\"center\">Extra utilities for using Django REST Framework.</p>\n</p>\n\n## Features\n\n- Python >= 3.6\n- Django >= 3.0\n- Generic views and mixins for all CRUD.\n- Custom pagination that supports cursor and page based pagination.\n- Integrated support for flex fields and django filters.\n- Base serializers.\n- Metadata, timestamp, and enum serializer fields.\n- Schema generation support via drf-spectacular.\n\n## Getting started\n\n1. Install the package:\n\n```sh\npip install drf-rehive-extras\n```\n\n2. Add \"drf_rehive_extras\" to your `INSTALLED_APPS` settings like this:\n\n```python\nINSTALLED_APPS = [\n # ...\n 'drf_rehive_extras',\n]\n```\n\n## Usage\n\n### Schema generation\n\nThis library allows you to use `drf-spectacular` to generate Open API schemas that match the Rehive eveloped request/response format as defined by the `drf-rehive-extras` views/serializers.\n\nTo use schema generation, install `drf-spectacular` (in addition to `drf-rehive-extras` as described above):\n\n```sh\npip install drf-spectacular[sidecar]\n```\n\nAnd add the following to the `INSTALLED_APPS` settings:\n\n```python\nINSTALLED_APPS = [\n # ...\n 'drf_spectacular',\n 'drf_spectacular_sidecar',\n]\n```\n\nFinally, configure the `REST_FRAMEWORK` settings with:\n\n```python\nREST_FRAMEWORK = {\n 'DEFAULT_SCHEMA_CLASS': 'drf_rehive_extras.schema.BaseAutoSchema',\n}\n```\n\nThe `schema.BaseAutoSchema` class also includes functionality to attach\nadditional documentation to the schema via yaml files.\n\nTo generate additional documentation, create a `docs.yaml` file in a `docs` folder in your Django app. The file should be formatted like this:\n\n```yaml\napp.views.ExampleView:\n GET:\n operationId:\n summary:\n description:\n x-code-samples:\n - lang:\n label:\n source: >\n - lang: Python\n label: Python SDK\n source: >\n```\n\nThen, in your `settings` file specify the above directory using the `ADDITIONAL_DOCS_DIRS` settings:\n\n```python\nimport os\n\nADDITIONAL_DOCS_DIRS = [\n \"/root/app/docs/\",\n]\n```\n\n### Pagination\n\nThis library adds extra pagination via `PageNumberPagination` and `CursorPagination` that can be used to generate paginated lists that return the results in the Rehive eveloped request/response format.\n\nYou can use them like this:\n\n```python\nfrom drf_rehive_extras.pagination import PageNumberPagination\n\nclass ExampleView(ListAPIView)\n pagination_class = PageNumberPagination\n```\n\nThese pagination classes will be automatically applied to any views that inherit from the `drf-rehive-extras` generics and mixins.\n\n### Serializers\n\nThis library includes base serializers that can be used to ensure all serializers share the same Rehive base:\n\n- `BaseModelSerializer` : A DRF `ModelSerializer` that includes `rest_flex_fields` functionality.\n- `ActionResponseSerializer` : A serializer that can be used to generate action responses.\n\n### Serializers fields\n\nThis library adds extra serializer fields that can be used in DRF serializers:\n\n- `MetadataField`\n- `TimestampField`\n- `EnumField`\n\nThese fields can be used like normal serializer fields.\n\n### Views\n\nThis library includes a collection of generic views and mixins that can be used to ensure all views follow the same Rehive standard.\n\nThe generic views can be used like this:\n\n```python\nfrom drf_rehive_extras.generics import ListAPIView\n\nclass ListExampleModelView(ListAPIView):\n serializer_class = ExampleModelSerializer\n\n def get_queryset(self):\n if getattr(self, 'swagger_fake_view', False):\n return ExampleModel.objects.none()\n\n return ExampleModel.objects.all().order_by('-created')\n```\n\nThe generic views allow for the customization of the serializer based on the method. This can be done by adding a `serializer_classes` attribute to the view:\n\n```python\n# Single shared request/response serializer.\nserializer_classes = {\n \"POST\": ExampleModelRequestSerializer\n}\n\n# Multiple serializers, the first for the request and the second for the response.\nserializer_classes = {\n \"POST\": (ExampleModelRequestSerializer, ExampleModelResponseSerializer,)\n}\n```\n\nThe generic views also support explicitly modifying the response status for a given method. This can be done via the `response_status_codes` attribute.\n\n```python\nresponse_status_codes = {\"POST\": status.HTTP_202_ACCEPTED}\n```\n\nIf possible, all generic views will attempt to add a `_resource` and `_resource_id` to the request object. This will only be done if there is a single model instance and the instance contains a `RESOURCE` and/or `RESOURCE_ID` attribute.\n\nFinally, in addition to the normal DRF generic views, the library contains an extra `ActionAPIView` that can be used for simple actions. These actions will default to a 200 response and will only ever return a `{\"status\": \"success\"}` response.\n\nUsage is as follows:\n\n```python\nfrom drf_rehive_extras.generics import ActionAPIView\nfrom drf_rehive_extras.serializers import ActionResponseSerializer\n\nclass ExampleActionView(ActionAPIView):\n serializer_class = ExampleActionSerializer\n serializer_classes = {\n \"POST\": (ExampleActionSerializer, ActionResponseSerializer,)\n }\n```\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Extras for DRF",
"version": "2.2.3",
"project_urls": {
"Download": "https://github.com/rehive/drf-rehive-extras/archive/2.2.3.zip",
"Homepage": "https://github.com/rehive/drf-rehive-extras"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "50e37218d4979bdf4d9bc66f39b2e8fd19c51363b60339e889cfea3feda763f1",
"md5": "4add843e388c106ae069b5fc84474d2a",
"sha256": "6e4a03fb128501d271d731534b7b196aa7ba14ab273be22bee8329fad0941a8d"
},
"downloads": -1,
"filename": "drf-rehive-extras-2.2.3.tar.gz",
"has_sig": false,
"md5_digest": "4add843e388c106ae069b5fc84474d2a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 14026,
"upload_time": "2024-11-06T11:44:24",
"upload_time_iso_8601": "2024-11-06T11:44:24.514470Z",
"url": "https://files.pythonhosted.org/packages/50/e3/7218d4979bdf4d9bc66f39b2e8fd19c51363b60339e889cfea3feda763f1/drf-rehive-extras-2.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-06 11:44:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rehive",
"github_project": "drf-rehive-extras",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "drf-rehive-extras"
}
JSON
