Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #3883 -- Added initial localflavor documentation. Thanks, Nick …

…Efford.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@6849 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit cb350d72abdaf02a4816ba65be1c5827bf14916e 1 parent ab75953
Malcolm Tredinnick authored December 02, 2007

Showing 1 changed file with 654 additions and 0 deletions. Show diff stats Hide diff stats

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

0 notes on commit cb350d7

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