ListModelView

Guide to implementing and utilizing the ListModelView in Django Ninja CRUD

ListModelView

Python

class ListModelView(AbstractModelView)

A view class that handles listing instances of a model.
It allows customization through a queryset getter and also supports decorators.

Example:

Python

from ninja_crud import views, viewsets

from examples.models import Department, Employee
from examples.schemas import DepartmentOut, EmployeeOut

class DepartmentViewSet(viewsets.ModelViewSet):
    model = Department

    # Basic usage: List all departments
    # GET /departments/
    list_departments_view = views.ListModelView(output_schema=DepartmentOut)

    # Advanced usage: List employees of a specific department
    # GET /departments/{id}/employees/
    list_employees_view = views.ListModelView(
        detail=True,
        queryset_getter=lambda id: Employee.objects.filter(department_id=id),
        output_schema=EmployeeOut,
    )

__init__

Python

def __init__(output_schema: Optional[Type[Schema]] = None,
             filter_schema: Optional[Type[FilterSchema]] = None,
             detail: bool = False,
             queryset_getter: Union[DetailQuerySetGetter,
                                    CollectionQuerySetGetter, None] = None,
             pagination_class: Optional[
                 Type[PaginationBase]] = LimitOffsetPagination,
             path: Optional[str] = None,
             decorators: Optional[List[Callable]] = None,
             router_kwargs: Optional[dict] = None) -> None

Initializes the ListModelView.

Arguments:

• output_schema Optional[Type[Schema]], optional - The schema used to serialize the retrieved objects.
  Defaults to None. If not provided, the default_output_schema of the ModelViewSet will be used.

• filter_schema Optional[Type[FilterSchema]], optional - The schema used to validate the filters.

• detail bool, optional - Whether the view is a detail or collection view. Defaults to False.

  If set to True, queryset_getter must be provided.

• queryset_getter Union[DetailQuerySetGetter, CollectionQuerySetGetter, None], optional - A
  function to customize the queryset used for retrieving the objects. Defaults to None.
  The function should have one of the following signatures:

  • For detail=False: () -> QuerySet[Model]
  • For detail=True: (id: Any) -> QuerySet[Model]

  If not provided, the default manager of the model specified in the ModelViewSet will be used.

• pagination_class Optional[Type[PaginationBase]], optional - The pagination class to use for the view.
  Defaults to LimitOffsetPagination.

• path Optional[str], optional - The path to use for the view. Defaults to:

  • For detail=False: "/"
  • For detail=True: "/{id}/{related_model_name_plural_to_snake_case}/"

  Where related_model_name_plural_to_snake_case refers to the plural form of the related model's name,
  converted to snake_case. For example, for a related model "ItemDetail", the path might look like
  "/{id}/item_details/".

• decorators Optional[List[Callable]], optional - A list of decorators to apply to the view. Defaults to [].

• router_kwargs Optional[dict], optional - Additional arguments to pass to the router. Defaults to {}.
  Overrides are allowed for most arguments except 'path', 'methods', and 'response'. If any of these
  arguments are provided, a warning will be logged and the override will be ignored.

get_response

Python

def get_response() -> dict

Provides a mapping of HTTP status codes to response schemas for the list view.

This response schema is used in API documentation to describe the response body for this view.
The response schema is critical and cannot be overridden using router_kwargs. Any overrides
will be ignored.

Returns:

• dict - A mapping of HTTP status codes to response schemas for the list view.
  Defaults to {200: List[self.output_schema]}. For example, for a model "Department", the response
  schema would be {200: List[DepartmentOut]}.

get_operation_id

Python

def get_operation_id(model_class: Type[Model]) -> str

Provides an operation ID for the list view.

This operation ID is used in API documentation to uniquely identify this view.
It can be overriden using the router_kwargs.

Arguments:

• model_class Type[Model] - The Django model class associated with this view.

Returns:

• str - The operation ID for the list view. Defaults to:
  • For detail=False: "list_{model_name_to_snake_case}s". For example, for a model "Department",
    the operation ID would be "list_departments".
  • For detail=True: "list{model_name_to_snake_case}{related_model_name_to_snake_case}s". For
    example, for a model "Department" with a related model "Item", the operation ID would be
    "list_department_items".

get_summary

Python

def get_summary(model_class: Type[Model]) -> str

Provides a summary description for the list view.

This summary is used in API documentation to give a brief description of what this view does.
It can be overriden using the router_kwargs.

Arguments:

• model_class Type[Model] - The Django model class associated with this view.

Returns:

• str - The summary description for the list view. Defaults to:
  • For detail=False: "List {model_name_plural}". For example, for a model "Department",
    the summary would be "List Departments".
  • For detail=True: "List {related_model_name_plural} related to a {model_name}". For example,
    for a model "Department" with a related model "Item", the summary would be
    "List Items related to a Department".