Changed DIF to CDMX in MX STATE_CHOICES

docs/changelog.rst

@@ -4,6 +4,15 @@ Changelog
 3.1   (unreleased)
 ------------------
 
+Breaking data changes:
+
+A schema and data migration are required for users of `mx.models.MXStateField` and `mx.forms.MXStateSelect`. After
+updating, users of these fields will need to run "manage.py makemigrations" to generate a schema migration and then
+create a data migration to change any stored values of "DIF" to "CDMX". A warning message will be displayed when
+`mx.forms.MXStateSelect` is used. See the
+`localflavor online docs <https://django-localflavor.readthedocs.io/en/latest/#backwards-compatibility>`_ for
+instructions on how to suppress this warning once the migration has been completed.
+
 New flavors:
 
 - None
@@ -16,7 +25,7 @@ Modifications to existing flavors:
 
 - Fix `FRNationalIdentificationNumber` validation for people born overseas
 - Updated Indian states and union territories names and code as per iso 3166 (https://www.iso.org/obp/ui/#iso:code:3166:IN)
-- Breaking data changes: The key for Chattisgarh has been changed from CG to CT, the key for Uttarakhand has been changed from UA to UT,
+- Breaking data change: The key for Chattisgarh has been changed from CG to CT, the key for Uttarakhand has been changed from UA to UT,
   and the keys DD (Dadra and Nagar Haveli) and DN (Daman and Diu) have been removed and combined into DH (Dadra and Nagar Haveli and Daman and Diu)
   Previous State Jammu and Kashmir (JK) is now under Union Territories, Ladakh (LA) is the new addition in the Union Territories.
   Few modificication in the States and Union Territories names: Orissa (OR) is now Odisha (OR), Pondicherry (PY) is now Puducherry (PY)
@@ -27,6 +36,11 @@ Modifications to existing flavors:
 - Added new region for CL (`gh-432 <https://github.com/django/django-localflavor/issues/432>`_, `gh-433 <https://github.com/django/django-localflavor/pull/433>`_).
 - Updated IBAN validation for changes in IBAN Registry release 89, March 2021
   (`gh-436 <https://github.com/django/django-localflavor/issues/436>`_).
+- Breaking data change: MX localflavor: `STATE_CHOICES` has been updated to change DIF/Distrito Federal to CDMX/Ciudad
+  de México, the legal name for this state as of 29 January 2016
+  (`gh-235 <https://github.com/django/django-localflavor/issues/235>`_,
+  `gh-400 <https://github.com/django/django-localflavor/issues/400>`_,
+  `gh-438 <https://github.com/django/django-localflavor/issues/438>`_).
 
 Other changes:
 

localflavor/mx/models.py

@@ -1,3 +1,5 @@
+import warnings
+
 from django.db.models import CharField
 from django.utils.translation import gettext_lazy as _
 
@@ -10,13 +12,14 @@
 
 
 class MXStateField(CharField):
-    """A model field that stores the three-letter Mexican state abbreviation in the database."""
+    """A model field that stores the three or four letter Mexican state abbreviation in the database."""
 
-    description = _("Mexico state (three uppercase letters)")
+    description = _("Mexico state (three or four uppercase letters)")
 
     def __init__(self, *args, **kwargs):
+        warnings.warn("Choices have changed for MXStateField in localflavor 3.1. See changelog for details.")
         kwargs['choices'] = STATE_CHOICES
-        kwargs['max_length'] = 3
+        kwargs['max_length'] = 4
         super().__init__(*args, **kwargs)
 
     def deconstruct(self):

localflavor/mx/mx_states.py

@@ -1,16 +1,16 @@
 from django.utils.translation import gettext_lazy as _
 
-#: All 31 states, plus the `Distrito Federal`.
+#: All 31 states, plus the `Ciudad de México`.
 STATE_CHOICES = (
     ('AGU', _('Aguascalientes')),
     ('BCN', _('Baja California')),
     ('BCS', _('Baja California Sur')),
     ('CAM', _('Campeche')),
+    ('CDMX', _('Ciudad de México')),
     ('CHH', _('Chihuahua')),
     ('CHP', _('Chiapas')),
     ('COA', _('Coahuila')),
     ('COL', _('Colima')),
-    ('DIF', _('Distrito Federal')),
     ('DUR', _('Durango')),
     ('GRO', _('Guerrero')),
     ('GUA', _('Guanajuato')),

tests/test_mx/tests.py

@@ -56,11 +56,11 @@ def test_field_blank_option(self):
 <option value="BCN">Baja California</option>
 <option value="BCS">Baja California Sur</option>
 <option value="CAM">Campeche</option>
+<option value="CDMX">Ciudad de México</option>
 <option value="CHH">Chihuahua</option>
 <option value="CHP">Chiapas</option>
 <option value="COA">Coahuila</option>
 <option value="COL">Colima</option>
-<option value="DIF">Distrito Federal</option>
 <option value="DUR">Durango</option>
 <option value="GRO">Guerrero</option>
 <option value="GUA">Guanajuato</option>
@@ -94,11 +94,11 @@ def test_MXStateSelect(self):
 <option value="BCN">Baja California</option>
 <option value="BCS">Baja California Sur</option>
 <option value="CAM">Campeche</option>
+<option value="CDMX">Ciudad de México</option>
 <option value="CHH">Chihuahua</option>
 <option value="CHP">Chiapas</option>
 <option value="COA">Coahuila</option>
 <option value="COL">Colima</option>
-<option value="DIF">Distrito Federal</option>
 <option value="DUR">Durango</option>
 <option value="GRO">Guerrero</option>
 <option value="GUA">Guanajuato</option>