Code

Ticket #3883: localflavor.2.txt

File localflavor.2.txt, 14.9 KB (added by nickefford, 6 years ago)

Updated version of localflavor.txt

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