diff --git a/docs/localflavor.txt b/docs/localflavor.txt index fe2d195f65..154922ff45 100644 --- a/docs/localflavor.txt +++ b/docs/localflavor.txt @@ -2,16 +2,22 @@ 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 organized as a set of +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 ``django.contrib.localflavor`` +package. + +Inside that package, country- or culture-specific code is organized into 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 localized 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 field for French telephone -numbers is created like so:: +the newforms_ 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 newforms as forms from django.contrib.localflavor import fr @@ -19,32 +25,48 @@ numbers is created like so:: class MyForm(forms.Form): my_french_phone_no = fr.forms.FRPhoneNumberField() +Supported countries +=================== + Countries currently supported by ``localflavor`` are: -* Argentina_ -* Australia_ -* Brazil_ -* Canada_ -* Chile_ -* Finland_ -* France_ -* Germany_ -* Holland_ -* Iceland_ -* India_ -* Italy_ -* Japan_ -* Mexico_ -* Norway_ -* Peru_ -* Poland_ -* Slovakia_ -* `South Africa`_ -* Spain_ -* Switzerland_ -* `United Kingdom`_ -* `United States of America`_ + * Argentina_ + * Australia_ + * Brazil_ + * Canada_ + * Chile_ + * Finland_ + * France_ + * Germany_ + * Holland_ + * Iceland_ + * India_ + * Italy_ + * Japan_ + * Mexico_ + * Norway_ + * Peru_ + * Poland_ + * Slovakia_ + * `South Africa`_ + * Spain_ + * Switzerland_ + * `United Kingdom`_ + * `United States of America`_ +The ``localflavor`` package also includes a ``generic`` subpackage, containing +useful code that is not specific to one particular country or culture. +Currently, it defines date and datetime 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() + +.. _ISO 3166 country codes: http://www.iso.org/iso/country_codes/iso_3166_code_lists/english_country_names_and_code_elements.htm .. _Argentina: `Argentina (django.contrib.localflavor.ar)`_ .. _Australia: `Australia (django.contrib.localflavor.au)`_ .. _Brazil: `Brazil (django.contrib.localflavor.br)`_ @@ -68,29 +90,15 @@ Countries currently supported by ``localflavor`` are: .. _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/ +Adding flavors +============== -.. 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). - +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. Argentina (``django.contrib.localflavor.ar``) ============================================= @@ -108,7 +116,6 @@ ARProvinceSelect A ``Select`` widget that uses a list of Argentina's provinces as its choices. - Australia (``django.contrib.localflavor.au``) ============================================= @@ -129,7 +136,6 @@ AUStateSelect A ``Select`` widget that uses a list of Australian states/territories as its choices. - Brazil (``django.contrib.localflavor.br``) ========================================== @@ -151,7 +157,6 @@ BRStateSelect A ``Select`` widget that uses a list of Brazilian states/territories as its choices. - Canada (``django.contrib.localflavor.ca``) ========================================== @@ -187,7 +192,6 @@ CAProvinceSelect A ``Select`` widget that uses a list of Canadian provinces and territories as its choices. - Chile (``django.contrib.localflavor.cl``) ========================================= @@ -203,7 +207,6 @@ CLRegionSelect A ``Select`` widget that uses a list of Chilean regions (Regiones) as its choices. - Finland (``django.contrib.localflavor.fi``) =========================================== @@ -215,7 +218,7 @@ 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 +A form field that validates input as a Finnish zip code. Valid codes consist of five digits. FIMunicipalitySelect @@ -224,7 +227,6 @@ FIMunicipalitySelect A ``Select`` widget that uses a list of Finnish municipalities as its choices. - France (``django.contrib.localflavor.fr``) ========================================== @@ -232,13 +234,13 @@ 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 +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 +A form field that validates input as a French zip code. Valid codes consist of five digits. FRDepartmentSelect @@ -246,7 +248,6 @@ FRDepartmentSelect A ``Select`` widget that uses a list of French departments as its choices. - Germany (``django.contrib.localflavor.de``) =========================================== @@ -254,7 +255,7 @@ DEIdentityCardNumberField ------------------------- A form field that validates input as a German identity card number -(Personalausweis_). Valid numbers have the format +(Personalausweis_). Valid numbers have the format XXXXXXXXXXX-XXXXXXX-XXXXXXX-X, with no group consisting entirely of zeroes. .. _Personalausweis: http://de.wikipedia.org/wiki/Personalausweis @@ -262,7 +263,7 @@ XXXXXXXXXXX-XXXXXXX-XXXXXXX-X, with no group consisting entirely of zeroes. DEZipCodeField -------------- -A form field that validates input as a German zip code. Valid codes +A form field that validates input as a German zip code. Valid codes consist of five digits. DEStateSelect @@ -270,7 +271,6 @@ DEStateSelect A ``Select`` widget that uses a list of German states as its choices. - Holland (``django.contrib.localflavor.nl``) =========================================== @@ -296,7 +296,6 @@ NLProvinceSelect A ``Select`` widget that uses a list of Dutch provinces as its list of choices. - Iceland (``django.contrib.localflavor.is_``) ============================================ @@ -304,7 +303,7 @@ ISIdNumberField --------------- A form field that validates input as an Icelandic identification number -(kennitala). The format is XXXXXX-XXXX. +(kennitala). The format is XXXXXX-XXXX. ISPhoneNumberField ------------------ @@ -318,7 +317,6 @@ ISPostalCodeSelect A ``Select`` widget that uses a list of Icelandic postal codes as its choices. - India (``django.contrib.localflavor.in_``) ========================================== @@ -326,7 +324,7 @@ INStateField ------------ A form field that validates input as an Indian state/territory name or -abbreviation. Input is normalized to the standard two-letter vehicle +abbreviation. Input is normalized to the standard two-letter vehicle registration abbreviation for the given state or territory. INZipCodeField @@ -341,7 +339,6 @@ INStateSelect A ``Select`` widget that uses a list of Indian states/territories as its choices. - Italy (``django.contrib.localflavor.it``) ========================================= @@ -361,7 +358,7 @@ A form field that validates Italian VAT numbers (partita IVA). ITZipCodeField -------------- -A form field that validates input as an Italian zip code. Valid codes +A form field that validates input as an Italian zip code. Valid codes must have five digits. ITProvinceSelect @@ -374,22 +371,20 @@ 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. +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. - Mexico (``django.contrib.localflavor.mx``) ========================================== @@ -398,7 +393,6 @@ MXStateSelect A ``Select`` widget that uses a list of Mexican states as its choices. - Norway (``django.contrib.localflavor.no``) ========================================== @@ -413,7 +407,7 @@ A form field that validates input as a Norwegian social security number NOZipCodeField -------------- -A form field that validates input as a Norwegian zip code. Valid codes +A form field that validates input as a Norwegian zip code. Valid codes have four digits. NOMunicipalitySelect @@ -422,7 +416,6 @@ NOMunicipalitySelect A ``Select`` widget that uses a list of Norwegian municipalities (fylker) as its choices. - Peru (``django.contrib.localflavor.pe``) ======================================== @@ -436,14 +429,13 @@ PERUCField ---------- A form field that validates input as an RUC (Registro Unico de -Contribuyentes) number. Valid RUC numbers have eleven digits. +Contribuyentes) number. Valid RUC numbers have 11 digits. PEDepartmentSelect ------------------ A ``Select`` widget that uses a list of Peruvian Departments as its choices. - Poland (``django.contrib.localflavor.pl``) ========================================== @@ -459,7 +451,7 @@ PLNationalBusinessRegisterField ------------------------------- A form field that validates input as a Polish National Official Business -Register Number (REGON_), having either seven or nine digits. The checksum +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. @@ -468,14 +460,14 @@ http://wipos.p.lodz.pl/zylla/ut/nip-rego.html. PLPostalCodeField ----------------- -A form field that validates input as a Polish postal code. The valid format +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 +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 @@ -490,14 +482,13 @@ 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 +A form field that validates input as a Slovak postal code. Valid formats are XXXXX or XXX XX, where X is a digit. SKDistrictSelect @@ -510,24 +501,22 @@ SKRegionSelect A ``Select`` widget that uses a list of Slovak regions as its choices. - South Africa (``django.contrib.localflavor.za``) ================================================ ZAIDField --------- -A form field that validates input as a South African ID number. Validation +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. ZAPostCodeField --------------- -A form field that validates input as a South African postcode. Valid +A form field that validates input as a South African postcode. Valid postcodes must have four digits. - Spain (``django.contrib.localflavor.es``) ========================================= @@ -541,23 +530,23 @@ 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 +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 +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. ESPhoneNumberField ------------------ -A form field that validates input as a Spanish phone number. Valid numbers +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. ESPostalCodeField ----------------- -A form field that validates input as a Spanish postal code. Valid codes +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. @@ -571,7 +560,6 @@ ESRegionSelect A ``Select`` widget that uses a list of Spanish regions as its choices. - Switzerland (``django.contrib.localflavor.ch``) =============================================== @@ -585,14 +573,14 @@ 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 +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 +A form field that validates input as a Swiss zip code. Valid codes consist of four digits. CHStateSelect @@ -600,7 +588,6 @@ CHStateSelect A ``Select`` widget that uses a list of Swiss states as its choices. - United Kingdom (``django.contrib.localflavor.uk``) ================================================== @@ -621,7 +608,6 @@ UKNationSelect A ``Select`` widget that uses a list of UK nations as its choices. - United States of America (``django.contrib.localflavor.us``) ============================================================ @@ -636,13 +622,13 @@ 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) + * 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 ------------ @@ -654,11 +640,11 @@ for the given state. USZipCodeField -------------- -A form field that validates input as a U.S. zip code. Valid formats are +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 +A form ``Select`` widget that uses a list of U.S. states/territories as its choices.