diff --git a/docs/localflavor.txt b/docs/localflavor.txt new file mode 100644 index 0000000000..3eecba57e7 --- /dev/null +++ b/docs/localflavor.txt @@ -0,0 +1,654 @@ +========================== +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 +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:: + + 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_ +* Mexico_ +* Norway_ +* Peru_ +* Poland_ +* Slovakia_ +* `South Africa`_ +* Spain_ +* 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)`_ +.. _Mexico: `Mexico (django.contrib.localflavor.mx)`_ +.. _Norway: `Norway (django.contrib.localflavor.no)`_ +.. _Peru: `Peru (django.contrib.localflavor.pe)`_ +.. _Poland: `Poland (django.contrib.localflavor.pl)`_ +.. _Slovakia: `Slovakia (django.contrib.localflavor.sk)`_ +.. _South Africa: `South Africa (django.contrib.localflavor.za)`_ +.. _Spain: `Spain (django.contrib.localflavor.es)`_ +.. _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. + + +Mexico (``django.contrib.localflavor.mx``) +========================================== + +MXStateSelect +------------- + +A ``Select`` widget that uses a list of Mexican states 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. + + +South Africa (``django.contrib.localflavor.za``) +================================================ + +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. + +ZAPostCodeField +--------------- + +A form field that validates input as a South African postcode. Valid +postcodes must have four digits. + + +Spain (``django.contrib.localflavor.es``) +========================================= + +ESIdentityCardNumberField +------------------------- + +A form field that validates input as a Spanish NIF/NIE/CIF (Fiscal +Identification Number) code. + +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. + +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. + +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. + +ESProvinceSelect +---------------- + +A ``Select`` widget that uses a list of Spanish provinces as its choices. + +ESRegionSelect +-------------- + +A ``Select`` widget that uses a list of Spanish 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.