/docs/ref/contrib/localflavor.txt

   1==========================
   2The "local flavor" add-ons
   3==========================
   4
   5.. module:: django.contrib.localflavor
   6    :synopsis: A collection of various Django snippets that are useful only for
   7               a particular country or culture.
   8
   9Following its "batteries included" philosophy, Django comes with assorted
  10pieces of code that are useful for particular countries or cultures. These are
  11called the "local flavor" add-ons and live in the
  12:mod:`django.contrib.localflavor` package.
  13
  14Inside that package, country- or culture-specific code is organized into
  15subpackages, named using `ISO 3166 country codes`_.
  16
  17Most of the ``localflavor`` add-ons are localized form components deriving
  18from the :doc:`forms </topics/forms/index>` framework -- for example, a
  19:class:`~django.contrib.localflavor.us.forms.USStateField` that knows how to
  20validate U.S. state abbreviations, and a
  21:class:`~django.contrib.localflavor.fi.forms.FISocialSecurityNumber` that
  22knows how to validate Finnish social security numbers.
  23
  24To use one of these localized components, just import the relevant subpackage.
  25For example, here's how you can create a form with a field representing a
  26French telephone number::
  27
  28    from django import forms
  29    from django.contrib.localflavor.fr.forms import FRPhoneNumberField
  30
  31    class MyForm(forms.Form):
  32        my_french_phone_no = FRPhoneNumberField()
  33
  34Supported countries
  35===================
  36
  37Countries currently supported by :mod:`~django.contrib.localflavor` are:
  38
  39    * Argentina_
  40    * Australia_
  41    * Austria_
  42    * Belgium_
  43    * Brazil_
  44    * Canada_
  45    * Chile_
  46    * Czech_
  47    * Finland_
  48    * France_
  49    * Germany_
  50    * Iceland_
  51    * India_
  52    * Indonesia_
  53    * Ireland_
  54    * Israel_
  55    * Italy_
  56    * Japan_
  57    * Kuwait_
  58    * Mexico_
  59    * `The Netherlands`_
  60    * Norway_
  61    * Peru_
  62    * Poland_
  63    * Portugal_
  64    * Romania_
  65    * Slovakia_
  66    * `South Africa`_
  67    * Spain_
  68    * Sweden_
  69    * Switzerland_
  70    * Turkey_
  71    * `United Kingdom`_
  72    * `United States of America`_
  73    * Uruguay_
  74
  75The ``django.contrib.localflavor`` package also includes a ``generic`` subpackage,
  76containing useful code that is not specific to one particular country or culture.
  77Currently, it defines date, datetime and split datetime input fields based on
  78those from :doc:`forms </topics/forms/index>`, but with non-US default formats.
  79Here's an example of how to use them::
  80
  81    from django import forms
  82    from django.contrib.localflavor import generic
  83
  84    class MyForm(forms.Form):
  85        my_date_field = generic.forms.DateField()
  86
  87.. _ISO 3166 country codes: http://www.iso.org/iso/country_codes/iso_3166_code_lists/english_country_names_and_code_elements.htm
  88.. _Argentina: `Argentina (ar)`_
  89.. _Australia: `Australia (au)`_
  90.. _Austria: `Austria (at)`_
  91.. _Belgium: `Belgium (be)`_
  92.. _Brazil: `Brazil (br)`_
  93.. _Canada: `Canada (ca)`_
  94.. _Chile: `Chile (cl)`_
  95.. _Czech: `Czech (cz)`_
  96.. _Finland: `Finland (fi)`_
  97.. _France: `France (fr)`_
  98.. _Germany: `Germany (de)`_
  99.. _The Netherlands: `The Netherlands (nl)`_
 100.. _Iceland: `Iceland (is\_)`_
 101.. _India: `India (in\_)`_
 102.. _Indonesia: `Indonesia (id)`_
 103.. _Ireland: `Ireland (ie)`_
 104.. _Israel: `Israel (il)`_
 105.. _Italy: `Italy (it)`_
 106.. _Japan: `Japan (jp)`_
 107.. _Kuwait: `Kuwait (kw)`_
 108.. _Mexico: `Mexico (mx)`_
 109.. _Norway: `Norway (no)`_
 110.. _Peru: `Peru (pe)`_
 111.. _Poland: `Poland (pl)`_
 112.. _Portugal: `Portugal (pt)`_
 113.. _Romania: `Romania (ro)`_
 114.. _Slovakia: `Slovakia (sk)`_
 115.. _South Africa: `South Africa (za)`_
 116.. _Spain: `Spain (es)`_
 117.. _Sweden: `Sweden (se)`_
 118.. _Switzerland: `Switzerland (ch)`_
 119.. _Turkey: `Turkey (tr)`_
 120.. _United Kingdom: `United Kingdom (uk)`_
 121.. _United States of America: `United States of America (us)`_
 122.. _Uruguay: `Uruguay (uy)`_
 123
 124Internationalization of localflavor
 125===================================
 126
 127Localflavor has its own catalog of translations, in the directory
 128``django/contrib/localflavor/locale``, and it's not loaded automatically like
 129Django's general catalog in ``django/conf/locale``. If you want localflavor's
 130texts to be translated, like form fields error messages, you must include
 131:mod:`django.contrib.localflavor` in the :setting:`INSTALLED_APPS` setting, so
 132the internationalization system can find the catalog, as explained in
 133:ref:`using-translations-in-your-own-projects`.
 134
 135Adding flavors
 136==============
 137
 138We'd love to add more of these to Django, so please `create a ticket`_ with
 139any code you'd like to contribute. One thing we ask is that you please use
 140Unicode objects (``u'mystring'``) for strings, rather than setting the encoding
 141in the file. See any of the existing flavors for examples.
 142
 143.. _create a ticket: http://code.djangoproject.com/simpleticket
 144
 145Localflavor and backwards compatibility
 146=======================================
 147
 148As documented in our :ref:`API stability
 149<misc-api-stability-localflavor>` policy, Django will always attempt
 150to make :mod:`django.contrib.localflavor` reflect the officially
 151gazetted policies of the appropriate local government authority. For
 152example, if a government body makes a change to add, alter, or remove
 153a province (or state, or county), that change will be reflected in
 154Django's localflavor in the next stable Django release.
 155
 156When a backwards-incompatible change is made (for example, the removal
 157or renaming of a province) the localflavor in question will raise a
 158warning when that localflavor is imported. This provides a runtime
 159indication that something may require attention.
 160
 161However, once you have addressed the backwards compatibility (for
 162example, auditing your code to see if any data migration is required),
 163the warning serves no purpose. The warning can then be supressed.
 164For example, to suppress the warnings raised by the Indonesian
 165localflavor you would use the following code::
 166
 167    import warnings
 168    warnings.filterwarnings('ignore',
 169                            category=RuntimeWarning,
 170                            module='django.contrib.localflavor.id')
 171    from django.contrib.localflavor.id import forms as id_forms
 172
 173
 174Argentina (``ar``)
 175=============================================
 176
 177.. class:: ar.forms.ARPostalCodeField
 178
 179    A form field that validates input as either a classic four-digit Argentinian
 180    postal code or a CPA_.
 181
 182.. _CPA: http://www.correoargentino.com.ar/consulta_cpa/home.php
 183
 184.. class:: ar.forms.ARDNIField
 185
 186    A form field that validates input as a Documento Nacional de Identidad (DNI)
 187    number.
 188
 189.. class:: ar.forms.ARCUITField
 190
 191    A form field that validates input as a Codigo Unico de Identificacion
 192    Tributaria (CUIT) number.
 193
 194.. class:: ar.forms.ARProvinceSelect
 195
 196    A ``Select`` widget that uses a list of Argentina's provinces and autonomous
 197    cities as its choices.
 198
 199Australia (``au``)
 200=============================================
 201
 202.. class:: au.forms.AUPostCodeField
 203
 204    A form field that validates input as an Australian postcode.
 205
 206.. class:: au.forms.AUPhoneNumberField
 207
 208    A form field that validates input as an Australian phone number. Valid numbers
 209    have ten digits.
 210
 211.. class:: au.forms.AUStateSelect
 212
 213    A ``Select`` widget that uses a list of Australian states/territories as its
 214    choices.
 215
 216Austria (``at``)
 217================
 218
 219.. class:: at.forms.ATZipCodeField
 220
 221    A form field that validates its input as an Austrian zip code.
 222
 223.. class:: at.forms.ATStateSelect
 224
 225    A ``Select`` widget that uses a list of Austrian states as its choices.
 226
 227.. class:: at.forms.ATSocialSecurityNumberField
 228
 229    A form field that validates its input as an Austrian social security number.
 230
 231Belgium (``be``)
 232================
 233
 234.. versionadded:: 1.3
 235
 236.. class:: be.forms.BEPhoneNumberField
 237
 238    A form field that validates input as a Belgium phone number, with one of
 239    the formats 0x xxx xx xx, 0xx xx xx xx, 04xx xx xx xx, 0x/xxx.xx.xx,
 240    0xx/xx.xx.xx, 04xx/xx.xx.xx, 0x.xxx.xx.xx, 0xx.xx.xx.xx, 04xx.xx.xx.xx,
 241    0xxxxxxxx or 04xxxxxxxx.
 242
 243.. class:: be.forms.BEPostalCodeField
 244
 245    A form field that validates input as a Belgium postal code, in the range
 246    and format 1XXX-9XXX.
 247
 248.. class:: be.forms.BEProvinceSelect
 249
 250    A ``Select`` widget that uses a list of Belgium provinces as its
 251    choices.
 252
 253.. class:: be.forms.BERegionSelect
 254
 255    A ``Select`` widget that uses a list of Belgium regions as its
 256    choices.
 257
 258Brazil (``br``)
 259===============
 260
 261.. class:: br.forms.BRPhoneNumberField
 262
 263    A form field that validates input as a Brazilian phone number, with the format
 264    XX-XXXX-XXXX.
 265
 266.. class:: br.forms.BRZipCodeField
 267
 268    A form field that validates input as a Brazilian zip code, with the format
 269    XXXXX-XXX.
 270
 271.. class:: br.forms.BRStateSelect
 272
 273    A ``Select`` widget that uses a list of Brazilian states/territories as its
 274    choices.
 275
 276.. class:: br.forms.BRCPFField
 277
 278    A form field that validates input as `Brazilian CPF`_.
 279
 280    Input can either be of the format XXX.XXX.XXX-VD or be a group of 11 digits.
 281
 282.. _Brazilian CPF: http://en.wikipedia.org/wiki/Cadastro_de_Pessoas_F%C3%ADsicas
 283
 284.. class:: br.forms.BRCNPJField
 285
 286    A form field that validates input as `Brazilian CNPJ`_.
 287
 288    Input can either be of the format XX.XXX.XXX/XXXX-XX or be a group of 14
 289    digits.
 290
 291.. _Brazilian CNPJ: http://en.wikipedia.org/wiki/National_identification_number#Brazil
 292
 293Canada (``ca``)
 294===============
 295
 296.. class:: ca.forms.CAPhoneNumberField
 297
 298    A form field that validates input as a Canadian phone number, with the format
 299    XXX-XXX-XXXX.
 300
 301.. class:: ca.forms.CAPostalCodeField
 302
 303    A form field that validates input as a Canadian postal code, with the format
 304    XXX XXX.
 305
 306.. class:: ca.forms.CAProvinceField
 307
 308    A form field that validates input as a Canadian province name or abbreviation.
 309
 310.. class:: ca.forms.CASocialInsuranceNumberField
 311
 312    A form field that validates input as a Canadian Social Insurance Number (SIN).
 313    A valid number must have the format XXX-XXX-XXX and pass a `Luhn mod-10
 314    checksum`_.
 315
 316.. _Luhn mod-10 checksum: http://en.wikipedia.org/wiki/Luhn_algorithm
 317
 318.. class:: ca.forms.CAProvinceSelect
 319
 320    A ``Select`` widget that uses a list of Canadian provinces and territories as
 321    its choices.
 322
 323Chile (``cl``)
 324==============
 325
 326.. class:: cl.forms.CLRutField
 327
 328    A form field that validates input as a Chilean national identification number
 329    ('Rol Unico Tributario' or RUT). The valid format is XX.XXX.XXX-X.
 330
 331.. class:: cl.forms.CLRegionSelect
 332
 333    A ``Select`` widget that uses a list of Chilean regions (Regiones) as its
 334    choices.
 335
 336Czech (``cz``)
 337==============
 338
 339.. class:: cz.forms.CZPostalCodeField
 340
 341    A form field that validates input as a Czech postal code. Valid formats
 342    are XXXXX or XXX XX, where X is a digit.
 343
 344.. class:: cz.forms.CZBirthNumberField
 345
 346    A form field that validates input as a Czech Birth Number.
 347    A valid number must be in format XXXXXX/XXXX (slash is optional).
 348
 349.. class:: cz.forms.CZICNumberField
 350
 351    A form field that validates input as a Czech IC number field.
 352
 353.. class:: cz.forms.CZRegionSelect
 354
 355    A ``Select`` widget that uses a list of Czech regions as its choices.
 356
 357Finland (``fi``)
 358================
 359
 360.. class:: fi.forms.FISocialSecurityNumber
 361
 362    A form field that validates input as a Finnish social security number.
 363
 364.. class:: fi.forms.FIZipCodeField
 365
 366    A form field that validates input as a Finnish zip code. Valid codes
 367    consist of five digits.
 368
 369.. class:: fi.forms.FIMunicipalitySelect
 370
 371    A ``Select`` widget that uses a list of Finnish municipalities as its
 372    choices.
 373
 374France (``fr``)
 375===============
 376
 377.. class:: fr.forms.FRPhoneNumberField
 378
 379    A form field that validates input as a French local phone number. The
 380    correct format is 0X XX XX XX XX. 0X.XX.XX.XX.XX and 0XXXXXXXXX validate
 381    but are corrected to 0X XX XX XX XX.
 382
 383.. class:: fr.forms.FRZipCodeField
 384
 385    A form field that validates input as a French zip code. Valid codes
 386    consist of five digits.
 387
 388.. class:: fr.forms.FRDepartmentSelect
 389
 390    A ``Select`` widget that uses a list of French departments as its choices.
 391
 392Germany (``de``)
 393================
 394
 395.. class:: de.forms.DEIdentityCardNumberField
 396
 397    A form field that validates input as a German identity card number
 398    (Personalausweis_). Valid numbers have the format
 399    XXXXXXXXXXX-XXXXXXX-XXXXXXX-X, with no group consisting entirely of zeroes.
 400
 401.. _Personalausweis: http://de.wikipedia.org/wiki/Personalausweis
 402
 403.. class:: de.forms.DEZipCodeField
 404
 405    A form field that validates input as a German zip code. Valid codes
 406    consist of five digits.
 407
 408.. class:: de.forms.DEStateSelect
 409
 410    A ``Select`` widget that uses a list of German states as its choices.
 411
 412The Netherlands (``nl``)
 413========================
 414
 415.. class:: nl.forms.NLPhoneNumberField
 416
 417    A form field that validates input as a Dutch telephone number.
 418
 419.. class:: nl.forms.NLSofiNumberField
 420
 421    A form field that validates input as a Dutch social security number
 422    (SoFI/BSN).
 423
 424.. class:: nl.forms.NLZipCodeField
 425
 426    A form field that validates input as a Dutch zip code.
 427
 428.. class:: nl.forms.NLProvinceSelect
 429
 430    A ``Select`` widget that uses a list of Dutch provinces as its list of
 431    choices.
 432
 433Iceland (``is_``)
 434=================
 435
 436.. class:: is_.forms.ISIdNumberField
 437
 438    A form field that validates input as an Icelandic identification number
 439    (kennitala). The format is XXXXXX-XXXX.
 440
 441.. class:: is_.forms.ISPhoneNumberField
 442
 443    A form field that validates input as an Icelandtic phone number (seven
 444    digits with an optional hyphen or space after the first three digits).
 445
 446.. class:: is_.forms.ISPostalCodeSelect
 447
 448    A ``Select`` widget that uses a list of Icelandic postal codes as its
 449    choices.
 450
 451India (``in_``)
 452===============
 453
 454.. class:: in.forms.INStateField
 455
 456    A form field that validates input as an Indian state/territory name or
 457    abbreviation. Input is normalized to the standard two-letter vehicle
 458    registration abbreviation for the given state or territory.
 459
 460.. class:: in.forms.INZipCodeField
 461
 462    A form field that validates input as an Indian zip code, with the
 463    format XXXXXXX.
 464
 465.. class:: in.forms.INStateSelect
 466
 467    A ``Select`` widget that uses a list of Indian states/territories as its
 468    choices.
 469
 470Ireland (``ie``)
 471================
 472
 473.. class:: ie.forms.IECountySelect
 474
 475    A ``Select`` widget that uses a list of Irish Counties as its choices.
 476
 477Indonesia (``id``)
 478==================
 479
 480.. class:: id.forms.IDPostCodeField
 481
 482    A form field that validates input as an Indonesian post code field.
 483
 484.. class:: id.forms.IDProvinceSelect
 485
 486    A ``Select`` widget that uses a list of Indonesian provinces as its choices.
 487
 488.. versionchanged:: 1.3
 489    The province "Nanggroe Aceh Darussalam (NAD)" has been removed
 490    from the province list in favor of the new official designation
 491    "Aceh (ACE)".
 492
 493.. class:: id.forms.IDPhoneNumberField
 494
 495    A form field that validates input as an Indonesian telephone number.
 496
 497.. class:: id.forms.IDLicensePlatePrefixSelect
 498
 499    A ``Select`` widget that uses a list of Indonesian license plate
 500    prefix code as its choices.
 501
 502.. class:: id.forms.IDLicensePlateField
 503
 504    A form field that validates input as an Indonesian vehicle license plate.
 505
 506.. class:: id.forms.IDNationalIdentityNumberField
 507
 508    A form field that validates input as an Indonesian national identity
 509    number (`NIK`_/KTP). The output will be in the format of
 510    'XX.XXXX.DDMMYY.XXXX'. Dots or spaces can be used in the input to break
 511    down the numbers.
 512
 513.. _NIK: http://en.wikipedia.org/wiki/Indonesian_identity_card
 514
 515Israel (``il``)
 516===============
 517
 518.. class:: il.forms.ILPostalCodeField
 519
 520    A form field that validates its input as an Israeli five-digit postal code.
 521
 522.. class:: il.forms.ILIDNumberField
 523
 524    A form field that validates its input as an `Israeli identification number`_.
 525    The output will be in the format of a 2-9 digit number, consisting of a
 526    1-8 digit ID number followed by a single checksum digit, calculated using
 527    the `Luhn algorithm`_.
 528
 529    Input may contain an optional hyphen separating the ID number from the checksum
 530    digit.
 531
 532.. _Israeli identification number: http://he.wikipedia.org/wiki/%D7%9E%D7%A1%D7%A4%D7%A8_%D7%96%D7%94%D7%95%D7%AA_(%D7%99%D7%A9%D7%A8%D7%90%D7%9C)
 533.. _Luhn algorithm: http://en.wikipedia.org/wiki/Luhn_algorithm
 534
 535
 536
 537Italy (``it``)
 538==============
 539
 540.. class:: it.forms.ITSocialSecurityNumberField
 541
 542    A form field that validates input as an Italian social security number
 543    (`codice fiscale`_).
 544
 545.. _codice fiscale: http://www.agenziaentrate.it/ilwwcm/connect/Nsi/Servizi/Codice+fiscale+-+tessera+sanitaria/NSI+Informazioni+sulla+codificazione+delle+persone+fisiche
 546
 547.. class:: it.forms.ITVatNumberField
 548
 549    A form field that validates Italian VAT numbers (partita IVA).
 550
 551.. class:: it.forms.ITZipCodeField
 552
 553    A form field that validates input as an Italian zip code. Valid codes
 554    must have five digits.
 555
 556.. class:: it.forms.ITProvinceSelect
 557
 558    A ``Select`` widget that uses a list of Italian provinces as its choices.
 559
 560.. class:: it.forms.ITRegionSelect
 561
 562    A ``Select`` widget that uses a list of Italian regions as its choices.
 563
 564Japan (``jp``)
 565==============
 566
 567.. class:: jp.forms.JPPostalCodeField
 568
 569    A form field that validates input as a Japanese postcode. It accepts seven
 570    digits, with or without a hyphen.
 571
 572.. class:: jp.forms.JPPrefectureSelect
 573
 574    A ``Select`` widget that uses a list of Japanese prefectures as its choices.
 575
 576Kuwait (``kw``)
 577===============
 578
 579.. class:: kw.forms.KWCivilIDNumberField
 580
 581    A form field that validates input as a Kuwaiti Civil ID number. A valid
 582    Civil ID number must obey the following rules:
 583
 584    * The number consist of 12 digits.
 585    * The birthdate of the person is a valid date.
 586    * The calculated checksum equals to the last digit of the Civil ID.
 587
 588Mexico (``mx``)
 589===============
 590
 591.. class:: mx.forms.MXStateSelect
 592
 593    A ``Select`` widget that uses a list of Mexican states as its choices.
 594
 595Norway (``no``)
 596===============
 597
 598.. class:: no.forms.NOSocialSecurityNumber
 599
 600    A form field that validates input as a Norwegian social security number
 601    (personnummer_).
 602
 603.. _personnummer: http://no.wikipedia.org/wiki/Personnummer
 604
 605.. class:: no.forms.NOZipCodeField
 606
 607    A form field that validates input as a Norwegian zip code. Valid codes
 608    have four digits.
 609
 610.. class:: no.forms.NOMunicipalitySelect
 611
 612    A ``Select`` widget that uses a list of Norwegian municipalities (fylker) as
 613    its choices.
 614
 615Peru (``pe``)
 616=============
 617
 618.. class:: pe.forms.PEDNIField
 619
 620    A form field that validates input as a DNI (Peruvian national identity)
 621    number.
 622
 623.. class:: pe.forms.PERUCField
 624
 625    A form field that validates input as an RUC (Registro Unico de
 626    Contribuyentes) number. Valid RUC numbers have 11 digits.
 627
 628.. class:: pe.forms.PEDepartmentSelect
 629
 630    A ``Select`` widget that uses a list of Peruvian Departments as its choices.
 631
 632Poland (``pl``)
 633===============
 634
 635.. class:: pl.forms.PLPESELField
 636
 637    A form field that validates input as a Polish national identification number
 638    (PESEL_).
 639
 640.. _PESEL: http://en.wikipedia.org/wiki/PESEL
 641
 642.. class:: pl.forms.PLREGONField
 643
 644    A form field that validates input as a Polish National Official Business
 645    Register Number (REGON_), having either seven or nine digits. The checksum
 646    algorithm used for REGONs is documented at
 647    http://wipos.p.lodz.pl/zylla/ut/nip-rego.html.
 648
 649.. _REGON: http://www.stat.gov.pl/bip/regon_ENG_HTML.htm
 650
 651.. class:: pl.forms.PLPostalCodeField
 652
 653    A form field that validates input as a Polish postal code. The valid format
 654    is XX-XXX, where X is a digit.
 655
 656.. class:: pl.forms.PLNIPField
 657
 658    A form field that validates input as a Polish Tax Number (NIP). Valid
 659    formats are XXX-XXX-XX-XX or XX-XX-XXX-XXX. The checksum algorithm used
 660    for NIPs is documented at http://wipos.p.lodz.pl/zylla/ut/nip-rego.html.
 661
 662.. class:: pl.forms.PLCountySelect
 663
 664    A ``Select`` widget that uses a list of Polish administrative units as its
 665    choices.
 666
 667.. class:: pl.forms.PLProvinceSelect
 668
 669    A ``Select`` widget that uses a list of Polish voivodeships (administrative
 670    provinces) as its choices.
 671
 672Portugal (``pt``)
 673=================
 674
 675.. class:: pt.forms.PTZipCodeField
 676
 677    A form field that validates input as a Portuguese zip code.
 678
 679.. class:: pt.forms.PTPhoneNumberField
 680
 681    A form field that validates input as a Portuguese phone number.
 682    Valid numbers have 9 digits (may include spaces) or start by 00
 683    or + (international).
 684
 685Romania (``ro``)
 686================
 687
 688.. class:: ro.forms.ROCIFField
 689
 690    A form field that validates Romanian fiscal identification codes (CIF). The
 691    return value strips the leading RO, if given.
 692
 693.. class:: ro.forms.ROCNPField
 694
 695    A form field that validates Romanian personal numeric codes (CNP).
 696
 697.. class:: ro.forms.ROCountyField
 698
 699    A form field that validates its input as a Romanian county (judet) name or
 700    abbreviation. It normalizes the input to the standard vehicle registration
 701    abbreviation for the given county. This field will only accept names written
 702    with diacritics; consider using ROCountySelect as an alternative.
 703
 704.. class:: ro.forms.ROCountySelect
 705
 706    A ``Select`` widget that uses a list of Romanian counties (judete) as its
 707    choices.
 708
 709.. class:: ro.forms.ROIBANField
 710
 711    A form field that validates its input as a Romanian International Bank
 712    Account Number (IBAN). The valid format is ROXX-XXXX-XXXX-XXXX-XXXX-XXXX,
 713    with or without hyphens.
 714
 715.. class:: ro.forms.ROPhoneNumberField
 716
 717    A form field that validates Romanian phone numbers, short special numbers
 718    excluded.
 719
 720.. class:: ro.forms.ROPostalCodeField
 721
 722    A form field that validates Romanian postal codes.
 723
 724Slovakia (``sk``)
 725=================
 726
 727.. class:: sk.forms.SKPostalCodeField
 728
 729    A form field that validates input as a Slovak postal code. Valid formats
 730    are XXXXX or XXX XX, where X is a digit.
 731
 732.. class:: sk.forms.SKDistrictSelect
 733
 734    A ``Select`` widget that uses a list of Slovak districts as its choices.
 735
 736.. class:: sk.forms.SKRegionSelect
 737
 738    A ``Select`` widget that uses a list of Slovak regions as its choices.
 739
 740South Africa (``za``)
 741=====================
 742
 743.. class:: za.forms.ZAIDField
 744
 745    A form field that validates input as a South African ID number. Validation
 746    uses the Luhn checksum and a simplistic (i.e., not entirely accurate) check
 747    for birth date.
 748
 749.. class:: za.forms.ZAPostCodeField
 750
 751    A form field that validates input as a South African postcode. Valid
 752    postcodes must have four digits.
 753
 754Spain (``es``)
 755==============
 756
 757.. class:: es.forms.ESIdentityCardNumberField
 758
 759    A form field that validates input as a Spanish NIF/NIE/CIF (Fiscal
 760    Identification Number) code.
 761
 762.. class:: es.forms.ESCCCField
 763
 764    A form field that validates input as a Spanish bank account number (Codigo
 765    Cuenta Cliente or CCC). A valid CCC number has the format
 766    EEEE-OOOO-CC-AAAAAAAAAA, where the E, O, C and A digits denote the entity,
 767    office, checksum and account, respectively. The first checksum digit
 768    validates the entity and office. The second checksum digit validates the
 769    account. It is also valid to use a space as a delimiter, or to use no
 770    delimiter.
 771
 772.. class:: es.forms.ESPhoneNumberField
 773
 774    A form field that validates input as a Spanish phone number. Valid numbers
 775    have nine digits, the first of which is 6, 8 or 9.
 776
 777.. class:: es.forms.ESPostalCodeField
 778
 779    A form field that validates input as a Spanish postal code. Valid codes
 780    have five digits, the first two being in the range 01 to 52, representing
 781    the province.
 782
 783.. class:: es.forms.ESProvinceSelect
 784
 785    A ``Select`` widget that uses a list of Spanish provinces as its choices.
 786
 787.. class:: es.forms.ESRegionSelect
 788
 789    A ``Select`` widget that uses a list of Spanish regions as its choices.
 790
 791Sweden (``se``)
 792===============
 793
 794.. class:: se.forms.SECountySelect
 795
 796    A Select form widget that uses a list of the Swedish counties (l?n) as its
 797    choices.
 798
 799    The cleaned value is the official county code -- see
 800    http://en.wikipedia.org/wiki/Counties_of_Sweden for a list.
 801
 802.. class:: se.forms.SEOrganisationNumber
 803
 804    A form field that validates input as a Swedish organisation number
 805    (organisationsnummer).
 806
 807    It accepts the same input as SEPersonalIdentityField (for sole
 808    proprietorships (enskild firma). However, co-ordination numbers are not
 809    accepted.
 810
 811    It also accepts ordinary Swedish organisation numbers with the format
 812    NNNNNNNNNN.
 813
 814    The return value will be YYYYMMDDXXXX for sole proprietors, and NNNNNNNNNN
 815    for other organisations.
 816
 817.. class:: se.forms.SEPersonalIdentityNumber
 818
 819    A form field that validates input as a Swedish personal identity number
 820    (personnummer).
 821
 822    The correct formats are YYYYMMDD-XXXX, YYYYMMDDXXXX, YYMMDD-XXXX,
 823    YYMMDDXXXX and YYMMDD+XXXX.
 824
 825    A \+ indicates that the person is older than 100 years, which will be taken
 826    into consideration when the date is validated.
 827
 828    The checksum will be calculated and checked. The birth date is checked
 829    to be a valid date.
 830
 831    By default, co-ordination numbers (samordningsnummer) will be accepted. To
 832    only allow real personal identity numbers, pass the keyword argument
 833    coordination_number=False to the constructor.
 834
 835    The cleaned value will always have the format YYYYMMDDXXXX.
 836
 837.. class:: se.forms.SEPostalCodeField
 838
 839    A form field that validates input as a Swedish postal code (postnummer).
 840    Valid codes consist of five digits (XXXXX). The number can optionally be
 841    formatted with a space after the third digit (XXX XX).
 842
 843    The cleaned value will never contain the space.
 844
 845Switzerland (``ch``)
 846====================
 847
 848.. class:: ch.forms.CHIdentityCardNumberField
 849
 850    A form field that validates input as a Swiss identity card number.
 851    A valid number must confirm to the X1234567<0 or 1234567890 format and
 852    have the correct checksums.
 853
 854.. class:: ch.forms.CHPhoneNumberField
 855
 856    A form field that validates input as a Swiss phone number. The correct
 857    format is 0XX XXX XX XX. 0XX.XXX.XX.XX and 0XXXXXXXXX validate but are
 858    corrected to 0XX XXX XX XX.
 859
 860.. class:: ch.forms.CHZipCodeField
 861
 862    A form field that validates input as a Swiss zip code. Valid codes
 863    consist of four digits.
 864
 865.. class:: ch.forms.CHStateSelect
 866
 867    A ``Select`` widget that uses a list of Swiss states as its choices.
 868
 869Turkey (``tr``)
 870===============
 871
 872.. class:: tr.forms.TRZipCodeField
 873
 874    A form field that validates input as a Turkish zip code. Valid codes
 875    consist of five digits.
 876
 877.. class:: tr.forms.TRPhoneNumberField
 878
 879    A form field that validates input as a Turkish phone number. The correct
 880    format is 0xxx xxx xxxx. +90xxx xxx xxxx and inputs without spaces also
 881    validates. The result is normalized to xxx xxx xxxx format.
 882
 883.. class:: tr.forms.TRIdentificationNumberField
 884
 885    A form field that validates input as a TR identification number. A valid
 886    number must satisfy the following:
 887
 888    * The number consist of 11 digits.
 889    * The first digit cannot be 0.
 890    * (sum(1st, 3rd, 5th, 7th, 9th)*7 - sum(2nd,4th,6th,8th)) % 10) must be
 891      equal to the 10th digit.
 892    * (sum(1st to 10th) % 10) must be equal to the 11th digit.
 893
 894.. class:: tr.forms.TRProvinceSelect
 895
 896    A ``select`` widget that uses a list of Turkish provinces as its choices.
 897
 898United Kingdom (``uk``)
 899=======================
 900
 901.. class:: uk.forms.UKPostcodeField
 902
 903    A form field that validates input as a UK postcode. The regular
 904    expression used is sourced from the schema for British Standard BS7666
 905    address types at http://www.cabinetoffice.gov.uk/media/291293/bs7666-v2-0.xml.
 906
 907.. class:: uk.forms.UKCountySelect
 908
 909    A ``Select`` widget that uses a list of UK counties/regions as its choices.
 910
 911.. class:: uk.forms.UKNationSelect
 912
 913    A ``Select`` widget that uses a list of UK nations as its choices.
 914
 915United States of America (``us``)
 916=================================
 917
 918.. class:: us.forms.USPhoneNumberField
 919
 920    A form field that validates input as a U.S. phone number.
 921
 922.. class:: us.forms.USSocialSecurityNumberField
 923
 924    A form field that validates input as a U.S. Social Security Number (SSN).
 925    A valid SSN must obey the following rules:
 926
 927        * Format of XXX-XX-XXXX
 928        * No group of digits consisting entirely of zeroes
 929        * Leading group of digits cannot be 666
 930        * Number not in promotional block 987-65-4320 through 987-65-4329
 931        * Number not one known to be invalid due to widespread promotional
 932          use or distribution (e.g., the Woolworth's number or the 1962
 933          promotional number)
 934
 935.. class:: us.forms.USStateField
 936
 937    A form field that validates input as a U.S. state name or abbreviation. It
 938    normalizes the input to the standard two-letter postal service abbreviation
 939    for the given state.
 940
 941.. class:: us.forms.USZipCodeField
 942
 943    A form field that validates input as a U.S. ZIP code. Valid formats are
 944    XXXXX or XXXXX-XXXX.
 945
 946.. class:: us.forms.USStateSelect
 947
 948    A form ``Select`` widget that uses a list of U.S. states/territories as its
 949    choices.
 950
 951.. class:: us.forms.USPSSelect
 952
 953    A form ``Select`` widget that uses a list of U.S Postal Service
 954    state, territory and country abbreviations as its choices.
 955
 956.. class:: us.models.PhoneNumberField
 957
 958    A :class:`CharField` that checks that the value is a valid U.S.A.-style phone
 959    number (in the format ``XXX-XXX-XXXX``).
 960
 961.. class:: us.models.USStateField
 962
 963    A model field that forms represent as a ``forms.USStateField`` field and
 964    stores the two-letter U.S. state abbreviation in the database.
 965
 966.. class:: us.models.USPostalCodeField
 967
 968    A model field that forms represent as a ``forms.USPSSelect`` field
 969    and stores the two-letter U.S Postal Service abbreviation in the
 970    database.
 971
 972Additionally, a variety of choice tuples are provided in
 973``django.contrib.localflavor.us.us_states``, allowing customized model
 974and form fields, and form presentations, for subsets of U.S states,
 975territories and U.S Postal Service abbreviations:
 976
 977.. data:: us.us_states.CONTIGUOUS_STATES
 978
 979    A tuple of choices of the postal abbreviations for the
 980    contiguous or "lower 48" states (i.e., all except Alaska and
 981    Hawaii), plus the District of Columbia.
 982
 983.. data:: us.us_states.US_STATES
 984
 985    A tuple of choices of the postal abbreviations for all
 986    50 U.S. states, plus the District of Columbia.
 987
 988.. data:: us.us_states.US_TERRITORIES
 989
 990    A tuple of choices of the postal abbreviations for U.S
 991    territories: American Samoa, Guam, the Northern Mariana Islands,
 992    Puerto Rico and the U.S. Virgin Islands.
 993
 994.. data:: us.us_states.ARMED_FORCES_STATES
 995
 996    A tuple of choices of the postal abbreviations of the three U.S
 997    military postal "states": Armed Forces Americas, Armed Forces
 998    Europe and Armed Forces Pacific.
 999
1000.. data:: us.us_states.COFA_STATES
1001
1002    A tuple of choices of the postal abbreviations of the three
1003    independent nations which, under the Compact of Free Association,
1004    are served by the U.S. Postal Service: the Federated States of
1005    Micronesia, the Marshall Islands and Palau.
1006
1007.. data:: us.us_states.OBSOLETE_STATES
1008
1009    A tuple of choices of obsolete U.S Postal Service state
1010    abbreviations: the former abbreviation for the Northern Mariana
1011    Islands, plus the Panama Canal Zone, the Philippines and the
1012    former Pacific trust territories.
1013
1014.. data:: us.us_states.STATE_CHOICES
1015
1016    A tuple of choices of all postal abbreviations corresponding to U.S states or
1017    territories, and the District of Columbia..
1018
1019.. data:: us.us_states.USPS_CHOICES
1020
1021    A tuple of choices of all postal abbreviations recognized by the
1022    U.S Postal Service (including all states and territories, the
1023    District of Columbia, armed forces "states" and independent
1024    nations serviced by USPS).
1025
1026Uruguay (``uy``)
1027================
1028
1029.. class:: uy.forms.UYCIField
1030
1031    A field that validates Uruguayan 'Cedula de identidad' (CI) numbers.
1032
1033.. class:: uy.forms.UYDepartamentSelect
1034
1035    A ``Select`` widget that uses a list of  Uruguayan departaments as its
1036    choices.