Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

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
Adrian Holovaty authored December 19, 2007

Showing 1 changed file with 95 additions and 109 deletions. Show diff stats Hide diff stats

  1. 204  docs/localflavor.txt
204  docs/localflavor.txt
@@ -2,16 +2,22 @@
2 2
 The "local flavor" add-ons
3 3
 ==========================
4 4
 
5  
-Django comes with assorted pieces of code that are useful only for a particular
6  
-country or culture.  These pieces of code are organized as a set of
7  
-subpackages, named using `ISO 3166 country codes`_.
  5
+Following its "batteries included" philosophy, Django comes with assorted
  6
+pieces of code that are useful for particular countries or cultures. These are
  7
+called the "local flavor" add-ons and live in the ``django.contrib.localflavor``
  8
+package.
8 9
 
9  
-.. _ISO 3166 country codes: http://www.iso.org/iso/country_codes/iso_3166_code_lists/english_country_names_and_code_elements.htm
  10
+Inside that package, country- or culture-specific code is organized into
  11
+subpackages, named using `ISO 3166 country codes`_.
10 12
 
11 13
 Most of the ``localflavor`` add-ons are localized form components deriving from
12  
-the newforms_ framework.  To use one of these localized components, just import
13  
-the relevant subpackage.  For example, a form with a field for French telephone
14  
-numbers is created like so::
  14
+the newforms_ framework -- for example, a ``USStateField`` that knows how to
  15
+validate U.S. state abbreviations, and a ``FISocialSecurityNumber`` that knows
  16
+how to validate Finnish social security numbers.
  17
+
  18
+To use one of these localized components, just import the relevant subpackage.
  19
+For example, here's how you can create a form with a field representing a
  20
+French telephone number::
15 21
 
16 22
     from django import newforms as forms
17 23
     from django.contrib.localflavor import fr
@@ -19,32 +25,48 @@ numbers is created like so::
19 25
     class MyForm(forms.Form):
20 26
         my_french_phone_no = fr.forms.FRPhoneNumberField()
21 27
 
  28
+Supported countries
  29
+===================
  30
+
22 31
 Countries currently supported by ``localflavor`` are:
23 32
 
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`_
  33
+    * Argentina_
  34
+    * Australia_
  35
+    * Brazil_
  36
+    * Canada_
  37
+    * Chile_
  38
+    * Finland_
  39
+    * France_
  40
+    * Germany_
  41
+    * Holland_
  42
+    * Iceland_
  43
+    * India_
  44
+    * Italy_
  45
+    * Japan_
  46
+    * Mexico_
  47
+    * Norway_
  48
+    * Peru_
  49
+    * Poland_
  50
+    * Slovakia_
  51
+    * `South Africa`_
  52
+    * Spain_
  53
+    * Switzerland_
  54
+    * `United Kingdom`_
  55
+    * `United States of America`_
  56
+
  57
+The ``localflavor`` package also includes a ``generic`` subpackage, containing
  58
+useful code that is not specific to one particular country or culture.
  59
+Currently, it defines date and datetime input fields based on those from
  60
+newforms_, but with non-US default formats. Here's an example of how to use
  61
+them::
  62
+
  63
+    from django import newforms as forms
  64
+    from django.contrib.localflavor import generic
  65
+
  66
+    class MyForm(forms.Form):
  67
+        my_date_field = generic.forms.DateField()
47 68
 
  69
+.. _ISO 3166 country codes: http://www.iso.org/iso/country_codes/iso_3166_code_lists/english_country_names_and_code_elements.htm
48 70
 .. _Argentina: `Argentina (django.contrib.localflavor.ar)`_
49 71
 .. _Australia: `Australia (django.contrib.localflavor.au)`_
50 72
 .. _Brazil: `Brazil (django.contrib.localflavor.br)`_
@@ -68,29 +90,15 @@ Countries currently supported by ``localflavor`` are:
68 90
 .. _Switzerland: `Switzerland (django.contrib.localflavor.ch)`_
69 91
 .. _United Kingdom: `United Kingdom (django.contrib.localflavor.uk)`_
70 92
 .. _United States of America: `United States of America (django.contrib.localflavor.us)`_
71  
-
72  
-The ``localflavor`` add-on also includes the ``generic`` subpackage, containing
73  
-useful code that is not specific to one particular country or culture.
74  
-Currently, it defines date and date & time input fields based on those from
75  
-newforms_, but with non-US default formats.  Here's an example of how to use
76  
-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 93
 .. _newforms: ../newforms/
85 94
 
  95
+Adding flavors
  96
+==============
86 97
 
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 file
92  
-   (see any of the existing flavors for examples).
93  
-
  98
+We'd love to add more of these to Django, so please `create a ticket`_ with
  99
+any code you'd like to contribute. One thing we ask is that you please use
  100
+Unicode objects (``u'mystring'``) for strings, rather than setting the encoding
  101
+in the file. See any of the existing flavors for examples.
94 102
 
95 103
 Argentina (``django.contrib.localflavor.ar``)
96 104
 =============================================
@@ -108,7 +116,6 @@ ARProvinceSelect
108 116
 
109 117
 A ``Select`` widget that uses a list of Argentina's provinces as its choices.
110 118
 
111  
-
112 119
 Australia (``django.contrib.localflavor.au``)
113 120
 =============================================
114 121
 
@@ -129,7 +136,6 @@ AUStateSelect
129 136
 A ``Select`` widget that uses a list of Australian states/territories as its
130 137
 choices.
131 138
 
132  
-
133 139
 Brazil (``django.contrib.localflavor.br``)
134 140
 ==========================================
135 141
 
@@ -151,7 +157,6 @@ BRStateSelect
151 157
 A ``Select`` widget that uses a list of Brazilian states/territories as its
152 158
 choices.
153 159
 
154  
-
155 160
 Canada (``django.contrib.localflavor.ca``)
156 161
 ==========================================
157 162
 
@@ -187,7 +192,6 @@ CAProvinceSelect
187 192
 A ``Select`` widget that uses a list of Canadian provinces and territories as
188 193
 its choices.
189 194
 
190  
-
191 195
 Chile (``django.contrib.localflavor.cl``)
192 196
 =========================================
193 197
 
@@ -203,7 +207,6 @@ CLRegionSelect
203 207
 A ``Select`` widget that uses a list of Chilean regions (Regiones) as its
204 208
 choices.
205 209
 
206  
-
207 210
 Finland (``django.contrib.localflavor.fi``)
208 211
 ===========================================
209 212
 
@@ -215,7 +218,7 @@ A form field that validates input as a Finnish social security number.
215 218
 FIZipCodeField
216 219
 --------------
217 220
 
218  
-A form field that validates input as a Finnish zip code.  Valid codes
  221
+A form field that validates input as a Finnish zip code. Valid codes
219 222
 consist of five digits.
220 223
 
221 224
 FIMunicipalitySelect
@@ -224,7 +227,6 @@ FIMunicipalitySelect
224 227
 A ``Select`` widget that uses a list of Finnish municipalities as its
225 228
 choices.
226 229
 
227  
-
228 230
 France (``django.contrib.localflavor.fr``)
229 231
 ==========================================
230 232
 
@@ -232,13 +234,13 @@ FRPhoneNumberField
232 234
 ------------------
233 235
 
234 236
 A form field that validates input as a French local phone number. The
235  
-correct format is 0X XX XX XX XX.  0X.XX.XX.XX.XX and 0XXXXXXXXX validate
  237
+correct format is 0X XX XX XX XX. 0X.XX.XX.XX.XX and 0XXXXXXXXX validate
236 238
 but are corrected to 0X XX XX XX XX.
237 239
 
238 240
 FRZipCodeField
239 241
 --------------
240 242
 
241  
-A form field that validates input as a French zip code.  Valid codes
  243
+A form field that validates input as a French zip code. Valid codes
242 244
 consist of five digits.
243 245
 
244 246
 FRDepartmentSelect
@@ -246,7 +248,6 @@ FRDepartmentSelect
246 248
 
247 249
 A ``Select`` widget that uses a list of French departments as its choices.
248 250
 
249  
-
250 251
 Germany (``django.contrib.localflavor.de``)
251 252
 ===========================================
252 253
 
@@ -254,7 +255,7 @@ DEIdentityCardNumberField
254 255
 -------------------------
255 256
 
256 257
 A form field that validates input as a German identity card number
257  
-(Personalausweis_).  Valid numbers have the format
  258
+(Personalausweis_). Valid numbers have the format
258 259
 XXXXXXXXXXX-XXXXXXX-XXXXXXX-X, with no group consisting entirely of zeroes.
259 260
 
260 261
 .. _Personalausweis: http://de.wikipedia.org/wiki/Personalausweis
@@ -262,7 +263,7 @@ XXXXXXXXXXX-XXXXXXX-XXXXXXX-X, with no group consisting entirely of zeroes.
262 263
 DEZipCodeField
263 264
 --------------
264 265
 
265  
-A form field that validates input as a German zip code.  Valid codes
  266
+A form field that validates input as a German zip code. Valid codes
266 267
 consist of five digits.
267 268
 
268 269
 DEStateSelect
@@ -270,7 +271,6 @@ DEStateSelect
270 271
 
271 272
 A ``Select`` widget that uses a list of German states as its choices.
272 273
 
273  
-
274 274
 Holland (``django.contrib.localflavor.nl``)
275 275
 ===========================================
276 276
 
@@ -296,7 +296,6 @@ NLProvinceSelect
296 296
 A ``Select`` widget that uses a list of Dutch provinces as its list of
297 297
 choices.
298 298
 
299  
-
300 299
 Iceland (``django.contrib.localflavor.is_``)
301 300
 ============================================
302 301
 
@@ -304,7 +303,7 @@ ISIdNumberField
304 303
 ---------------
305 304
 
306 305
 A form field that validates input as an Icelandic identification number
307  
-(kennitala).  The format is XXXXXX-XXXX.
  306
+(kennitala). The format is XXXXXX-XXXX.
308 307
 
309 308
 ISPhoneNumberField
310 309
 ------------------
@@ -318,7 +317,6 @@ ISPostalCodeSelect
318 317
 A ``Select`` widget that uses a list of Icelandic postal codes as its
319 318
 choices.
320 319
 
321  
-
322 320
 India (``django.contrib.localflavor.in_``)
323 321
 ==========================================
324 322
 
@@ -326,7 +324,7 @@ INStateField
326 324
 ------------
327 325
 
328 326
 A form field that validates input as an Indian state/territory name or
329  
-abbreviation.  Input is normalized to the standard two-letter vehicle
  327
+abbreviation. Input is normalized to the standard two-letter vehicle
330 328
 registration abbreviation for the given state or territory.
331 329
 
332 330
 INZipCodeField
@@ -341,7 +339,6 @@ INStateSelect
341 339
 A ``Select`` widget that uses a list of Indian states/territories as its
342 340
 choices.
343 341
 
344  
-
345 342
 Italy (``django.contrib.localflavor.it``)
346 343
 =========================================
347 344
 
@@ -361,7 +358,7 @@ A form field that validates Italian VAT numbers (partita IVA).
361 358
 ITZipCodeField
362 359
 --------------
363 360
 
364  
-A form field that validates input as an Italian zip code.  Valid codes
  361
+A form field that validates input as an Italian zip code. Valid codes
365 362
 must have five digits.
366 363
 
367 364
 ITProvinceSelect
@@ -374,22 +371,20 @@ ITRegionSelect
374 371
 
375 372
 A ``Select`` widget that uses a list of Italian regions as its choices.
376 373
 
377  
-
378 374
 Japan (``django.contrib.localflavor.jp``)
379 375
 =========================================
380 376
 
381 377
 JPPostalCodeField
382 378
 -----------------
383 379
 
384  
-A form field that validates input as a Japanese postcode.
385  
-It accepts seven digits, with or without a hyphen.
  380
+A form field that validates input as a Japanese postcode. It accepts seven
  381
+digits, with or without a hyphen.
386 382
 
387 383
 JPPrefectureSelect
388 384
 ------------------
389 385
 
390 386
 A ``Select`` widget that uses a list of Japanese prefectures as its choices.
391 387
 
392  
-
393 388
 Mexico (``django.contrib.localflavor.mx``)
394 389
 ==========================================
395 390
 
@@ -398,7 +393,6 @@ MXStateSelect
398 393
 
399 394
 A ``Select`` widget that uses a list of Mexican states as its choices.
400 395
 
401  
-
402 396
 Norway (``django.contrib.localflavor.no``)
403 397
 ==========================================
404 398
 
@@ -413,7 +407,7 @@ A form field that validates input as a Norwegian social security number
413 407
 NOZipCodeField
414 408
 --------------
415 409
 
416  
-A form field that validates input as a Norwegian zip code.  Valid codes
  410
+A form field that validates input as a Norwegian zip code. Valid codes
417 411
 have four digits.
418 412
 
419 413
 NOMunicipalitySelect
@@ -422,7 +416,6 @@ NOMunicipalitySelect
422 416
 A ``Select`` widget that uses a list of Norwegian municipalities (fylker) as
423 417
 its choices.
424 418
 
425  
-
426 419
 Peru (``django.contrib.localflavor.pe``)
427 420
 ========================================
428 421
 
@@ -436,14 +429,13 @@ PERUCField
436 429
 ----------
437 430
 
438 431
 A form field that validates input as an RUC (Registro Unico de
439  
-Contribuyentes) number.  Valid RUC numbers have eleven digits.
  432
+Contribuyentes) number. Valid RUC numbers have 11 digits.
440 433
 
441 434
 PEDepartmentSelect
442 435
 ------------------
443 436
 
444 437
 A ``Select`` widget that uses a list of Peruvian Departments as its choices.
445 438
 
446  
-
447 439
 Poland (``django.contrib.localflavor.pl``)
448 440
 ==========================================
449 441
 
@@ -459,7 +451,7 @@ PLNationalBusinessRegisterField
459 451
 -------------------------------
460 452
 
461 453
 A form field that validates input as a Polish National Official Business
462  
-Register Number (REGON_), having either seven or nine digits.  The checksum
  454
+Register Number (REGON_), having either seven or nine digits. The checksum
463 455
 algorithm used for REGONs is documented at
464 456
 http://wipos.p.lodz.pl/zylla/ut/nip-rego.html.
465 457
 
@@ -468,14 +460,14 @@ http://wipos.p.lodz.pl/zylla/ut/nip-rego.html.
468 460
 PLPostalCodeField
469 461
 -----------------
470 462
 
471  
-A form field that validates input as a Polish postal code.  The valid format
  463
+A form field that validates input as a Polish postal code. The valid format
472 464
 is XX-XXX, where X is a digit.
473 465
 
474 466
 PLTaxNumberField
475 467
 ----------------
476 468
 
477  
-A form field that validates input as a Polish Tax Number (NIP).  Valid
478  
-formats are XXX-XXX-XX-XX or XX-XX-XXX-XXX.  The checksum algorithm used
  469
+A form field that validates input as a Polish Tax Number (NIP). Valid
  470
+formats are XXX-XXX-XX-XX or XX-XX-XXX-XXX. The checksum algorithm used
479 471
 for NIPs is documented at http://wipos.p.lodz.pl/zylla/ut/nip-rego.html.
480 472
 
481 473
 PLAdministrativeUnitSelect
@@ -490,14 +482,13 @@ PLVoivodeshipSelect
490 482
 A ``Select`` widget that uses a list of Polish voivodeships (administrative
491 483
 provinces) as its choices.
492 484
 
493  
-
494 485
 Slovakia (``django.contrib.localflavor.sk``)
495 486
 ============================================
496 487
 
497 488
 SKPostalCodeField
498 489
 -----------------
499 490
 
500  
-A form field that validates input as a Slovak postal code.  Valid formats
  491
+A form field that validates input as a Slovak postal code. Valid formats
501 492
 are XXXXX or XXX XX, where X is a digit.
502 493
 
503 494
 SKDistrictSelect
@@ -510,24 +501,22 @@ SKRegionSelect
510 501
 
511 502
 A ``Select`` widget that uses a list of Slovak regions as its choices.
512 503
 
513  
-
514 504
 South Africa (``django.contrib.localflavor.za``)
515 505
 ================================================
516 506
 
517 507
 ZAIDField
518 508
 ---------
519 509
 
520  
-A form field that validates input as a South African ID number.  Validation
  510
+A form field that validates input as a South African ID number. Validation
521 511
 uses the Luhn checksum and a simplistic (i.e., not entirely accurate) check
522 512
 for birth date.
523 513
 
524 514
 ZAPostCodeField
525 515
 ---------------
526 516
 
527  
-A form field that validates input as a South African postcode.  Valid
  517
+A form field that validates input as a South African postcode. Valid
528 518
 postcodes must have four digits.
529 519
 
530  
-
531 520
 Spain (``django.contrib.localflavor.es``)
532 521
 =========================================
533 522
 
@@ -541,23 +530,23 @@ ESCCCField
541 530
 ----------
542 531
 
543 532
 A form field that validates input as a Spanish bank account number (Codigo
544  
-Cuenta Cliente or CCC).  A valid CCC number has the format
  533
+Cuenta Cliente or CCC). A valid CCC number has the format
545 534
 EEEE-OOOO-CC-AAAAAAAAAA, where the E, O, C and A digits denote the entity,
546  
-office, checksum and account, respectively.  The first checksum digit
547  
-validates the entity and office.  The second checksum digit validates the
548  
-account.  It is also valid to use a space as a delimiter, or to use no
  535
+office, checksum and account, respectively. The first checksum digit
  536
+validates the entity and office. The second checksum digit validates the
  537
+account. It is also valid to use a space as a delimiter, or to use no
549 538
 delimiter.
550 539
 
551 540
 ESPhoneNumberField
552 541
 ------------------
553 542
 
554  
-A form field that validates input as a Spanish phone number.  Valid numbers
  543
+A form field that validates input as a Spanish phone number. Valid numbers
555 544
 have nine digits, the first of which is 6, 8 or 9.
556 545
 
557 546
 ESPostalCodeField
558 547
 -----------------
559 548
 
560  
-A form field that validates input as a Spanish postal code.  Valid codes
  549
+A form field that validates input as a Spanish postal code. Valid codes
561 550
 have five digits, the first two being in the range 01 to 52, representing
562 551
 the province.
563 552
 
@@ -571,7 +560,6 @@ ESRegionSelect
571 560
 
572 561
 A ``Select`` widget that uses a list of Spanish regions as its choices.
573 562
 
574  
-
575 563
 Switzerland (``django.contrib.localflavor.ch``)
576 564
 ===============================================
577 565
 
@@ -585,14 +573,14 @@ have the correct checksums -- see http://adi.kousz.ch/artikel/IDCHE.htm.
585 573
 CHPhoneNumberField
586 574
 ------------------
587 575
 
588  
-A form field that validates input as a Swiss phone number.  The correct
589  
-format is 0XX XXX XX XX.  0XX.XXX.XX.XX and 0XXXXXXXXX validate but are
  576
+A form field that validates input as a Swiss phone number. The correct
  577
+format is 0XX XXX XX XX. 0XX.XXX.XX.XX and 0XXXXXXXXX validate but are
590 578
 corrected to 0XX XXX XX XX.
591 579
 
592 580
 CHZipCodeField
593 581
 --------------
594 582
 
595  
-A form field that validates input as a Swiss zip code.  Valid codes
  583
+A form field that validates input as a Swiss zip code. Valid codes
596 584
 consist of four digits.
597 585
 
598 586
 CHStateSelect
@@ -600,7 +588,6 @@ CHStateSelect
600 588
 
601 589
 A ``Select`` widget that uses a list of Swiss states as its choices.
602 590
 
603  
-
604 591
 United Kingdom (``django.contrib.localflavor.uk``)
605 592
 ==================================================
606 593
 
@@ -621,7 +608,6 @@ UKNationSelect
621 608
 
622 609
 A ``Select`` widget that uses a list of UK nations as its choices.
623 610
 
624  
-
625 611
 United States of America (``django.contrib.localflavor.us``) 
626 612
 ============================================================
627 613
 
@@ -636,13 +622,13 @@ USSocialSecurityNumberField
636 622
 A form field that validates input as a U.S. Social Security Number (SSN).
637 623
 A valid SSN must obey the following rules:
638 624
 
639  
-* Format of XXX-XX-XXXX
640  
-* No group of digits consisting entirely of zeroes
641  
-* Leading group of digits cannot be 666
642  
-* Number not in promotional block 987-65-4320 through 987-65-4329
643  
-* Number not one known to be invalid due to widespread promotional
644  
-  use or distribution (e.g., the Woolworth's number or the 1962
645  
-  promotional number)
  625
+    * Format of XXX-XX-XXXX
  626
+    * No group of digits consisting entirely of zeroes
  627
+    * Leading group of digits cannot be 666
  628
+    * Number not in promotional block 987-65-4320 through 987-65-4329
  629
+    * Number not one known to be invalid due to widespread promotional
  630
+      use or distribution (e.g., the Woolworth's number or the 1962
  631
+      promotional number)
646 632
 
647 633
 USStateField
648 634
 ------------
@@ -654,11 +640,11 @@ for the given state.
654 640
 USZipCodeField
655 641
 --------------
656 642
 
657  
-A form field that validates input as a U.S. zip code.  Valid formats are
  643
+A form field that validates input as a U.S. ZIP code. Valid formats are
658 644
 XXXXX or XXXXX-XXXX.
659 645
 
660 646
 USStateSelect
661 647
 -------------
662 648
 
663  
-A form Select widget that uses a list of U.S. states/territories as its
  649
+A form ``Select`` widget that uses a list of U.S. states/territories as its
664 650
 choices.

0 notes on commit 48a5898

Please sign in to comment.
Something went wrong with that request. Please try again.