Returning files

We support file and other binary responses.

Warning

Returning files via Python and Django in particular is very performance inefficient. It should not be used for anything serious.

Instead return files with S3-like systems or at least on a proxy-server level.

To do so, you indicate that you will return a file with dmr.files.FileResponseSpec and specify a renderer file renderer. We provide dmr.renderers.FileRenderer for this case. It can also accept a specific content_type to render:

views.py

Show imports... 10 lines hidden

[source]

import pathlib
from typing import Final

from django.http import FileResponse

from dmr import Controller, validate
from dmr.files import FileResponseSpec
from dmr.plugins.pydantic import PydanticSerializer
from dmr.renderers import FileRenderer

_FILEPATH: Final = pathlib.Path('examples/components/receipt.txt')


class FileController(Controller[PydanticSerializer]):
    @validate(
        FileResponseSpec(),
        renderers=[FileRenderer('text/plain')],
    )
    def get(self) -> FileResponse:
        return FileResponse(
            _FILEPATH.open(mode='rb'),
            filename='receipt.txt',
            as_attachment=True,
            content_type='text/plain',
        )

Run result

$ curl http://127.0.0.1:8000/api/file/ -D - -X GET
HTTP/1.1 200 OK
date: Sun, 29 Mar 2026 18:53:23 GMT
server: uvicorn
Content-Type: text/plain
Content-Length: 16
Content-Disposition: attachment; filename="receipt.txt"
X-Frame-Options: DENY
Vary: Accept-Language
Content-Language: en
X-Content-Type-Options: nosniff
Referrer-Policy: same-origin
Cross-Origin-Opener-Policy: same-origin

Example receipt

OpenAPI Schema

Preview openapi.json

{
  "components": {
    "schemas": {
      "ErrorDetail": {
        "description": "Base schema for error details description.",
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "string"
                }
              ]
            },
            "title": "Loc",
            "type": "array"
          },
          "msg": {
            "title": "Msg",
            "type": "string"
          },
          "type": {
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "msg"
        ],
        "title": "ErrorDetail",
        "type": "object"
      },
      "ErrorModel": {
        "description": "Default error response schema.\n\nCan be customized.\nSee :ref:`customizing-error-messages` for more details.",
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ErrorDetail"
            },
            "title": "Detail",
            "type": "array"
          }
        },
        "required": [
          "detail"
        ],
        "title": "ErrorModel",
        "type": "object"
      }
    },
    "securitySchemes": {}
  },
  "info": {
    "title": "Django Modern Rest",
    "version": "0.1.0"
  },
  "openapi": "3.2.0",
  "paths": {
    "/api/filecontroller/": {
      "get": {
        "deprecated": false,
        "operationId": "getFilecontrollerApiFilecontroller",
        "responses": {
          "200": {
            "content": {
              "text/plain": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              }
            },
            "description": "OK",
            "headers": {
              "Content-Disposition": {
                "required": true,
                "schema": {
                  "type": "string"
                }
              },
              "Content-Length": {
                "required": true,
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "406": {
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when provided `Accept` header cannot be satisfied"
          },
          "422": {
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when returned response does not match the response schema"
          }
        }
      }
    }
  }
}

API Reference

class dmr.files.FileBody

Special type that indicates that response returns a file body.

classmethod encoding(model: Any, schema: Schema) → dict[str, Encoding] | None

Returns the openapi encoding for the defined media type.

classmethod get_schema(schema: Schema | Reference, context: OpenAPIContext) → Schema

Returns the openapi schema that this object represents.

classmethod media_type(schema: Schema | Reference, model: Any, model_meta: tuple[Any, ...], parser: Parser, context: OpenAPIContext) → MediaType

Returns the media type for the given file.

class dmr.files.FileResponseSpec(return_type: type[FileBody] = <class 'dmr.files.FileBody'>, *, status_code: HTTPStatus = HTTPStatus.OK, headers: Mapping[str, ~dmr.headers.HeaderSpec] | None=<factory>, cookies: Mapping[str, CookieSpec] | None=None, limit_to_content_types: Set[str] | None = None, streaming: bool = False, description: str | None = None, links: dict[str, Link | Reference] | None=None, file_body: type[FileBody] = <class 'dmr.files.FileBody'>)

Special ResponseSpec subclass for files.

file_body

Model to be used for file body schema generation.

Type:

type[dmr.files.FileBody]

get_schema(metadata: EndpointMetadata, serializer: type[BaseSerializer], context: OpenAPIContext) → Response

Customize schema for the file response.