Fixed #3883 -- Added initial localflavor documentation. Thanks, Nick Efford.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@6849 bcc190cf-cafb-0310-a4f2-bffc1f526a37

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.