1"""
  2Type stubs for typed model fields.
  3
  4These stubs tell type checkers that field constructors return primitive types,
  5enabling typed model definitions like:
  6    name: str = types.CharField()
  7
  8At runtime, these are Field instances (descriptors), but type checkers see the primitives.
  9
 10The return type is conditional on allow_null:
 11- allow_null=False (default) returns the primitive type (e.g., str)
 12- allow_null=True returns the primitive type | None (e.g., str | None)
 13"""
 14
 15from collections.abc import Callable, Sequence
 16from datetime import date, datetime, time, timedelta
 17from decimal import Decimal
 18from json import JSONDecoder, JSONEncoder
 19from typing import Any, Literal, TypeVar, overload
 20from uuid import UUID
 21
 22# TypeVar for generic ForeignKey/ManyToManyField support
 23_T = TypeVar("_T")
 24
 25# String fields
 26@overload
 27def CharField(
 28    *,
 29    max_length: int | None = None,
 30    required: bool = True,
 31    allow_null: Literal[True],
 32    default: Any = ...,
 33    choices: Any = None,
 34    db_column: str | None = None,
 35    db_collation: str | None = None,
 36    validators: Sequence[Callable[..., Any]] = (),
 37    error_messages: dict[str, str] | None = None,
 38    db_comment: str | None = None,
 39) -> str | None: ...
 40@overload
 41def CharField(
 42    *,
 43    max_length: int | None = None,
 44    required: bool = True,
 45    allow_null: Literal[False] = False,
 46    default: Any = ...,
 47    choices: Any = None,
 48    db_column: str | None = None,
 49    db_collation: str | None = None,
 50    validators: Sequence[Callable[..., Any]] = (),
 51    error_messages: dict[str, str] | None = None,
 52    db_comment: str | None = None,
 53) -> str: ...
 54@overload
 55def TextField(
 56    *,
 57    max_length: int | None = None,
 58    required: bool = True,
 59    allow_null: Literal[True],
 60    default: Any = ...,
 61    choices: Any = None,
 62    db_column: str | None = None,
 63    db_collation: str | None = None,
 64    validators: Sequence[Callable[..., Any]] = (),
 65    error_messages: dict[str, str] | None = None,
 66    db_comment: str | None = None,
 67) -> str | None: ...
 68@overload
 69def TextField(
 70    *,
 71    max_length: int | None = None,
 72    required: bool = True,
 73    allow_null: Literal[False] = False,
 74    default: Any = ...,
 75    choices: Any = None,
 76    db_column: str | None = None,
 77    db_collation: str | None = None,
 78    validators: Sequence[Callable[..., Any]] = (),
 79    error_messages: dict[str, str] | None = None,
 80    db_comment: str | None = None,
 81) -> str: ...
 82@overload
 83def EmailField(
 84    *,
 85    max_length: int | None = None,
 86    required: bool = True,
 87    allow_null: Literal[True],
 88    default: Any = ...,
 89    choices: Any = None,
 90    db_column: str | None = None,
 91    db_collation: str | None = None,
 92    validators: Sequence[Callable[..., Any]] = (),
 93    error_messages: dict[str, str] | None = None,
 94    db_comment: str | None = None,
 95) -> str | None: ...
 96@overload
 97def EmailField(
 98    *,
 99    max_length: int | None = None,
100    required: bool = True,
101    allow_null: Literal[False] = False,
102    default: Any = ...,
103    choices: Any = None,
104    db_column: str | None = None,
105    db_collation: str | None = None,
106    validators: Sequence[Callable[..., Any]] = (),
107    error_messages: dict[str, str] | None = None,
108    db_comment: str | None = None,
109) -> str: ...
110@overload
111def URLField(
112    *,
113    max_length: int | None = None,
114    required: bool = True,
115    allow_null: Literal[True],
116    default: Any = ...,
117    choices: Any = None,
118    db_column: str | None = None,
119    db_collation: str | None = None,
120    validators: Sequence[Callable[..., Any]] = (),
121    error_messages: dict[str, str] | None = None,
122    db_comment: str | None = None,
123) -> str | None: ...
124@overload
125def URLField(
126    *,
127    max_length: int | None = None,
128    required: bool = True,
129    allow_null: Literal[False] = False,
130    default: Any = ...,
131    choices: Any = None,
132    db_column: str | None = None,
133    db_collation: str | None = None,
134    validators: Sequence[Callable[..., Any]] = (),
135    error_messages: dict[str, str] | None = None,
136    db_comment: str | None = None,
137) -> str: ...
138
139# Integer fields
140@overload
141def IntegerField(
142    *,
143    max_length: int | None = None,
144    required: bool = True,
145    allow_null: Literal[True],
146    default: Any = ...,
147    choices: Any = None,
148    db_column: str | None = None,
149    validators: Sequence[Callable[..., Any]] = (),
150    error_messages: dict[str, str] | None = None,
151    db_comment: str | None = None,
152) -> int | None: ...
153@overload
154def IntegerField(
155    *,
156    max_length: int | None = None,
157    required: bool = True,
158    allow_null: Literal[False] = False,
159    default: Any = ...,
160    choices: Any = None,
161    db_column: str | None = None,
162    validators: Sequence[Callable[..., Any]] = (),
163    error_messages: dict[str, str] | None = None,
164    db_comment: str | None = None,
165) -> int: ...
166@overload
167def BigIntegerField(
168    *,
169    max_length: int | None = None,
170    required: bool = True,
171    allow_null: Literal[True],
172    default: Any = ...,
173    choices: Any = None,
174    db_column: str | None = None,
175    validators: Sequence[Callable[..., Any]] = (),
176    error_messages: dict[str, str] | None = None,
177    db_comment: str | None = None,
178) -> int | None: ...
179@overload
180def BigIntegerField(
181    *,
182    max_length: int | None = None,
183    required: bool = True,
184    allow_null: Literal[False] = False,
185    default: Any = ...,
186    choices: Any = None,
187    db_column: str | None = None,
188    validators: Sequence[Callable[..., Any]] = (),
189    error_messages: dict[str, str] | None = None,
190    db_comment: str | None = None,
191) -> int: ...
192@overload
193def SmallIntegerField(
194    *,
195    max_length: int | None = None,
196    required: bool = True,
197    allow_null: Literal[True],
198    default: Any = ...,
199    choices: Any = None,
200    db_column: str | None = None,
201    validators: Sequence[Callable[..., Any]] = (),
202    error_messages: dict[str, str] | None = None,
203    db_comment: str | None = None,
204) -> int | None: ...
205@overload
206def SmallIntegerField(
207    *,
208    max_length: int | None = None,
209    required: bool = True,
210    allow_null: Literal[False] = False,
211    default: Any = ...,
212    choices: Any = None,
213    db_column: str | None = None,
214    validators: Sequence[Callable[..., Any]] = (),
215    error_messages: dict[str, str] | None = None,
216    db_comment: str | None = None,
217) -> int: ...
218@overload
219def PositiveIntegerField(
220    *,
221    max_length: int | None = None,
222    required: bool = True,
223    allow_null: Literal[True],
224    default: Any = ...,
225    choices: Any = None,
226    db_column: str | None = None,
227    validators: Sequence[Callable[..., Any]] = (),
228    error_messages: dict[str, str] | None = None,
229    db_comment: str | None = None,
230) -> int | None: ...
231@overload
232def PositiveIntegerField(
233    *,
234    max_length: int | None = None,
235    required: bool = True,
236    allow_null: Literal[False] = False,
237    default: Any = ...,
238    choices: Any = None,
239    db_column: str | None = None,
240    validators: Sequence[Callable[..., Any]] = (),
241    error_messages: dict[str, str] | None = None,
242    db_comment: str | None = None,
243) -> int: ...
244@overload
245def PositiveBigIntegerField(
246    *,
247    max_length: int | None = None,
248    required: bool = True,
249    allow_null: Literal[True],
250    default: Any = ...,
251    choices: Any = None,
252    db_column: str | None = None,
253    validators: Sequence[Callable[..., Any]] = (),
254    error_messages: dict[str, str] | None = None,
255    db_comment: str | None = None,
256) -> int | None: ...
257@overload
258def PositiveBigIntegerField(
259    *,
260    max_length: int | None = None,
261    required: bool = True,
262    allow_null: Literal[False] = False,
263    default: Any = ...,
264    choices: Any = None,
265    db_column: str | None = None,
266    validators: Sequence[Callable[..., Any]] = (),
267    error_messages: dict[str, str] | None = None,
268    db_comment: str | None = None,
269) -> int: ...
270@overload
271def PositiveSmallIntegerField(
272    *,
273    max_length: int | None = None,
274    required: bool = True,
275    allow_null: Literal[True],
276    default: Any = ...,
277    choices: Any = None,
278    db_column: str | None = None,
279    validators: Sequence[Callable[..., Any]] = (),
280    error_messages: dict[str, str] | None = None,
281    db_comment: str | None = None,
282) -> int | None: ...
283@overload
284def PositiveSmallIntegerField(
285    *,
286    max_length: int | None = None,
287    required: bool = True,
288    allow_null: Literal[False] = False,
289    default: Any = ...,
290    choices: Any = None,
291    db_column: str | None = None,
292    validators: Sequence[Callable[..., Any]] = (),
293    error_messages: dict[str, str] | None = None,
294    db_comment: str | None = None,
295) -> int: ...
296@overload
297def PrimaryKeyField(
298    *,
299    max_length: int | None = None,
300    required: bool = True,
301    allow_null: Literal[True],
302    default: Any = ...,
303    choices: Any = None,
304    db_column: str | None = None,
305    validators: Sequence[Callable[..., Any]] = (),
306    error_messages: dict[str, str] | None = None,
307    db_comment: str | None = None,
308) -> int | None: ...
309@overload
310def PrimaryKeyField(
311    *,
312    max_length: int | None = None,
313    required: bool = True,
314    allow_null: Literal[False] = False,
315    default: Any = ...,
316    choices: Any = None,
317    db_column: str | None = None,
318    validators: Sequence[Callable[..., Any]] = (),
319    error_messages: dict[str, str] | None = None,
320    db_comment: str | None = None,
321) -> int: ...
322
323# Numeric fields
324@overload
325def FloatField(
326    *,
327    max_length: int | None = None,
328    required: bool = True,
329    allow_null: Literal[True],
330    default: Any = ...,
331    choices: Any = None,
332    db_column: str | None = None,
333    validators: Sequence[Callable[..., Any]] = (),
334    error_messages: dict[str, str] | None = None,
335    db_comment: str | None = None,
336) -> float | None: ...
337@overload
338def FloatField(
339    *,
340    max_length: int | None = None,
341    required: bool = True,
342    allow_null: Literal[False] = False,
343    default: Any = ...,
344    choices: Any = None,
345    db_column: str | None = None,
346    validators: Sequence[Callable[..., Any]] = (),
347    error_messages: dict[str, str] | None = None,
348    db_comment: str | None = None,
349) -> float: ...
350@overload
351def DecimalField(
352    *,
353    max_digits: int | None = None,
354    decimal_places: int | None = None,
355    max_length: int | None = None,
356    required: bool = True,
357    allow_null: Literal[True],
358    default: Any = ...,
359    choices: Any = None,
360    db_column: str | None = None,
361    validators: Sequence[Callable[..., Any]] = (),
362    error_messages: dict[str, str] | None = None,
363    db_comment: str | None = None,
364) -> Decimal | None: ...
365@overload
366def DecimalField(
367    *,
368    max_digits: int | None = None,
369    decimal_places: int | None = None,
370    max_length: int | None = None,
371    required: bool = True,
372    allow_null: Literal[False] = False,
373    default: Any = ...,
374    choices: Any = None,
375    db_column: str | None = None,
376    validators: Sequence[Callable[..., Any]] = (),
377    error_messages: dict[str, str] | None = None,
378    db_comment: str | None = None,
379) -> Decimal: ...
380
381# Boolean field
382@overload
383def BooleanField(
384    *,
385    max_length: int | None = None,
386    required: bool = True,
387    allow_null: Literal[True],
388    default: Any = ...,
389    choices: Any = None,
390    db_column: str | None = None,
391    validators: Sequence[Callable[..., Any]] = (),
392    error_messages: dict[str, str] | None = None,
393    db_comment: str | None = None,
394) -> bool | None: ...
395@overload
396def BooleanField(
397    *,
398    max_length: int | None = None,
399    required: bool = True,
400    allow_null: Literal[False] = False,
401    default: Any = ...,
402    choices: Any = None,
403    db_column: str | None = None,
404    validators: Sequence[Callable[..., Any]] = (),
405    error_messages: dict[str, str] | None = None,
406    db_comment: str | None = None,
407) -> bool: ...
408
409# Date/time fields
410@overload
411def DateField(
412    *,
413    auto_now: bool = False,
414    auto_now_add: bool = False,
415    max_length: int | None = None,
416    required: bool = True,
417    allow_null: Literal[True],
418    default: Any = ...,
419    choices: Any = None,
420    db_column: str | None = None,
421    validators: Sequence[Callable[..., Any]] = (),
422    error_messages: dict[str, str] | None = None,
423    db_comment: str | None = None,
424) -> date | None: ...
425@overload
426def DateField(
427    *,
428    auto_now: bool = False,
429    auto_now_add: bool = False,
430    max_length: int | None = None,
431    required: bool = True,
432    allow_null: Literal[False] = False,
433    default: Any = ...,
434    choices: Any = None,
435    db_column: str | None = None,
436    validators: Sequence[Callable[..., Any]] = (),
437    error_messages: dict[str, str] | None = None,
438    db_comment: str | None = None,
439) -> date: ...
440@overload
441def DateTimeField(
442    *,
443    auto_now: bool = False,
444    auto_now_add: bool = False,
445    max_length: int | None = None,
446    required: bool = True,
447    allow_null: Literal[True],
448    default: Any = ...,
449    choices: Any = None,
450    db_column: str | None = None,
451    validators: Sequence[Callable[..., Any]] = (),
452    error_messages: dict[str, str] | None = None,
453    db_comment: str | None = None,
454) -> datetime | None: ...
455@overload
456def DateTimeField(
457    *,
458    auto_now: bool = False,
459    auto_now_add: bool = False,
460    max_length: int | None = None,
461    required: bool = True,
462    allow_null: Literal[False] = False,
463    default: Any = ...,
464    choices: Any = None,
465    db_column: str | None = None,
466    validators: Sequence[Callable[..., Any]] = (),
467    error_messages: dict[str, str] | None = None,
468    db_comment: str | None = None,
469) -> datetime: ...
470@overload
471def TimeField(
472    *,
473    auto_now: bool = False,
474    auto_now_add: bool = False,
475    max_length: int | None = None,
476    required: bool = True,
477    allow_null: Literal[True],
478    default: Any = ...,
479    choices: Any = None,
480    db_column: str | None = None,
481    validators: Sequence[Callable[..., Any]] = (),
482    error_messages: dict[str, str] | None = None,
483    db_comment: str | None = None,
484) -> time | None: ...
485@overload
486def TimeField(
487    *,
488    auto_now: bool = False,
489    auto_now_add: bool = False,
490    max_length: int | None = None,
491    required: bool = True,
492    allow_null: Literal[False] = False,
493    default: Any = ...,
494    choices: Any = None,
495    db_column: str | None = None,
496    validators: Sequence[Callable[..., Any]] = (),
497    error_messages: dict[str, str] | None = None,
498    db_comment: str | None = None,
499) -> time: ...
500@overload
501def DurationField(
502    *,
503    max_length: int | None = None,
504    required: bool = True,
505    allow_null: Literal[True],
506    default: Any = ...,
507    choices: Any = None,
508    db_column: str | None = None,
509    validators: Sequence[Callable[..., Any]] = (),
510    error_messages: dict[str, str] | None = None,
511    db_comment: str | None = None,
512) -> timedelta | None: ...
513@overload
514def DurationField(
515    *,
516    max_length: int | None = None,
517    required: bool = True,
518    allow_null: Literal[False] = False,
519    default: Any = ...,
520    choices: Any = None,
521    db_column: str | None = None,
522    validators: Sequence[Callable[..., Any]] = (),
523    error_messages: dict[str, str] | None = None,
524    db_comment: str | None = None,
525) -> timedelta: ...
526
527# Other fields
528@overload
529def UUIDField(
530    *,
531    max_length: int | None = None,
532    required: bool = True,
533    allow_null: Literal[True],
534    default: Any = ...,
535    choices: Any = None,
536    db_column: str | None = None,
537    validators: Sequence[Callable[..., Any]] = (),
538    error_messages: dict[str, str] | None = None,
539    db_comment: str | None = None,
540) -> UUID | None: ...
541@overload
542def UUIDField(
543    *,
544    max_length: int | None = None,
545    required: bool = True,
546    allow_null: Literal[False] = False,
547    default: Any = ...,
548    choices: Any = None,
549    db_column: str | None = None,
550    validators: Sequence[Callable[..., Any]] = (),
551    error_messages: dict[str, str] | None = None,
552    db_comment: str | None = None,
553) -> UUID: ...
554@overload
555def BinaryField(
556    *,
557    max_length: int | None = None,
558    required: bool = True,
559    allow_null: Literal[True],
560    default: Any = ...,
561    choices: Any = None,
562    db_column: str | None = None,
563    validators: Sequence[Callable[..., Any]] = (),
564    error_messages: dict[str, str] | None = None,
565    db_comment: str | None = None,
566) -> bytes | None: ...
567@overload
568def BinaryField(
569    *,
570    max_length: int | None = None,
571    required: bool = True,
572    allow_null: Literal[False] = False,
573    default: Any = ...,
574    choices: Any = None,
575    db_column: str | None = None,
576    validators: Sequence[Callable[..., Any]] = (),
577    error_messages: dict[str, str] | None = None,
578    db_comment: str | None = None,
579) -> bytes: ...
580@overload
581def GenericIPAddressField(
582    *,
583    protocol: str = "both",
584    unpack_ipv4: bool = False,
585    max_length: int | None = None,
586    required: bool = True,
587    allow_null: Literal[True],
588    default: Any = ...,
589    choices: Any = None,
590    db_column: str | None = None,
591    validators: Sequence[Callable[..., Any]] = (),
592    error_messages: dict[str, str] | None = None,
593    db_comment: str | None = None,
594) -> str | None: ...
595@overload
596def GenericIPAddressField(
597    *,
598    protocol: str = "both",
599    unpack_ipv4: bool = False,
600    max_length: int | None = None,
601    required: bool = True,
602    allow_null: Literal[False] = False,
603    default: Any = ...,
604    choices: Any = None,
605    db_column: str | None = None,
606    validators: Sequence[Callable[..., Any]] = (),
607    error_messages: dict[str, str] | None = None,
608    db_comment: str | None = None,
609) -> str: ...
610@overload
611def JSONField(
612    *,
613    encoder: type[JSONEncoder] | None = None,
614    decoder: type[JSONDecoder] | None = None,
615    max_length: int | None = None,
616    required: bool = True,
617    allow_null: Literal[True],
618    default: Any = ...,
619    choices: Any = None,
620    db_column: str | None = None,
621    validators: Sequence[Callable[..., Any]] = (),
622    error_messages: dict[str, str] | None = None,
623    db_comment: str | None = None,
624) -> Any: ...
625@overload
626def JSONField(
627    *,
628    encoder: type[JSONEncoder] | None = None,
629    decoder: type[JSONDecoder] | None = None,
630    max_length: int | None = None,
631    required: bool = True,
632    allow_null: Literal[False] = False,
633    default: Any = ...,
634    choices: Any = None,
635    db_column: str | None = None,
636    validators: Sequence[Callable[..., Any]] = (),
637    error_messages: dict[str, str] | None = None,
638    db_comment: str | None = None,
639) -> Any: ...
640
641# Related fields
642@overload
643def ForeignKey(
644    to: type[_T],
645    on_delete: Any,
646    *,
647    related_name: str | None = None,
648    related_query_name: str | None = None,
649    limit_choices_to: Any = None,
650    db_index: bool = True,
651    db_constraint: bool = True,
652    max_length: int | None = None,
653    required: bool = True,
654    allow_null: Literal[True],
655    default: Any = ...,
656    choices: Any = None,
657    db_column: str | None = None,
658    validators: Sequence[Callable[..., Any]] = (),
659    error_messages: dict[str, str] | None = None,
660    db_comment: str | None = None,
661) -> _T | None: ...
662@overload
663def ForeignKey(
664    to: type[_T],
665    on_delete: Any,
666    *,
667    related_name: str | None = None,
668    related_query_name: str | None = None,
669    limit_choices_to: Any = None,
670    db_index: bool = True,
671    db_constraint: bool = True,
672    max_length: int | None = None,
673    required: bool = True,
674    allow_null: Literal[False] = False,
675    default: Any = ...,
676    choices: Any = None,
677    db_column: str | None = None,
678    validators: Sequence[Callable[..., Any]] = (),
679    error_messages: dict[str, str] | None = None,
680    db_comment: str | None = None,
681) -> _T: ...
682def ManyToManyField(
683    to: type[_T],
684    *,
685    through: Any,
686    through_fields: tuple[str, str] | None = None,
687    related_name: str | None = None,
688    related_query_name: str | None = None,
689    limit_choices_to: Any = None,
690    symmetrical: bool | None = None,
691    max_length: int | None = None,
692    required: bool = True,
693    allow_null: bool = False,
694    default: Any = ...,
695    choices: Any = None,
696    db_column: str | None = None,
697    validators: Sequence[Callable[..., Any]] = (),
698    error_messages: dict[str, str] | None = None,
699    db_comment: str | None = None,
700) -> Any: ...