Fixed #35870 -- Made blank choice label in forms more accessible.

Added new constant django.db.models.fields.BLANK_CHOICE_LABEL for
an accessible and translatable blank choice label in forms.
Deprecated django.db.models.fields.BLANK_CHOICE_DASH constant.
Added the immediately deprecated transitional setting
USE_BLANK_CHOICE_DASH.

Co-Authored-By: Marijke Luttekes <mail@marijkeluttekes.dev>

Author: 2 people

django/conf/__init__.py

@@ -16,12 +16,19 @@
 import django
 from django.conf import global_settings
 from django.core.exceptions import ImproperlyConfigured
+from django.utils.deprecation import RemovedInDjango70Warning, django_file_prefixes
 from django.utils.functional import LazyObject, empty
 
 ENVIRONMENT_VARIABLE = "DJANGO_SETTINGS_MODULE"
 DEFAULT_STORAGE_ALIAS = "default"
 STATICFILES_STORAGE_ALIAS = "staticfiles"
 
+USE_BLANK_CHOICE_DASH_DEPRECATED_MSG = (
+    "The USE_BLANK_CHOICE_DASH setting is deprecated. If you wish to define "
+    "your own default blank choice label, override "
+    "django.db.models.fields.BLANK_CHOICE_LABEL in your app's ready() method."
+)
+
 
 class SettingsReference(str):
     """
@@ -226,6 +233,12 @@ def __getattr__(self, name):
 
     def __setattr__(self, name, value):
         self._deleted.discard(name)
+        if name == "USE_BLANK_CHOICE_DASH":
+            warnings.warn(
+                USE_BLANK_CHOICE_DASH_DEPRECATED_MSG,
+                RemovedInDjango70Warning,
+                skip_file_prefixes=django_file_prefixes(),
+            )
         super().__setattr__(name, value)
 
     def __delattr__(self, name):

django/conf/global_settings.py

@@ -218,6 +218,9 @@ def gettext_noop(s):
 
 # Default form rendering class.
 FORM_RENDERER = "django.forms.renderers.DjangoTemplates"
+# RemovedInDjango70Warning: This setting allows to revert back to the old
+# blank choice label in Django 6.1.
+USE_BLANK_CHOICE_DASH = False
 
 # Default email address to use for various automated correspondence from
 # the site managers.

django/contrib/admin/options.py

@@ -43,6 +43,7 @@
 from django.core.paginator import Paginator
 from django.db import models, router, transaction
 from django.db.models.constants import LOOKUP_SEP
+from django.db.models.utils import get_blank_choice_label
 from django.forms.formsets import DELETION_FIELD_NAME, all_valid
 from django.forms.models import (
     BaseInlineFormSet,
@@ -1049,11 +1050,13 @@ def get_actions(self, request):
         actions = self._filter_actions_by_permissions(request, self._get_base_actions())
         return {name: (func, name, desc) for func, name, desc in actions}
 
-    def get_action_choices(self, request, default_choices=models.BLANK_CHOICE_DASH):
+    def get_action_choices(self, request, default_choices=None):
         """
         Return a list of choices for use in a form object. Each choice is a
         tuple (name, description).
         """
+        if default_choices is None:
+            default_choices = [("", get_blank_choice_label())]
         choices = [*default_choices]
         for func, name, description in self.get_actions(request).values():
             choice = (name, description % model_format_dict(self.opts))

django/db/models/fields/__init__.py

@@ -15,6 +15,7 @@
 from django.db import connection, connections, router
 from django.db.models.constants import LOOKUP_SEP
 from django.db.models.query_utils import DeferredAttribute, RegisterLookupMixin
+from django.db.models.utils import get_blank_choice_label
 from django.db.utils import NotSupportedError
 from django.utils import timezone
 from django.utils.choices import (
@@ -39,7 +40,9 @@
 
 __all__ = [
     "AutoField",
+    # RemovedInDjango70Warning
     "BLANK_CHOICE_DASH",
+    "BLANK_CHOICE_LABEL",
     "BigAutoField",
     "BigIntegerField",
     "BinaryField",
@@ -81,9 +84,13 @@ class NOT_PROVIDED:
     pass
 
 
-# The values to use for "blank" in SelectFields. Will be appended to the start
-# of most "choices" lists.
+# RemovedInDjango70Warning: From Django 6.1, the values to use for "blank"
+# in SelectFields will be defined by the below BLANK_CHOICE_LABEL constant.
+# Will be appended to the start of most "choices" lists.
+# BLANK_CHOICE_DASH is still available as a constant in Django 6.1.
 BLANK_CHOICE_DASH = [("", "---------")]
+# This allows any app's ready() method to overwrite BLANK_CHOICE_LABEL.
+BLANK_CHOICE_LABEL = _("- Select an option -")
 
 
 def _load_field(app_label, model_name, field_name):
@@ -1088,14 +1095,16 @@ def _db_default_expression(self):
     def get_choices(
         self,
         include_blank=True,
-        blank_choice=BLANK_CHOICE_DASH,
+        blank_choice=None,
         limit_choices_to=None,
         ordering=(),
     ):
         """
         Return choices with a default blank choices included, for use
         as <select> choices for this field.
         """
+        if blank_choice is None:
+            blank_choice = [("", get_blank_choice_label())]
         if self.choices is not None:
             if include_blank:
                 return BlankChoiceIterator(self.choices, blank_choice)

django/db/models/fields/reverse_related.py

@@ -13,7 +13,7 @@
 from django.utils.functional import cached_property
 from django.utils.hashable import make_hashable
 
-from . import BLANK_CHOICE_DASH
+from ..utils import get_blank_choice_label
 from .mixins import FieldCacheMixin
 
 
@@ -172,7 +172,7 @@ def __getstate__(self):
     def get_choices(
         self,
         include_blank=True,
-        blank_choice=BLANK_CHOICE_DASH,
+        blank_choice=None,
         limit_choices_to=None,
         ordering=(),
     ):
@@ -183,6 +183,8 @@ def get_choices(
         Analog of django.db.models.fields.Field.get_choices(), provided
         initially for utilization by RelatedFieldListFilter.
         """
+        if blank_choice is None:
+            blank_choice = [("", get_blank_choice_label())]
         limit_choices_to = limit_choices_to or self.limit_choices_to
         qs = self.related_model._default_manager.complex_filter(limit_choices_to)
         if ordering:

django/db/models/utils.py

@@ -67,3 +67,15 @@ def __init_subclass__(cls, **kwargs):
                         break
 
         super().__init_subclass__(**kwargs)
+
+
+# RemovedInDjango70Warning: At the end of the deprecation, remove this function
+# and use .fields.BLANK_CHOICE_LABEL directly instead.
+def get_blank_choice_label():
+    from django.conf import settings
+
+    from .fields import BLANK_CHOICE_DASH, BLANK_CHOICE_LABEL
+
+    if settings.USE_BLANK_CHOICE_DASH:
+        return BLANK_CHOICE_DASH[0][1]
+    return BLANK_CHOICE_LABEL

django/forms/fields.py

@@ -15,6 +15,7 @@
 
 from django.core import validators
 from django.core.exceptions import ValidationError
+from django.db.models.utils import get_blank_choice_label
 from django.forms.boundfield import BoundField
 from django.forms.utils import from_current_timezone, to_current_timezone
 from django.forms.widgets import (
@@ -1200,7 +1201,7 @@ def __init__(
         if self.required:
             self.choices = []
         else:
-            self.choices = [("", "---------")]
+            self.choices = [("", get_blank_choice_label())]
 
         if self.match is not None:
             self.match_re = re.compile(self.match)

django/forms/models.py

@@ -12,7 +12,7 @@
     ValidationError,
 )
 from django.core.validators import ProhibitNullCharactersValidator
-from django.db.models.utils import AltersData
+from django.db.models.utils import AltersData, get_blank_choice_label
 from django.forms.fields import ChoiceField, Field
 from django.forms.forms import BaseForm, DeclarativeFieldsMetaclass
 from django.forms.formsets import BaseFormSet, formset_factory
@@ -1481,7 +1481,7 @@ def __init__(
         self,
         queryset,
         *,
-        empty_label="---------",
+        empty_label="",
         required=True,
         widget=None,
         label=None,
@@ -1508,6 +1508,8 @@ def __init__(
         ):
             self.empty_label = None
         else:
+            if empty_label == "":
+                empty_label = get_blank_choice_label()
             self.empty_label = empty_label
         self.queryset = queryset
         self.limit_choices_to = limit_choices_to  # limit the queryset later.

docs/internals/deprecation.txt

@@ -64,6 +64,10 @@ details on these changes.
   :class:`~django.db.models.JSONNull` to query for a JSON ``null`` value
   instead.
 
+* The ``django.db.models.fields.BLANK_CHOICE_DASH`` constant will be removed.
+
+* The ``USE_BLANK_CHOICE_DASH`` transitional setting will be removed.
+
 * The ``Field.get_placeholder_sql`` shim over the deprecated
   ``get_placeholder`` method will be removed.