saritasa-drf-tools¶

GitHub last commit GitHub Workflow Status (with event) PyPI PyPI - Status PyPI - Python Version PyPI - Django Version PyPI - License PyPI - Downloads

Check out our other open-source projects

Tools For DRF Used By Saritasa

Table of contents¶

Installation
Features
Optional dependencies
Serializers
Views
Pagination
Filters
Renderers
OpenAPI
Tester

Installation¶

pip install saritasa-drf-tools

or if you are using uv

uv add saritasa-drf-tools

or if you are using poetry

poetry add saritasa-drf-tools

Features¶

Views - collection of mixins and viewsets classes
Serializers - collection of mixins and serializers classes
Filters - Custom filter backends that improve integration with drf-spectacular
OpenAPI - tools for drf-spectacular
pytest - plugin which provides different api_client fixtures.
Testing classes(Warning: Very experimental) - Test class which contains shortcut to reduce boilerplate across tests.

For examples and to just check it out in action you can use example folder.

Optional dependencies¶

[filters] - Add this to enable django-filters support
[openapi] - Add this to enable drf-spectacular support

Views¶

Views mixins¶

ActionPermissionsMixin: Mixin which allows to define specific permissions per actions For example you have:

class CRUDView(
  ActionPermissionsMixin,
  ActionMixins, # Anything you need
  GenericViewSet,
):
  """CRUD view."""
  base_permission_classes = (permissions.AllowAny,)
  extra_permission_classes = (permissions.IsAuthenticated,)
  extra_permissions_map = {
      "create": (permissions.IsAdminUser,),
      "update": (permissions.IsAdminUser,),
      "destroy": (permissions.IsAdminUser,),
  }

base_permission_classes - Will be applied to any action (Usually you want this in base class of your project)
extra_permission_classes - Will be added to base_permission_classes
extra_permission_map - Will be added to (base_permission_classes + extra_permission_classes) on action you specify in mapping

To learn more read class docs.

ActionSerializerMixin: Mixin which allows to define specific serializers per action. For example you have

class CRUDView(
  ActionPermissionsMixin,
  ActionMixins, # Anything you need
  GenericViewSet,
):
  """CRUD view."""

  queryset = models.TestModel.objects.select_related("related_model").all()
  serializers_map = {
      "default": serializers.TestModelDetailSerializer,
      "list": serializers.TestModelListSerializer,
  }

That means that on list view will use TestModelListSerializer, but on any other actions TestModelDetailSerializer. This will also will be reflected in generated openapi specs via drf-spectacular

To learn more read class docs.

UpdateModelWithoutPatchMixin: Same as UpdateModelMixin but without patch method

Viewset classes¶

BaseViewSet: Viewset with ActionPermissionsMixin and ActionSerializerMixin
CRUDViewSet: Viewset with crud endpoint based on BaseViewSet
ReadOnlyViewSet: Viewset with read endpoint based on BaseViewSet

Pagination¶

LimitOffsetPagination: Customized paginator class to limit max objects in list APIs. Use SARITASA_DRF_MAX_PAGINATION_SIZE to set default max for whole project. Also supports overriding pagination settings per view via pagination_default_limit and pagination_max_limit attributes.

Serializers¶

Serializers mixins¶

CleanValidationMixin: Enable model clean validation in serializer
FieldMappingOverride: Override or extend field mapping via SARITASA_DRF_FIELD_MAPPING. For example you can set following in settings.

SARITASA_DRF_FIELD_MAPPING = {
  "django.db.models.TextField": "example.app.api.fields.CustomCharField",
}

And now all TextField of your models will have CustomCharField in serializers.

UserAndRequestFromContextMixin: Extracts user and request from context and sets it as attr of serializer instance.
NestedFieldsMixin: Allows to define nested data fields for serializers via Meta class.

Serializers classes¶

BaseSerializer: Serializer with UserAndRequestFromContextMixin
ModelBaseSerializer: ModelSerializer with mixins.FieldMappingOverride, mixins.CleanValidationMixin, mixins.UserAndRequestFromContextMixin, mixins.NestedFieldsMixin.

Filters¶

Needs filters and openapi to be included to work properly.

OrderingFilterBackend: Add supported fields to ordering param's description in specs generated by drf-spectacular. Will raise warning specs validation on empty ordering_fields or if queryset is unable to order itself using ordering_fields. Example of description:

Which fields to use when ordering the results. A list fields separated by ,. Example: field1,field2

Supported fields: id, text_field, related_model__text_field.

To reverse order just add - to field. Example:field -> -field

Also has support for nulls_first and nulls_last ordering. You can either set these options globally in your settings:

SARITASA_DRF_ORDERING_IS_NULL_FIRST = True
SARITASA_DRF_ORDERING_IS_NULL_LAST = True

Or you can set them per view:

class MyView(views.APIView):
    ordering_fields_extra_kwargs = {
        "my_field": {
            "nulls_first": True,
            "nulls_last": False,
        },
    }

If you have list of items ordered by non-unique fields only (or without any ordering), this filter will add secondary sorting by pk to make sure that order of items will be consistent across requests. You can enable secondary sorting via add_pk_to_ordering flag in your views:

class MyView(views.APIView):
    add_pk_to_ordering = True

By default, this option is enabled. You can either set this option globally in your settings:

SARITASA_DRF_ORDERING_ADD_PK_TO_ORDERING = True

SearchFilterBackend: Add supported fields to search param's description in specs generated by drf-spectacular. Will raise warning specs validation on empty search_fields or if queryset is unable to perform search using search_fields.

Example of description:

A search term.

Performed on this fields: text_field, related_model__text_field.

DjangoFilterBackend: Customized DjangoFilterBackend to reduce queries count when viewing api requests via browser

Renderers¶

BrowsableAPIRenderer: Customization over drf's BrowsableAPIRenderer. With SARITASA_DRF_BROWSABLE_API_ENABLE_HTML_FORM(Default: True) or setting enable_browsable_api_rendered_html_form(If not present will use global setting) in view you can disable all extra forms which results in extra SQL queries.

OpenAPI¶

Needs openapi to be included to work properly.

OpenApiSerializer: Serializer that should be used for customizing open_api spec. Made to avoid warnings about unimplemented methods.
DetailSerializer: To show in spec responses like this {detail: text}.
fix_api_view_warning: Fix warning This is graceful fallback handling for APIViews.

Pytest¶

Plugin provides following fixtures:

api_client_factory - factory which generated rest_framework.test.ApiClient instance
api_client - uses api_client_factory to generate rest_framework.test.ApiClient instance
user_api_client(Needs user fixture) uses api_client_factory to generate rest_framework.test.ApiClient instance forces auth to user
admin_api_client(Needs admin fixture) uses api_client_factory to generate rest_framework.test.ApiClient instance forces auth to admin

Tester¶

Warning: Very experimental.

saritasa_drf_tools.testing.ApiActionTester - is a tester class which contains fixtures and shortcuts to simply and reduce boilerplate in tests for viewsets.

All you need to is create tester.py(you what ever you want it's just recommendation). In this file declare new class which inherits ApiActionTester.

class CRUDApiActionTester(
    saritasa_drf_tools.testing.ApiActionTester.init_subclass(
        model=models.TestModel, # Model of queryset in viewset
        user_model=models.User, # Model of user used across project
        factory=factories.TestModelFactory, # Factory which is used to generate instances for model
        api_view=api.views.CRUDView, # Class of viewset against which we will be writing tests
        url_basename="crud-api", # Base name of urls of viewset. {url_basename}-{action}
    ),
):
    """Tester for crud API."""

Next you can write test just like this. (For more examples check this folder: tests/test_crud_api)

class TestCRUD(tester.CRUDApiActionTester):
    """Define tests."""

    @pytest.mark.parametrize(
        argnames=[
            "parametrize_user",
            "status_code",
        ],
        argvalues=[
            [
                None,
                status.HTTP_403_FORBIDDEN,
            ],
            [
                pytest_lazy_fixtures.lf("user"),
                status.HTTP_403_FORBIDDEN,
            ],
            [
                pytest_lazy_fixtures.lf("admin"),
                status.HTTP_201_CREATED,
            ],
        ],
    )
    def test_permission_map_specified_action_create(
        self,
        instance: tester.CRUDApiActionTester.model,
        parametrize_user: tester.CRUDApiActionTester.user_model | None,
        status_code: int,
    ) -> None:
        """Test that create action will properly handle permissions."""
        self.make_request(
            method="post",
            user=parametrize_user,
            expected_status=status_code,
            path=self.lazy_url(action="list"),
            data=self.serialize_data(action="create", data=instance),
        )