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

This feature adds native support for the Oracle Database’s ​Vector data type introduced in Oracle 23c. It enables AI and ML applications to store and query high-dimensional data directly in the database using a new VectorField model field, VectorIndex support for similarity search, and ORM expressions for vector operations.

Features Included:

VectorField model field:

1. Accepts optional dimensions, storage_format, and storage_type arguments.

2. Supports Dense and Sparse vector storage.

3. Auto-converts lists, NumPy arrays, and oracledb.SparseVector for insert/update.

Vector Index support:

1. VectorIndex class using Meta.indexes.

2. Support for HNSW and IVF index types.

3. Optional parameters: distance, accuracy, parallel, etc.

Vector distance expressions and lookups:

1. Custom Func class VectorDistance for VECTOR_DISTANCE(lhs, rhs, metric)

2. CosineDistance, EuclideanDistance, and NegativeDotProduct etc. as lookups.

3. Query syntax via filter() and order_by() for similarity search.

Testing:

1. Dense and Sparse vector insert/query tests added.

2. Stress test scripts for repeated inserts/queries included.

Example:

from django.db import models
VectorIndex = model.VectorIndex
VectorDistanceType = models.VectorDistanceType
VectorIndexType = models.VectorIndexType
class Product(models.Model):
    name = models.CharField(max_length=100)
    embedding = models.VectorField(dim=3, storage_format=VectorStorageFormat.FLOAT32, storage_type=VectorStorageType.DENSE)
    class Meta:
        indexes = [
            VectorIndex(
                fields=["embedding"],
                name="vec_idx_product",
                index_type=VectorIndexType.HNSW,
                distance=VectorDistanceType.COSINE,
            )
        ]

And a Similarity search can be performed

query_vector = array.array("f", [1.0, 2.0, 3.0])
    products = Product.objects.annotate(
        score=VectorDistance(
            "embedding",
            query_vector,
            metric=VectorDistanceType.COSINE,
        )
    ).order_by("score")[:5]

Implementation Status

We have already implemented:

1. Custom VectorField with support for DENSE and SPARSE formats

2. Automatic SQL generation for model/table creation

3. VectorIndex support with customizable parameters and distance metrics

4. ORM expressions and lookups for vector distance queries (e.g., CosineDistance, EuclideanDistance)

5. Basic tests for dense vector creation, insertion, indexing, and querying

6. Integration with Oracle’s Python driver (oracledb) for runtime behavior

PR Readiness

We have finalized the major components of this feature and are ready to open a public pull request after community feedback or approval of this feature proposal.

Hi,

I'm a Fedora packager that co-maintains our Django packages. When building 5.2.4 in Rawhide (the upcoming Fedora 43 release) that currently has Python 3.14b4, in addition to strip_tags() that our openSUSE colleague has reported (https://code.djangoproject.com/ticket/36499), test_parsing_errors also fails:

======================================================================
FAIL: test_parsing_errors (test_utils.tests.HTMLEqualTests.test_parsing_errors)
----------------------------------------------------------------------
AssertionError: &lt; div&gt; != <div>
- &lt; div&gt;   
+ <div>   

I'm currently conditionally disabling the test when building with Python >= 3.14, but hopefully this can be fixed.