Ticket #3883: localflavor.4.txt

File localflavor.4.txt, 16.2 KB (added by nickefford, 8 years ago)

Final version, rectifying accidental omission of Spain :)

Line 
1==========================
2The "local flavor" add-ons
3==========================
4
5Django comes with assorted pieces of code that are useful only for a
6particular country or culture.  These pieces of code are organized as a
7set of subpackages, named using `ISO 3166 country codes`_.
8
9.. _ISO 3166 country codes: http://www.iso.org/iso/country_codes/iso_3166_code_lists/english_country_names_and_code_elements.htm
10
11Most of the ``localflavor`` add-ons are localized form components deriving
12from the newforms_ framework.  To use one of these localized components,
13just import the relevant subpackage.  For example, a form with a field for
14French telephone numbers is created like so::
15
16    from django import newforms as forms
17    from django.contrib.localflavor import fr
18
19    class MyForm(forms.Form):
20        my_french_phone_no = fr.forms.FRPhoneNumberField()
21
22Countries currently supported by ``localflavor`` are:
23
24* Argentina_
25* Australia_
26* Brazil_
27* Canada_
28* Chile_
29* Finland_
30* France_
31* Germany_
32* Holland_
33* Iceland_
34* India_
35* Italy_
36* Japan_
37* Norway_
38* Peru_
39* Poland_
40* Slovakia_
41* Spain_
42* Switzerland_
43* `United Kingdom`_
44* `United States of America`_
45
46.. _Argentina: `Argentina (django.contrib.localflavor.ar)`_
47.. _Australia: `Australia (django.contrib.localflavor.au)`_
48.. _Brazil: `Brazil (django.contrib.localflavor.br)`_
49.. _Canada: `Canada (django.contrib.localflavor.ca)`_
50.. _Chile: `Chile (django.contrib.localflavor.cl)`_
51.. _Finland: `Finland (django.contrib.localflavor.fi)`_
52.. _France: `France (django.contrib.localflavor.fr)`_
53.. _Germany: `Germany (django.contrib.localflavor.de)`_
54.. _Holland: `Holland (django.contrib.localflavor.nl)`_
55.. _Iceland: `Iceland (django.contrib.localflavor.is\_)`_
56.. _India: `India (django.contrib.localflavor.in\_)`_
57.. _Italy: `Italy (django.contrib.localflavor.it)`_
58.. _Japan: `Japan (django.contrib.localflavor.jp)`_
59.. _Norway: `Norway (django.contrib.localflavor.no)`_
60.. _Peru: `Peru (django.contrib.localflavor.pe)`_
61.. _Poland: `Poland (django.contrib.localflavor.pl)`_
62.. _Slovakia: `Slovakia (django.contrib.localflavor.sk)`_
63.. _Spain: `Spain (django.contrib.localflavor.es)`_
64.. _Switzerland: `Switzerland (django.contrib.localflavor.ch)`_
65.. _United Kingdom: `United Kingdom (django.contrib.localflavor.uk)`_
66.. _United States of America: `United States of America (django.contrib.localflavor.us)`_
67
68The ``localflavor`` add-on also includes the ``generic`` subpackage,
69containing useful code that is not specific to one particular country or
70culture.  Currently, it defines date and date & time input fields based on
71those from newforms_, but with non-US default formats.  Here's an example of
72how to use them::
73
74    from django import newforms as forms
75    from django.contrib.localflavor import generic
76
77    class MyForm(forms.Form):
78        my_date_field = generic.forms.DateField()
79
80.. _newforms: ../newforms/
81
82
83.. admonition:: Adding a Flavor
84
85   We'd love to add more of these to Django, so please create a ticket for
86   anything that you've found useful. Please use unicode objects
87   (``u'mystring'``) for strings, rather than setting the encoding in the
88   file (see any of the existing flavors for examples).
89
90
91Argentina (``django.contrib.localflavor.ar``)
92=============================================
93
94ARPostalCodeField
95-----------------
96
97A form field that validates input as either a classic four-digit
98Argentinian postal code or a CPA_.
99
100.. _CPA: http://www.correoargentino.com.ar/consulta_cpa/home.php
101
102ARProvinceSelect
103----------------
104
105A ``Select`` widget that uses a list of Argentina's provinces as its
106choices.
107
108
109Australia (``django.contrib.localflavor.au``)
110=============================================
111
112AUPostCodeField
113---------------
114
115A form field that validates input as an Australian postcode.
116
117AUPhoneNumberField
118------------------
119
120A form field that validates input as an Australian phone number.  Valid
121numbers have ten digits.
122
123AUStateSelect
124-------------
125
126A ``Select`` widget that uses a list of Australian states/territories as its
127choices.
128
129
130Brazil (``django.contrib.localflavor.br``)
131==========================================
132
133BRPhoneNumberField
134------------------
135
136A form field that validates input as a Brazilian phone number, with the
137format XX-XXXX-XXXX.
138
139BRZipCodeField
140--------------
141
142A form field that validates input as a Brazilian zip code, with the format
143XXXXX-XXX.
144
145BRStateSelect
146-------------
147
148A ``Select`` widget that uses a list of Brazilian states/territories as its
149choices.
150
151
152Canada (``django.contrib.localflavor.ca``)
153==========================================
154
155CAPhoneNumberField
156------------------
157
158A form field that validates input as a Canadian phone number, with the
159format XXX-XXX-XXXX.
160
161CAPostalCodeField
162-----------------
163
164A form field that validates input as a Canadian postal code, with the
165format XXX XXX.
166
167CAProvinceField
168---------------
169
170A form field that validates input as a Canadian province name or
171abbreviation.
172
173CASocialInsuranceNumberField
174----------------------------
175
176A form field that validates input as a Canadian Social Insurance Number
177(SIN).  A valid number must have the format XXX-XXX-XXXX and pass a
178`Luhn mod-10 checksum`_.
179
180.. _Luhn mod-10 checksum: http://en.wikipedia.org/wiki/Luhn_algorithm
181
182CAProvinceSelect
183----------------
184
185A ``Select`` widget that uses a list of Canadian provinces and territories
186as its choices.
187
188
189Chile (``django.contrib.localflavor.cl``)
190=========================================
191
192CLRutField
193----------
194
195A form field that validates input as a Chilean national identification
196number ('Rol Unico Tributario' or RUT).  The valid format is
197XX.XXX.XXX-X.
198
199CLRegionSelect
200--------------
201
202A ``Select`` widget that uses a list of Chilean regions (Regiones) as its
203choices.
204
205
206Finland (``django.contrib.localflavor.fi``)
207===========================================
208
209FISocialSecurityNumber
210----------------------
211
212A form field that validates input as a Finnish social security number.
213
214FIZipCodeField
215--------------
216
217A form field that validates input as a Finnish zip code.  Valid codes
218consist of five digits.
219
220FIMunicipalitySelect
221--------------------
222
223A ``Select`` widget that uses a list of Finnish municipalities as its
224choices.
225
226
227France (``django.contrib.localflavor.fr``)
228==========================================
229
230FRPhoneNumberField
231------------------
232
233A form field that validates input as a French local phone number. The
234correct format is 0X XX XX XX XX.  0X.XX.XX.XX.XX and 0XXXXXXXXX validate
235but are corrected to 0X XX XX XX XX.
236
237FRZipCodeField
238--------------
239
240A form field that validates input as a French zip code.  Valid codes
241consist of five digits.
242
243FRDepartmentSelect
244------------------
245
246A ``Select`` widget that uses a list of French departments as its choices.
247
248
249Germany (``django.contrib.localflavor.de``)
250===========================================
251
252DEIdentityCardNumberField
253-------------------------
254
255A form field that validates input as a German identity card number
256(Personalausweis_).  Valid numbers have the format
257XXXXXXXXXXX-XXXXXXX-XXXXXXX-X, with no group consisting entirely of zeroes.
258
259.. _Personalausweis: http://de.wikipedia.org/wiki/Personalausweis
260
261DEZipCodeField
262--------------
263
264A form field that validates input as a German zip code.  Valid codes
265consist of five digits.
266
267DEStateSelect
268-------------
269
270A ``Select`` widget that uses a list of German states as its choices.
271
272
273Holland (``django.contrib.localflavor.nl``)
274===========================================
275
276NLPhoneNumberField
277------------------
278
279A form field that validates input as a Dutch telephone number.
280
281NLSofiNumberField
282-----------------
283
284A form field that validates input as a Dutch social security number
285(SoFI/BSN).
286
287NLZipCodeField
288--------------
289
290A form field that validates input as a Dutch zip code.
291
292NLProvinceSelect
293----------------
294
295A ``Select`` widget that uses a list of Dutch provinces as its list of
296choices.
297
298
299Iceland (``django.contrib.localflavor.is_``)
300============================================
301
302ISIdNumberField
303---------------
304
305A form field that validates input as an Icelandic identification number
306(kennitala).  The format is XXXXXX-XXXX.
307
308ISPhoneNumberField
309------------------
310
311A form field that validates input as an Icelandtic phone number (seven
312digits with an optional hyphen or space after the first three digits).
313
314ISPostalCodeSelect
315------------------
316
317A ``Select`` widget that uses a list of Icelandic postal codes as its
318choices.
319
320
321India (``django.contrib.localflavor.in_``)
322==========================================
323
324INStateField
325------------
326
327A form field that validates input as an Indian state/territory name or
328abbreviation.  Input is normalized to the standard two-letter vehicle
329registration abbreviation for the given state or territory.
330
331INZipCodeField
332--------------
333
334A form field that validates input as an Indian zip code, with the
335format XXXXXXX.
336
337INStateSelect
338-------------
339
340A ``Select`` widget that uses a list of Indian states/territories as its
341choices.
342
343
344Italy (``django.contrib.localflavor.it``)
345=========================================
346
347ITSocialSecurityNumberField
348---------------------------
349
350A form field that validates input as an Italian social security number
351(`codice fiscale`_).
352
353.. _codice fiscale: http://www.agenziaentrate.it/ilwwcm/connect/Nsi/Servizi/Codice+fiscale+-+tessera+sanitaria/Codice+fiscale/NSI+Informazioni+sulla+codificazione+delle+persone+fisiche
354
355ITVatNumberField
356----------------
357
358A form field that validates Italian VAT numbers (partita IVA).
359
360ITZipCodeField
361--------------
362
363A form field that validates input as an Italian zip code.  Valid codes
364must have five digits.
365
366ITProvinceSelect
367----------------
368
369A ``Select`` widget that uses a list of Italian provinces as its choices.
370
371ITRegionSelect
372--------------
373
374A ``Select`` widget that uses a list of Italian regions as its choices.
375
376
377Japan (``django.contrib.localflavor.jp``)
378=========================================
379
380JPPostalCodeField
381-----------------
382
383A form field that validates input as a Japanese postcode.
384It accepts seven digits, with or without a hyphen.
385
386JPPrefectureSelect
387------------------
388
389A ``Select`` widget that uses a list of Japanese prefectures as its choices.
390
391
392Norway (``django.contrib.localflavor.no``)
393==========================================
394
395NOSocialSecurityNumber
396----------------------
397
398A form field that validates input as a Norwegian social security number
399(personnummer_).
400
401.. _personnummer: http://no.wikipedia.org/wiki/Personnummer
402
403NOZipCodeField
404--------------
405
406A form field that validates input as a Norwegian zip code.  Valid codes
407have four digits.
408
409NOMunicipalitySelect
410--------------------
411
412A ``Select`` widget that uses a list of Norwegian municipalities (fylker) as
413its choices.
414
415
416Peru (``django.contrib.localflavor.pe``)
417========================================
418
419PEDNIField
420----------
421
422A form field that validates input as a DNI (Peruvian national identity)
423number.
424
425PERUCField
426----------
427
428A form field that validates input as an RUC (Registro Unico de
429Contribuyentes) number.  Valid RUC numbers have eleven digits.
430
431PEDepartmentSelect
432------------------
433
434A ``Select`` widget that uses a list of Peruvian Departments as its choices.
435
436
437Poland (``django.contrib.localflavor.pl``)
438==========================================
439
440PLNationalIdentificationNumberField
441-----------------------------------
442
443A form field that validates input as a Polish national identification number
444(PESEL_).
445
446.. _PESEL: http://en.wikipedia.org/wiki/PESEL
447
448PLNationalBusinessRegisterField
449-------------------------------
450
451A form field that validates input as a Polish National Official Business
452Register Number (REGON_), having either seven or nine digits.  The checksum
453algorithm used for REGONs is documented at
454http://wipos.p.lodz.pl/zylla/ut/nip-rego.html.
455
456.. _REGON: http://www.stat.gov.pl/bip/regon_ENG_HTML.htm
457
458PLPostalCodeField
459-----------------
460
461A form field that validates input as a Polish postal code.  The valid format
462is XX-XXX, where X is a digit.
463
464PLTaxNumberField
465----------------
466
467A form field that validates input as a Polish Tax Number (NIP).  Valid
468formats are XXX-XXX-XX-XX or XX-XX-XXX-XXX.  The checksum algorithm used
469for NIPs is documented at http://wipos.p.lodz.pl/zylla/ut/nip-rego.html.
470
471PLAdministrativeUnitSelect
472--------------------------
473
474A ``Select`` widget that uses a list of Polish administrative units as its
475choices.
476
477PLVoivodeshipSelect
478-------------------
479
480A ``Select`` widget that uses a list of Polish voivodeships (administrative
481provinces) as its choices.
482
483
484Slovakia (``django.contrib.localflavor.sk``)
485============================================
486
487SKPostalCodeField
488-----------------
489
490A form field that validates input as a Slovak postal code.  Valid formats
491are XXXXX or XXX XX, where X is a digit.
492
493SKDistrictSelect
494----------------
495
496A ``Select`` widget that uses a list of Slovak districts as its choices.
497
498SKRegionSelect
499--------------
500
501A ``Select`` widget that uses a list of Slovak regions as its choices.
502
503
504Spain (``django.contrib.localflavor.es``)
505=========================================
506
507ESIdentityCardNumberField
508-------------------------
509
510A form field that validates input as a Spanish NIF/NIE/CIF (Fiscal
511Identification Number) code.
512
513ESCCCField
514----------
515
516A form field that validates input as a Spanish bank account number (Codigo
517Cuenta Cliente or CCC).  A valid CCC number has the format
518EEEE-OOOO-CC-AAAAAAAAAA, where the E, O, C and A digits denote the entity,
519office, checksum and account, respectively.  The first checksum digit
520validates the entity and office.  The second checksum digit validates the
521account.  It is also valid to use a space as a delimiter, or to use no
522delimiter.
523
524ESPhoneNumberField
525------------------
526
527A form field that validates input as a Spanish phone number.  Valid numbers
528have nine digits, the first of which is 6, 8 or 9.
529
530ESPostalCodeField
531-----------------
532
533A form field that validates input as a Spanish postal code.  Valid codes
534have five digits, the first two being in the range 01 to 52, representing
535the province.
536
537ESProvinceSelect
538----------------
539
540A ``Select`` widget that uses a list of Spanish provinces as its choices.
541
542ESRegionSelect
543--------------
544
545A ``Select`` widget that uses a list of Spanish regions as its choices.
546
547
548Switzerland (``django.contrib.localflavor.ch``)
549===============================================
550
551CHIdentityCardNumberField
552-------------------------
553
554A form field that validates input as a Swiss identity card number.
555A valid number must confirm to the X1234567<0 or 1234567890 format and
556have the correct checksums -- see http://adi.kousz.ch/artikel/IDCHE.htm.
557
558CHPhoneNumberField
559------------------
560
561A form field that validates input as a Swiss phone number.  The correct
562format is 0XX XXX XX XX.  0XX.XXX.XX.XX and 0XXXXXXXXX validate but are
563corrected to 0XX XXX XX XX.
564
565CHZipCodeField
566--------------
567
568A form field that validates input as a Swiss zip code.  Valid codes
569consist of four digits.
570
571CHStateSelect
572-------------
573
574A ``Select`` widget that uses a list of Swiss states as its choices.
575
576
577United Kingdom (``django.contrib.localflavor.uk``)
578==================================================
579
580UKPostcodeField
581---------------
582
583A form field that validates input as a UK postcode. The regular
584expression used is sourced from the schema for British Standard BS7666
585address types at http://www.govtalk.gov.uk/gdsc/schemas/bs7666-v2-0.xsd.
586
587
588United States of America (``django.contrib.localflavor.us``)
589============================================================
590
591USPhoneNumberField
592------------------
593
594A form field that validates input as a U.S. phone number.
595
596USSocialSecurityNumberField
597---------------------------
598
599A form field that validates input as a U.S. Social Security Number (SSN).
600A valid SSN must obey the following rules:
601
602* Format of XXX-XX-XXXX
603* No group of digits consisting entirely of zeroes
604* Leading group of digits cannot be 666
605* Number not in promotional block 987-65-4320 through 987-65-4329
606* Number not one known to be invalid due to widespread promotional
607  use or distribution (e.g., the Woolworth's number or the 1962
608  promotional number)
609
610USStateField
611------------
612
613A form field that validates input as a U.S. state name or abbreviation. It
614normalizes the input to the standard two-letter postal service abbreviation
615for the given state.
616
617USZipCodeField
618--------------
619
620A form field that validates input as a U.S. zip code.  Valid formats are
621XXXXX or XXXXX-XXXX.
622
623USStateSelect
624-------------
625
626A form Select widget that uses a list of U.S. states/territories as its
627choices.
Back to Top