/docs/ref/contrib/localflavor.txt
Plain Text | 1036 lines | 678 code | 358 blank | 0 comment | 0 complexity | 555d874bdf88296411d4a9806b601813 MD5 | raw file
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.