ListView

Guide to implementing and utilizing the ListView in Django Ninja CRUD

ListView

Python

class ListView(APIView)

Declarative class-based view for listing model instances in Django Ninja.

This class provides a standard implementation for a list view, which retrieves
a queryset of model instances based on path and query parameters provided in the
URL. It is intended to be used in viewsets or as standalone views to simplify the
creation of list endpoints.

Arguments:

• name str | None, optional - View function name. Defaults to None. If None,
  uses class attribute name in viewsets or "handler" for standalone views.
• methods List[str], optional - HTTP methods. Defaults to ["GET"].
• path str, optional - URL path. Defaults to "/".
• response_status int, optional - HTTP response status code. Defaults to 200.
• response_body Type | None, optional - Response body type. Defaults to None.
  If None, uses the default response body of the viewset as a list type.
• path_parameters Type[BaseModel] | None, optional - Path parameters type.
  Defaults to None. If not provided, resolved from the path and model.
• query_parameters Type[BaseModel] | None, optional - Query parameters type.
  Defaults to None.
• model Type[django.db.models.Model] | None, optional - Associated Django model.
  Inherits from viewset if not provided. Defaults to None.
• get_queryset Callable | None, optional - Callable to retrieve the queryset.
  Default uses self.model.objects.get_queryset(). Useful for selecting
  related models or optimizing queries. Should have the signature:
  • (request: HttpRequest, path_parameters: Optional[BaseModel]) -> QuerySet
• filter_queryset Callable | None, optional - Callable to filter the queryset.
  Default uses query_parameters.filter(queryset) if query_parameters is a
  ninja.FilterSchema, otherwise filters the queryset based on the query
  parameters as keyword arguments:
  queryset.filter(**query_parameters.model_dump(exclude_unset=True)).
  Should have the signature:
  • (queryset: QuerySet, query_parameters: Optional[BaseModel]) -> QuerySet
• pagination_class Type[PaginationBase] | None, optional - Pagination class.
  Defaults to LimitOffsetPagination. If None, no pagination is applied.
• decorators List[Callable] | None, optional - View function decorators
  (applied in reverse order). Defaults to None.
• operation_kwargs Dict[str, Any] | None, optional - Additional operation
  keyword arguments. Defaults to None.

Example:

Python

from ninja import NinjaAPI
from ninja_crud import views, viewsets

from examples.models import Department
from examples.schemas import DepartmentOut

api = NinjaAPI()

# Usage as a class attribute in a viewset:
class DepartmentViewSet(viewsets.APIViewSet):
    api = api
    model = Department
    default_response_body = DepartmentOut

    list_departments = views.ListView()

# Usage as a standalone view:
views.ListView(
    name="list_departments",
    model=Department,
    response_body=List[DepartmentOut],
).add_view_to(api)

set_api_viewset_class

Python

def set_api_viewset_class(api_viewset_class: Type["APIViewSet"]) -> None

Bind the view to a viewset class.

This method sets the model and path parameters type based on the viewset class,
and assigns the response body from the viewset class's default_response_body
as a list type if the response body is not already set.

Notes:

This method is called internally and automatically by the viewset when
defining views as class attributes. It should not be called manually.