or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdmodel-annotations.mdmonkey-patching.mdprotocols.mdqueryset-types.mdstring-types.md
tile.json

tessl/pypi-django-stubs-ext

Monkey-patching and extensions for django-stubs providing runtime type support for Django generic classes

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/django-stubs-ext@4.2.x

To install, run

npx @tessl/cli install tessl/pypi-django-stubs-ext@4.2.0

index.mddocs/

Django Stubs Extensions

Runtime extensions and monkey-patching functionality for the django-stubs type stubs package. This package enables advanced typing features for Django framework classes that cannot be implemented through static type stubs alone, providing runtime support for generic Django classes and comprehensive type annotations.

Package Information

  • Package Name: django-stubs-ext
  • Language: Python
  • Installation: pip install django-stubs-ext
  • Dependencies: django, typing-extensions
  • Python Support: 3.8+
  • Django Support: 3.2, 4.1, 4.2

Core Imports

import django_stubs_ext

Specific functionality:

from django_stubs_ext import monkeypatch
from django_stubs_ext import QuerySetAny, ValuesQuerySet, WithAnnotations, Annotations
from django_stubs_ext import AnyAttrAllowed, StrPromise, StrOrPromise

Basic Usage

import django_stubs_ext

# Apply monkey-patches once in your Django settings
django_stubs_ext.monkeypatch()

# Use type aliases for better type checking
from django_stubs_ext import QuerySetAny, WithAnnotations
from django.db import models
from django.db.models import Count, Case, When
from typing import TypedDict

# Example model with annotations
class User(models.Model):
    name = models.CharField(max_length=100)
    email = models.EmailField()
    last_login = models.DateTimeField(null=True, blank=True)

class UserStats(TypedDict):
    count: int
    active: bool

# Type-annotated QuerySet with custom annotations
annotated_queryset: WithAnnotations[User, UserStats] = User.objects.annotate(
    count=Count('id'),
    active=Case(When(last_login__isnull=False, then=True), default=False)
)

Architecture

The package consists of three main components:

  • Monkey-patching System: Dynamically adds __class_getitem__ methods to Django classes that need generic type support
  • Type Aliases: Provides specialized QuerySet and string type aliases for improved type checking
  • Annotation Support: Offers typed containers for model annotations and typed base classes for Django components

The monkey-patching system is version-aware, automatically detecting the Django version at runtime and applying only the necessary patches to ensure compatibility across multiple Django versions.

Capabilities

Runtime Monkey-Patching

Core functionality for patching Django generic classes to support type parameterization. This enables proper type checking for Django classes that don't natively support generic syntax.

def monkeypatch(
    extra_classes: Optional[Iterable[type]] = None, 
    include_builtins: bool = True
) -> None:
    """Apply runtime monkey-patches to Django classes for generic type support."""

Monkey-Patching

QuerySet Type Aliases

Specialized type aliases for Django QuerySets that provide better type safety and IDE support when working with query results and values() calls.

QuerySetAny = QuerySet  # Type alias for generic QuerySet with any model
ValuesQuerySet = QuerySet  # Type alias for QuerySet with values() calls

QuerySet Types

Model Annotations

Type-safe containers and annotations for Django model annotations, enabling proper typing of models with computed fields and aggregations.

class Annotations[_Annotations]:
    """Generic container for TypedDict-style model annotations."""

WithAnnotations = Annotated[_T, Annotations[_Annotations]]
"""Annotated type combining Django models with their annotation types."""

Model Annotations

String Type Handling

Type aliases for Django's Promise-based string handling system, providing proper type safety for lazy string evaluation and internationalization.

StrPromise = Promise  # Django Promise string type
StrOrPromise = Union[str, StrPromise]  # Union of str and Promise types

String Types

Protocol Definitions

Protocol definitions for flexible attribute access and typed base classes for Django components like Model.Meta and database routers.

class AnyAttrAllowed(Protocol):
    """Protocol for classes allowing arbitrary attribute access."""
    def __getattr__(self, item: str) -> Any: ...
    def __setattr__(self, item: str, value: Any) -> None: ...

Protocols and Base Classes

Types

from typing import Any, Generic, Iterable, Mapping, Optional, Protocol, TypeVar, Union
from typing_extensions import Annotated
from django.db.models.base import Model

_T = TypeVar("_T", bound=Model)
_Annotations = TypeVar("_Annotations", covariant=True, bound=Mapping[str, Any])