#36521: Proposal: Add Static Type Annotations to Django Core (Phase-wise Plan)
-------------------------------------+-------------------------------------
Reporter: Kapil Dagur | Type: New
| feature
Status: new | Component:
| Uncategorized
Version: dev | Severity: Normal
Keywords: Generic, typing, | Triage Stage:
Type Hints, Type Hinting, Static | Unreviewed
Type, Annotations, Static Type |
Annotations |
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
== **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]
--
Ticket URL: <https://code.djangoproject.com/ticket/36521>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to django-updates+unsubscr...@googlegroups.com.
To view this discussion visit
https://groups.google.com/d/msgid/django-updates/01070198360e9b84-17e84081-4f69-4ceb-bd1b-2c068d650498-000000%40eu-central-1.amazonses.com.
