Micro-framework out of Django#

Single file Django#

You don’t need microframeworks to build small APIs, because Django is a microframework itself. With the only difference: it scales!

[source]

import secrets
import sys
import uuid

import pydantic
from django.conf import settings
from django.core.management import execute_from_command_line

from dmr import Body, Controller
from dmr.openapi import build_schema
from dmr.openapi.views import OpenAPIJsonView, SwaggerView
from dmr.plugins.pydantic import PydanticFastSerializer
from dmr.routing import Router, path

if not settings.configured:
    settings.configure(
        ROOT_URLCONF=__name__,
        ALLOWED_HOSTS='*',
        DEBUG=True,
        INSTALLED_APPS=['dmr', 'django.contrib.staticfiles'],
        STATIC_URL='/static/',
        STATICFILES_FINDERS=[
            'django.contrib.staticfiles.finders.AppDirectoriesFinder',
        ],
        TEMPLATES=[
            {
                'APP_DIRS': True,
                'BACKEND': 'django.template.backends.django.DjangoTemplates',
            },
        ],
        # Secret key for tests, will be new on each run,
        # in production it must be the same token, kept in secret:
        SECRET_KEY=secrets.token_hex(),
    )


class UserCreateModel(pydantic.BaseModel):
    email: str


class UserResponseModel(UserCreateModel):
    uid: uuid.UUID


class UserController(Controller[PydanticFastSerializer]):
    async def post(
        self,
        parsed_body: Body[UserCreateModel],
    ) -> UserResponseModel:
        return UserResponseModel(uid=uuid.uuid4(), email=parsed_body.email)


router = Router(
    'api/',
    [
        path('user/', UserController.as_view(), name='users'),
    ],
)
schema = build_schema(router)

urlpatterns = [
    router.to_urlpatterns(namespace='api'),
    path('docs/openapi.json/', OpenAPIJsonView.as_view(schema), name='openapi'),
    path('docs/swagger/', SwaggerView.as_view(schema), name='swagger'),
]

if __name__ == '__main__':
    # Use `python THIS_FILE_NAME.py runserver` to run the example.
    # Then visit `http://localhost:8000/docs/swagger` to view the docs.
    execute_from_command_line(sys.argv)

Run result

$ curl http://127.0.0.1:8000/api/user/ -X POST -d '{"email": "djangomodernrest@wemake.services"}' -H 'Content-Type: application/json'
{"email":"djangomodernrest@wemake.services","uid":"b2655eac-4691-460b-9847-77f1319008a9"}

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"
      },
      "UserCreateModel": {
        "properties": {
          "email": {
            "title": "Email",
            "type": "string"
          }
        },
        "required": [
          "email"
        ],
        "title": "UserCreateModel",
        "type": "object"
      },
      "UserResponseModel": {
        "properties": {
          "email": {
            "title": "Email",
            "type": "string"
          },
          "uid": {
            "format": "uuid",
            "title": "Uid",
            "type": "string"
          }
        },
        "required": [
          "email",
          "uid"
        ],
        "title": "UserResponseModel",
        "type": "object"
      }
    }
  },
  "info": {
    "title": "Django Modern Rest",
    "version": "0.1.0"
  },
  "openapi": "3.2.0",
  "paths": {
    "/api/user/": {
      "post": {
        "operationId": "postUserControllerApiUser",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UserCreateModel"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserResponseModel"
                }
              }
            },
            "description": "Created"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when request components cannot be parsed"
          },
          "406": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when provided `Accept` header cannot be satisfied"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when returned response does not match the response schema"
          }
        }
      }
    }
  }
}

Microframeworks#

The single file example above is already a complete microframework app. But if you are reaching for one of the popular microframework styles, django-modern-rest drops into both without any special glue:

µDjango is a demo of exactly this idea: a whole Django app in a single file, exposed as a plain ASGIHandler and served by any ASGI server.

It is not a package you install, so there is nothing to integrate with. It is a shape your own file can take, and django-modern-rest fits into it without any glue code:

[source]

import secrets
import uuid

import django
import pydantic
from django.conf import settings
from django.core.handlers.asgi import ASGIHandler

from dmr import Body, Controller
from dmr.plugins.pydantic import PydanticFastSerializer
from dmr.routing import path

if not settings.configured:
    settings.configure(
        ROOT_URLCONF=__name__,
        ALLOWED_HOSTS='*',
        DEBUG=True,
        INSTALLED_APPS=['dmr'],
        # Secret key for tests, will be new on each run,
        # in production it must be the same token, kept in secret:
        SECRET_KEY=secrets.token_hex(),
    )
    django.setup()


class UserCreateModel(pydantic.BaseModel):
    email: str


class UserResponseModel(UserCreateModel):
    uid: uuid.UUID


class UserController(Controller[PydanticFastSerializer]):
    async def post(
        self,
        parsed_body: Body[UserCreateModel],
    ) -> UserResponseModel:
        return UserResponseModel(uid=uuid.uuid4(), email=parsed_body.email)


urlpatterns = [
    path('user/', UserController.as_view(), name='users'),
]

# Use `uvicorn udjango_style_asgi:app --reload` to run the example.
app = ASGIHandler()

Run result

$ curl http://127.0.0.1:8000/user/ -X POST -d '{"email": "djangomodernrest@wemake.services"}' -H 'Content-Type: application/json'
{"email":"djangomodernrest@wemake.services","uid":"dc8029ef-19d8-43d3-b0a0-98fd186231ae"}

Run it with any ASGI server:

uvicorn udjango_style_asgi:app --reload

Note

µDjango itself is explicitly a demonstration project and is not meant for production. The pattern it shows, however, is just regular Django.

nanodjango is a real package that wraps the single file idea into a Flask-like API: it configures the settings for you and collects urls via decorators.

Two things are needed to use it with django-modern-rest:

Add dmr to EXTRA_APPS, so its templates and static files are found. EXTRA_APPS is appended to nanodjango’s own INSTALLED_APPS defaults
Mount a Router with app.path() called as a function with include(), not as a decorator

[source]

import secrets
import uuid

import pydantic
from django.urls import include
from nanodjango import Django

from dmr import Body, Controller
from dmr.openapi import build_schema
from dmr.openapi.views import OpenAPIJsonView, SwaggerView
from dmr.plugins.pydantic import PydanticFastSerializer
from dmr.routing import Router, path

app = Django(
    # `dmr` must be in `INSTALLED_APPS` for its templates and static files:
    EXTRA_APPS=['dmr'],
    ALLOWED_HOSTS=['*'],
    # Secret key for tests, will be new on each run,
    # in production it must be the same token, kept in secret:
    SECRET_KEY=secrets.token_hex(),
)


class UserCreateModel(pydantic.BaseModel):
    email: str


class UserResponseModel(UserCreateModel):
    uid: uuid.UUID


class UserController(Controller[PydanticFastSerializer]):
    async def post(
        self,
        parsed_body: Body[UserCreateModel],
    ) -> UserResponseModel:
        return UserResponseModel(uid=uuid.uuid4(), email=parsed_body.email)


router = Router(
    'api/',
    [
        path('user/', UserController.as_view(), name='users'),
    ],
)
schema = build_schema(router)

# `app.path()` is called as a function here, not as a decorator,
# because we mount whole url confs instead of single views:
app.path(router.to_urlpatterns(namespace='api'))
app.path(
    'docs/',
    include(
        [
            path('openapi.json/', OpenAPIJsonView.as_view(schema)),
            path('swagger/', SwaggerView.as_view(schema)),
        ],
    ),
)

if __name__ == '__main__':
    # Use `python nanodjango_app.py` to run the example.
    # Then visit `http://localhost:8000/docs/swagger/` to view the docs.
    app.run()

Single controllers can also be registered with the decorator form, since app.path() handles class-based views:

@app.path('user/')
class UserController(Controller[PydanticFastSerializer]): ...

But you lose the OpenAPI schema this way, because it is built from a Router.

Warning

app.run() picks uvicorn over Django’s runserver only when nanodjango detects async views, and it detects them by inspecting the functions passed to its own decorators. Controllers mounted via include() are invisible to that check, so an app with only async controllers will still be served over WSGI.

Async views keep working, Django adapts them. But to actually serve them over ASGI, run the app directly:

uvicorn nanodjango_app:app.asgi --interface asgi3

Note that app.asgi serves in nanodjango’s production mode, where static files are served by whitenoise from STATIC_ROOT. Run app.manage(['collectstatic']) once beforehand, otherwise the Swagger UI assets will 404.

Scaling it for real projects#

However, all projects tend to grow while they are alive. Microframeworks handle the scale poorly, because they are not designed for this task.

We recommend using https://github.com/wemake-services/wemake-django-template to set up production ready Django boilerplate code with all the best practices.

It can handle any scale!