From f8c3acc8074988eed88667e58255abab1b093119 Mon Sep 17 00:00:00 2001 From: Adrian Holovaty Date: Fri, 12 Oct 2012 17:00:35 -0500 Subject: [PATCH] Updated localflavor docs to note the new packages --- docs/ref/contrib/localflavor.txt | 1464 +++--------------------------- 1 file changed, 105 insertions(+), 1359 deletions(-) diff --git a/docs/ref/contrib/localflavor.txt b/docs/ref/contrib/localflavor.txt index 0d1319ec61..dfcb5028b3 100644 --- a/docs/ref/contrib/localflavor.txt +++ b/docs/ref/contrib/localflavor.txt @@ -6,86 +6,128 @@ The "local flavor" add-ons :synopsis: A collection of various Django snippets that are useful only for a particular country or culture. -Following its "batteries included" philosophy, Django comes with assorted -pieces of code that are useful for particular countries or cultures. These are -called the "local flavor" add-ons and live in the -:mod:`django.contrib.localflavor` package. +Historically, Django has shipped with ``django.contrib.localflavor`` -- +assorted pieces of code that are useful for particular countries or cultures. +Starting with Django 1.5, we've started the process of moving the code to +outside packages (i.e., packages distributed separately from Django), for +easier maintenance and to trim the size of Django's codebase. -Inside that package, country- or culture-specific code is organized into -subpackages, named using `ISO 3166 country codes`_. +The localflavor packages are named ``django-localflavor-*``, where the asterisk +is an `ISO 3166 country code`_. For example: ``django-localflavor-us`` is the +localflavor package for the U.S.A. -Most of the ``localflavor`` add-ons are localized form components deriving -from the :doc:`forms ` framework -- for example, a -:class:`~django.contrib.localflavor.us.forms.USStateField` that knows how to -validate U.S. state abbreviations, and a -:class:`~django.contrib.localflavor.fi.forms.FISocialSecurityNumber` that -knows how to validate Finnish social security numbers. +Most of these ``localflavor`` add-ons are country-specific fields for the +:doc:`forms ` framework -- for example, a +``USStateField`` that knows how to validate U.S. state abbreviations and a +``FISocialSecurityNumber`` that knows how to validate Finnish social security +numbers. To use one of these localized components, just import the relevant subpackage. For example, here's how you can create a form with a field representing a French telephone number:: from django import forms - from django.contrib.localflavor.fr.forms import FRPhoneNumberField + from django_localflavor_fr.forms import FRPhoneNumberField class MyForm(forms.Form): my_french_phone_no = FRPhoneNumberField() +For documentation on a given country's localflavor helpers, see its README +file. + +.. _ISO 3166 country code: http://www.iso.org/iso/country_codes.htm + +How to migrate +============== + +If you've used the old ``django.contrib.localflavor`` package, follow these two +easy steps to update your code: + +1. Install the appropriate third-party ``django-localflavor-*`` package(s). + Go to https://github.com/django/ and find the package for your country. + +2. Change your app's import statements to reference the new packages. + + For example, change this:: + + from django.contrib.localflavor.fr.forms import FRPhoneNumberField + + ...to this:: + + from django_localflavor_fr.forms import FRPhoneNumberField + +The code in the new packages is the same (it was copied directly from Django), +so you don't have to worry about backwards compatibility in terms of +functionality. Only the imports have changed. + +Deprecation policy +================== + +In Django 1.5, importing from ``django.contrib.localflavor`` will result in a +``DeprecationWarning``. This means your code will still work, but you should +change it as soon as possible. + +In Django 1.6, importing from ``django.contrib.localflavor`` will no longer +work. + Supported countries =================== -Countries currently supported by :mod:`~django.contrib.localflavor` are: +The following countries have django-localflavor- packages. -* Argentina_ -* Australia_ -* Austria_ -* Belgium_ -* Brazil_ -* Canada_ -* Chile_ -* China_ -* Colombia_ -* Croatia_ -* Czech_ -* Ecuador_ -* Finland_ -* France_ -* Germany_ -* `Hong Kong`_ -* Iceland_ -* India_ -* Indonesia_ -* Ireland_ -* Israel_ -* Italy_ -* Japan_ -* Kuwait_ -* Macedonia_ -* Mexico_ -* `The Netherlands`_ -* Norway_ -* Peru_ -* Poland_ -* Portugal_ -* Paraguay_ -* Romania_ -* Russia_ -* Slovakia_ -* Slovenia_ -* `South Africa`_ -* Spain_ -* Sweden_ -* Switzerland_ -* Turkey_ -* `United Kingdom`_ -* `United States of America`_ -* Uruguay_ +* Argentina: https://github.com/django/django-localflavor-ar +* Australia: https://github.com/django/django-localflavor-au +* Austria: https://github.com/django/django-localflavor-at +* Belgium: https://github.com/django/django-localflavor-be +* Brazil: https://github.com/django/django-localflavor-br +* Canada: https://github.com/django/django-localflavor-ca +* Chile: https://github.com/django/django-localflavor-cl +* China: https://github.com/django/django-localflavor-cn +* Colombia: https://github.com/django/django-localflavor-co +* Croatia: https://github.com/django/django-localflavor-cr +* Czech Republic: https://github.com/django/django-localflavor-cz +* Ecuador: https://github.com/django/django-localflavor-ec +* Finland: https://github.com/django/django-localflavor-fi +* France: https://github.com/django/django-localflavor-fr +* Germany: https://github.com/django/django-localflavor-de +* Hong Kong: https://github.com/django/django-localflavor-hk +* Iceland: https://github.com/django/django-localflavor-is +* India: https://github.com/django/django-localflavor-in +* Indonesia: https://github.com/django/django-localflavor-id +* Ireland: https://github.com/django/django-localflavor-ie +* Israel: https://github.com/django/django-localflavor-il +* Italy: https://github.com/django/django-localflavor-it +* Japan: https://github.com/django/django-localflavor-jp +* Kuwait: https://github.com/django/django-localflavor-kw +* Macedonia: https://github.com/django/django-localflavor-mk +* Mexico: https://github.com/django/django-localflavor-mx +* The Netherlands: https://github.com/django/django-localflavor-nl +* Norway: https://github.com/django/django-localflavor-no +* Peru: https://github.com/django/django-localflavor-pe +* Poland: https://github.com/django/django-localflavor-pl +* Portugal: https://github.com/django/django-localflavor-pt +* Paraguay: https://github.com/django/django-localflavor-py +* Romania: https://github.com/django/django-localflavor-ro +* Russia: https://github.com/django/django-localflavor-ru +* Slovakia: https://github.com/django/django-localflavor-sk +* Slovenia: https://github.com/django/django-localflavor-si +* South Africa: https://github.com/django/django-localflavor-za +* Spain: https://github.com/django/django-localflavor-es +* Sweden: https://github.com/django/django-localflavor-se +* Switzerland: https://github.com/django/django-localflavor-ch +* Turkey: https://github.com/django/django-localflavor-tr +* United Kingdom: https://github.com/django/django-localflavor-gb +* United States of America: https://github.com/django/django-localflavor-us +* Uruguay: https://github.com/django/django-localflavor-uy -The ``django.contrib.localflavor`` package also includes a ``generic`` subpackage, -containing useful code that is not specific to one particular country or culture. -Currently, it defines date, datetime and split datetime input fields based on -those from :doc:`forms `, but with non-US default formats. -Here's an example of how to use them:: +django.contrib.localflavor.generic +================================== + +The ``django.contrib.localflavor.generic`` package, which hasn't been removed from +Django yet, contains useful code that is not specific to one particular country +or culture. Currently, it defines date, datetime and split datetime input +fields based on those from :doc:`forms `, but with non-US +default formats. Here's an example of how to use them:: from django import forms from django.contrib.localflavor import generic @@ -93,52 +135,6 @@ Here's an example of how to use them:: class MyForm(forms.Form): my_date_field = generic.forms.DateField() -.. _ISO 3166 country codes: http://www.iso.org/iso/country_codes.htm -.. _Argentina: `Argentina (ar)`_ -.. _Australia: `Australia (au)`_ -.. _Austria: `Austria (at)`_ -.. _Belgium: `Belgium (be)`_ -.. _Brazil: `Brazil (br)`_ -.. _Canada: `Canada (ca)`_ -.. _Chile: `Chile (cl)`_ -.. _China: `China (cn)`_ -.. _Colombia: `Colombia (co)`_ -.. _Croatia: `Croatia (hr)`_ -.. _Czech: `Czech (cz)`_ -.. _Ecuador: `Ecuador (ec)`_ -.. _Finland: `Finland (fi)`_ -.. _France: `France (fr)`_ -.. _Germany: `Germany (de)`_ -.. _Hong Kong: `Hong Kong (hk)`_ -.. _The Netherlands: `The Netherlands (nl)`_ -.. _Iceland: `Iceland (is\_)`_ -.. _India: `India (in\_)`_ -.. _Indonesia: `Indonesia (id)`_ -.. _Ireland: `Ireland (ie)`_ -.. _Israel: `Israel (il)`_ -.. _Italy: `Italy (it)`_ -.. _Japan: `Japan (jp)`_ -.. _Kuwait: `Kuwait (kw)`_ -.. _Macedonia: `Macedonia (mk)`_ -.. _Mexico: `Mexico (mx)`_ -.. _Norway: `Norway (no)`_ -.. _Paraguay: `Paraguay (py)`_ -.. _Peru: `Peru (pe)`_ -.. _Poland: `Poland (pl)`_ -.. _Portugal: `Portugal (pt)`_ -.. _Romania: `Romania (ro)`_ -.. _Russia: `Russia (ru)`_ -.. _Slovakia: `Slovakia (sk)`_ -.. _Slovenia: `Slovenia (si)`_ -.. _South Africa: `South Africa (za)`_ -.. _Spain: `Spain (es)`_ -.. _Sweden: `Sweden (se)`_ -.. _Switzerland: `Switzerland (ch)`_ -.. _Turkey: `Turkey (tr)`_ -.. _United Kingdom: `United Kingdom (gb)`_ -.. _United States of America: `United States of America (us)`_ -.. _Uruguay: `Uruguay (uy)`_ - Internationalization of localflavor =================================== @@ -149,1253 +145,3 @@ texts to be translated, like form fields error messages, you must include :mod:`django.contrib.localflavor` in the :setting:`INSTALLED_APPS` setting, so the internationalization system can find the catalog, as explained in :ref:`how-django-discovers-translations`. - -Adding flavors -============== - -We'd love to add more of these to Django, so please `create a ticket`_ with -any code you'd like to contribute. One thing we ask is that you please use -Unicode objects (``u'mystring'``) for strings, rather than setting the encoding -in the file. See any of the existing flavors for examples. - -.. _create a ticket: https://code.djangoproject.com/newticket - -Localflavor and backwards compatibility -======================================= - -As documented in our :ref:`API stability -` policy, Django will always attempt -to make :mod:`django.contrib.localflavor` reflect the officially -gazetted policies of the appropriate local government authority. For -example, if a government body makes a change to add, alter, or remove -a province (or state, or county), that change will be reflected in -Django's localflavor in the next stable Django release. - -When a backwards-incompatible change is made (for example, the removal -or renaming of a province) the localflavor in question will raise a -warning when that localflavor is imported. This provides a runtime -indication that something may require attention. - -However, once you have addressed the backwards compatibility (for -example, auditing your code to see if any data migration is required), -the warning serves no purpose. The warning can then be supressed. -For example, to suppress the warnings raised by the Indonesian -localflavor you would use the following code:: - - import warnings - warnings.filterwarnings('ignore', - category=RuntimeWarning, - module='django.contrib.localflavor.id') - from django.contrib.localflavor.id import forms as id_forms - - -Argentina (``ar``) -============================================= - -.. class:: ar.forms.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 - -.. class:: ar.forms.ARDNIField - - A form field that validates input as a Documento Nacional de Identidad (DNI) - number. - -.. class:: ar.forms.ARCUITField - - A form field that validates input as a Codigo Unico de Identificacion - Tributaria (CUIT) number. - -.. class:: ar.forms.ARProvinceSelect - - A ``Select`` widget that uses a list of Argentina's provinces and autonomous - cities as its choices. - -Australia (``au``) -============================================= - -.. versionadded:: 1.4 - -.. class:: au.forms.AUPostCodeField - - A form field that validates input as an Australian postcode. - -.. class:: au.forms.AUPhoneNumberField - - A form field that validates input as an Australian phone number. Valid numbers - have ten digits. - -.. class:: au.forms.AUStateSelect - - A ``Select`` widget that uses a list of Australian states/territories as its - choices. - -.. class:: au.models.AUPhoneNumberField - - A model field that checks that the value is a valid Australian phone - number (ten digits). - -.. class:: au.models.AUStateField - - A model field that forms represent as a ``forms.AUStateField`` field and - stores the three-letter Australian state abbreviation in the database. - -.. class:: au.models.AUPostCodeField - - A model field that forms represent as a ``forms.AUPostCodeField`` field - and stores the four-digit Australian postcode in the database. - -Austria (``at``) -================ - -.. class:: at.forms.ATZipCodeField - - A form field that validates its input as an Austrian zip code, with the - format XXXX (first digit must be greater than 0). - -.. class:: at.forms.ATStateSelect - - A ``Select`` widget that uses a list of Austrian states as its choices. - -.. class:: at.forms.ATSocialSecurityNumberField - - A form field that validates its input as an Austrian social security number. - -Belgium (``be``) -================ - -.. class:: be.forms.BEPhoneNumberField - - A form field that validates input as a Belgium phone number, with one of - the formats 0x xxx xx xx, 0xx xx xx xx, 04xx xx xx xx, 0x/xxx.xx.xx, - 0xx/xx.xx.xx, 04xx/xx.xx.xx, 0x.xxx.xx.xx, 0xx.xx.xx.xx, 04xx.xx.xx.xx, - 0xxxxxxxx or 04xxxxxxxx. - -.. class:: be.forms.BEPostalCodeField - - A form field that validates input as a Belgium postal code, in the range - and format 1XXX-9XXX. - -.. class:: be.forms.BEProvinceSelect - - A ``Select`` widget that uses a list of Belgium provinces as its - choices. - -.. class:: be.forms.BERegionSelect - - A ``Select`` widget that uses a list of Belgium regions as its - choices. - -Brazil (``br``) -=============== - -.. class:: br.forms.BRPhoneNumberField - - A form field that validates input as a Brazilian phone number, with the format - XX-XXXX-XXXX. - -.. class:: br.forms.BRZipCodeField - - A form field that validates input as a Brazilian zip code, with the format - XXXXX-XXX. - -.. class:: br.forms.BRStateSelect - - A ``Select`` widget that uses a list of Brazilian states/territories as its - choices. - -.. class:: br.forms.BRCPFField - - A form field that validates input as `Brazilian CPF`_. - - Input can either be of the format XXX.XXX.XXX-VD or be a group of 11 digits. - -.. _Brazilian CPF: http://en.wikipedia.org/wiki/Cadastro_de_Pessoas_F%C3%ADsicas - -.. class:: br.forms.BRCNPJField - - A form field that validates input as `Brazilian CNPJ`_. - - Input can either be of the format XX.XXX.XXX/XXXX-XX or be a group of 14 - digits. - -.. _Brazilian CNPJ: http://en.wikipedia.org/wiki/National_identification_number#Brazil - -Canada (``ca``) -=============== - -.. class:: ca.forms.CAPhoneNumberField - - A form field that validates input as a Canadian phone number, with the format - XXX-XXX-XXXX. - -.. class:: ca.forms.CAPostalCodeField - - A form field that validates input as a Canadian postal code, with the format - XXX XXX. - -.. class:: ca.forms.CAProvinceField - - A form field that validates input as a Canadian province name or abbreviation. - -.. class:: ca.forms.CASocialInsuranceNumberField - - A form field that validates input as a Canadian Social Insurance Number (SIN). - A valid number must have the format XXX-XXX-XXX and pass a `Luhn mod-10 - checksum`_. - -.. _Luhn mod-10 checksum: http://en.wikipedia.org/wiki/Luhn_algorithm - -.. class:: ca.forms.CAProvinceSelect - - A ``Select`` widget that uses a list of Canadian provinces and territories as - its choices. - -Chile (``cl``) -============== - -.. class:: cl.forms.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. - -.. class:: cl.forms.CLRegionSelect - - A ``Select`` widget that uses a list of Chilean regions (Regiones) as its - choices. - -China (``cn``) -============== - -.. versionadded:: 1.4 - -.. class:: cn.forms.CNProvinceSelect - - A ``Select`` widget that uses a list of Chinese regions as its choices. - -.. class:: cn.forms.CNPostCodeField - - A form field that validates input as a Chinese post code. - Valid formats are XXXXXX where X is digit. - -.. class:: cn.forms.CNIDCardField - - A form field that validates input as a Chinese Identification Card Number. - Both 1st and 2nd generation ID Card Number are validated. - -.. class:: cn.forms.CNPhoneNumberField - - A form field that validates input as a Chinese phone number. - Valid formats are 0XX-XXXXXXXX, composed of 3 or 4 digits of region code - and 7 or 8 digits of phone number. - -.. class:: cn.forms.CNCellNumberField - - A form field that validates input as a Chinese mobile phone number. - Valid formats are like 1XXXXXXXXXX, where X is digit. - The second digit could only be 3, 5 and 8. - -Colombia (``co``) -================= - -.. versionadded:: 1.4 - -.. class:: co.forms.CoDepartmentSelect - - A ``Select`` widget that uses a list of Colombian departments - as its choices. - -Croatia (``hr``) -================ - -.. versionadded:: 1.4 - -.. class:: hr.forms.HRCountySelect - - A ``Select`` widget that uses a list of counties of Croatia as its choices. - -.. class:: hr.forms.HRPhoneNumberPrefixSelect - - A ``Select`` widget that uses a list of phone number prefixes of Croatia as - its choices. - -.. class:: hr.forms.HRLicensePlatePrefixSelect - - A ``Select`` widget that uses a list of vehicle license plate prefixes of - Croatia as its choices. - -.. class:: hr.forms.HRPhoneNumberField - - A form field that validates input as a phone number of Croatia. - A valid format is a country code or a leading zero, area code prefix, 6 or 7 - digit number; e.g. +385XXXXXXXX or 0XXXXXXXX - Validates fixed, mobile and FGSM numbers. Normalizes to a full number with - country code (+385 prefix). - -.. class:: hr.forms.HRLicensePlateField - - A form field that validates input as a vehicle license plate of Croatia. - Normalizes to the specific format XX YYYY-XX where X is a letter and Y a - digit. There can be three or four digits. - Suffix is constructed from the shared letters of the Croatian and English - alphabets. - It is used for standardized license plates only. Special cases like license - plates for oldtimers, temporary license plates, government institution - license plates and customized license plates are not covered by this field. - -.. class:: hr.forms.HRPostalCodeField - - A form field that validates input as a postal code of Croatia. - It consists of exactly five digits ranging from 10000 to 59999 inclusive. - -.. class:: hr.forms.HROIBField - - A form field that validates input as a Personal Identification Number (OIB) - of Croatia. - It consists of exactly eleven digits. - -.. class:: hr.forms.HRJMBGField - - A form field that validates input as a Unique Master Citizen Number (JMBG). - The number is still in use in Croatia, but it is being replaced by OIB. - This field works for other ex-Yugoslavia countries as well where the JMBG is - still in use. - The area segment of the JMBG is not validated because the citizens might - have emigrated to another ex-Yugoslavia country. - The number consists of exactly thirteen digits. - -.. class:: hr.forms.HRJMBAGField - - A form field that validates input as a Unique Master Academic Citizen Number - (JMBAG) of Croatia. - This number is used by college students and professors in Croatia. - The number consists of exactly nineteen digits. - -Czech (``cz``) -============== - -.. class:: cz.forms.CZPostalCodeField - - A form field that validates input as a Czech postal code. Valid formats - are XXXXX or XXX XX, where X is a digit. - -.. class:: cz.forms.CZBirthNumberField - - A form field that validates input as a Czech Birth Number. - A valid number must be in format XXXXXX/XXXX (slash is optional). - -.. class:: cz.forms.CZICNumberField - - A form field that validates input as a Czech IC number field. - -.. class:: cz.forms.CZRegionSelect - - A ``Select`` widget that uses a list of Czech regions as its choices. - -Ecuador (``ec``) -================ - -.. versionadded:: 1.4 - -.. class:: ec.forms.EcProvinceSelect - - A ``Select`` widget that uses a list of Ecuatorian provinces as - its choices. - -Finland (``fi``) -================ - -.. class:: fi.forms.FISocialSecurityNumber - - A form field that validates input as a Finnish social security number. - -.. class:: fi.forms.FIZipCodeField - - A form field that validates input as a Finnish zip code. Valid codes - consist of five digits. - -.. class:: fi.forms.FIMunicipalitySelect - - A ``Select`` widget that uses a list of Finnish municipalities as its - choices. - -France (``fr``) -=============== - -.. class:: fr.forms.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. - -.. class:: fr.forms.FRZipCodeField - - A form field that validates input as a French zip code. Valid codes - consist of five digits. - -.. class:: fr.forms.FRDepartmentSelect - - A ``Select`` widget that uses a list of French departments as its choices. - -Germany (``de``) -================ - -.. class:: de.forms.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 - -.. class:: de.forms.DEZipCodeField - - A form field that validates input as a German zip code. Valid codes - consist of five digits. - -.. class:: de.forms.DEStateSelect - - A ``Select`` widget that uses a list of German states as its choices. - -Hong Kong (``hk``) -================== - -.. class:: hk.forms.HKPhoneNumberField - - A form field that validates input as a Hong Kong phone number. - - -The Netherlands (``nl``) -======================== - -.. class:: nl.forms.NLPhoneNumberField - - A form field that validates input as a Dutch telephone number. - -.. class:: nl.forms.NLSofiNumberField - - A form field that validates input as a Dutch social security number - (SoFI/BSN). - -.. class:: nl.forms.NLZipCodeField - - A form field that validates input as a Dutch zip code. - -.. class:: nl.forms.NLProvinceSelect - - A ``Select`` widget that uses a list of Dutch provinces as its list of - choices. - -Iceland (``is_``) -================= - -.. class:: is_.forms.ISIdNumberField - - A form field that validates input as an Icelandic identification number - (kennitala). The format is XXXXXX-XXXX. - -.. class:: is_.forms.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). - -.. class:: is_.forms.ISPostalCodeSelect - - A ``Select`` widget that uses a list of Icelandic postal codes as its - choices. - -India (``in_``) -=============== - -.. class:: in_.forms.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. - -.. class:: in_.forms.INZipCodeField - - A form field that validates input as an Indian zip code, with the - format XXXXXXX. - -.. class:: in_.forms.INStateSelect - - A ``Select`` widget that uses a list of Indian states/territories as its - choices. - -.. versionadded:: 1.4 - -.. class:: in_.forms.INPhoneNumberField - - A form field that validates that the data is a valid Indian phone number, - including the STD code. It's normalised to 0XXX-XXXXXXX or 0XXX XXXXXXX - format. The first string is the STD code which is a '0' followed by 2-4 - digits. The second string is 8 digits if the STD code is 3 digits, 7 - digits if the STD code is 4 digits and 6 digits if the STD code is 5 - digits. The second string will start with numbers between 1 and 6. The - separator is either a space or a hyphen. - -Ireland (``ie``) -================ - -.. class:: ie.forms.IECountySelect - - A ``Select`` widget that uses a list of Irish Counties as its choices. - -Indonesia (``id``) -================== - -.. class:: id.forms.IDPostCodeField - - A form field that validates input as an Indonesian post code field. - -.. class:: id.forms.IDProvinceSelect - - A ``Select`` widget that uses a list of Indonesian provinces as its choices. - -.. class:: id.forms.IDPhoneNumberField - - A form field that validates input as an Indonesian telephone number. - -.. class:: id.forms.IDLicensePlatePrefixSelect - - A ``Select`` widget that uses a list of Indonesian license plate - prefix code as its choices. - -.. class:: id.forms.IDLicensePlateField - - A form field that validates input as an Indonesian vehicle license plate. - -.. class:: id.forms.IDNationalIdentityNumberField - - A form field that validates input as an Indonesian national identity - number (`NIK`_/KTP). The output will be in the format of - 'XX.XXXX.DDMMYY.XXXX'. Dots or spaces can be used in the input to break - down the numbers. - -.. _NIK: http://en.wikipedia.org/wiki/Indonesian_identity_card - -Israel (``il``) -=============== - -.. class:: il.forms.ILPostalCodeField - - A form field that validates its input as an Israeli five-digit postal code. - -.. class:: il.forms.ILIDNumberField - - A form field that validates its input as an `Israeli identification number`_. - The output will be in the format of a 2-9 digit number, consisting of a - 1-8 digit ID number followed by a single checksum digit, calculated using - the `Luhn algorithm`_. - - Input may contain an optional hyphen separating the ID number from the checksum - digit. - -.. _Israeli identification number: http://he.wikipedia.org/wiki/%D7%9E%D7%A1%D7%A4%D7%A8_%D7%96%D7%94%D7%95%D7%AA_(%D7%99%D7%A9%D7%A8%D7%90%D7%9C) -.. _Luhn algorithm: http://en.wikipedia.org/wiki/Luhn_algorithm - -Italy (``it``) -============== - -.. class:: it.forms.ITSocialSecurityNumberField - - A form field that validates input as an Italian social security number - (`codice fiscale`_). - -.. _codice fiscale: http://www.agenziaentrate.gov.it/wps/content/Nsilib/Nsi/Home/CosaDeviFare/Richiedere/Codice+fiscale+e+tessera+sanitaria/Richiesta+TS_CF/SchedaI/Informazioni+codificazione+pf/ - -.. class:: it.forms.ITVatNumberField - - A form field that validates Italian VAT numbers (partita IVA). - -.. class:: it.forms.ITZipCodeField - - A form field that validates input as an Italian zip code. Valid codes - must have five digits. - -.. class:: it.forms.ITProvinceSelect - - A ``Select`` widget that uses a list of Italian provinces as its choices. - -.. class:: it.forms.ITRegionSelect - - A ``Select`` widget that uses a list of Italian regions as its choices. - -Japan (``jp``) -============== - -.. class:: jp.forms.JPPostalCodeField - - A form field that validates input as a Japanese postcode. It accepts seven - digits, with or without a hyphen. - -.. class:: jp.forms.JPPrefectureSelect - - A ``Select`` widget that uses a list of Japanese prefectures as its choices. - -Kuwait (``kw``) -=============== - -.. class:: kw.forms.KWCivilIDNumberField - - A form field that validates input as a Kuwaiti Civil ID number. A valid - Civil ID number must obey the following rules: - - * The number consist of 12 digits. - * The birthdate of the person is a valid date. - * The calculated checksum equals to the last digit of the Civil ID. - -Macedonia (``mk``) -=================== - -.. versionadded:: 1.4 - -.. class:: mk.forms.MKIdentityCardNumberField - - A form field that validates input as a Macedonian identity card number. - Both old and new identity card numbers are supported. - - -.. class:: mk.forms.MKMunicipalitySelect - - A form ``Select`` widget that uses a list of Macedonian municipalities as - choices. - - -.. class:: mk.forms.UMCNField - - A form field that validates input as a unique master citizen - number. - - The format of the unique master citizen number is not unique - to Macedonia. For more information see: - https://secure.wikimedia.org/wikipedia/en/wiki/Unique_Master_Citizen_Number - - A value will pass validation if it complies to the following rules: - - * Consists of exactly 13 digits - * The first 7 digits represent a valid past date in the format DDMMYYY - * The last digit of the UMCN passes a checksum test - - -.. class:: mk.models.MKIdentityCardNumberField - - A model field that forms represent as a - ``forms.MKIdentityCardNumberField`` field. - - -.. class:: mk.models.MKMunicipalityField - - A model field that forms represent as a - ``forms.MKMunicipalitySelect`` and stores the 2 character code of the - municipality in the database. - - -.. class:: mk.models.UMCNField - - A model field that forms represent as a ``forms.UMCNField`` field. - - -Mexico (``mx``) -=============== - -.. class:: mx.forms.MXZipCodeField - - .. versionadded:: 1.4 - - A form field that accepts a Mexican Zip Code. - - More info about this: List of postal codes in Mexico (zipcodes_) - -.. _zipcodes: http://en.wikipedia.org/wiki/List_of_postal_codes_in_Mexico - -.. class:: mx.forms.MXRFCField - - .. versionadded:: 1.4 - - A form field that validates a Mexican *Registro Federal de Contribuyentes* for - either **Persona física** or **Persona moral**. This field accepts RFC strings - whether or not it contains a *homoclave*. - - More info about this: Registro Federal de Contribuyentes (rfc_) - -.. _rfc: http://es.wikipedia.org/wiki/Registro_Federal_de_Contribuyentes_(M%C3%A9xico) - -.. class:: mx.forms.MXCURPField - - .. versionadded:: 1.4 - - A field that validates a Mexican *Clave Única de Registro de Población*. - - More info about this: Clave Unica de Registro de Poblacion (curp_) - -.. _curp: http://www.condusef.gob.mx/index.php/clave-unica-de-registro-de-poblacion-curp - -.. class:: mx.forms.MXStateSelect - - A ``Select`` widget that uses a list of Mexican states as its choices. - -.. class:: mx.models.MXStateField - - .. versionadded:: 1.4 - - A model field that stores the three-letter Mexican state abbreviation in the - database. - -.. class:: mx.models.MXZipCodeField - - .. versionadded:: 1.4 - - A model field that forms represent as a ``forms.MXZipCodeField`` field and - stores the five-digit Mexican zip code. - -.. class:: mx.models.MXRFCField - - .. versionadded:: 1.4 - - A model field that forms represent as a ``forms.MXRFCField`` field and - stores the value of a valid Mexican RFC. - -.. class:: mx.models.MXCURPField - - .. versionadded:: 1.4 - - A model field that forms represent as a ``forms.MXCURPField`` field and - stores the value of a valid Mexican CURP. - -Additionally, a choice tuple is provided in ``django.contrib.localflavor.mx.mx_states``, -allowing customized model and form fields, and form presentations, for subsets of -Mexican states abbreviations: - -.. data:: mx.mx_states.STATE_CHOICES - - A tuple of choices of the states abbreviations for all 31 Mexican states, - plus the `Distrito Federal`. - -Norway (``no``) -=============== - -.. class:: no.forms.NOSocialSecurityNumber - - A form field that validates input as a Norwegian social security number - (personnummer_). - -.. _personnummer: http://no.wikipedia.org/wiki/Personnummer - -.. class:: no.forms.NOZipCodeField - - A form field that validates input as a Norwegian zip code. Valid codes - have four digits. - -.. class:: no.forms.NOMunicipalitySelect - - A ``Select`` widget that uses a list of Norwegian municipalities (fylker) as - its choices. - -Paraguay (``py``) -================= - -.. versionadded:: 1.4 - -.. class:: py.forms.PyDepartmentSelect - - A ``Select`` widget with a list of Paraguayan departments as choices. - -.. class:: py.forms.PyNumberedDepartmentSelect - - A ``Select`` widget with a roman numbered list of Paraguayan departments as choices. - -Peru (``pe``) -============= - -.. class:: pe.forms.PEDNIField - - A form field that validates input as a DNI (Peruvian national identity) - number. - -.. class:: pe.forms.PERUCField - - A form field that validates input as an RUC (Registro Unico de - Contribuyentes) number. Valid RUC numbers have 11 digits. - -.. class:: pe.forms.PEDepartmentSelect - - A ``Select`` widget that uses a list of Peruvian Departments as its choices. - -Poland (``pl``) -=============== - -.. class:: pl.forms.PLPESELField - - A form field that validates input as a Polish national identification number - (PESEL_). - -.. _PESEL: http://en.wikipedia.org/wiki/PESEL - -.. versionadded:: 1.4 - -.. class:: pl.forms.PLNationalIDCardNumberField - - A form field that validates input as a Polish National ID Card number. The - valid format is AAAXXXXXX, where A is letter (A-Z), X is digit and left-most - digit is checksum digit. More information about checksum calculation algorithm - see `Polish identity card`_. - -.. _`Polish identity card`: http://en.wikipedia.org/wiki/Polish_identity_card - -.. class:: pl.forms.PLREGONField - - 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 - -.. class:: pl.forms.PLPostalCodeField - - A form field that validates input as a Polish postal code. The valid format - is XX-XXX, where X is a digit. - -.. class:: pl.forms.PLNIPField - - A form field that validates input as a Polish Tax Number (NIP). Valid formats - are XXX-XXX-XX-XX, XXX-XX-XX-XXX or XXXXXXXXXX. The checksum algorithm used - for NIPs is documented at http://wipos.p.lodz.pl/zylla/ut/nip-rego.html. - -.. class:: pl.forms.PLCountySelect - - A ``Select`` widget that uses a list of Polish administrative units as its - choices. - -.. class:: pl.forms.PLProvinceSelect - - A ``Select`` widget that uses a list of Polish voivodeships (administrative - provinces) as its choices. - -Portugal (``pt``) -================= - -.. class:: pt.forms.PTZipCodeField - - A form field that validates input as a Portuguese zip code. - -.. class:: pt.forms.PTPhoneNumberField - - A form field that validates input as a Portuguese phone number. - Valid numbers have 9 digits (may include spaces) or start by 00 - or + (international). - -Romania (``ro``) -================ - -.. class:: ro.forms.ROCIFField - - A form field that validates Romanian fiscal identification codes (CIF). The - return value strips the leading RO, if given. - -.. class:: ro.forms.ROCNPField - - A form field that validates Romanian personal numeric codes (CNP). - -.. class:: ro.forms.ROCountyField - - A form field that validates its input as a Romanian county (judet) name or - abbreviation. It normalizes the input to the standard vehicle registration - abbreviation for the given county. This field will only accept names written - with diacritics; consider using ROCountySelect as an alternative. - -.. class:: ro.forms.ROCountySelect - - A ``Select`` widget that uses a list of Romanian counties (judete) as its - choices. - -.. class:: ro.forms.ROIBANField - - A form field that validates its input as a Romanian International Bank - Account Number (IBAN). The valid format is ROXX-XXXX-XXXX-XXXX-XXXX-XXXX, - with or without hyphens. - -.. class:: ro.forms.ROPhoneNumberField - - A form field that validates Romanian phone numbers, short special numbers - excluded. - -.. class:: ro.forms.ROPostalCodeField - - A form field that validates Romanian postal codes. - -Russia (``ru``) -=============== - -.. versionadded:: 1.4 - -.. class:: ru.forms.RUPostalCodeField - - Russian Postal code field. The valid format is XXXXXX, where X is any - digit and the first digit is not zero. - -.. class:: ru.forms.RUCountySelect - - A ``Select`` widget that uses a list of Russian Counties as its choices. - -.. class:: ru.forms.RURegionSelect - - A ``Select`` widget that uses a list of Russian Regions as its choices. - -.. class:: ru.forms.RUPassportNumberField - - Russian internal passport number. The valid format is XXXX XXXXXX, where X - is any digit. - -.. class:: ru.forms.RUAlienPassportNumberField - - Russian alien's passport number. The valid format is XX XXXXXXX, where X - is any digit. - -Slovakia (``sk``) -================= - -.. class:: sk.forms.SKPostalCodeField - - A form field that validates input as a Slovak postal code. Valid formats - are XXXXX or XXX XX, where X is a digit. - -.. class:: sk.forms.SKDistrictSelect - - A ``Select`` widget that uses a list of Slovak districts as its choices. - -.. class:: sk.forms.SKRegionSelect - - A ``Select`` widget that uses a list of Slovak regions as its choices. - -Slovenia (``si``) -================= - -.. class:: si.forms.SIEMSOField - - A form field that validates input as Slovenian personal identification - number and stores gender and birthday to self.info dictionary. - -.. class:: si.forms.SITaxNumberField - - A form field that validates input as a Slovenian tax number. Valid input - is SIXXXXXXXX or XXXXXXXX. - -.. class:: si.forms.SIPhoneNumberField - - A form field that validates input as a Slovenian phone number. Phone - number must contain at least local area code with optional country code. - -.. class:: si.forms.SIPostalCodeField - - A form field that provides a choice field of major Slovenian postal - codes. - -.. class:: si.forms.SIPostalCodeSelect - - A ``Select`` widget that uses a list of major Slovenian postal codes as - its choices. - - -South Africa (``za``) -===================== - -.. class:: za.forms.ZAIDField - - A form field that validates input as a South African ID number. Validation - uses the Luhn checksum and a simplistic (i.e., not entirely accurate) check - for birth date. - -.. class:: za.forms.ZAPostCodeField - - A form field that validates input as a South African postcode. Valid - postcodes must have four digits. - -Spain (``es``) -============== - -.. class:: es.forms.ESIdentityCardNumberField - - A form field that validates input as a Spanish NIF/NIE/CIF (Fiscal - Identification Number) code. - -.. class:: es.forms.ESCCCField - - A form field that validates input as a Spanish bank account number (Codigo - Cuenta Cliente or CCC). A valid CCC number has the format - EEEE-OOOO-CC-AAAAAAAAAA, where the E, O, C and A digits denote the entity, - office, checksum and account, respectively. The first checksum digit - validates the entity and office. The second checksum digit validates the - account. It is also valid to use a space as a delimiter, or to use no - delimiter. - -.. class:: es.forms.ESPhoneNumberField - - A form field that validates input as a Spanish phone number. Valid numbers - have nine digits, the first of which is 6, 8 or 9. - -.. class:: es.forms.ESPostalCodeField - - A form field that validates input as a Spanish postal code. Valid codes - have five digits, the first two being in the range 01 to 52, representing - the province. - -.. class:: es.forms.ESProvinceSelect - - A ``Select`` widget that uses a list of Spanish provinces as its choices. - -.. class:: es.forms.ESRegionSelect - - A ``Select`` widget that uses a list of Spanish regions as its choices. - -Sweden (``se``) -=============== - -.. class:: se.forms.SECountySelect - - A Select form widget that uses a list of the Swedish counties (län) as its - choices. - - The cleaned value is the official county code -- see - http://en.wikipedia.org/wiki/Counties_of_Sweden for a list. - -.. class:: se.forms.SEOrganisationNumber - - A form field that validates input as a Swedish organisation number - (organisationsnummer). - - It accepts the same input as SEPersonalIdentityField (for sole - proprietorships (enskild firma). However, co-ordination numbers are not - accepted. - - It also accepts ordinary Swedish organisation numbers with the format - NNNNNNNNNN. - - The return value will be YYYYMMDDXXXX for sole proprietors, and NNNNNNNNNN - for other organisations. - -.. class:: se.forms.SEPersonalIdentityNumber - - A form field that validates input as a Swedish personal identity number - (personnummer). - - The correct formats are YYYYMMDD-XXXX, YYYYMMDDXXXX, YYMMDD-XXXX, - YYMMDDXXXX and YYMMDD+XXXX. - - A \+ indicates that the person is older than 100 years, which will be taken - into consideration when the date is validated. - - The checksum will be calculated and checked. The birth date is checked - to be a valid date. - - By default, co-ordination numbers (samordningsnummer) will be accepted. To - only allow real personal identity numbers, pass the keyword argument - coordination_number=False to the constructor. - - The cleaned value will always have the format YYYYMMDDXXXX. - -.. class:: se.forms.SEPostalCodeField - - A form field that validates input as a Swedish postal code (postnummer). - Valid codes consist of five digits (XXXXX). The number can optionally be - formatted with a space after the third digit (XXX XX). - - The cleaned value will never contain the space. - -Switzerland (``ch``) -==================== - -.. class:: ch.forms.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. - -.. class:: ch.forms.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. - -.. class:: ch.forms.CHZipCodeField - - A form field that validates input as a Swiss zip code. Valid codes - consist of four digits. - -.. class:: ch.forms.CHStateSelect - - A ``Select`` widget that uses a list of Swiss states as its choices. - -Turkey (``tr``) -=============== - -.. class:: tr.forms.TRZipCodeField - - A form field that validates input as a Turkish zip code. Valid codes - consist of five digits. - -.. class:: tr.forms.TRPhoneNumberField - - A form field that validates input as a Turkish phone number. The correct - format is 0xxx xxx xxxx. +90xxx xxx xxxx and inputs without spaces also - validates. The result is normalized to xxx xxx xxxx format. - -.. class:: tr.forms.TRIdentificationNumberField - - A form field that validates input as a TR identification number. A valid - number must satisfy the following: - - * The number consist of 11 digits. - * The first digit cannot be 0. - * (sum(1st, 3rd, 5th, 7th, 9th)*7 - sum(2nd,4th,6th,8th)) % 10) must be - equal to the 10th digit. - * (sum(1st to 10th) % 10) must be equal to the 11th digit. - -.. class:: tr.forms.TRProvinceSelect - - A ``select`` widget that uses a list of Turkish provinces as its choices. - -United Kingdom (``gb``) -======================= - -.. class:: gb.forms.GBPostcodeField - - 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.cabinetoffice.gov.uk/media/291293/bs7666-v2-0.xml. - -.. class:: gb.forms.GBCountySelect - - A ``Select`` widget that uses a list of UK counties/regions as its choices. - -.. class:: gb.forms.GBNationSelect - - A ``Select`` widget that uses a list of UK nations as its choices. - -United States of America (``us``) -================================= - -.. class:: us.forms.USPhoneNumberField - - A form field that validates input as a U.S. phone number. - -.. class:: us.forms.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) - -.. class:: us.forms.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. - -.. class:: us.forms.USZipCodeField - - A form field that validates input as a U.S. ZIP code. Valid formats are - XXXXX or XXXXX-XXXX. - -.. class:: us.forms.USStateSelect - - 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 - number (in the format ``XXX-XXX-XXXX``). - -.. class:: us.models.USStateField - - 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``) -================ - -.. class:: uy.forms.UYCIField - - A field that validates Uruguayan 'Cedula de identidad' (CI) numbers. - -.. class:: uy.forms.UYDepartamentSelect - - A ``Select`` widget that uses a list of Uruguayan departments as its - choices.