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