Ticket #3883: localflavor.3.txt

==========================
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_
* Norway_
* Peru_
* Poland_
* Slovakia_
* Switzerland_
* `United Kingdom`_
* `United States of America`_

.. _Argentina: `Argentina (django.contrib.localflavor.ar)`_
.. _Australia: `Australia (django.contrib.localflavor.au)`_
.. _Brazil: `Brazil (django.contrib.localflavor.br)`_
.. _Canada: `Canada (django.contrib.localflavor.ca)`_
.. _Chile: `Chile (django.contrib.localflavor.cl)`_
.. _Finland: `Finland (django.contrib.localflavor.fi)`_
.. _France: `France (django.contrib.localflavor.fr)`_
.. _Germany: `Germany (django.contrib.localflavor.de)`_
.. _Holland: `Holland (django.contrib.localflavor.nl)`_
.. _Iceland: `Iceland (django.contrib.localflavor.is\_)`_
.. _India: `India (django.contrib.localflavor.in\_)`_
.. _Italy: `Italy (django.contrib.localflavor.it)`_
.. _Japan: `Japan (django.contrib.localflavor.jp)`_
.. _Norway: `Norway (django.contrib.localflavor.no)`_
.. _Peru: `Peru (django.contrib.localflavor.pe)`_
.. _Poland: `Poland (django.contrib.localflavor.pl)`_
.. _Slovakia: `Slovakia (django.contrib.localflavor.sk)`_
.. _Switzerland: `Switzerland (django.contrib.localflavor.ch)`_
.. _United Kingdom: `United Kingdom (django.contrib.localflavor.uk)`_
.. _United States of America: `United States of America (django.contrib.localflavor.us)`_

The ``localflavor`` add-on also includes the ``generic`` subpackage,
containing useful code that is not specific to one particular country or
culture.  Currently, it defines date and date & time input fields based on
those from newforms_, but with non-US default formats.  Here's an example of
how to use them::

    from django import newforms as forms
    from django.contrib.localflavor import generic

    class MyForm(forms.Form):
        my_date_field = generic.forms.DateField()

.. _newforms: ../newforms/


.. admonition:: Adding a Flavor

   We'd love to add more of these to Django, so please create a ticket for
   anything that you've found useful. Please use unicode objects
   (``u'mystring'``) for strings, rather than setting the encoding in the
   file (see any of the existing flavors for examples).


Argentina (``django.contrib.localflavor.ar``)
=============================================

ARPostalCodeField
-----------------

A form field that validates input as either a classic four-digit
Argentinian postal code or a CPA_.

.. _CPA: http://www.correoargentino.com.ar/consulta_cpa/home.php

ARProvinceSelect
----------------

A ``Select`` widget that uses a list of Argentina's provinces as its
choices.


Australia (``django.contrib.localflavor.au``)
=============================================

AUPostCodeField
---------------

A form field that validates input as an Australian postcode.

AUPhoneNumberField
------------------

A form field that validates input as an Australian phone number.  Valid
numbers have ten digits.

AUStateSelect
-------------

A ``Select`` widget that uses a list of Australian states/territories as its
choices.


Brazil (``django.contrib.localflavor.br``)
==========================================

BRPhoneNumberField
------------------

A form field that validates input as a Brazilian phone number, with the
format XX-XXXX-XXXX.

BRZipCodeField
--------------

A form field that validates input as a Brazilian zip code, with the format
XXXXX-XXX.

BRStateSelect
-------------

A ``Select`` widget that uses a list of Brazilian states/territories as its
choices.


Canada (``django.contrib.localflavor.ca``)
==========================================

CAPhoneNumberField
------------------

A form field that validates input as a Canadian phone number, with the
format XXX-XXX-XXXX.

CAPostalCodeField
-----------------

A form field that validates input as a Canadian postal code, with the
format XXX XXX.

CAProvinceField
---------------

A form field that validates input as a Canadian province name or
abbreviation.

CASocialInsuranceNumberField
----------------------------

A form field that validates input as a Canadian Social Insurance Number
(SIN).  A valid number must have the format XXX-XXX-XXXX and pass a
`Luhn mod-10 checksum`_.

.. _Luhn mod-10 checksum: http://en.wikipedia.org/wiki/Luhn_algorithm

CAProvinceSelect
----------------

A ``Select`` widget that uses a list of Canadian provinces and territories
as its choices.


Chile (``django.contrib.localflavor.cl``)
=========================================

CLRutField
----------

A form field that validates input as a Chilean national identification
number ('Rol Unico Tributario' or RUT).  The valid format is
XX.XXX.XXX-X.

CLRegionSelect
--------------

A ``Select`` widget that uses a list of Chilean regions (Regiones) as its
choices.


Finland (``django.contrib.localflavor.fi``)
===========================================

FISocialSecurityNumber
----------------------

A form field that validates input as a Finnish social security number.

FIZipCodeField
--------------

A form field that validates input as a Finnish zip code.  Valid codes
consist of five digits.

FIMunicipalitySelect
--------------------

A ``Select`` widget that uses a list of Finnish municipalities as its
choices.


France (``django.contrib.localflavor.fr``)
==========================================

FRPhoneNumberField
------------------

A form field that validates input as a French local phone number. The
correct format is 0X XX XX XX XX.  0X.XX.XX.XX.XX and 0XXXXXXXXX validate
but are corrected to 0X XX XX XX XX.

FRZipCodeField
--------------

A form field that validates input as a French zip code.  Valid codes
consist of five digits.

FRDepartmentSelect
------------------

A ``Select`` widget that uses a list of French departments as its choices.


Germany (``django.contrib.localflavor.de``)
===========================================

DEIdentityCardNumberField
-------------------------

A form field that validates input as a German identity card number
(Personalausweis_).  Valid numbers have the format
XXXXXXXXXXX-XXXXXXX-XXXXXXX-X, with no group consisting entirely of zeroes.

.. _Personalausweis: http://de.wikipedia.org/wiki/Personalausweis

DEZipCodeField
--------------

A form field that validates input as a German zip code.  Valid codes
consist of five digits.

DEStateSelect
-------------

A ``Select`` widget that uses a list of German states as its choices.


Holland (``django.contrib.localflavor.nl``)
===========================================

NLPhoneNumberField
------------------

A form field that validates input as a Dutch telephone number.

NLSofiNumberField
-----------------

A form field that validates input as a Dutch social security number
(SoFI/BSN).

NLZipCodeField
--------------

A form field that validates input as a Dutch zip code.

NLProvinceSelect
----------------

A ``Select`` widget that uses a list of Dutch provinces as its list of
choices.


Iceland (``django.contrib.localflavor.is_``)
============================================

ISIdNumberField
---------------

A form field that validates input as an Icelandic identification number
(kennitala).  The format is XXXXXX-XXXX.

ISPhoneNumberField
------------------

A form field that validates input as an Icelandtic phone number (seven
digits with an optional hyphen or space after the first three digits).

ISPostalCodeSelect
------------------

A ``Select`` widget that uses a list of Icelandic postal codes as its
choices.


India (``django.contrib.localflavor.in_``)
==========================================

INStateField
------------

A form field that validates input as an Indian state/territory name or
abbreviation.  Input is normalized to the standard two-letter vehicle
registration abbreviation for the given state or territory.

INZipCodeField
--------------

A form field that validates input as an Indian zip code, with the
format XXXXXXX.

INStateSelect
-------------

A ``Select`` widget that uses a list of Indian states/territories as its
choices.


Italy (``django.contrib.localflavor.it``)
=========================================

ITSocialSecurityNumberField
---------------------------

A form field that validates input as an Italian social security number
(`codice fiscale`_).

.. _codice fiscale: http://www.agenziaentrate.it/ilwwcm/connect/Nsi/Servizi/Codice+fiscale+-+tessera+sanitaria/Codice+fiscale/NSI+Informazioni+sulla+codificazione+delle+persone+fisiche

ITVatNumberField
----------------

A form field that validates Italian VAT numbers (partita IVA).

ITZipCodeField
--------------

A form field that validates input as an Italian zip code.  Valid codes
must have five digits.

ITProvinceSelect
----------------

A ``Select`` widget that uses a list of Italian provinces as its choices.

ITRegionSelect
--------------

A ``Select`` widget that uses a list of Italian regions as its choices.


Japan (``django.contrib.localflavor.jp``)
=========================================

JPPostalCodeField
-----------------

A form field that validates input as a Japanese postcode.
It accepts seven digits, with or without a hyphen.

JPPrefectureSelect
------------------

A ``Select`` widget that uses a list of Japanese prefectures as its choices.


Norway (``django.contrib.localflavor.no``)
==========================================

NOSocialSecurityNumber
----------------------

A form field that validates input as a Norwegian social security number
(personnummer_).

.. _personnummer: http://no.wikipedia.org/wiki/Personnummer

NOZipCodeField
--------------

A form field that validates input as a Norwegian zip code.  Valid codes
have four digits.

NOMunicipalitySelect
--------------------

A ``Select`` widget that uses a list of Norwegian municipalities (fylker) as
its choices.


Peru (``django.contrib.localflavor.pe``)
========================================

PEDNIField
----------

A form field that validates input as a DNI (Peruvian national identity)
number.

PERUCField
----------

A form field that validates input as an RUC (Registro Unico de
Contribuyentes) number.  Valid RUC numbers have eleven digits.

PEDepartmentSelect
------------------

A ``Select`` widget that uses a list of Peruvian Departments as its choices.


Poland (``django.contrib.localflavor.pl``)
==========================================

PLNationalIdentificationNumberField
-----------------------------------

A form field that validates input as a Polish national identification number
(PESEL_).

.. _PESEL: http://en.wikipedia.org/wiki/PESEL

PLNationalBusinessRegisterField
-------------------------------

A form field that validates input as a Polish National Official Business
Register Number (REGON_), having either seven or nine digits.  The checksum
algorithm used for REGONs is documented at
http://wipos.p.lodz.pl/zylla/ut/nip-rego.html.

.. _REGON: http://www.stat.gov.pl/bip/regon_ENG_HTML.htm

PLPostalCodeField
-----------------

A form field that validates input as a Polish postal code.  The valid format
is XX-XXX, where X is a digit.

PLTaxNumberField
----------------

A form field that validates input as a Polish Tax Number (NIP).  Valid
formats are XXX-XXX-XX-XX or XX-XX-XXX-XXX.  The checksum algorithm used
for NIPs is documented at http://wipos.p.lodz.pl/zylla/ut/nip-rego.html.

PLAdministrativeUnitSelect
--------------------------

A ``Select`` widget that uses a list of Polish administrative units as its
choices.

PLVoivodeshipSelect
-------------------

A ``Select`` widget that uses a list of Polish voivodeships (administrative
provinces) as its choices.


Slovakia (``django.contrib.localflavor.sk``)
============================================

SKPostalCodeField
-----------------

A form field that validates input as a Slovak postal code.  Valid formats
are XXXXX or XXX XX, where X is a digit.

SKDistrictSelect
----------------

A ``Select`` widget that uses a list of Slovak districts as its choices.

SKRegionSelect
--------------

A ``Select`` widget that uses a list of Slovak regions as its choices.


Switzerland (``django.contrib.localflavor.ch``)
===============================================

CHIdentityCardNumberField
-------------------------

A form field that validates input as a Swiss identity card number.
A valid number must confirm to the X1234567<0 or 1234567890 format and
have the correct checksums -- see http://adi.kousz.ch/artikel/IDCHE.htm.

CHPhoneNumberField
------------------

A form field that validates input as a Swiss phone number.  The correct
format is 0XX XXX XX XX.  0XX.XXX.XX.XX and 0XXXXXXXXX validate but are
corrected to 0XX XXX XX XX.

CHZipCodeField
--------------

A form field that validates input as a Swiss zip code.  Valid codes
consist of four digits.

CHStateSelect
-------------

A ``Select`` widget that uses a list of Swiss states as its choices.


United Kingdom (``django.contrib.localflavor.uk``)
==================================================

UKPostcodeField
---------------

A form field that validates input as a UK postcode. The regular
expression used is sourced from the schema for British Standard BS7666
address types at http://www.govtalk.gov.uk/gdsc/schemas/bs7666-v2-0.xsd.


United States of America (``django.contrib.localflavor.us``) 
============================================================

USPhoneNumberField
------------------

A form field that validates input as a U.S. phone number.

USSocialSecurityNumberField
---------------------------

A form field that validates input as a U.S. Social Security Number (SSN).
A valid SSN must obey the following rules:

* Format of XXX-XX-XXXX
* No group of digits consisting entirely of zeroes
* Leading group of digits cannot be 666
* Number not in promotional block 987-65-4320 through 987-65-4329
* Number not one known to be invalid due to widespread promotional
  use or distribution (e.g., the Woolworth's number or the 1962
  promotional number)

USStateField
------------

A form field that validates input as a U.S. state name or abbreviation. It 
normalizes the input to the standard two-letter postal service abbreviation
for the given state.

USZipCodeField
--------------

A form field that validates input as a U.S. zip code.  Valid formats are
XXXXX or XXXXX-XXXX.

USStateSelect
-------------

A form Select widget that uses a list of U.S. states/territories as its
choices.