========================== The "local flavor" add-ons ========================== Django comes with assorted pieces of code that are useful only for a particular country or culture. These pieces of code are organised as a set of subpackages, named using `ISO 3166 country codes`_. .. _ISO 3166 country codes: http://www.iso.org/iso/country_codes/iso_3166_code_lists/english_country_names_and_code_elements.htm Most of the ``localflavor`` add-ons are localised form components deriving from the newforms_ framework. To use one of these localized components, just import the relevant subpackage. For example, a form with a form with a field for French telephone numbers is created like so:: from django import newforms as forms from django.contrib.localflavor import fr class MyForm(forms.Form): my_french_phone_no = fr.forms.FRPhoneNumberField() Countries currently supported by ``localflavor`` are: * Argentina_ * Australia_ * Brazil_ * Canada_ * Chile_ * Finland_ * France_ * Germany_ * Holland_ * Iceland_ * India_ * Italy_ * Japan_ * Norway_ * Peru_ * Poland_ * Slovakia_ * Switzerland_ * `United Kingdom`_ * `United States of America`_ .. _Argentina: `Argentina (django.contrib.localflavor.ar)`_ .. _Australia: `Australia (django.contrib.localflavor.au)`_ .. _Brazil: `Brazil (django.contrib.localflavor.br)`_ .. _Canada: `Canada (django.contrib.localflavor.ca)`_ .. _Chile: `Chile (django.contrib.localflavor.cl)`_ .. _Finland: `Finland (django.contrib.localflavor.fi)`_ .. _France: `France (django.contrib.localflavor.fr)`_ .. _Germany: `Germany (django.contrib.localflavor.de)`_ .. _Holland: `Holland (django.contrib.localflavor.nl)`_ .. _Iceland: `Iceland (django.contrib.localflavor.is\_)`_ .. _India: `India (django.contrib.localflavor.in\_)`_ .. _Italy: `Italy (django.contrib.localflavor.it)`_ .. _Japan: `Japan (django.contrib.localflavor.jp)`_ .. _Norway: `Norway (django.contrib.localflavor.no)`_ .. _Peru: `Peru (django.contrib.localflavor.pe)`_ .. _Poland: `Poland (django.contrib.localflavor.pl)`_ .. _Slovakia: `Slovakia (django.contrib.localflavor.sk)`_ .. _Switzerland: `Switzerland (django.contrib.localflavor.ch)`_ .. _United Kingdom: `United Kingdom (django.contrib.localflavor.uk)`_ .. _United States of America: `United States of America (django.contrib.localflavor.us)`_ The ``localflavor`` add-on also includes the ``generic`` subpackage, containing useful code that is not specific to one particular country or culture. Currently, it defines date and date & time input fields based on those from newforms_, but with non-US default formats. Here's an example of how to use them:: from django import newforms as forms from django.contrib.localflavor import generic class MyForm(forms.Form): my_date_field = generic.forms.DateField() .. _newforms: ../newforms/ .. admonition:: Adding a Flavor We'd love to add more of these to Django, so please create a ticket for anything that you've found useful. Please use unicode objects (``u'mystring'``) for strings, rather than setting the encoding in the file (see any of the existing flavors for examples). Argentina (``django.contrib.localflavor.ar``) ============================================= ARPostalCodeField ----------------- A form field that validates input as either a classic four-digit Argentinian postal code or a CPA_. .. _CPA: http://www.correoargentino.com.ar/consulta_cpa/home.php ARProvinceSelect ---------------- A ``Select`` widget that uses a list of Argentina's provinces as its choices. Australia (``django.contrib.localflavor.au``) ============================================= AUPostCodeField --------------- A form field that validates input as an Australian postcode. AUPhoneNumberField ------------------ A form field that validates input as an Australian phone number. Valid numbers have ten digits. AUStateSelect ------------- A ``Select`` widget that uses a list of Australian states/territories as its choices. Brazil (``django.contrib.localflavor.br``) ========================================== BRPhoneNumberField ------------------ A form field that validates input as a Brazilian phone number, with the format XX-XXXX-XXXX. BRZipCodeField -------------- A form field that validates input as a Brazilian zip code, with the format XXXXX-XXX. BRStateSelect ------------- A ``Select`` widget that uses a list of Brazilian states/territories as its choices. Canada (``django.contrib.localflavor.ca``) ========================================== CAPhoneNumberField ------------------ A form field that validates input as a Canadian phone number, with the format XXX-XXX-XXXX. CAPostalCodeField ----------------- A form field that validates input as a Canadian postal code, with the format XXX XXX. CAProvinceField --------------- A form field that validates input as a Canadian province name or abbreviation. CASocialInsuranceNumberField ---------------------------- A form field that validates input as a Canadian Social Insurance Number (SIN). A valid number must have the format XXX-XXX-XXXX and pass a `Luhn mod-10 checksum`_. .. _Luhn mod-10 checksum: http://en.wikipedia.org/wiki/Luhn_algorithm CAProvinceSelect ---------------- A ``Select`` widget that uses a list of Canadian provinces and territories as its choices. Chile (``django.contrib.localflavor.cl``) ========================================= CLRutField ---------- A form field that validates input as a Chilean national identification number ('Rol Unico Tributario' or RUT). The valid format is XX.XXX.XXX-X. CLRegionSelect -------------- A ``Select`` widget that uses a list of Chilean regions (Regiones) as its choices. Finland (``django.contrib.localflavor.fi``) =========================================== FISocialSecurityNumber ---------------------- A form field that validates input as a Finnish social security number. FIZipCodeField -------------- A form field that validates input as a Finnish zip code. Valid codes consist of five digits. FIMunicipalitySelect -------------------- A ``Select`` widget that uses a list of Finnish municipalities as its choices. France (``django.contrib.localflavor.fr``) ========================================== FRPhoneNumberField ------------------ A form field that validates input as a French local phone number. The correct format is 0X XX XX XX XX. 0X.XX.XX.XX.XX and 0XXXXXXXXX validate but are corrected to 0X XX XX XX XX. FRZipCodeField -------------- A form field that validates input as a French zip code. Valid codes consist of five digits. FRDepartmentSelect ------------------ A ``Select`` widget that uses a list of French departments as its choices. Germany (``django.contrib.localflavor.de``) =========================================== DEIdentityCardNumberField ------------------------- A form field that validates input as a German identity card number (Personalausweis_). Valid numbers have the format XXXXXXXXXXX-XXXXXXX-XXXXXXX-X, with no group consisting entirely of zeroes. .. _Personalausweis: http://de.wikipedia.org/wiki/Personalausweis DEZipCodeField -------------- A form field that validates input as a German zip code. Valid codes consist of five digits. DEStateSelect ------------- A ``Select`` widget that uses a list of German states as its choices. Holland (``django.contrib.localflavor.nl``) =========================================== NLPhoneNumberField ------------------ A form field that validates input as a Dutch telephone number. NLSofiNumberField ----------------- A form field that validates input as a Dutch social security number (SoFI/BSN). NLZipCodeField -------------- A form field that validates input as a Dutch zip code. NLProvinceSelect ---------------- A ``Select`` widget that uses a list of Dutch provinces as its list of choices. Iceland (``django.contrib.localflavor.is_``) ============================================ ISIdNumberField --------------- A form field that validates input as an Icelandic identification number (kennitala). The format is XXXXXX-XXXX. ISPhoneNumberField ------------------ A form field that validates input as an Icelandtic phone number (seven digits with an optional hyphen or space after the first three digits). ISPostalCodeSelect ------------------ A ``Select`` widget that uses a list of Icelandic postal codes as its choices. India (``django.contrib.localflavor.in_``) ========================================== INStateField ------------ A form field that validates input as an Indian state/territory name or abbreviation. Input is normalized to the standard two-letter vehicle registration abbreviation for the given state or territory. INZipCodeField -------------- A form field that validates input as an Indian zip code, with the format XXXXXXX. INStateSelect ------------- A ``Select`` widget that uses a list of Indian states/territories as its choices. Italy (``django.contrib.localflavor.it``) ========================================= ITSocialSecurityNumberField --------------------------- A form field that validates input as an Italian social security number (`codice fiscale`_). .. _codice fiscale: http://www.agenziaentrate.it/ilwwcm/connect/Nsi/Servizi/Codice+fiscale+-+tessera+sanitaria/Codice+fiscale/NSI+Informazioni+sulla+codificazione+delle+persone+fisiche ITVatNumberField ---------------- A form field that validates Italian VAT numbers (partita IVA). ITZipCodeField -------------- A form field that validates input as an Italian zip code. Valid codes must have five digits. ITProvinceSelect ---------------- A ``Select`` widget that uses a list of Italian provinces as its choices. ITRegionSelect -------------- A ``Select`` widget that uses a list of Italian regions as its choices. Japan (``django.contrib.localflavor.jp``) ========================================= JPPostalCodeField ----------------- A form field that validates input as a Japanese postcode. It accepts seven digits, with or without a hyphen. JPPrefectureSelect ------------------ A ``Select`` widget that uses a list of Japanese prefectures as its choices. Norway (``django.contrib.localflavor.no``) ========================================== NOSocialSecurityNumber ---------------------- A form field that validates input as a Norwegian social security number (personnummer_). .. _personnummer: http://no.wikipedia.org/wiki/Personnummer NOZipCodeField -------------- A form field that validates input as a Norwegian zip code. Valid codes have four digits. NOMunicipalitySelect -------------------- A ``Select`` widget that uses a list of Norwegian municipalities (fylker) as its choices. Peru (``django.contrib.localflavor.pe``) ======================================== PEDNIField ---------- A form field that validates input as a DNI (Peruvian national identity) number. PERUCField ---------- A form field that validates input as an RUC (Registro Unico de Contribuyentes) number. Valid RUC numbers have eleven digits. PEDepartmentSelect ------------------ A ``Select`` widget that uses a list of Peruvian Departments as its choices. Poland (``django.contrib.localflavor.pl``) ========================================== PLNationalIdentificationNumberField ----------------------------------- A form field that validates input as a Polish national identification number (PESEL_). .. _PESEL: http://en.wikipedia.org/wiki/PESEL PLNationalBusinessRegisterField ------------------------------- A form field that validates input as a Polish National Official Business Register Number (REGON_), having either seven or nine digits. The checksum algorithm used for REGONs is documented at http://wipos.p.lodz.pl/zylla/ut/nip-rego.html. .. _REGON: http://www.stat.gov.pl/bip/regon_ENG_HTML.htm PLPostalCodeField ----------------- A form field that validates input as a Polish postal code. The valid format is XX-XXX, where X is a digit. PLTaxNumberField ---------------- A form field that validates input as a Polish Tax Number (NIP). Valid formats are XXX-XXX-XX-XX or XX-XX-XXX-XXX. The checksum algorithm used for NIPs is documented at http://wipos.p.lodz.pl/zylla/ut/nip-rego.html. PLAdministrativeUnitSelect -------------------------- A ``Select`` widget that uses a list of Polish administrative units as its choices. PLVoivodeshipSelect ------------------- A ``Select`` widget that uses a list of Polish voivodeships (administrative provinces) as its choices. Slovakia (``django.contrib.localflavor.sk``) ============================================ SKPostalCodeField ----------------- A form field that validates input as a Slovak postal code. Valid formats are XXXXX or XXX XX, where X is a digit. SKDistrictSelect ---------------- A ``Select`` widget that uses a list of Slovak districts as its choices. SKRegionSelect -------------- A ``Select`` widget that uses a list of Slovak regions as its choices. Switzerland (``django.contrib.localflavor.ch``) =============================================== CHIdentityCardNumberField ------------------------- A form field that validates input as a Swiss identity card number. A valid number must confirm to the X1234567<0 or 1234567890 format and have the correct checksums -- see http://adi.kousz.ch/artikel/IDCHE.htm. CHPhoneNumberField ------------------ A form field that validates input as a Swiss phone number. The correct format is 0XX XXX XX XX. 0XX.XXX.XX.XX and 0XXXXXXXXX validate but are corrected to 0XX XXX XX XX. CHZipCodeField -------------- A form field that validates input as a Swiss zip code. Valid codes consist of four digits. CHStateSelect ------------- A ``Select`` widget that uses a list of Swiss states as its choices. United Kingdom (``django.contrib.localflavor.uk``) ================================================== UKPostcodeField --------------- A form field that validates input as a UK postcode. The regular expression used is sourced from the schema for British Standard BS7666 address types at http://www.govtalk.gov.uk/gdsc/schemas/bs7666-v2-0.xsd. United States of America (``django.contrib.localflavor.us``) ============================================================ USPhoneNumberField ------------------ A form field that validates input as a U.S. phone number. USSocialSecurityNumberField --------------------------- A form field that validates input as a U.S. Social Security Number (SSN). A valid SSN must obey the following rules: * Format of XXX-XX-XXXX * No group of digits consisting entirely of zeroes * Leading group of digits cannot be 666 * Number not in promotional block 987-65-4320 through 987-65-4329 * Number not one known to be invalid due to widespread promotional use or distribution (e.g., the Woolworth's number or the 1962 promotional number) USStateField ------------ A form field that validates input as a U.S. state name or abbreviation. It normalizes the input to the standard two-letter postal service abbreviation for the given state. USZipCodeField -------------- A form field that validates input as a U.S. zip code. Valid formats are XXXXX or XXXXX-XXXX. USStateSelect ------------- A form Select widget that uses a list of U.S. states/territories as its choices.