$ show typeddjango/django-stubs
django-stubs is a distribution package of type stubs (`.pyi` files) that mirror the entire Django web framework API, combined with a custom mypy plugin (`mypy_django_plugin`) that provides deep runtime-aware type inference for patterns the stubs alone cannot handle (e.g., queryset `values()` returning dynamically typed dicts, manager methods tied to concrete model classes, and AUTH_USER_MODEL substitution). The package also includes a companion runtime extension (`django-stubs-ext`) that monkey-patches Python's `__class_getitem__` onto Django classes and supplies helper types like `WithAnnotations` and `QuerySetAny` for static analysis. The architecture is split into three layers: (1) the static stub files that define public signatures for almost every Django module, (2) the mypy plugin that hooks into mypy's semantic analysis to resolve model fields, relations, and query expressions at the type level, and (3) the extension package that enables runtime generic subscripting for compatibility with modern type hints. Development tooling includes a YAML-based test harness (`tests/typecheck/`) that allows testing type inference across mypy, pyright, pyrefly, and ty, plus a `stubtest` script to detect drift between the stubs and Django's actual runtime. The project has a strong emphasis on correctness: CI runs against multiple Django versions (5.2–6.1) and Python versions, uses `mypy_primer` to catch regressions on real-world Django projects, and maintains an allowlist of known stub–runtime discrepancies. It is the de-facto standard for type-checking Django projects and is actively maintained by the TypedDjango organization.
The LLM identified 4 files worth highlighting for reuse:
Public API of the `django-stubs-ext` package. Exports `monkeypatch()`, `WithAnnotations`, `StrOrPromise`, and other utility types that can be used independently to enable generic type subscripting on Django classes at runtime. Isolated and self-contained, requiring only the `typing` module and Django. Any project with custom Django model type hints can benefit from this module without adopting the full stubs or plugin.
Defines `WithAnnotations` and `_WithAnnotations` – a pattern for merging a typed dict of annotations into a model instance type. Uses `__class_getitem__` and `__origin__` to produce a proxy type that combines the model's fields with additional annotation keys. This is a general-purpose technique for representing 'vanilla model + extra attributes' in the type system, reusable in any framework where querysets can supplement fields.
Performs `__class_getitem__` patching on Django classes (e.g., `Model`, `Manager`, `QuerySet`) that lack it. The logic iterates over a curated list of class names from Django modules and sets `__class_getitem__` to a generic alias proxy. This is a clean, idempotent patching strategy that could be extracted to enable generic subscripting on any third-party API that uses metaclass tricks.
Implements `DjangoSettings` and `SettingsConf` classes to read mypy configuration from both INI (`mypy.ini`) and TOML (`pyproject.toml`) formats. It resolves `django_settings_module`, `strict_settings`, and other plugin-specific options. The `parse_ini_section` and `parse_toml_table` methods are well-structured and could be reused by any mypy plugin needing custom config parsing without pulling in the entire Django plugin ecosystem.