#37247 new Cleanup/optimization

Consider grouping the constants exported by `django.db.models` under enums

Reported by: Natalia Bidart Owned by:
Component: Database layer (models, ORM) Version: dev
Severity: Normal Keywords:
Cc: Triage Stage: Unreviewed
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

The django.db.models namespace exports a set of bare uppercase constants that carry no indication of where they apply. A reader coming across SET, SET_NULL or DO_NOTHING has no way to tell from the name alone which argument accepts it, and the groups sit next to each other in a single flat namespace. The problem grows with every new group added, as seen in https://github.com/django/django/pull/21696, where a rename was needed to keep one group from being mistaken for another.

Enums solve this directly. Membership is visible at the call site, the valid options for a given argument are discoverable from one place, and adding a new group costs nothing in namespace clarity. Django already uses this pattern in the ORM with Deferrable, WindowFrameExclusion, the Choices classes and the internal OnConflict.

An enum was proposed for the fetch modes during the review linked above. The Steering Council discussed it on 2026-08-03 and agreed the change only makes sense applied across the exported constants rather than to a single group, hence this ticket.

Work involved:

  • Not every constant is a plain value. Some are callables, some are class instances, and one is a factory. Member values need a form that preserves the current behavior.
  • Existing migration files reference the current import paths, so the module-level names have to keep resolving. enum.Enum is already registered to EnumSerializer, so newly written migrations are covered.
  • Naming, and whether the current names become aliases or get a deprecation path.

A forum thread is likely needed before a patch, since this touches long stable API.

Change History (0)

Note: See TracTickets for help on using tickets.
Back to Top