Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Edited docs/localflavor.txt changes from [6849]

git-svn-id: http://code.djangoproject.com/svn/django/trunk@6946 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 48a5898f2462f0d8cd76326b86836f258eb3d0b2 1 parent 0b78944
@adrianholovaty adrianholovaty authored
Showing with 95 additions and 109 deletions.
  1. +95 −109 docs/localflavor.txt
View
204 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
-subpackages, named using `ISO 3166 country codes`_.
+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.
-.. _ISO 3166 country codes: http://www.iso.org/iso/country_codes/iso_3166_code_lists/english_country_names_and_code_elements.htm
+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 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.
Please sign in to comment.
Something went wrong with that request. Please try again.