Refactor the choices for localflavor's USStateField, and add new US postal code support. Fixes #14937 and #9022, refs #10308 and #8425.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@15029 bcc190cf-cafb-0310-a4f2-bffc1f526a37

2 files changed, 111 insertions, 0 deletions

diff --git a/docs/ref/contrib/localflavor.txt b/docs/ref/contrib/localflavor.txt
index aabc98c711..f54341ee6e 100644
--- a/docs/ref/contrib/localflavor.txt
+++ b/docs/ref/contrib/localflavor.txt
@@ -937,6 +937,11 @@ United States of America (``us``)
     A form ``Select`` widget that uses a list of U.S. states/territories as its
     choices.
 
+.. class:: us.forms.USPSSelect
+
+    A form ``Select`` widget that uses a list of U.S Postal Service
+    state, territory and country abbreviations as its choices.
+
 .. class:: us.models.PhoneNumberField
 
     A :class:`CharField` that checks that the value is a valid U.S.A.-style phone
@@ -947,6 +952,66 @@ United States of America (``us``)
     A model field that forms represent as a ``forms.USStateField`` field and
     stores the two-letter U.S. state abbreviation in the database.
 
+.. class:: us.models.USPostalCodeField
+
+    A model field that forms represent as a ``forms.USPSSelect`` field
+    and stores the two-letter U.S Postal Service abbreviation in the
+    database.
+
+Additionally, a variety of choice tuples are provided in
+``django.contrib.localflavor.us.us_states``, allowing customized model
+and form fields, and form presentations, for subsets of U.S states,
+territories and U.S Postal Service abbreviations:
+
+.. data:: us.us_states.CONTIGUOUS_STATES
+
+    A tuple of choices of the postal abbreviations for the
+    contiguous or "lower 48" states (i.e., all except Alaska and
+    Hawaii), plus the District of Columbia.
+
+.. data:: us.us_states.US_STATES
+
+    A tuple of choices of the postal abbreviations for all
+    50 U.S. states, plus the District of Columbia.
+
+.. data:: us.us_states.US_TERRITORIES
+
+    A tuple of choices of the postal abbreviations for U.S
+    territories: American Samoa, Guam, the Northern Mariana Islands,
+    Puerto Rico and the U.S. Virgin Islands.
+
+.. data:: us.us_states.ARMED_FORCES_STATES
+
+    A tuple of choices of the postal abbreviations of the three U.S
+    military postal "states": Armed Forces Americas, Armed Forces
+    Europe and Armed Forces Pacific.
+
+.. data:: us.us_states.COFA_STATES
+
+    A tuple of choices of the postal abbreviations of the three
+    independent nations which, under the Compact of Free Association,
+    are served by the U.S. Postal Service: the Federated States of
+    Micronesia, the Marshall Islands and Palau.
+
+.. data:: us.us_states.OBSOLETE_STATES
+
+    A tuple of choices of obsolete U.S Postal Service state
+    abbreviations: the former abbreviation for the Northern Mariana
+    Islands, plus the Panama Canal Zone, the Philippines and the
+    former Pacific trust territories.
+
+.. data:: us.us_states.STATE_CHOICES
+
+    A tuple of choices of all postal abbreviations corresponding to U.S states or
+    territories, and the District of Columbia..
+
+.. data:: us.us_states.USPS_CHOICES
+
+    A tuple of choices of all postal abbreviations recognized by the
+    U.S Postal Service (including all states and territories, the
+    District of Columbia, armed forces "states" and independent
+    nations serviced by USPS).
+
 Uruguay (``uy``)
 ================
 
diff --git a/docs/releases/1.3-beta-1.txt b/docs/releases/1.3-beta-1.txt
index 342136cd2f..749a68b14a 100644
--- a/docs/releases/1.3-beta-1.txt
+++ b/docs/releases/1.3-beta-1.txt
@@ -120,6 +120,52 @@ attribute.
 
 .. _r12634: http://code.djangoproject.com/changeset/12634
 
+Changes to ``USStateField``
+===========================
+
+The :mod:`django.contrib.localflavor` application contains collections
+of code relevant to specific countries or cultures. One such is
+:class:`~django.contrib.localflavor.us.models.USStateField`, which
+provides a field for storing the two-letter postal abbreviation of a
+U.S. state. This field has consistently caused problems, however,
+because it is often used to store the state portion of a U.S postal
+address, but not all "states" recognized by the U.S Postal Service are
+actually states of the U.S. or even U.S. territory. Several
+compromises over the list of choices resulted in some users feeling
+the field supported too many locations, while others felt it supported
+too few.
+
+In Django 1.3 we're taking a new approach to this problem, implemented
+as a pair of changes:
+
+* The choice list for `USStateField` has changed. Previously, it
+  consisted of the 50 U.S. states, the District of Columbia and
+  U.S. overseas territories. As of Django 1.3 it includes all previous
+  choices, plus the U.S. Armed Forces postal codes.
+
+* A new model field,
+  :class:`django.contrib.localflavor.us.models.USPostalCodeField`, has
+  been added which draws its choices from a list of all postal
+  abbreviations recognized by the U.S Postal Service. This includes
+  all abbreviations recognized by `USStateField`, plus three
+  independent nations -- the Federated States of Micronesia, the
+  Republic of the Marshall Islands and the Republic of Palau -- which
+  are serviced under treaty by the U.S. postal system. A new form
+  widget, :class:`django.contrib.localflavor.us.forms.USPSSelect`, is
+  also available and provides the same set of choices.
+
+Additionally, several finer-grained choice tuples are provided which
+allow mixing and matching of subsets of the U.S. states and
+territories, and other locations serviced by the U.S. postal
+system. Consult the :mod:`django.contrib.localflavor` documentation
+for more details.
+
+The change to `USStateField` is technically backwards-incompatible for
+users who expect this field to exclude Armed Forces locations. If you
+need to support U.S. mailing addresses without Armed Forces locations,
+see the list of choice tuples available in the localflavor
+documentation.
+
 The Django 1.3 roadmap
 ======================