==========================

The "local flavor" add-ons

==========================

.. module:: django.contrib.localflavor

    :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.

Inside that package, country- or culture-specific code is organized into

subpackages, named using `ISO 3166 country codes`_.

Most of the ``localflavor`` add-ons are localized form components deriving

from the :doc:`forms </topics/forms/index>` 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.

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

    class MyForm(forms.Form):

        my_french_phone_no = FRPhoneNumberField()

Supported countries

===================

Countries currently supported by :mod:`~django.contrib.localflavor` are:

    * Argentina_

    * Australia_

    * Austria_

    * Brazil_

    * Canada_

    * Chile_

    * Czech_

    * Finland_

    * France_

    * Germany_

    * Iceland_

    * India_

    * Indonesia_

    * Ireland_

    * Italy_

    * Japan_

    * Kuwait_

    * Mexico_

    * `The Netherlands`_

    * Norway_

    * Peru_

    * Poland_

    * Portugal_

    * Romania_

    * Slovakia_

    * `South Africa`_

    * Spain_

    * Sweden_

    * Switzerland_

    * `United Kingdom`_

    * `United States of America`_

    * Uruguay_

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 </topics/forms/index>`, 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

    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 (ar)`_

.. _Australia: `Australia (au)`_

.. _Austria: `Austria (at)`_

.. _Brazil: `Brazil (br)`_

.. _Canada: `Canada (ca)`_

.. _Chile: `Chile (cl)`_

.. _Czech: `Czech (cz)`_

.. _Finland: `Finland (fi)`_

.. _France: `France (fr)`_

.. _Germany: `Germany (de)`_

.. _The Netherlands: `The Netherlands (nl)`_

.. _Iceland: `Iceland (is\_)`_

.. _India: `India (in\_)`_

.. _Indonesia: `Indonesia (id)`_

.. _Ireland: `Ireland (ie)`_

.. _Italy: `Italy (it)`_

.. _Japan: `Japan (jp)`_

.. _Kuwait: `Kuwait (kw)`_

.. _Mexico: `Mexico (mx)`_

.. _Norway: `Norway (no)`_

.. _Peru: `Peru (pe)`_

.. _Poland: `Poland (pl)`_

.. _Portugal: `Portugal (pt)`_

.. _Romania: `Romania (ro)`_

.. _Slovakia: `Slovakia (sk)`_

.. _South Africa: `South Africa (za)`_

.. _Spain: `Spain (es)`_

.. _Sweden: `Sweden (se)`_

.. _Switzerland: `Switzerland (ch)`_

.. _United Kingdom: `United Kingdom (uk)`_

.. _United States of America: `United States of America (us)`_

.. _Uruguay: `Uruguay (uy)`_

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: http://code.djangoproject.com/simpleticket

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``)

=============================================

.. 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.

Austria (``at``)

================

.. class:: at.forms.ATZipCodeField

    A form field that validates its input as an Austrian zip code.

.. 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.

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.

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.

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.

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.

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.