drf-flex-fields2 2.0.0__tar.gz

drf_flex_fields2-2.0.0/LICENSE.md

@@ -0,0 +1,23 @@
+MIT License
+===========
+
+Copyright © 2016 – 2023 Robert Singer <br>
+Copyright © 2026 Dennis Schulmeister-Zimolong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

drf_flex_fields2-2.0.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.1
+Name: drf-flex-fields2
+Version: 2.0.0
+Summary: Flexible, dynamic fields and nested resources for Django REST Framework serializers (forked from drf-flex-fields).
+Home-page: https://drf-flex-fields2.readthedocs.io/en/stable/
+License: MIT
+Keywords: django,rest,api,dynamic,fields
+Author: Robert Singer
+Maintainer: Dennis Schulmeister-Zimolong
+Requires-Python: >=3.12,<4
+Classifier: Framework :: Django
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: django (>=5.0,<=6.0.3)
+Requires-Dist: djangorestframework (>=3.14.0,<3.17.1)
+Project-URL: Repository, https://github.com/openbook-education/drf-flex-fields2
+Description-Content-Type: text/markdown
+
+# drf-flex-fields2
+
+[![Package version](https://badge.fury.io/py/drf-flex-fields2.svg)](https://pypi.org/project/drf-flex-fields2/)
+
+Flexible dynamic fields and nested resources for Django REST Framework serializers.
+
+This project is for people building APIs, people integrating them, and people
+maintaining the ecosystem around them. If you are new to flexible serializers,
+welcome. If you are evaluating this for production, welcome. If you want to
+contribute fixes, docs, tests, or ideas, welcome.
+
+1. [Migration from drf-flex-fields](#migration-from-drf-flex-fields)
+1. [Documentation](#documentation)
+1. [Installation](#installation)
+1. [Quick Example](#quick-example)
+1. [Highlights](#highlights)
+1. [License](#license)
+1. [History](#history)
+
+## Migration from drf-flex-fields
+
+This is a fork of `drf-flex-fields` developed and maintained by Robert Singer
+between 2018 and 2023. For more details on why this fork exists, see
+[History](#history) below. See the [Migration Guide](https://drf-flex-fields2.readthedocs.io/en/latest/getting-started/migration/)
+in the documentation for detailed instructions. The short version is:
+
+1. Upgrade Django and DRF dependencies, if not done already.
+2. Install `drf-flex-fields2` instead of `drf-flex-fields`.
+3. Fix package name in import paths: `rest_flex_fields2` instead of `rest_flex_fields`
+4. Change package-level imports to deep imports, e.g.: `from rest_flex_fields2.serializers import FlexFieldsModelSerializer`
+5. Rename `REST_FLEX_FIELDS` to `REST_FLEX_FIELDS2` in Django settings.
+
+The `drf-flex-fields2` API is stable and compatible with the original `drf-flex-fields`
+package. There are currently no plans to break the existing API. However, if breaking
+changes become necessary in the future, they will follow [semantic versioning](https://semver.org/)
+guidelines and the major version number will be incremented accordingly.
+
+Users, community contributors, and maintainers are warmly welcome to keep this
+package useful and maintained.
+
+## Documentation
+
+The full documentation is published on Read the Docs: <https://drf-flex-fields2.readthedocs.io/>
+
+## Installation
+
+```bash
+pip install drf-flex-fields2
+```
+
+## Quick Example
+
+```python
+from rest_flex_fields2.serializers import FlexFieldsModelSerializer
+
+
+class StateSerializer(FlexFieldsModelSerializer):
+    class Meta:
+        model = State
+        fields = ("id", "name")
+
+
+class CountrySerializer(FlexFieldsModelSerializer):
+    class Meta:
+        model = Country
+        fields = ("id", "name", "population", "states")
+        expandable_fields = {
+            "states": (StateSerializer, {"many": True}),
+        }
+
+
+class PersonSerializer(FlexFieldsModelSerializer):
+    class Meta:
+        model = Person
+        fields = ("id", "name", "country", "occupation")
+        expandable_fields = {
+            "country": CountrySerializer,
+        }
+```
+
+Default response:
+
+```json
+{
+    "id": 142,
+    "name": "Jim Halpert",
+    "country": 1
+}
+```
+
+Expanded response for `GET /people/142/?expand=country.states`:
+
+```json
+{
+    "id": 142,
+    "name": "Jim Halpert",
+    "country": {
+        "id": 1,
+        "name": "United States",
+        "states": [
+            {
+                "id": 23,
+                "name": "Ohio"
+            },
+            {
+                "id": 2,
+                "name": "Pennsylvania"
+            }
+        ]
+    }
+}
+```
+
+## Highlights
+
+- Expand nested relations with `?expand=`.
+- Limit response payloads with `?fields=` and `?omit=`.
+- Use dot notation for nested expansion and sparse fieldsets.
+- Reuse serializers by passing `expand`, `fields`, and `omit` directly.
+
+## License
+
+MIT. See [LICENSE.md](LICENSE.md).
+
+## History
+
+The original `drf-flex-fields` was developed and maintained by Robert Singer
+between 2018 and 2023. However, in 2023 maintenance appeared to stop with no
+further commits and issues and pull-requests remaining unanswered.
+
+In March 2026, Django REST Framework 3.17.0 removed coreapi support, which
+unfortunately broke the existing package. Although the immediate fix was
+simple, the project was due for broader modernization, including tooling updates,
+Python 2 to 3 cleanup, dependency version maintenance and proper documentation.
+
+This fork exists because `drf-flex-fields` is used in the
+[OpenBook project](https://github.com/openbook-education/openbook), and we want to
+reduce supply-chain risk from outdated dependencies while keeping this
+package healthy and maintained. Please join the community and help us with
+this mission. Oh, and keep your own packages up to date and maintained, will
+you? :-)
+

drf_flex_fields2-2.0.0/README.md

@@ -0,0 +1,141 @@
+# drf-flex-fields2
+
+[![Package version](https://badge.fury.io/py/drf-flex-fields2.svg)](https://pypi.org/project/drf-flex-fields2/)
+
+Flexible dynamic fields and nested resources for Django REST Framework serializers.
+
+This project is for people building APIs, people integrating them, and people
+maintaining the ecosystem around them. If you are new to flexible serializers,
+welcome. If you are evaluating this for production, welcome. If you want to
+contribute fixes, docs, tests, or ideas, welcome.
+
+1. [Migration from drf-flex-fields](#migration-from-drf-flex-fields)
+1. [Documentation](#documentation)
+1. [Installation](#installation)
+1. [Quick Example](#quick-example)
+1. [Highlights](#highlights)
+1. [License](#license)
+1. [History](#history)
+
+## Migration from drf-flex-fields
+
+This is a fork of `drf-flex-fields` developed and maintained by Robert Singer
+between 2018 and 2023. For more details on why this fork exists, see
+[History](#history) below. See the [Migration Guide](https://drf-flex-fields2.readthedocs.io/en/latest/getting-started/migration/)
+in the documentation for detailed instructions. The short version is:
+
+1. Upgrade Django and DRF dependencies, if not done already.
+2. Install `drf-flex-fields2` instead of `drf-flex-fields`.
+3. Fix package name in import paths: `rest_flex_fields2` instead of `rest_flex_fields`
+4. Change package-level imports to deep imports, e.g.: `from rest_flex_fields2.serializers import FlexFieldsModelSerializer`
+5. Rename `REST_FLEX_FIELDS` to `REST_FLEX_FIELDS2` in Django settings.
+
+The `drf-flex-fields2` API is stable and compatible with the original `drf-flex-fields`
+package. There are currently no plans to break the existing API. However, if breaking
+changes become necessary in the future, they will follow [semantic versioning](https://semver.org/)
+guidelines and the major version number will be incremented accordingly.
+
+Users, community contributors, and maintainers are warmly welcome to keep this
+package useful and maintained.
+
+## Documentation
+
+The full documentation is published on Read the Docs: <https://drf-flex-fields2.readthedocs.io/>
+
+## Installation
+
+```bash
+pip install drf-flex-fields2
+```
+
+## Quick Example
+
+```python
+from rest_flex_fields2.serializers import FlexFieldsModelSerializer
+
+
+class StateSerializer(FlexFieldsModelSerializer):
+    class Meta:
+        model = State
+        fields = ("id", "name")
+
+
+class CountrySerializer(FlexFieldsModelSerializer):
+    class Meta:
+        model = Country
+        fields = ("id", "name", "population", "states")
+        expandable_fields = {
+            "states": (StateSerializer, {"many": True}),
+        }
+
+
+class PersonSerializer(FlexFieldsModelSerializer):
+    class Meta:
+        model = Person
+        fields = ("id", "name", "country", "occupation")
+        expandable_fields = {
+            "country": CountrySerializer,
+        }
+```
+
+Default response:
+
+```json
+{
+    "id": 142,
+    "name": "Jim Halpert",
+    "country": 1
+}
+```
+
+Expanded response for `GET /people/142/?expand=country.states`:
+
+```json
+{
+    "id": 142,
+    "name": "Jim Halpert",
+    "country": {
+        "id": 1,
+        "name": "United States",
+        "states": [
+            {
+                "id": 23,
+                "name": "Ohio"
+            },
+            {
+                "id": 2,
+                "name": "Pennsylvania"
+            }
+        ]
+    }
+}
+```
+
+## Highlights
+
+- Expand nested relations with `?expand=`.
+- Limit response payloads with `?fields=` and `?omit=`.
+- Use dot notation for nested expansion and sparse fieldsets.
+- Reuse serializers by passing `expand`, `fields`, and `omit` directly.
+
+## License
+
+MIT. See [LICENSE.md](LICENSE.md).
+
+## History
+
+The original `drf-flex-fields` was developed and maintained by Robert Singer
+between 2018 and 2023. However, in 2023 maintenance appeared to stop with no
+further commits and issues and pull-requests remaining unanswered.
+
+In March 2026, Django REST Framework 3.17.0 removed coreapi support, which
+unfortunately broke the existing package. Although the immediate fix was
+simple, the project was due for broader modernization, including tooling updates,
+Python 2 to 3 cleanup, dependency version maintenance and proper documentation.
+
+This fork exists because `drf-flex-fields` is used in the
+[OpenBook project](https://github.com/openbook-education/openbook), and we want to
+reduce supply-chain risk from outdated dependencies while keeping this
+package healthy and maintained. Please join the community and help us with
+this mission. Oh, and keep your own packages up to date and maintained, will
+you? :-)

drf_flex_fields2-2.0.0/pyproject.toml

@@ -0,0 +1,46 @@
+[tool.poetry]
+name = "drf-flex-fields2"
+version = "2.0.0"
+description = "Flexible, dynamic fields and nested resources for Django REST Framework serializers (forked from drf-flex-fields)."
+authors = ["Robert Singer", "Dennis Schulmeister-Zimolong"]
+maintainers = ["Dennis Schulmeister-Zimolong"]
+license = "MIT"
+readme = "README.md"
+homepage = "https://drf-flex-fields2.readthedocs.io/en/stable/"
+repository = "https://github.com/openbook-education/drf-flex-fields2"
+keywords = ["django", "rest", "api", "dynamic", "fields"]
+packages = [{ include = "rest_flex_fields2", from = "src" }]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Framework :: Django",
+]
+
+[tool.poetry.dependencies]
+python = ">=3.12,<4"
+django = ">=5.0,<=6.0.3"
+djangorestframework = ">=3.14.0,<3.17.1"
+
+[tool.poetry.group.docs.dependencies]
+sphinx = "^8.0"
+sphinx-rtd-theme = "^3.0"
+sphinx-autoapi = "^3.0"
+
+[tool.poetry.group.dev.dependencies]
+coverage = "^7.8"
+
+[tool.coverage.run]
+branch = true
+source = ["src/rest_flex_fields2"]
+
+[tool.coverage.report]
+fail_under = 90
+show_missing = true
+skip_covered = true
+omit = [
+    "*/__pycache__/*",
+]
+
+[build-system]
+requires = ["poetry-core>=1.9.0"]
+build-backend = "poetry.core.masonry.api"

drf_flex_fields2-2.0.0/src/rest_flex_fields2/config.py

@@ -0,0 +1,58 @@
+"""Runtime configuration for ``REST_FLEX_FIELDS2``.
+
+Reads the optional ``REST_FLEX_FIELDS2`` dict from Django settings and
+exposes validated constants used throughout the package.  Raises
+``AssertionError`` or ``ValueError`` on invalid configuration so
+errors surface at import time rather than at request time.
+"""
+
+from django.conf import settings
+
+FLEX_FIELDS_OPTIONS = getattr(settings, "REST_FLEX_FIELDS2", {})
+"""Raw ``REST_FLEX_FIELDS2`` dictionary from Django settings."""
+
+EXPAND_PARAM = FLEX_FIELDS_OPTIONS.get("EXPAND_PARAM", "expand")
+"""Query parameter name used to request expandable fields."""
+
+FIELDS_PARAM = FLEX_FIELDS_OPTIONS.get("FIELDS_PARAM", "fields")
+"""Query parameter name used to include only selected fields."""
+
+OMIT_PARAM = FLEX_FIELDS_OPTIONS.get("OMIT_PARAM", "omit")
+"""Query parameter name used to omit selected fields."""
+
+MAXIMUM_EXPANSION_DEPTH = FLEX_FIELDS_OPTIONS.get("MAXIMUM_EXPANSION_DEPTH", None)
+"""Maximum nested expansion depth. ``None`` means unlimited."""
+
+RECURSIVE_EXPANSION_PERMITTED = FLEX_FIELDS_OPTIONS.get("RECURSIVE_EXPANSION_PERMITTED", True)
+"""Whether recursive field expansion is allowed."""
+
+WILDCARD_ALL = "~all"
+"""Wildcard token that expands all fields."""
+
+WILDCARD_ASTERISK = "*"
+"""Wildcard token alternative that expands all fields."""
+
+if "WILDCARD_EXPAND_VALUES" in FLEX_FIELDS_OPTIONS:
+    wildcard_values = FLEX_FIELDS_OPTIONS["WILDCARD_EXPAND_VALUES"]
+elif "WILDCARD_VALUES" in FLEX_FIELDS_OPTIONS:
+    wildcard_values = FLEX_FIELDS_OPTIONS["WILDCARD_VALUES"]
+else:
+    wildcard_values = [WILDCARD_ALL, WILDCARD_ASTERISK]
+
+WILDCARD_VALUES = wildcard_values
+"""Allowed wildcard tokens for expansion, configurable via Django settings."""
+
+assert isinstance(EXPAND_PARAM, str), "'EXPAND_PARAM' should be a string"
+assert isinstance(FIELDS_PARAM, str), "'FIELDS_PARAM' should be a string"
+assert isinstance(OMIT_PARAM, str),   "'OMIT_PARAM' should be a string"
+
+if not isinstance(WILDCARD_VALUES, (list, type(None))):
+    raise ValueError(
+        "'WILDCARD_EXPAND_VALUES' or 'WILDCARD_VALUES' should be a list of strings or None"
+    )
+
+if not isinstance(MAXIMUM_EXPANSION_DEPTH, (int, type(None))):
+    raise ValueError("'MAXIMUM_EXPANSION_DEPTH' should be a int or None")
+
+if not isinstance(RECURSIVE_EXPANSION_PERMITTED, bool):
+    raise ValueError("'RECURSIVE_EXPANSION_PERMITTED' should be a bool")

drf_flex_fields2-2.0.0/src/rest_flex_fields2/filter_backends.py

@@ -0,0 +1,331 @@
+"""DRF filter backends for flex-fields.
+
+Provides two backends:
+
+- ``FlexFieldsDocsFilterBackend`` — a no-op backend whose only purpose is to
+  inject the ``fields``, ``omit``, and ``expand`` query parameters into the
+  generated API schema (e.g. drf-spectacular / drf-yasg).  Downstream projects
+  normally shouldn't use this.
+
+- ``FlexFieldsFilterBackend`` — extends the docs backend with actual queryset
+  optimisation: it resolves the active field selection and expansion options
+  and applies ``only()`` / ``select_related()`` / ``prefetch_related()`` to
+  the queryset automatically.
+"""
+
+from functools import lru_cache
+import importlib
+from typing import Any, Optional, TYPE_CHECKING
+
+from django.core.exceptions import FieldDoesNotExist
+from django.db import models
+from django.db.models import QuerySet
+from rest_framework import serializers
+from rest_framework.filters import BaseFilterBackend
+
+if TYPE_CHECKING:
+    from rest_framework.viewsets import GenericViewSet
+    from rest_framework.request import Request
+
+from .config import (
+    EXPAND_PARAM,
+    FIELDS_PARAM,
+    OMIT_PARAM,
+    WILDCARD_VALUES,
+)
+from .serializers import FlexFieldsSerializerMixin
+
+WILDCARD_VALUES_JOINED = ",".join(WILDCARD_VALUES or [])
+
+
+class FlexFieldsDocsFilterBackend(BaseFilterBackend):
+    """No-op filter backend that adds flex-fields parameters to the API schema.
+
+    Does not modify the queryset.  Its sole purpose is to expose the
+    ``fields``, ``omit``, and ``expand`` query parameters in the OpenAPI
+    schema generated by tools such as drf-spectacular. Downstream projects
+    normally shouldn't use this; use ``FlexFieldsFilterBackend`` instead.
+    """
+
+    def filter_queryset(self, request, queryset, view):
+        """Return `queryset` unchanged."""
+        return queryset
+
+    @staticmethod
+    @lru_cache()
+    def _get_model_field(field_name: str, model: models.Model) -> Optional[models.Field]:
+        """Return the Django model field for `field_name`, or ``None``.
+
+        Result is cached per ``(field_name, model)`` pair via ``lru_cache``.
+        Returns ``None`` when the field does not exist on the model (e.g. for
+        serializer-only or method fields).
+        """
+        try:
+            # noinspection PyProtectedMember
+            return model._meta.get_field(field_name)
+        except FieldDoesNotExist:
+            return None
+
+    @classmethod
+    def _get_expandable_fields(
+        cls, serializer_class: Any, parents: tuple = (), prefix: str = ""
+    ) -> list:
+        """Return a flat list of all expandable field paths for `serializer_class`.
+
+        Traverses nested `FlexFieldsSerializerMixin` subclasses recursively
+        and builds dot-separated paths (e.g. ``['author', 'author.profile']``).
+        Lazy string serializer paths are resolved before traversal.
+        """
+        if serializer_class in parents:
+            # Break endless recursion
+            return []
+
+        meta = getattr(serializer_class, "Meta", None)
+
+        if meta is not None and hasattr(meta, "expandable_fields"):
+            expandable_fields_dict = meta.expandable_fields
+        elif hasattr(serializer_class, "expandable_fields"):
+            expandable_fields_dict = serializer_class.expandable_fields
+        else:
+            return []
+
+        expandable_fields = list(expandable_fields_dict.items())
+        expand_list = []
+
+        while expandable_fields:
+            key, field_options = expandable_fields.pop()
+
+            if isinstance(field_options, tuple):
+                nested_serializer_class = field_options[0]
+            else:
+                nested_serializer_class = field_options
+
+            if isinstance(nested_serializer_class, str):
+                nested_serializer_class = FlexFieldsDocsFilterBackend._get_serializer_class_from_lazy_string(
+                    nested_serializer_class
+                )
+
+            expand_list.append(f"{prefix}{key}")
+
+            expand_list += cls._get_expandable_fields(
+                serializer_class = nested_serializer_class,
+                parents          = parents + (serializer_class,),
+                prefix           = f"{prefix}{key}.",
+            )
+
+        return expand_list
+
+    @staticmethod
+    def _get_serializer_class_from_lazy_string(full_lazy_path: str):
+        """Resolve a dotted string path to a serializer class.
+
+        Tries the exact path first; if that fails and the path does not
+        already end in ``.serializers``, appends ``.serializers`` and retries.
+        Raises ``Exception`` when the class cannot be found.
+        """
+        def _import_serializer_class(path: str, class_name: str):
+            """Import `class_name` from the module at `path`."""
+            try:
+                module = importlib.import_module(path)
+            except ImportError:
+                return None
+
+            serializer_class = getattr(module, class_name, None)
+
+            if isinstance(serializer_class, type) and issubclass(serializer_class, serializers.Serializer):
+                return serializer_class
+
+            return None
+
+        path_parts = full_lazy_path.split(".")
+        class_name = path_parts.pop()
+        path = ".".join(path_parts)
+
+        serializer_class = _import_serializer_class(path, class_name)
+        if serializer_class is None and not path.endswith(".serializers"):
+            serializer_class = _import_serializer_class(
+                f"{path}.serializers", class_name
+            )
+
+        if serializer_class:
+            return serializer_class
+
+        raise Exception(f"Could not resolve serializer class '{class_name}' from path '{path}'.")
+
+    @staticmethod
+    def _get_serializer_fields(serializer_class):
+        """Return a comma-joined string of the field names declared on `serializer_class`.
+
+        Reads ``Meta.fields`` and converts it into an example-friendly string
+        for schema generation. Returns an empty string for ``"__all__"`` or
+        unsupported field declarations.
+        """
+        meta = getattr(serializer_class, "Meta", None)
+
+        if meta is not None and hasattr(meta, "fields"):
+            fields = getattr(serializer_class.Meta, "fields", [])
+
+            if isinstance(fields, str):
+                return "" if fields == "__all__" else fields
+
+            if isinstance(fields, (list, tuple)):
+                serializer_fields = [field_name for field_name in fields if isinstance(field_name, str)]
+                return ",".join(serializer_fields)
+
+            return ""
+        else:
+            return ""
+
+    def get_schema_operation_parameters(self, view):
+        """Return the OpenAPI query parameter definitions for the flex-fields params.
+
+        Emits ``fields``, ``omit``, and ``expand`` parameter objects for the
+        view's serializer when it is a `FlexFieldsSerializerMixin` subclass.
+        Returns an empty list for views that do not use flex fields.
+        """
+        serializer_class = view.get_serializer_class()
+
+        if not issubclass(serializer_class, FlexFieldsSerializerMixin):
+            return []
+
+        fields = self._get_serializer_fields(serializer_class)
+        expandable_fields = self._get_expandable_fields(serializer_class)
+        expandable_fields.extend(WILDCARD_VALUES or [])
+
+        parameters = [
+            {
+                "name": FIELDS_PARAM,
+                "required": False,
+                "in": "query",
+                "description": "Specify required fields by comma",
+                "schema": {
+                    "title": "Selected fields",
+                    "type": "string",
+                },
+                "example": (fields or "field1,field2,nested.field") + "," + WILDCARD_VALUES_JOINED,
+            },
+            {
+                "name": OMIT_PARAM,
+                "required": False,
+                "in": "query",
+                "description": "Specify omitted fields by comma",
+                "schema": {
+                    "title": "Omitted fields",
+                    "type": "string",
+                },
+                "example": (fields or "field1,field2,nested.field") + "," + WILDCARD_VALUES_JOINED,
+            },
+            {
+                "name": EXPAND_PARAM,
+                "required": False,
+                "in": "query",
+                "description": "Select fields to expand",
+                "style": "form",
+                "explode": False,
+                "schema": {
+                    "title": "Expanded fields",
+                    "type": "array",
+                    "items": {
+                        "type": "string",
+                        "enum": expandable_fields
+                    }
+                },
+            },
+        ]
+
+        return parameters
+
+
+class FlexFieldsFilterBackend(FlexFieldsDocsFilterBackend):
+    """Filter backend that optimises querysets based on the active flex-fields options.
+
+    Extends `FlexFieldsDocsFilterBackend` with actual queryset manipulation:
+    applies ``only()`` to restrict fetched columns and ``select_related()`` and
+    ``prefetch_related()`` for expanded relation fields.  Only active for ``GET``
+    requests on views whose serializer is a ``FlexFieldsSerializerMixin`` subclass.
+
+    View-level opt-out attributes:
+
+    - ``auto_remove_fields_from_query`` (default ``True``): disable ``only()`` optimisation.
+    - ``auto_select_related_on_query`` (default ``True``): disable relation prefetching.
+    - ``required_query_fields`` (default ``[]``): extra field names always included in the ``only()`` call.
+    """
+    def filter_queryset(
+        self, request: "Request", queryset: "QuerySet", view: "GenericViewSet"
+    ):
+        """Apply field-selection and relation-prefetch optimisations to `queryset`.
+
+        Resolves the active ``fields`` / ``omit`` / ``expand`` options from
+        the request, then calls ``only()``, ``select_related()``, and
+        ``prefetch_related()`` as appropriate.  Returns `queryset` unchanged
+        when the view's serializer is not a `FlexFieldsSerializerMixin`
+        subclass, or when the request method is not ``GET``.
+        """
+        # Early exit: only process GET requests on flex-fields serializers.
+        if not issubclass(view.get_serializer_class(), FlexFieldsSerializerMixin) or request.method != "GET":
+            return queryset
+
+        # Retrieve view-level configuration for query optimisation.
+        auto_remove_fields_from_query = getattr(view, "auto_remove_fields_from_query", True)
+        auto_select_related_on_query = getattr(view, "auto_select_related_on_query", True)
+        required_query_fields = list(getattr(view, "required_query_fields", []))
+
+        # Instantiate serializer and apply active flex-fields options.
+        serializer = view.get_serializer(context=view.get_serializer_context()) # type: FlexFieldsSerializerMixin
+        serializer.apply_flex_fields(serializer.fields, serializer._flex_options_rep_only)
+        serializer._flex_fields_rep_applied = True
+
+        # Classify model fields: regular fields and nested relations.
+        model_fields = []
+        nested_model_fields = []
+
+        for field in serializer.fields.values():
+            model_field = self._get_model_field(field.source, queryset.model)
+
+            if model_field:
+                model_fields.append(model_field)
+
+                if (
+                    (field.field_name in serializer.expanded_fields) or
+                    (model_field.is_relation and not model_field.many_to_one) or
+                    (model_field.is_relation and model_field.many_to_one and not model_field.concrete)
+                ):  # Include GenericForeignKey
+                    nested_model_fields.append(model_field)
+
+        # Optimise queryset: restrict fetched columns via only().
+        if auto_remove_fields_from_query:
+            queryset = queryset.only(
+                *(
+                    required_query_fields
+                    + [
+                        model_field.name
+                        for model_field in model_fields if (
+                            not model_field.is_relation or
+                            model_field.many_to_one and model_field.concrete)
+                    ]
+                )
+            )
+
+        # Optimise queryset: prefetch relations via select_related() and prefetch_related().
+        if auto_select_related_on_query and nested_model_fields:
+            queryset = queryset.select_related(
+                *(
+                    model_field.name
+                    for model_field in nested_model_fields if (
+                            model_field.is_relation and
+                            model_field.many_to_one and
+                            model_field.concrete)  # Exclude GenericForeignKey
+                )
+            )
+
+            queryset = queryset.prefetch_related(
+                *(
+                    model_field.name
+                    for model_field in nested_model_fields if
+                        (model_field.is_relation and not model_field.many_to_one) or
+                        (model_field.is_relation and model_field.many_to_one and not model_field.concrete)  # Include GenericForeignKey)
+                )
+            )
+
+        return queryset
+

drf_flex_fields2-2.0.0/src/rest_flex_fields2/serializers.py

@@ -0,0 +1,449 @@
+"""Flex-fields serializer mixin and model serializer.
+
+Provides `FlexFieldsSerializerMixin` which adds ``fields``, ``omit``, and
+``expand`` support to any DRF serializer, and the ready-to-use
+`FlexFieldsModelSerializer` that combines the mixin with
+``serializers.ModelSerializer``.
+"""
+
+import copy
+import importlib
+from typing import List, Optional, Tuple, Type
+
+from rest_framework.serializers import (Serializer, ModelSerializer, ValidationError)
+
+from .config import (
+    EXPAND_PARAM,
+    FIELDS_PARAM,
+    MAXIMUM_EXPANSION_DEPTH,
+    OMIT_PARAM,
+    RECURSIVE_EXPANSION_PERMITTED,
+    WILDCARD_VALUES,
+)
+from .utils import split_levels
+
+
+class FlexFieldsSerializerMixin(Serializer):
+    """Mixin that adds sparse-fieldset and nested-expansion support to a serializer.
+
+    Accepts the ``fields``, ``omit``, and ``expand`` keyword arguments (names
+    are configurable via ``REST_FLEX_FIELDS2`` settings) both as constructor
+    kwargs and as query-string parameters on the current request.  Query
+    parameters are only read on the root serializer; nested serializers
+    receive their options through constructor kwargs propagated by the parent.
+
+    Declare expandable relations either on ``Meta.expandable_fields`` (preferred)
+    or directly on ``expandable_fields`` for backwards compatibility.
+    """
+
+    expandable_fields = {}
+    maximum_expansion_depth: Optional[int] = None
+    recursive_expansion_permitted: Optional[bool] = None
+
+    def __init__(self, *args, **kwargs):
+        """Initialize flex-fields options from kwargs and request query params."""
+        expand = list(kwargs.pop(EXPAND_PARAM, []))
+        fields = list(kwargs.pop(FIELDS_PARAM, []))
+        omit   = list(kwargs.pop(OMIT_PARAM, []))
+        parent = kwargs.pop("parent", None)
+
+        super().__init__(*args, **kwargs)
+
+        self.parent = parent
+        self.expanded_fields = []
+        self._flex_fields_rep_applied = False
+
+        self._flex_options_base = {
+            "expand": expand,
+            "fields": fields,
+            "omit":   omit,
+        }
+
+        self._flex_options_rep_only = {
+            "expand": self._get_permitted_expands_from_query_param(EXPAND_PARAM) if not expand else [],
+            "fields": self._get_query_param_value(FIELDS_PARAM) if not fields else [],
+            "omit":   self._get_query_param_value(OMIT_PARAM) if not omit else [],
+        }
+
+        self._flex_options_all = {
+            "expand": self._flex_options_base["expand"] + self._flex_options_rep_only["expand"],
+            "fields": self._flex_options_base["fields"] + self._flex_options_rep_only["fields"],
+            "omit":   self._flex_options_base["omit"]   + self._flex_options_rep_only["omit"],
+        }
+
+    def get_maximum_expansion_depth(self) -> Optional[int]:
+        """Return the effective maximum expansion depth.
+
+        Uses the serializer-level ``maximum_expansion_depth`` attribute when
+        set, otherwise falls back to the ``MAXIMUM_EXPANSION_DEPTH`` setting.
+        """
+        return self.maximum_expansion_depth or MAXIMUM_EXPANSION_DEPTH
+
+    def get_recursive_expansion_permitted(self) -> bool:
+        """Return whether recursive expansion is allowed.
+
+        Uses the serializer-level ``recursive_expansion_permitted`` attribute
+        when set, otherwise falls back to the ``RECURSIVE_EXPANSION_PERMITTED``
+        setting.
+        """
+        if self.recursive_expansion_permitted is not None:
+            return self.recursive_expansion_permitted
+        else:
+            return RECURSIVE_EXPANSION_PERMITTED
+
+    def to_representation(self, instance):
+        """Apply request-sourced flex-fields options once, then delegate to super."""
+        if not self._flex_fields_rep_applied:
+            self.apply_flex_fields(self.fields, self._flex_options_rep_only)
+            self._flex_fields_rep_applied = True
+
+        return super().to_representation(instance)
+
+    def get_fields(self):
+        """Return fields after applying constructor-sourced flex-fields options."""
+        fields = super().get_fields()
+        self.apply_flex_fields(fields, self._flex_options_base)
+        return fields
+
+    def apply_flex_fields(self, fields, flex_options):
+        """Apply sparse-fieldset and expansion options to `fields` in place.
+
+        Removes fields that are excluded by ``omit`` or not present in
+        ``fields`` (sparse-fieldset), then replaces fields listed in
+        ``expand`` with their nested serializer instances.
+        Returns the modified `fields` mapping.
+        """
+        expand_fields, next_expand_fields = split_levels(flex_options["expand"])
+        sparse_fields, next_sparse_fields = split_levels(flex_options["fields"])
+        omit_fields, next_omit_fields = split_levels(flex_options["omit"])
+
+        for field_name in self._get_fields_names_to_remove(
+            list(fields.keys()), omit_fields, sparse_fields, list(next_omit_fields.keys())
+        ):
+            fields.pop(field_name)
+
+        for name in self._get_expanded_field_names(
+            expand_fields, omit_fields, sparse_fields, list(next_omit_fields.keys())
+        ):
+            self.expanded_fields.append(name)
+
+            fields[name] = self._make_expanded_field_serializer(
+                name, next_expand_fields, next_sparse_fields, next_omit_fields
+            )
+
+        return fields
+
+    def _make_expanded_field_serializer(
+        self, name, nested_expand, nested_fields, nested_omit
+    ):
+        """Build and return the nested serializer instance for an expanded field.
+
+        Looks up `name` in ``_expandable_fields``, resolves any lazy string
+        path to a concrete class, then instantiates the serializer with the
+        appropriate ``context``, ``parent``, ``expand``, ``fields``, and
+        ``omit`` kwargs for the next nesting level.
+        """
+        field_options = self._expandable_fields[name]
+
+        if isinstance(field_options, tuple):
+            serializer_class = field_options[0]
+            settings = copy.deepcopy(field_options[1]) if len(field_options) > 1 else {}
+        else:
+            serializer_class = field_options
+            settings = {}
+
+        if isinstance(serializer_class, str):
+            serializer_class = self._get_serializer_class_from_lazy_string(serializer_class)
+
+        if issubclass(serializer_class, Serializer):
+            settings["context"] = self.context
+
+        if issubclass(serializer_class, FlexFieldsSerializerMixin):
+            settings["parent"] = self
+
+            if name in nested_expand:
+                settings[EXPAND_PARAM] = nested_expand[name]
+
+            if name in nested_fields:
+                settings[FIELDS_PARAM] = nested_fields[name]
+
+            if name in nested_omit:
+                settings[OMIT_PARAM] = nested_omit[name]
+
+        return serializer_class(**settings)
+
+    def _get_serializer_class_from_lazy_string(self, full_lazy_path: str) -> Type[Serializer]:
+        """Resolve a dotted string path to a serializer class.
+
+        Tries the exact path first; if that fails and the path does not
+        already end in ``.serializers``, appends ``.serializers`` and retries.
+        Raises ``Exception`` when the class cannot be found.
+        """
+        path_parts = full_lazy_path.split(".")
+        class_name = path_parts.pop()
+        path = ".".join(path_parts)
+        serializer_class, error = self._import_serializer_class(path, class_name)
+
+        if error and not path.endswith(".serializers"):
+            serializer_class, error = self._import_serializer_class(
+                path + ".serializers", class_name
+            )
+
+        if serializer_class:
+            return serializer_class
+
+        raise Exception(error)
+
+    def _import_serializer_class(self, path: str, class_name: str) -> Tuple[Optional[Type[Serializer]], Optional[str]]:
+        """Import `class_name` from the module at `path`.
+
+        Returns a ``(serializer_class, None)`` tuple on success, or
+        ``(None, error_message)`` when the module cannot be imported, the
+        attribute does not exist, or the attribute is not a
+        ``Serializer`` subclass.
+        """
+        try:
+            module = importlib.import_module(path)
+        except ImportError:
+            return None, f"No module found at path: {path} when trying to import {class_name}"
+
+        try:
+            resolved = getattr(module, class_name)
+        except AttributeError:
+            return None, f"No class {class_name} class found in module {path}"
+
+        # Validate that the resolved attribute is actually a serializer class
+        if not isinstance(resolved, type):
+            return None, f"Attribute {class_name} in module {path} is not a class"
+
+        if not issubclass(resolved, Serializer):
+            return None, f"Class {class_name} in module {path} is not a Serializer subclass"
+
+        return resolved, None
+
+    def _get_fields_names_to_remove(
+        self,
+        current_fields: List[str],
+        omit_fields: List[str],
+        sparse_fields: List[str],
+        next_level_omits: List[str],
+    ) -> List[str]:
+        """Return a list of field names that should be removed from the serializer.
+
+        A field is removed when it appears in `omit_fields`, or when
+        `sparse_fields` is non-empty and the field is not listed there.
+        Fields in `next_level_omits` are never removed at this level because
+        their omit rule targets a deeper nesting (e.g. ``omit=house.rooms.kitchen``
+        must not remove ``house`` or ``rooms``).
+        """
+        sparse = len(sparse_fields) > 0
+        to_remove = []
+
+        if not sparse and len(omit_fields) == 0:
+            return to_remove
+
+        for field_name in current_fields:
+            should_exist = self._should_field_exist(field_name, omit_fields, sparse_fields, next_level_omits)
+
+            if not should_exist:
+                to_remove.append(field_name)
+
+        return to_remove
+
+    def _should_field_exist(
+        self,
+        field_name: str,
+        omit_fields: List[str],
+        sparse_fields: List[str],
+        next_level_omits: List[str],
+    ) -> bool:
+        """Return whether `field_name` should be kept in the serializer output.
+
+        `next_level_omits` contains field names whose omit rule targets a
+        deeper nesting level; they must not be removed at the current level
+        (e.g. ``omit=house.rooms.kitchen`` must preserve ``house`` and
+        ``rooms``).
+        """
+        if field_name in omit_fields and field_name not in next_level_omits:
+            return False
+        elif self._contains_wildcard_value(sparse_fields):
+            return True
+        elif len(sparse_fields) > 0 and field_name not in sparse_fields:
+            return False
+        else:
+            return True
+
+    def _get_expanded_field_names(
+        self,
+        expand_fields: List[str],
+        omit_fields: List[str],
+        sparse_fields: List[str],
+        next_level_omits: List[str],
+    ) -> List[str]:
+        """Return the validated list of field names to expand.
+
+        Wildcards are resolved to all declared expandable field names.
+        Fields not present in ``_expandable_fields``, or excluded by the
+        sparse-fieldset / omit rules, are silently skipped.
+        """
+        if len(expand_fields) == 0:
+            return []
+
+        if self._contains_wildcard_value(expand_fields):
+            expand_fields = list(self._expandable_fields.keys())
+
+        expanded_field_names = []
+
+        for name in expand_fields:
+            if name not in self._expandable_fields:
+                continue
+
+            if not self._should_field_exist(
+                name, omit_fields, sparse_fields, next_level_omits
+            ):
+                continue
+
+            expanded_field_names.append(name)
+
+        return expanded_field_names
+
+    @property
+    def _expandable_fields(self) -> dict:
+        """Return the mapping of expandable field names to their serializer config.
+
+        Prefers ``Meta.expandable_fields`` for consistency with the DRF
+        convention of placing serializer metadata on the inner ``Meta`` class.
+        Falls back to the class-level ``expandable_fields`` attribute for
+        backwards compatibility.
+        """
+        meta = getattr(self, "Meta", None)
+
+        if meta is not None and hasattr(meta, "expandable_fields"):
+            return meta.expandable_fields
+
+        return self.expandable_fields
+
+    def _get_query_param_value(self, field: str) -> List[str]:
+        """Return the parsed query-parameter values for `field`.
+
+        Only reads query parameters on the root serializer (i.e. when
+        ``self.parent`` is ``None``).  Supports both plain repeated params
+        (``field=a,b``) and bracket-style params (``field[]=a``).  Runs
+        recursive-expansion and depth validation on every returned path.
+        Returns an empty list when the parameter is absent or this is a
+        nested serializer.
+        """
+        if self.parent:
+            return []
+
+        if not hasattr(self, "context") or not self.context.get("request"):
+            return []
+
+        values = self.context["request"].query_params.getlist(field)
+
+        if not values:
+            values = self.context["request"].query_params.getlist(f"{field}[]")
+
+        if values and len(values) == 1:
+            values = values[0].split(",")
+
+        for expand_path in values:
+            self._validate_recursive_expansion(expand_path)
+            self._validate_expansion_depth(expand_path)
+
+        return values or []
+
+    def _split_expand_field(self, expand_path: str) -> List[str]:
+        """Split a dot-separated expand path into its individual segments."""
+        return expand_path.split(".")  # noqa: E501
+
+    def recursive_expansion_not_permitted(self):
+        """Raise a validation error indicating recursive expansion.
+
+        Override this method to raise a custom exception instead of the
+        default ``ValidationError``.
+        """
+        raise ValidationError(detail="Recursive expansion found")
+
+    def _validate_recursive_expansion(self, expand_path: str) -> None:
+        """Raise when `expand_path` contains a repeated segment.
+
+        Parses the dot-separated `expand_path` and checks for duplicate
+        segments.  Does nothing when recursive expansion is permitted
+        (``RECURSIVE_EXPANSION_PERMITTED`` is ``True``).
+        """
+        recursive_expansion_permitted = self.get_recursive_expansion_permitted()
+        if recursive_expansion_permitted is True:
+            return
+
+        expansion_path = self._split_expand_field(expand_path)
+        expansion_length = len(expansion_path)
+        expansion_length_unique = len(set(expansion_path))
+
+        if expansion_length != expansion_length_unique:
+            self.recursive_expansion_not_permitted()
+
+    def expansion_depth_exceeded(self):
+        """Raise a validation error indicating the expansion depth limit was exceeded.
+
+        Override this method to raise a custom exception instead of the
+        default ``ValidationError``.
+        """
+        raise ValidationError(detail="Expansion depth exceeded")
+
+    def _validate_expansion_depth(self, expand_path: str) -> None:
+        """Raise when `expand_path` exceeds the configured maximum depth.
+
+        Counts the dot-separated segments of `expand_path` and compares
+        against ``get_maximum_expansion_depth()``.  Does nothing when no
+        maximum depth is configured.
+        """
+        maximum_expansion_depth = self.get_maximum_expansion_depth()
+        if maximum_expansion_depth is None:
+            return
+
+        expansion_path = self._split_expand_field(expand_path)
+        if len(expansion_path) > maximum_expansion_depth:
+            self.expansion_depth_exceeded()
+
+    def _get_permitted_expands_from_query_param(self, expand_param: str) -> List[str]:
+        """Return the expand list filtered by ``permitted_expands`` from context.
+
+        When ``permitted_expands`` is present in the serializer context (e.g.
+        set by `FlexFieldsMixin` for list actions), wildcard expansion is
+        resolved to the full permitted list, and any other values are
+        intersected with it.  Returns the unfiltered expand list when no
+        permission constraint is active.
+        """
+        expand = self._get_query_param_value(expand_param)
+
+        if "permitted_expands" in self.context:
+            permitted_expands = self.context["permitted_expands"]
+
+            if self._contains_wildcard_value(expand):
+                return permitted_expands
+            else:
+                return list(set(expand) & set(permitted_expands))
+
+        return expand
+
+    def _contains_wildcard_value(self, expand_values: List[str]) -> bool:
+        """Return whether `expand_values` contains any configured wildcard token.
+
+        Always returns ``False`` when ``WILDCARD_VALUES`` is ``None``
+        (wildcards disabled).
+        """
+        if WILDCARD_VALUES is None:
+            return False
+
+        intersecting_values = list(set(expand_values) & set(WILDCARD_VALUES))
+        return len(intersecting_values) > 0
+
+
+class FlexFieldsModelSerializer(FlexFieldsSerializerMixin, ModelSerializer):
+    """Convenience serializer combining `FlexFieldsSerializerMixin` with ``ModelSerializer``.
+
+    Drop-in replacement for ``serializers.ModelSerializer`` that adds
+    sparse-fieldset (``fields``, ``omit``) and nested-expansion (``expand``)
+    support out of the box.
+    """

drf_flex_fields2-2.0.0/src/rest_flex_fields2/utils.py

@@ -0,0 +1,92 @@
+"""Utility helpers for ``rest_flex_fields2``.
+
+Provides request-inspection functions (`is_expanded`, `is_included`) and
+the `split_levels` helper that partitions dot-notation field lists into
+current-level and next-level fragments.
+"""
+
+from collections.abc import Iterable
+
+from .config import EXPAND_PARAM, FIELDS_PARAM, OMIT_PARAM, WILDCARD_VALUES
+
+
+def is_expanded(request, field: str) -> bool:
+    """Return whether `field` is requested for expansion.
+
+    Inspects the ``expand`` query parameter on `request`.  Returns
+    ``True`` when `field` appears in the comma-separated expand list, or
+    when a wildcard value (e.g. ``*`` or ``~all``) is present.
+    """
+    expand_value = request.query_params.get(EXPAND_PARAM)
+    expand_fields = []
+
+    if expand_value:
+        for f in expand_value.split(","):
+            expand_fields.extend([_ for _ in f.split(".")])
+
+    wildcard_values = WILDCARD_VALUES or []
+    return any(field for field in expand_fields if field in wildcard_values) or field in expand_fields
+
+
+def is_included(request, field: str) -> bool:
+    """Return whether `field` should be included in the response.
+
+    Returns ``False`` when the ``fields`` sparse-fieldset parameter is
+    present and `field` is not listed, or when the ``omit`` parameter is
+    present and `field` is listed.  Returns ``True`` otherwise.
+    """
+    sparse_value = request.query_params.get(FIELDS_PARAM)
+    omit_value = request.query_params.get(OMIT_PARAM)
+    sparse_fields, omit_fields = [], []
+
+    if sparse_value:
+        for f in sparse_value.split(","):
+            sparse_fields.extend([_ for _ in f.split(".")])
+
+    if omit_value:
+        for f in omit_value.split(","):
+            omit_fields.extend([_ for _ in f.split(".")])
+
+    if len(sparse_fields) > 0 and field not in sparse_fields:
+        return False
+
+    if len(omit_fields) > 0 and field in omit_fields:
+        return False
+
+    return True
+
+
+def split_levels(
+    fields: str | Iterable[str],
+) -> tuple[list[str], dict[str, list[str]]]:
+    """Split a dot-notation field list into current-level and next-level parts.
+
+    Given an iterable such as ``['a', 'a.b', 'a.d', 'c']``, returns a
+    tuple ``(first_level, next_level)`` where ``first_level`` is the
+    deduplicated list of top-level names (e.g. ``['a', 'c']``) and
+    ``next_level`` is a dict mapping each name to its remaining path
+    fragments (e.g. ``{'a': ['b', 'd']}``).  A plain string is treated
+    as a comma-separated field list.
+    """
+    first_level_fields: list[str] = []
+    next_level_fields: dict[str, list[str]] = {}
+
+    if not fields:
+        return first_level_fields, next_level_fields
+
+    assert isinstance(
+        fields, Iterable
+    ), "`fields` must be iterable (e.g. list, tuple, or generator)"
+
+    if isinstance(fields, str):
+        fields = [a.strip() for a in fields.split(",") if a.strip()]
+    for e in fields:
+        if "." in e:
+            first_level, next_level = e.split(".", 1)
+            first_level_fields.append(first_level)
+            next_level_fields.setdefault(first_level, []).append(next_level)
+        else:
+            first_level_fields.append(e)
+
+    first_level_fields = list(set(first_level_fields))
+    return first_level_fields, next_level_fields

drf_flex_fields2-2.0.0/src/rest_flex_fields2/views.py

@@ -0,0 +1,44 @@
+"""Flex-fields view mixin and model view set.
+
+Provides `FlexFieldsMixin` for controlling per-action expansion permissions
+and the ready-to-use `FlexFieldsModelViewSet` that combines the mixin with
+``ModelViewSet`` from Django REST Framework.
+"""
+
+from typing import Any
+from rest_framework.viewsets import ModelViewSet
+
+
+class FlexFieldsMixin:
+    """View mixin that restricts which fields may be expanded on list actions.
+
+    Set ``permit_list_expands`` to a list of field names that are allowed to
+    be expanded when the view is handling a ``list`` request.  The allowed
+    names are passed to the serializer via ``context['permitted_expands']``
+    so that `FlexFieldsSerializerMixin` can enforce the constraint.
+    """
+    permit_list_expands: list[str] = []
+    action: str | None = None
+
+    def get_serializer_context(self) -> dict[str, Any]:
+        """Extend the serializer context with ``permitted_expands`` for list actions.
+
+        When the current action is ``list``, adds
+        ``context['permitted_expands']`` populated from ``permit_list_expands``
+        so the serializer can restrict expansion accordingly.
+        """
+        default_context = super().get_serializer_context()  # type: ignore[misc]
+
+        if hasattr(self, "action") and self.action == "list":
+            default_context["permitted_expands"] = self.permit_list_expands
+
+        return default_context
+
+
+class FlexFieldsModelViewSet(FlexFieldsMixin, ModelViewSet):
+    """Convenience view set combining `FlexFieldsMixin` with ``ModelViewSet``.
+
+    Drop-in replacement for ``viewsets.ModelViewSet`` with list-action
+    expansion control provided by `FlexFieldsMixin`.
+    """
+