Proposal: Add Static Type Annotations to Django Core (Phase-wise Plan)

[Kapil Dagur]

Introduction

My name is Kapil Dagur. I’ve been using Django for over three years, and over the past two years, I’ve spent significant time understanding its core internals and architecture.

This proposal outlines a plan to gradually introduce static type annotations into Django’s codebase in a structured and non-intrusive way. The goal is to enhance code clarity, improve tooling support, and help both users and contributors—while preserving Django’s flexibility and stability.

Django has long set the benchmark for clean, pragmatic web development in Python. Its design principles and backward compatibility guarantees have made it an exceptional framework to work with. I’m excited about the opportunity to contribute meaningfully to its evolution.

Motivation

Type annotations improve code clarity, autocomplete, and IDE support.

Static analysis tools (e.g., mypy, pyright) can help prevent bugs before runtime.

Community-driven projects like django-stubs show strong demand and technical feasibility.

Popular libraries (e.g., FastAPI, SQLAlchemy, Python stdlib) are gradually adopting typing with success.

Typing can reduce onboarding time for contributors and enhance long-term maintainability.

Scope and Approach

I propose a gradual and modular strategy to introduce type hints, beginning with static, low-complexity modules. Each PR will focus on typing a single module or component to keep changes clear and manageable.

Key principles:

• Follow PEP 484 and PEP 561 guidelines.

• Avoid breaking changes or modifying public APIs.

• Defer typing of dynamic internals (e.g., querysets, models) until consensus is reached.

• Submit only meaningful, self-contained type additions with appropriate tests.

• Align with django-stubs where practical.

Proposed Phased Roadmap

Phase 1 – Low Complexity, High Value
Modules with minimal dynamic behavior and high type stability:

• django.utils (e.g., text, dateparse, crypto)

• django.conf (LazySettings)

• django.core.exceptions

• django.http (HttpRequest, HttpResponse)

• django.core.files

Phase 2 – Intermediate Complexity
Modules with more abstraction and inheritance:

• django.core.management

• django.forms

• django.middleware

• django.template

• django.views

Phase 3 – High Complexity / Dynamic Components
Highly dynamic or metaclass-heavy modules:

• django.db.models and query

• django.db.migrations

• django.contrib.admin

• django.dispatch

These may remain stubbed externally or be addressed in collaboration with tools like django-stubs.

Contribution Plan

If the proposal is accepted, I plan to:

Start with Phase 1 modules.

Submit isolated PRs with full type annotations and relevant tests.

Validate with mypy and pyright.

Track progress in a public roadmap document.

Engage actively with the community and Django team throughout.

Request for Feedback

Would the core team support gradual inline type hinting in low-risk modules?

Are there preferred annotation styles or conventions?

Would partial type checking via CI be considered for typed modules?

Is collaboration with django-stubs maintainers advisable as part of this effort?

Conclusion

This initiative aims to modernize Django’s developer experience through structured, incremental typing. It respects Django’s commitment to stability and clarity, while preparing the codebase for future developer needs.

I appreciate the opportunity to propose this idea and look forward to any feedback from the Django team and the wider community.

Thank you for maintaining such an exceptional framework—and for considering this contribution.

—
Kapil Dagur
GitHub: @KapilDagur​https://github.com/KapilDagur

[Sarah Boyce]

Duplicate of #29299
I think it would be best to discuss the plan on the ​Django forum and read up on historic discussions