Ticket #3883: localflavor.5.txt

File localflavor.5.txt, 16.9 KB (added by nickefford, 8 years ago)

Final final version, incorporating za localflavor (rev 6843) and mx localflavor (#5676)

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