docs/localflavor.txt

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