United States of America (us)

Forms

USA-specific Form helpers

class localflavor.us.forms.USPSSelect(attrs=None)[source]

A Select widget that uses a list of US Postal Service codes as its choices.

Note

If you are looking for a form field that validates U.S. ZIP codes please use USZipCodeField.

class localflavor.us.forms.USPhoneNumberField(max_length=None, min_length=None, strip=True, *args, **kwargs)[source]

A form field that validates input as a U.S. phone number.

class localflavor.us.forms.USSocialSecurityNumberField(max_length=None, min_length=None, strip=True, *args, **kwargs)[source]

A United States Social Security number.

Checks the following rules to determine whether the number is valid:

  • Conforms to the XXX-XX-XXXX format.
  • No group consists entirely of zeroes.
  • The leading group is not “666” (block “666” will never be allocated).
  • The number is not in the promotional block 987-65-4320 through 987-65-4329, which are permanently invalid.
  • The number is not one known to be invalid due to otherwise widespread promotional use or distribution (e.g., the Woolworth’s number or the 1962 promotional number).

New in version 1.1.

class localflavor.us.forms.USStateField(required=True, widget=None, label=None, initial=None, help_text='', error_messages=None, show_hidden_initial=False, validators=[], localize=False, disabled=False, label_suffix=None)[source]

A form field that validates its input is a U.S. state name or abbreviation. It normalizes the input to the standard two-leter postal service abbreviation for the given state.

class localflavor.us.forms.USStateSelect(attrs=None)[source]

A Select widget that uses a list of U.S. states/territories as its choices.

class localflavor.us.forms.USZipCodeField(max_length=None, min_length=None, *args, **kwargs)[source]

” A form field that validates input as a U.S. ZIP code. Valid formats are XXXXX or XXXXX-XXXX.

Note

If you are looking for a form field with a list of U.S. Postal Service locations please use USPSSelect.

New in version 1.1.

Whitespace around the ZIP code is accepted and automatically trimmed.

Models

class localflavor.us.models.PhoneNumberField(*args, **kwargs)[source]

A CharField that checks that the value is a valid U.S.A.-style phone number (in the format XXX-XXX-XXXX).

class localflavor.us.models.USPostalCodeField(*args, **kwargs)[source]

” A model field that forms represent as a USPSSelect` field and stores the two-letter U.S. Postal Service abbreviation in the database.

Note

If you are looking for a model field that validates U.S. ZIP codes please use USZipCodeField.

class localflavor.us.models.USSocialSecurityNumberField(*args, **kwargs)[source]

A model field that forms represent as forms.USSocialSecurityNumberField and stores in the format XXX-XX-XXXX.

New in version 1.1.

class localflavor.us.models.USStateField(*args, **kwargs)[source]

A model field that forms represent as a forms.USStateField field and stores the two-letter U.S. state abbreviation in the database.

class localflavor.us.models.USZipCodeField(*args, **kwargs)[source]

A model field that forms represent as a USZipCodeField field and stores the U.S. ZIP code in the database.

Note

If you are looking for a model field with a list of U.S. Postal Service locations please use USPostalCodeField.

New in version 1.1.

Data

localflavor.us.us_states.CONTIGUOUS_STATES = (('AL', 'Alabama'), ('AZ', 'Arizona'), ('AR', 'Arkansas'), ('CA', 'California'), ('CO', 'Colorado'), ('CT', 'Connecticut'), ('DE', 'Delaware'), ('DC', 'District of Columbia'), ('FL', 'Florida'), ('GA', 'Georgia'), ('ID', 'Idaho'), ('IL', 'Illinois'), ('IN', 'Indiana'), ('IA', 'Iowa'), ('KS', 'Kansas'), ('KY', 'Kentucky'), ('LA', 'Louisiana'), ('ME', 'Maine'), ('MD', 'Maryland'), ('MA', 'Massachusetts'), ('MI', 'Michigan'), ('MN', 'Minnesota'), ('MS', 'Mississippi'), ('MO', 'Missouri'), ('MT', 'Montana'), ('NE', 'Nebraska'), ('NV', 'Nevada'), ('NH', 'New Hampshire'), ('NJ', 'New Jersey'), ('NM', 'New Mexico'), ('NY', 'New York'), ('NC', 'North Carolina'), ('ND', 'North Dakota'), ('OH', 'Ohio'), ('OK', 'Oklahoma'), ('OR', 'Oregon'), ('PA', 'Pennsylvania'), ('RI', 'Rhode Island'), ('SC', 'South Carolina'), ('SD', 'South Dakota'), ('TN', 'Tennessee'), ('TX', 'Texas'), ('UT', 'Utah'), ('VT', 'Vermont'), ('VA', 'Virginia'), ('WA', 'Washington'), ('WV', 'West Virginia'), ('WI', 'Wisconsin'), ('WY', 'Wyoming'))

The 48 contiguous states, plus the District of Columbia.

localflavor.us.us_states.US_STATES = (('AL', 'Alabama'), ('AK', 'Alaska'), ('AZ', 'Arizona'), ('AR', 'Arkansas'), ('CA', 'California'), ('CO', 'Colorado'), ('CT', 'Connecticut'), ('DE', 'Delaware'), ('DC', 'District of Columbia'), ('FL', 'Florida'), ('GA', 'Georgia'), ('HI', 'Hawaii'), ('ID', 'Idaho'), ('IL', 'Illinois'), ('IN', 'Indiana'), ('IA', 'Iowa'), ('KS', 'Kansas'), ('KY', 'Kentucky'), ('LA', 'Louisiana'), ('ME', 'Maine'), ('MD', 'Maryland'), ('MA', 'Massachusetts'), ('MI', 'Michigan'), ('MN', 'Minnesota'), ('MS', 'Mississippi'), ('MO', 'Missouri'), ('MT', 'Montana'), ('NE', 'Nebraska'), ('NV', 'Nevada'), ('NH', 'New Hampshire'), ('NJ', 'New Jersey'), ('NM', 'New Mexico'), ('NY', 'New York'), ('NC', 'North Carolina'), ('ND', 'North Dakota'), ('OH', 'Ohio'), ('OK', 'Oklahoma'), ('OR', 'Oregon'), ('PA', 'Pennsylvania'), ('RI', 'Rhode Island'), ('SC', 'South Carolina'), ('SD', 'South Dakota'), ('TN', 'Tennessee'), ('TX', 'Texas'), ('UT', 'Utah'), ('VT', 'Vermont'), ('VA', 'Virginia'), ('WA', 'Washington'), ('WV', 'West Virginia'), ('WI', 'Wisconsin'), ('WY', 'Wyoming'))

All 50 states, plus the District of Columbia.

localflavor.us.us_states.US_TERRITORIES = (('AS', 'American Samoa'), ('GU', 'Guam'), ('MP', 'Northern Mariana Islands'), ('PR', 'Puerto Rico'), ('VI', 'Virgin Islands'))

Non-state territories.

localflavor.us.us_states.ARMED_FORCES_STATES = (('AA', 'Armed Forces Americas'), ('AE', 'Armed Forces Europe'), ('AP', 'Armed Forces Pacific'))

Military postal “states”. Note that ‘AE’ actually encompasses Europe, Canada, Africa and the Middle East.

localflavor.us.us_states.COFA_STATES = (('FM', 'Federated States of Micronesia'), ('MH', 'Marshall Islands'), ('PW', 'Palau'))

Non-US locations serviced by USPS (under Compact of Free Association).

localflavor.us.us_states.OBSOLETE_STATES = (('CM', 'Commonwealth of the Northern Mariana Islands'), ('CZ', 'Panama Canal Zone'), ('PI', 'Philippine Islands'), ('TT', 'Trust Territory of the Pacific Islands'))

Obsolete abbreviations (no longer US territories/USPS service, or code changed).

localflavor.us.us_states.STATE_CHOICES = (('AL', 'Alabama'), ('AK', 'Alaska'), ('AS', 'American Samoa'), ('AZ', 'Arizona'), ('AR', 'Arkansas'), ('AA', 'Armed Forces Americas'), ('AE', 'Armed Forces Europe'), ('AP', 'Armed Forces Pacific'), ('CA', 'California'), ('CO', 'Colorado'), ('CT', 'Connecticut'), ('DE', 'Delaware'), ('DC', 'District of Columbia'), ('FL', 'Florida'), ('GA', 'Georgia'), ('GU', 'Guam'), ('HI', 'Hawaii'), ('ID', 'Idaho'), ('IL', 'Illinois'), ('IN', 'Indiana'), ('IA', 'Iowa'), ('KS', 'Kansas'), ('KY', 'Kentucky'), ('LA', 'Louisiana'), ('ME', 'Maine'), ('MD', 'Maryland'), ('MA', 'Massachusetts'), ('MI', 'Michigan'), ('MN', 'Minnesota'), ('MS', 'Mississippi'), ('MO', 'Missouri'), ('MT', 'Montana'), ('NE', 'Nebraska'), ('NV', 'Nevada'), ('NH', 'New Hampshire'), ('NJ', 'New Jersey'), ('NM', 'New Mexico'), ('NY', 'New York'), ('NC', 'North Carolina'), ('ND', 'North Dakota'), ('MP', 'Northern Mariana Islands'), ('OH', 'Ohio'), ('OK', 'Oklahoma'), ('OR', 'Oregon'), ('PA', 'Pennsylvania'), ('PR', 'Puerto Rico'), ('RI', 'Rhode Island'), ('SC', 'South Carolina'), ('SD', 'South Dakota'), ('TN', 'Tennessee'), ('TX', 'Texas'), ('UT', 'Utah'), ('VT', 'Vermont'), ('VI', 'Virgin Islands'), ('VA', 'Virginia'), ('WA', 'Washington'), ('WV', 'West Virginia'), ('WI', 'Wisconsin'), ('WY', 'Wyoming'))

All US states and territories plus DC and military mail.

localflavor.us.us_states.USPS_CHOICES = (('AL', 'Alabama'), ('AK', 'Alaska'), ('AS', 'American Samoa'), ('AZ', 'Arizona'), ('AR', 'Arkansas'), ('AA', 'Armed Forces Americas'), ('AE', 'Armed Forces Europe'), ('AP', 'Armed Forces Pacific'), ('CA', 'California'), ('CO', 'Colorado'), ('CT', 'Connecticut'), ('DE', 'Delaware'), ('DC', 'District of Columbia'), ('FM', 'Federated States of Micronesia'), ('FL', 'Florida'), ('GA', 'Georgia'), ('GU', 'Guam'), ('HI', 'Hawaii'), ('ID', 'Idaho'), ('IL', 'Illinois'), ('IN', 'Indiana'), ('IA', 'Iowa'), ('KS', 'Kansas'), ('KY', 'Kentucky'), ('LA', 'Louisiana'), ('ME', 'Maine'), ('MH', 'Marshall Islands'), ('MD', 'Maryland'), ('MA', 'Massachusetts'), ('MI', 'Michigan'), ('MN', 'Minnesota'), ('MS', 'Mississippi'), ('MO', 'Missouri'), ('MT', 'Montana'), ('NE', 'Nebraska'), ('NV', 'Nevada'), ('NH', 'New Hampshire'), ('NJ', 'New Jersey'), ('NM', 'New Mexico'), ('NY', 'New York'), ('NC', 'North Carolina'), ('ND', 'North Dakota'), ('MP', 'Northern Mariana Islands'), ('OH', 'Ohio'), ('OK', 'Oklahoma'), ('OR', 'Oregon'), ('PW', 'Palau'), ('PA', 'Pennsylvania'), ('PR', 'Puerto Rico'), ('RI', 'Rhode Island'), ('SC', 'South Carolina'), ('SD', 'South Dakota'), ('TN', 'Tennessee'), ('TX', 'Texas'), ('UT', 'Utah'), ('VT', 'Vermont'), ('VI', 'Virgin Islands'), ('VA', 'Virginia'), ('WA', 'Washington'), ('WV', 'West Virginia'), ('WI', 'Wisconsin'), ('WY', 'Wyoming'))

All US Postal Service locations.

localflavor.us.us_states.STATES_NORMALIZED = {'ri': 'RI', 'marianas islands of the pacific': 'MP', 'conn': 'CT', 'new jersey': 'NJ', 'wisconsin': 'WI', 'wva': 'WV', 'arkansas': 'AR', 'as': 'AS', 'connecticut': 'CT', 'colo': 'CO', 'del': 'DE', 'missouri': 'MO', 'massachusetts': 'MA', 'n h': 'NH', 'wv': 'WV', 'tex': 'TX', 'oklahoma': 'OK', 'florida': 'FL', 'il': 'IL', 'wisc': 'WI', 'virgin islands': 'VI', 'american samoa': 'AS', 'miss': 'MS', 'kans': 'KS', 'okla': 'OK', 'illinois': 'IL', 'arizona': 'AZ', 'nm': 'NM', 'texas': 'TX', 'ms': 'MS', 'fl': 'FL', 'iowa': 'IA', 'virgina': 'VA', 'wis': 'WI', 'ky': 'KY', 'deleware': 'DE', 'minnesota': 'MN', 'mississippi': 'MS', 'northern mariana islands': 'MP', 'oreg': 'OR', 'alaska': 'AK', 'delaware': 'DE', 'nd': 'ND', 'american samao': 'AS', 'north dakota': 'ND', 'ark': 'AR', 'kan': 'KS', 'ariz': 'AZ', 'in': 'IN', 'new york': 'NY', 'ia': 'IA', 'id': 'ID', 'md': 'MD', 'calf': 'CA', 'ca': 'CA', 'fla': 'FL', 'or': 'OR', 'la': 'LA', 'ala': 'AL', 'new hampshire': 'NH', 'us virgin islands': 'VI', 'washington': 'WA', 'kansas': 'KS', 'south carolina': 'SC', 'georgia': 'GA', 'guam': 'GU', 'dc': 'DC', 'ind': 'IN', 'marianas islands': 'MP', 'maine': 'ME', 'michigan': 'MI', 'california': 'CA', 'n j': 'NJ', 'sc': 'SC', 'n dak': 'ND', 'ut': 'UT', 'mont': 'MT', 'pr': 'PR', 'ae': 'AE', 'colorado': 'CO', 'louisiana': 'LA', 'ak': 'AK', 'aa': 'AA', 'ny': 'NY', 'neb': 'NE', 'ne': 'NE', 'kentucky': 'KY', 'penn': 'PA', 'nebraska': 'NE', 'gu': 'GU', 'nj': 'NJ', 'w va': 'WV', 'usvi': 'VI', 'nmex': 'NM', 'calif': 'CA', 'alabama': 'AL', 'viginia': 'VA', 'territory of hawaii': 'HI', 'pennsylvania': 'PA', 'sdak': 'SD', 'massachussetts': 'MA', 'puerto rico': 'PR', 'al': 'AL', 'tx': 'TX', 'ct': 'CT', 'hi': 'HI', 'nc': 'NC', 'mt': 'MT', 'ohio': 'OH', 'wyo': 'WY', 'nev': 'NV', 'mo': 'MO', 'new mexico': 'NM', 'ga': 'GA', 'va': 'VA', 'mich': 'MI', 'co': 'CO', 'indiana': 'IN', 'n m': 'NM', 'virginia': 'VA', 'west virginia': 'WV', 'ore': 'OR', 'north carolina': 'NC', 'sd': 'SD', 'vt': 'VT', 'maryland': 'MD', 'wyoming': 'WY', 'marinas islands of the pacific': 'MP', 'pa': 'PA', 'nv': 'NV', 'ar': 'AR', 'minn': 'MN', 'utah': 'UT', 's dak': 'SD', 'tennessee': 'TN', 'ok': 'OK', 'rhode island': 'RI', 'oh': 'OH', 'nebr': 'NE', 'idaho': 'ID', 'ma': 'MA', 'ks': 'KS', 'south dakota': 'SD', 'mass': 'MA', 'nevada': 'NV', 'ill': 'IL', 'vermont': 'VT', 'n mex': 'NM', 'mn': 'MN', 'hawaii': 'HI', 'wash': 'WA', 'wi': 'WI', 'tenn': 'TN', 'district of columbia': 'DC', 'mp': 'MP', 'wa': 'WA', 'montana': 'MT', 'nh': 'NH', 'tn': 'TN', 'n d': 'ND', 'vi': 'VI', 'me': 'ME', 'ap': 'AP', 'mi': 'MI', 'az': 'AZ', 'wy': 'WY', 'de': 'DE', 'oregon': 'OR'}

Normalized versions of state names