django-allresponses 0.1.0

Django response classes for all RFC9110 HTTP status codes

django-allresponses

A Django package that provides response classes for all RFC 9110 HTTP status codes.

Features

• Response classes for all RFC 9110 HTTP status codes
• Compatible with Django 4.2 LTS and later versions
• Full test coverage
• Type hints included

Installation

uv add django-allresponses

# or with pip

pip install django-allresponses

Usage

All response classes in this package are subclasses of Django’s HttpResponse. You can use them anywhere you would use a normal HttpResponse, and they work with Django’s middleware and testing tools.

For HTML or other content, use the HttpResponse-prefixed classes:

from django_allresponses import HttpResponseOK, HttpResponseNoContent, HttpResponseCreated

def my_view(request):
    # Return a 200 OK response (explicit status)
    return HttpResponseOK("<p>Hello</p>")

    # Or 204 No Content
    return HttpResponseNoContent()
    # Or 201 Created with a Location header
    return HttpResponseCreated(location='/api/resource/123')

For JSON APIs, use the JsonResponse-prefixed classes (they subclass Django’s JsonResponse and set the status code for you):

from django_allresponses import JsonResponseOK, JsonResponseCreated, JsonResponseUnauthorized

def api_view(request):
    if not request.user.is_authenticated:
        return JsonResponseUnauthorized({"error": "Authentication required"})
    data = {"id": 123, "name": "Example"}
    return JsonResponseCreated(data, location="/api/items/123")

Why this package?

Basically, because Django has a whole bunch of custom HttpResponse subclasses, for BadRequest, for ResponseNotFound, for ResponseNotModified and so on.

But for some very standard response codes such as No Content (HTTP 204) and Created (HTTP 201) there are no subclasses. In RESTy systems I use these response codes all the time.

It feels very arbitrary that some classes exist and others don't.

Of course I can make my own subclass and use that but I would like Django to have it built-in. So I opened a discussion about this:

https://forum.djangoproject.com/t/proposal-or-discussion-add-subclasses-for-no-content-and-created-httpresponses/39020

TL;DR: people do not find it is 'worth it' to add these response codes that are used a lot, because you could just as well write your own, or use the 'generic' HTTPResponse and add a custom code.

That's all fair, but I do think that custom classes have other benefits too. I think it's beneficial to list the responses that you can choose from all in one place, instead of having a specific response for Gone (HTTP 410) but none for Created.

So I went all maximalist and added a complete list of all RFC9110 HTTP status codes as subclasses in this django-allresponses module. Many of those will probably never be used at all, which I think is fine, but at least now you'll have one easy way to refer to all possible HTTP responses in one go!

Several subclasses add real behaviour on top of the status code, so they are not just “a status number in a class”. For example: 204 No Content and 205 Reset Content strip the Content-Type header and forbid setting a response body; 201 Created requires a location and sets the Location header; 405 Method Not Allowed requires the list of allowed methods and sets the Allow header (as required by RFC 9110); 503 Service Unavailable accepts an optional retry_after keyword (seconds or a datetime) and sets the Retry-After header. Using these classes keeps your responses spec-compliant and consistent. Plus the explicit status names also help with readability of your code!

One last benefit of using this module is that some HTTP status codes changed name in different RFCs. Django being a seasoned project is using th e 'older' names for HTTP statuses. Our module uses newer names. For example, Django's HttpResponsePermanentRedirect returns a 302 by default but 302 is now "Found". Our HttpResponsePermanentRedirect returns 308, and we also include HttpResponseFound which returns 302 for when you might need it.

Development

This project uses uv for dependency management and hatch for building. A Makefile wraps the common commands (run make help for a list).

To set up the development environment:

# Install uv if you haven't already
pip install uv

# Create a virtual environment and install dependencies
uv venv
source .venv/bin/activate  # On Unix/macOS
# or
.venv\Scripts\activate  # On Windows

# Install dependencies
make install
# Or with dev tools (pytest, pdoc, ruff, ty):  make install-dev

Running tests

Run from the project root (the directory that contains manage.py and the Makefile).

make test          # Django test runner (no extra deps)
make test-pytest   # Pytest (needs: make install-dev)

The test suite uses a minimal Django project under tests/ (tests/settings.py and the tests app). Django needs DJANGO_SETTINGS_MODULE=tests.settings, which manage.py sets automatically; pytest uses the same via pyproject.toml.

Building the documentation site

Docstrings on every response class explain when and why to use that status code; they appear in your editor (e.g. hover) and can be turned into a static documentation site with Zensical (MkDocs-compatible) and mkdocstrings.

make install-deps  # once: install zensical and other dev deps
make docs         # build HTML into site/
make serve-docs   # serve docs in the browser at http://localhost:8080

Type checking

Type checking uses ty (Astral’s type checker). Run from the project root (requires dev deps):

make install-dev   # once: install ty and other dev deps
make typecheck     # uv run ty check .

After make docs, open site/index.html in a browser, or run make serve-docs to preview with live reload. Source lives in docs/; Zensical writes the built site to site/ (in .gitignore). The project uses Zensical (from the Material for MkDocs team), which reads mkdocs.yml directly. Building the docs requires Python 3.10+ (the runtime package still supports 3.8+).

License

MIT License