1 # -*- coding: utf-8 -*-

     2 r"""

     3 >>> from django.newforms import *

     4 >>> import datetime

     5 >>> import re

     6 

     7 ###########

     8 # Widgets #

     9 ###########

    10 

    11 Each Widget class corresponds to an HTML form widget. A Widget knows how to

    12 render itself, given a field name and some data. Widgets don't perform

    13 validation.

    14 

    15 # TextInput Widget ############################################################

    16 

    17 >>> w = TextInput()

    18 >>> w.render('email', '')

    19 u'<input type="text" name="email" />'

    20 >>> w.render('email', None)

    21 u'<input type="text" name="email" />'

    22 >>> w.render('email', 'test@example.com')

    23 u'<input type="text" name="email" value="test@example.com" />'

    24 >>> w.render('email', 'some "quoted" & ampersanded value')

    25 u'<input type="text" name="email" value="some &quot;quoted&quot; &amp; ampersanded value" />'

    26 >>> w.render('email', 'test@example.com', attrs={'class': 'fun'})

    27 u'<input type="text" name="email" value="test@example.com" class="fun" />'

    28 

    29 # Note that doctest in Python 2.4 (and maybe 2.5?) doesn't support non-ascii

    30 # characters in output, so we're displaying the repr() here.

    31 >>> w.render('email', 'ŠĐĆŽćžšđ', attrs={'class': 'fun'})

    32 u'<input type="text" name="email" value="\u0160\u0110\u0106\u017d\u0107\u017e\u0161\u0111" class="fun" />'

    33 

    34 You can also pass 'attrs' to the constructor:

    35 >>> w = TextInput(attrs={'class': 'fun'})

    36 >>> w.render('email', '')

    37 u'<input type="text" class="fun" name="email" />'

    38 >>> w.render('email', 'foo@example.com')

    39 u'<input type="text" class="fun" value="foo@example.com" name="email" />'

    40 

    41 'attrs' passed to render() get precedence over those passed to the constructor:

    42 >>> w = TextInput(attrs={'class': 'pretty'})

    43 >>> w.render('email', '', attrs={'class': 'special'})

    44 u'<input type="text" class="special" name="email" />'

    45 

    46 # PasswordInput Widget ############################################################

    47 

    48 >>> w = PasswordInput()

    49 >>> w.render('email', '')

    50 u'<input type="password" name="email" />'

    51 >>> w.render('email', None)

    52 u'<input type="password" name="email" />'

    53 >>> w.render('email', 'test@example.com')

    54 u'<input type="password" name="email" value="test@example.com" />'

    55 >>> w.render('email', 'some "quoted" & ampersanded value')

    56 u'<input type="password" name="email" value="some &quot;quoted&quot; &amp; ampersanded value" />'

    57 >>> w.render('email', 'test@example.com', attrs={'class': 'fun'})

    58 u'<input type="password" name="email" value="test@example.com" class="fun" />'

    59 

    60 You can also pass 'attrs' to the constructor:

    61 >>> w = PasswordInput(attrs={'class': 'fun'})

    62 >>> w.render('email', '')

    63 u'<input type="password" class="fun" name="email" />'

    64 >>> w.render('email', 'foo@example.com')

    65 u'<input type="password" class="fun" value="foo@example.com" name="email" />'

    66 

    67 'attrs' passed to render() get precedence over those passed to the constructor:

    68 >>> w = PasswordInput(attrs={'class': 'pretty'})

    69 >>> w.render('email', '', attrs={'class': 'special'})

    70 u'<input type="password" class="special" name="email" />'

    71 

    72 >>> w.render('email', 'ŠĐĆŽćžšđ', attrs={'class': 'fun'})

    73 u'<input type="password" class="fun" value="\u0160\u0110\u0106\u017d\u0107\u017e\u0161\u0111" name="email" />'

    74 

    75 The render_value argument lets you specify whether the widget should render

    76 its value. You may want to do this for security reasons.

    77 >>> w = PasswordInput(render_value=True)

    78 >>> w.render('email', 'secret')

    79 u'<input type="password" name="email" value="secret" />'

    80 >>> w = PasswordInput(render_value=False)

    81 >>> w.render('email', '')

    82 u'<input type="password" name="email" />'

    83 >>> w.render('email', None)

    84 u'<input type="password" name="email" />'

    85 >>> w.render('email', 'secret')

    86 u'<input type="password" name="email" />'

    87 >>> w = PasswordInput(attrs={'class': 'fun'}, render_value=False)

    88 >>> w.render('email', 'secret')

    89 u'<input type="password" class="fun" name="email" />'

    90 

    91 # HiddenInput Widget ############################################################

    92 

    93 >>> w = HiddenInput()

    94 >>> w.render('email', '')

    95 u'<input type="hidden" name="email" />'

    96 >>> w.render('email', None)

    97 u'<input type="hidden" name="email" />'

    98 >>> w.render('email', 'test@example.com')

    99 u'<input type="hidden" name="email" value="test@example.com" />'

   100 >>> w.render('email', 'some "quoted" & ampersanded value')

   101 u'<input type="hidden" name="email" value="some &quot;quoted&quot; &amp; ampersanded value" />'

   102 >>> w.render('email', 'test@example.com', attrs={'class': 'fun'})

   103 u'<input type="hidden" name="email" value="test@example.com" class="fun" />'

   104 

   105 You can also pass 'attrs' to the constructor:

   106 >>> w = HiddenInput(attrs={'class': 'fun'})

   107 >>> w.render('email', '')

   108 u'<input type="hidden" class="fun" name="email" />'

   109 >>> w.render('email', 'foo@example.com')

   110 u'<input type="hidden" class="fun" value="foo@example.com" name="email" />'

   111 

   112 'attrs' passed to render() get precedence over those passed to the constructor:

   113 >>> w = HiddenInput(attrs={'class': 'pretty'})

   114 >>> w.render('email', '', attrs={'class': 'special'})

   115 u'<input type="hidden" class="special" name="email" />'

   116 

   117 >>> w.render('email', 'ŠĐĆŽćžšđ', attrs={'class': 'fun'})

   118 u'<input type="hidden" class="fun" value="\u0160\u0110\u0106\u017d\u0107\u017e\u0161\u0111" name="email" />'

   119 

   120 'attrs' passed to render() get precedence over those passed to the constructor:

   121 >>> w = HiddenInput(attrs={'class': 'pretty'})

   122 >>> w.render('email', '', attrs={'class': 'special'})

   123 u'<input type="hidden" class="special" name="email" />'

   124 

   125 # MultipleHiddenInput Widget ##################################################

   126 

   127 >>> w = MultipleHiddenInput()

   128 >>> w.render('email', [])

   129 u''

   130 >>> w.render('email', None)

   131 u''

   132 >>> w.render('email', ['test@example.com'])

   133 u'<input type="hidden" name="email" value="test@example.com" />'

   134 >>> w.render('email', ['some "quoted" & ampersanded value'])

   135 u'<input type="hidden" name="email" value="some &quot;quoted&quot; &amp; ampersanded value" />'

   136 >>> w.render('email', ['test@example.com', 'foo@example.com'])

   137 u'<input type="hidden" name="email" value="test@example.com" />\n<input type="hidden" name="email" value="foo@example.com" />'

   138 >>> w.render('email', ['test@example.com'], attrs={'class': 'fun'})

   139 u'<input type="hidden" name="email" value="test@example.com" class="fun" />'

   140 >>> w.render('email', ['test@example.com', 'foo@example.com'], attrs={'class': 'fun'})

   141 u'<input type="hidden" name="email" value="test@example.com" class="fun" />\n<input type="hidden" name="email" value="foo@example.com" class="fun" />'

   142 

   143 You can also pass 'attrs' to the constructor:

   144 >>> w = MultipleHiddenInput(attrs={'class': 'fun'})

   145 >>> w.render('email', [])

   146 u''

   147 >>> w.render('email', ['foo@example.com'])

   148 u'<input type="hidden" class="fun" value="foo@example.com" name="email" />'

   149 >>> w.render('email', ['foo@example.com', 'test@example.com'])

   150 u'<input type="hidden" class="fun" value="foo@example.com" name="email" />\n<input type="hidden" class="fun" value="test@example.com" name="email" />'

   151 

   152 'attrs' passed to render() get precedence over those passed to the constructor:

   153 >>> w = MultipleHiddenInput(attrs={'class': 'pretty'})

   154 >>> w.render('email', ['foo@example.com'], attrs={'class': 'special'})

   155 u'<input type="hidden" class="special" value="foo@example.com" name="email" />'

   156 

   157 >>> w.render('email', ['ŠĐĆŽćžšđ'], attrs={'class': 'fun'})

   158 u'<input type="hidden" class="fun" value="\u0160\u0110\u0106\u017d\u0107\u017e\u0161\u0111" name="email" />'

   159 

   160 'attrs' passed to render() get precedence over those passed to the constructor:

   161 >>> w = MultipleHiddenInput(attrs={'class': 'pretty'})

   162 >>> w.render('email', ['foo@example.com'], attrs={'class': 'special'})

   163 u'<input type="hidden" class="special" value="foo@example.com" name="email" />'

   164 

   165 # FileInput Widget ############################################################

   166 

   167 >>> w = FileInput()

   168 >>> w.render('email', '')

   169 u'<input type="file" name="email" />'

   170 >>> w.render('email', None)

   171 u'<input type="file" name="email" />'

   172 >>> w.render('email', 'test@example.com')

   173 u'<input type="file" name="email" value="test@example.com" />'

   174 >>> w.render('email', 'some "quoted" & ampersanded value')

   175 u'<input type="file" name="email" value="some &quot;quoted&quot; &amp; ampersanded value" />'

   176 >>> w.render('email', 'test@example.com', attrs={'class': 'fun'})

   177 u'<input type="file" name="email" value="test@example.com" class="fun" />'

   178 

   179 You can also pass 'attrs' to the constructor:

   180 >>> w = FileInput(attrs={'class': 'fun'})

   181 >>> w.render('email', '')

   182 u'<input type="file" class="fun" name="email" />'

   183 >>> w.render('email', 'foo@example.com')

   184 u'<input type="file" class="fun" value="foo@example.com" name="email" />'

   185 

   186 >>> w.render('email', 'ŠĐĆŽćžšđ', attrs={'class': 'fun'})

   187 u'<input type="file" class="fun" value="\u0160\u0110\u0106\u017d\u0107\u017e\u0161\u0111" name="email" />'

   188 

   189 # Textarea Widget #############################################################

   190 

   191 >>> w = Textarea()

   192 >>> w.render('msg', '')

   193 u'<textarea name="msg"></textarea>'

   194 >>> w.render('msg', None)

   195 u'<textarea name="msg"></textarea>'

   196 >>> w.render('msg', 'value')

   197 u'<textarea name="msg">value</textarea>'

   198 >>> w.render('msg', 'some "quoted" & ampersanded value')

   199 u'<textarea name="msg">some &quot;quoted&quot; &amp; ampersanded value</textarea>'

   200 >>> w.render('msg', 'value', attrs={'class': 'pretty'})

   201 u'<textarea name="msg" class="pretty">value</textarea>'

   202 

   203 You can also pass 'attrs' to the constructor:

   204 >>> w = Textarea(attrs={'class': 'pretty'})

   205 >>> w.render('msg', '')

   206 u'<textarea class="pretty" name="msg"></textarea>'

   207 >>> w.render('msg', 'example')

   208 u'<textarea class="pretty" name="msg">example</textarea>'

   209 

   210 'attrs' passed to render() get precedence over those passed to the constructor:

   211 >>> w = Textarea(attrs={'class': 'pretty'})

   212 >>> w.render('msg', '', attrs={'class': 'special'})

   213 u'<textarea class="special" name="msg"></textarea>'

   214 

   215 >>> w.render('msg', 'ŠĐĆŽćžšđ', attrs={'class': 'fun'})

   216 u'<textarea class="fun" name="msg">\u0160\u0110\u0106\u017d\u0107\u017e\u0161\u0111</textarea>'

   217 

   218 # CheckboxInput Widget ########################################################

   219 

   220 >>> w = CheckboxInput()

   221 >>> w.render('is_cool', '')

   222 u'<input type="checkbox" name="is_cool" />'

   223 >>> w.render('is_cool', None)

   224 u'<input type="checkbox" name="is_cool" />'

   225 >>> w.render('is_cool', False)

   226 u'<input type="checkbox" name="is_cool" />'

   227 >>> w.render('is_cool', True)

   228 u'<input checked="checked" type="checkbox" name="is_cool" />'

   229 

   230 Using any value that's not in ('', None, False, True) will check the checkbox

   231 and set the 'value' attribute.

   232 >>> w.render('is_cool', 'foo')

   233 u'<input checked="checked" type="checkbox" name="is_cool" value="foo" />'

   234 

   235 >>> w.render('is_cool', False, attrs={'class': 'pretty'})

   236 u'<input type="checkbox" name="is_cool" class="pretty" />'

   237 

   238 You can also pass 'attrs' to the constructor:

   239 >>> w = CheckboxInput(attrs={'class': 'pretty'})

   240 >>> w.render('is_cool', '')

   241 u'<input type="checkbox" class="pretty" name="is_cool" />'

   242 

   243 'attrs' passed to render() get precedence over those passed to the constructor:

   244 >>> w = CheckboxInput(attrs={'class': 'pretty'})

   245 >>> w.render('is_cool', '', attrs={'class': 'special'})

   246 u'<input type="checkbox" class="special" name="is_cool" />'

   247 

   248 You can pass 'check_test' to the constructor. This is a callable that takes the

   249 value and returns True if the box should be checked.

   250 >>> w = CheckboxInput(check_test=lambda value: value.startswith('hello'))

   251 >>> w.render('greeting', '')

   252 u'<input type="checkbox" name="greeting" />'

   253 >>> w.render('greeting', 'hello')

   254 u'<input checked="checked" type="checkbox" name="greeting" value="hello" />'

   255 >>> w.render('greeting', 'hello there')

   256 u'<input checked="checked" type="checkbox" name="greeting" value="hello there" />'

   257 >>> w.render('greeting', 'hello & goodbye')

   258 u'<input checked="checked" type="checkbox" name="greeting" value="hello &amp; goodbye" />'

   259 

   260 A subtlety: If the 'check_test' argument cannot handle a value and raises any

   261 exception during its __call__, then the exception will be swallowed and the box

   262 will not be checked. In this example, the 'check_test' assumes the value has a

   263 startswith() method, which fails for the values True, False and None.

   264 >>> w.render('greeting', True)

   265 u'<input type="checkbox" name="greeting" />'

   266 >>> w.render('greeting', False)

   267 u'<input type="checkbox" name="greeting" />'

   268 >>> w.render('greeting', None)

   269 u'<input type="checkbox" name="greeting" />'

   270 

   271 # Select Widget ###############################################################

   272 

   273 >>> w = Select()

   274 >>> print w.render('beatle', 'J', choices=(('J', 'John'), ('P', 'Paul'), ('G', 'George'), ('R', 'Ringo')))

   275 <select name="beatle">

   276 <option value="J" selected="selected">John</option>

   277 <option value="P">Paul</option>

   278 <option value="G">George</option>

   279 <option value="R">Ringo</option>

   280 </select>

   281 

   282 If the value is None, none of the options are selected:

   283 >>> print w.render('beatle', None, choices=(('J', 'John'), ('P', 'Paul'), ('G', 'George'), ('R', 'Ringo')))

   284 <select name="beatle">

   285 <option value="J">John</option>

   286 <option value="P">Paul</option>

   287 <option value="G">George</option>

   288 <option value="R">Ringo</option>

   289 </select>

   290 

   291 If the value corresponds to a label (but not to an option value), none of the options are selected:

   292 >>> print w.render('beatle', 'John', choices=(('J', 'John'), ('P', 'Paul'), ('G', 'George'), ('R', 'Ringo')))

   293 <select name="beatle">

   294 <option value="J">John</option>

   295 <option value="P">Paul</option>

   296 <option value="G">George</option>

   297 <option value="R">Ringo</option>

   298 </select>

   299 

   300 The value is compared to its str():

   301 >>> print w.render('num', 2, choices=[('1', '1'), ('2', '2'), ('3', '3')])

   302 <select name="num">

   303 <option value="1">1</option>

   304 <option value="2" selected="selected">2</option>

   305 <option value="3">3</option>

   306 </select>

   307 >>> print w.render('num', '2', choices=[(1, 1), (2, 2), (3, 3)])

   308 <select name="num">

   309 <option value="1">1</option>

   310 <option value="2" selected="selected">2</option>

   311 <option value="3">3</option>

   312 </select>

   313 >>> print w.render('num', 2, choices=[(1, 1), (2, 2), (3, 3)])

   314 <select name="num">

   315 <option value="1">1</option>

   316 <option value="2" selected="selected">2</option>

   317 <option value="3">3</option>

   318 </select>

   319 

   320 The 'choices' argument can be any iterable:

   321 >>> from itertools import chain

   322 >>> def get_choices():

   323 ...     for i in range(5):

   324 ...         yield (i, i)

   325 >>> print w.render('num', 2, choices=get_choices())

   326 <select name="num">

   327 <option value="0">0</option>

   328 <option value="1">1</option>

   329 <option value="2" selected="selected">2</option>

   330 <option value="3">3</option>

   331 <option value="4">4</option>

   332 </select>

   333 >>> things = ({'id': 1, 'name': 'And Boom'}, {'id': 2, 'name': 'One More Thing!'})

   334 >>> class SomeForm(Form):

   335 ...     somechoice = ChoiceField(choices=chain((('', '-'*9),), [(thing['id'], thing['name']) for thing in things]))

   336 >>> f = SomeForm()

   337 >>> f.as_table()

   338 u'<tr><th><label for="id_somechoice">Somechoice:</label></th><td><select name="somechoice" id="id_somechoice">\n<option value="" selected="selected">---------</option>\n<option value="1">And Boom</option>\n<option value="2">One More Thing!</option>\n</select></td></tr>'

   339 >>> f.as_table()

   340 u'<tr><th><label for="id_somechoice">Somechoice:</label></th><td><select name="somechoice" id="id_somechoice">\n<option value="" selected="selected">---------</option>\n<option value="1">And Boom</option>\n<option value="2">One More Thing!</option>\n</select></td></tr>'

   341 >>> f = SomeForm({'somechoice': 2})

   342 >>> f.as_table()

   343 u'<tr><th><label for="id_somechoice">Somechoice:</label></th><td><select name="somechoice" id="id_somechoice">\n<option value="">---------</option>\n<option value="1">And Boom</option>\n<option value="2" selected="selected">One More Thing!</option>\n</select></td></tr>'

   344 

   345 You can also pass 'choices' to the constructor:

   346 >>> w = Select(choices=[(1, 1), (2, 2), (3, 3)])

   347 >>> print w.render('num', 2)

   348 <select name="num">

   349 <option value="1">1</option>

   350 <option value="2" selected="selected">2</option>

   351 <option value="3">3</option>

   352 </select>

   353 

   354 If 'choices' is passed to both the constructor and render(), then they'll both be in the output:

   355 >>> print w.render('num', 2, choices=[(4, 4), (5, 5)])

   356 <select name="num">

   357 <option value="1">1</option>

   358 <option value="2" selected="selected">2</option>

   359 <option value="3">3</option>

   360 <option value="4">4</option>

   361 <option value="5">5</option>

   362 </select>

   363 

   364 >>> w.render('email', 'ŠĐĆŽćžšđ', choices=[('ŠĐĆŽćžšđ', 'ŠĐabcĆŽćžšđ'), ('ćžšđ', 'abcćžšđ')])

   365 u'<select name="email">\n<option value="1">1</option>\n<option value="2">2</option>\n<option value="3">3</option>\n<option value="\u0160\u0110\u0106\u017d\u0107\u017e\u0161\u0111" selected="selected">\u0160\u0110abc\u0106\u017d\u0107\u017e\u0161\u0111</option>\n<option value="\u0107\u017e\u0161\u0111">abc\u0107\u017e\u0161\u0111</option>\n</select>'

   366 

   367 If choices is passed to the constructor and is a generator, it can be iterated

   368 over multiple times without getting consumed:

   369 >>> w = Select(choices=get_choices())

   370 >>> print w.render('num', 2)

   371 <select name="num">

   372 <option value="0">0</option>

   373 <option value="1">1</option>

   374 <option value="2" selected="selected">2</option>

   375 <option value="3">3</option>

   376 <option value="4">4</option>

   377 </select>

   378 >>> print w.render('num', 3)

   379 <select name="num">

   380 <option value="0">0</option>

   381 <option value="1">1</option>

   382 <option value="2">2</option>

   383 <option value="3" selected="selected">3</option>

   384 <option value="4">4</option>

   385 </select>

   386 

   387 # NullBooleanSelect Widget ####################################################

   388 

   389 >>> w = NullBooleanSelect()

   390 >>> print w.render('is_cool', True)

   391 <select name="is_cool">

   392 <option value="1">Unknown</option>

   393 <option value="2" selected="selected">Yes</option>

   394 <option value="3">No</option>

   395 </select>

   396 >>> print w.render('is_cool', False)

   397 <select name="is_cool">

   398 <option value="1">Unknown</option>

   399 <option value="2">Yes</option>

   400 <option value="3" selected="selected">No</option>

   401 </select>

   402 >>> print w.render('is_cool', None)

   403 <select name="is_cool">

   404 <option value="1" selected="selected">Unknown</option>

   405 <option value="2">Yes</option>

   406 <option value="3">No</option>

   407 </select>

   408 >>> print w.render('is_cool', '2')

   409 <select name="is_cool">

   410 <option value="1">Unknown</option>

   411 <option value="2" selected="selected">Yes</option>

   412 <option value="3">No</option>

   413 </select>

   414 >>> print w.render('is_cool', '3')

   415 <select name="is_cool">

   416 <option value="1">Unknown</option>

   417 <option value="2">Yes</option>

   418 <option value="3" selected="selected">No</option>

   419 </select>

   420 

   421 # SelectMultiple Widget #######################################################

   422 

   423 >>> w = SelectMultiple()

   424 >>> print w.render('beatles', ['J'], choices=(('J', 'John'), ('P', 'Paul'), ('G', 'George'), ('R', 'Ringo')))

   425 <select multiple="multiple" name="beatles">

   426 <option value="J" selected="selected">John</option>

   427 <option value="P">Paul</option>

   428 <option value="G">George</option>

   429 <option value="R">Ringo</option>

   430 </select>

   431 >>> print w.render('beatles', ['J', 'P'], choices=(('J', 'John'), ('P', 'Paul'), ('G', 'George'), ('R', 'Ringo')))

   432 <select multiple="multiple" name="beatles">

   433 <option value="J" selected="selected">John</option>

   434 <option value="P" selected="selected">Paul</option>

   435 <option value="G">George</option>

   436 <option value="R">Ringo</option>

   437 </select>

   438 >>> print w.render('beatles', ['J', 'P', 'R'], choices=(('J', 'John'), ('P', 'Paul'), ('G', 'George'), ('R', 'Ringo')))

   439 <select multiple="multiple" name="beatles">

   440 <option value="J" selected="selected">John</option>

   441 <option value="P" selected="selected">Paul</option>

   442 <option value="G">George</option>

   443 <option value="R" selected="selected">Ringo</option>

   444 </select>

   445 

   446 If the value is None, none of the options are selected:

   447 >>> print w.render('beatles', None, choices=(('J', 'John'), ('P', 'Paul'), ('G', 'George'), ('R', 'Ringo')))

   448 <select multiple="multiple" name="beatles">

   449 <option value="J">John</option>

   450 <option value="P">Paul</option>

   451 <option value="G">George</option>

   452 <option value="R">Ringo</option>

   453 </select>

   454 

   455 If the value corresponds to a label (but not to an option value), none of the options are selected:

   456 >>> print w.render('beatles', ['John'], choices=(('J', 'John'), ('P', 'Paul'), ('G', 'George'), ('R', 'Ringo')))

   457 <select multiple="multiple" name="beatles">

   458 <option value="J">John</option>

   459 <option value="P">Paul</option>

   460 <option value="G">George</option>

   461 <option value="R">Ringo</option>

   462 </select>

   463 

   464 If multiple values are given, but some of them are not valid, the valid ones are selected:

   465 >>> print w.render('beatles', ['J', 'G', 'foo'], choices=(('J', 'John'), ('P', 'Paul'), ('G', 'George'), ('R', 'Ringo')))

   466 <select multiple="multiple" name="beatles">

   467 <option value="J" selected="selected">John</option>

   468 <option value="P">Paul</option>

   469 <option value="G" selected="selected">George</option>

   470 <option value="R">Ringo</option>

   471 </select>

   472 

   473 The value is compared to its str():

   474 >>> print w.render('nums', [2], choices=[('1', '1'), ('2', '2'), ('3', '3')])

   475 <select multiple="multiple" name="nums">

   476 <option value="1">1</option>

   477 <option value="2" selected="selected">2</option>

   478 <option value="3">3</option>

   479 </select>

   480 >>> print w.render('nums', ['2'], choices=[(1, 1), (2, 2), (3, 3)])

   481 <select multiple="multiple" name="nums">

   482 <option value="1">1</option>

   483 <option value="2" selected="selected">2</option>

   484 <option value="3">3</option>

   485 </select>

   486 >>> print w.render('nums', [2], choices=[(1, 1), (2, 2), (3, 3)])

   487 <select multiple="multiple" name="nums">

   488 <option value="1">1</option>

   489 <option value="2" selected="selected">2</option>

   490 <option value="3">3</option>

   491 </select>

   492 

   493 The 'choices' argument can be any iterable:

   494 >>> def get_choices():

   495 ...     for i in range(5):

   496 ...         yield (i, i)

   497 >>> print w.render('nums', [2], choices=get_choices())

   498 <select multiple="multiple" name="nums">

   499 <option value="0">0</option>

   500 <option value="1">1</option>

   501 <option value="2" selected="selected">2</option>

   502 <option value="3">3</option>

   503 <option value="4">4</option>

   504 </select>

   505 

   506 You can also pass 'choices' to the constructor:

   507 >>> w = SelectMultiple(choices=[(1, 1), (2, 2), (3, 3)])

   508 >>> print w.render('nums', [2])

   509 <select multiple="multiple" name="nums">

   510 <option value="1">1</option>

   511 <option value="2" selected="selected">2</option>

   512 <option value="3">3</option>

   513 </select>

   514 

   515 If 'choices' is passed to both the constructor and render(), then they'll both be in the output:

   516 >>> print w.render('nums', [2], choices=[(4, 4), (5, 5)])

   517 <select multiple="multiple" name="nums">

   518 <option value="1">1</option>

   519 <option value="2" selected="selected">2</option>

   520 <option value="3">3</option>

   521 <option value="4">4</option>

   522 <option value="5">5</option>

   523 </select>

   524 

   525 >>> w.render('nums', ['ŠĐĆŽćžšđ'], choices=[('ŠĐĆŽćžšđ', 'ŠĐabcĆŽćžšđ'), ('ćžšđ', 'abcćžšđ')])

   526 u'<select multiple="multiple" name="nums">\n<option value="1">1</option>\n<option value="2">2</option>\n<option value="3">3</option>\n<option value="\u0160\u0110\u0106\u017d\u0107\u017e\u0161\u0111" selected="selected">\u0160\u0110abc\u0106\u017d\u0107\u017e\u0161\u0111</option>\n<option value="\u0107\u017e\u0161\u0111">abc\u0107\u017e\u0161\u0111</option>\n</select>'

   527 

   528 # RadioSelect Widget ##########################################################

   529 

   530 >>> w = RadioSelect()

   531 >>> print w.render('beatle', 'J', choices=(('J', 'John'), ('P', 'Paul'), ('G', 'George'), ('R', 'Ringo')))

   532 <ul>

   533 <li><label><input checked="checked" type="radio" name="beatle" value="J" /> John</label></li>

   534 <li><label><input type="radio" name="beatle" value="P" /> Paul</label></li>

   535 <li><label><input type="radio" name="beatle" value="G" /> George</label></li>

   536 <li><label><input type="radio" name="beatle" value="R" /> Ringo</label></li>

   537 </ul>

   538 

   539 If the value is None, none of the options are checked:

   540 >>> print w.render('beatle', None, choices=(('J', 'John'), ('P', 'Paul'), ('G', 'George'), ('R', 'Ringo')))

   541 <ul>

   542 <li><label><input type="radio" name="beatle" value="J" /> John</label></li>

   543 <li><label><input type="radio" name="beatle" value="P" /> Paul</label></li>

   544 <li><label><input type="radio" name="beatle" value="G" /> George</label></li>

   545 <li><label><input type="radio" name="beatle" value="R" /> Ringo</label></li>

   546 </ul>

   547 

   548 If the value corresponds to a label (but not to an option value), none of the options are checked:

   549 >>> print w.render('beatle', 'John', choices=(('J', 'John'), ('P', 'Paul'), ('G', 'George'), ('R', 'Ringo')))

   550 <ul>

   551 <li><label><input type="radio" name="beatle" value="J" /> John</label></li>

   552 <li><label><input type="radio" name="beatle" value="P" /> Paul</label></li>

   553 <li><label><input type="radio" name="beatle" value="G" /> George</label></li>

   554 <li><label><input type="radio" name="beatle" value="R" /> Ringo</label></li>

   555 </ul>

   556 

   557 The value is compared to its str():

   558 >>> print w.render('num', 2, choices=[('1', '1'), ('2', '2'), ('3', '3')])

   559 <ul>

   560 <li><label><input type="radio" name="num" value="1" /> 1</label></li>

   561 <li><label><input checked="checked" type="radio" name="num" value="2" /> 2</label></li>

   562 <li><label><input type="radio" name="num" value="3" /> 3</label></li>

   563 </ul>

   564 >>> print w.render('num', '2', choices=[(1, 1), (2, 2), (3, 3)])

   565 <ul>

   566 <li><label><input type="radio" name="num" value="1" /> 1</label></li>

   567 <li><label><input checked="checked" type="radio" name="num" value="2" /> 2</label></li>

   568 <li><label><input type="radio" name="num" value="3" /> 3</label></li>

   569 </ul>

   570 >>> print w.render('num', 2, choices=[(1, 1), (2, 2), (3, 3)])

   571 <ul>

   572 <li><label><input type="radio" name="num" value="1" /> 1</label></li>

   573 <li><label><input checked="checked" type="radio" name="num" value="2" /> 2</label></li>

   574 <li><label><input type="radio" name="num" value="3" /> 3</label></li>

   575 </ul>

   576 

   577 The 'choices' argument can be any iterable:

   578 >>> def get_choices():

   579 ...     for i in range(5):

   580 ...         yield (i, i)

   581 >>> print w.render('num', 2, choices=get_choices())

   582 <ul>

   583 <li><label><input type="radio" name="num" value="0" /> 0</label></li>

   584 <li><label><input type="radio" name="num" value="1" /> 1</label></li>

   585 <li><label><input checked="checked" type="radio" name="num" value="2" /> 2</label></li>

   586 <li><label><input type="radio" name="num" value="3" /> 3</label></li>

   587 <li><label><input type="radio" name="num" value="4" /> 4</label></li>

   588 </ul>

   589 

   590 You can also pass 'choices' to the constructor:

   591 >>> w = RadioSelect(choices=[(1, 1), (2, 2), (3, 3)])

   592 >>> print w.render('num', 2)

   593 <ul>

   594 <li><label><input type="radio" name="num" value="1" /> 1</label></li>

   595 <li><label><input checked="checked" type="radio" name="num" value="2" /> 2</label></li>

   596 <li><label><input type="radio" name="num" value="3" /> 3</label></li>

   597 </ul>

   598 

   599 If 'choices' is passed to both the constructor and render(), then they'll both be in the output:

   600 >>> print w.render('num', 2, choices=[(4, 4), (5, 5)])

   601 <ul>

   602 <li><label><input type="radio" name="num" value="1" /> 1</label></li>

   603 <li><label><input checked="checked" type="radio" name="num" value="2" /> 2</label></li>

   604 <li><label><input type="radio" name="num" value="3" /> 3</label></li>

   605 <li><label><input type="radio" name="num" value="4" /> 4</label></li>

   606 <li><label><input type="radio" name="num" value="5" /> 5</label></li>

   607 </ul>

   608 

   609 The render() method returns a RadioFieldRenderer object, whose str() is a <ul>.

   610 You can manipulate that object directly to customize the way the RadioSelect

   611 is rendered.

   612 >>> w = RadioSelect()

   613 >>> r = w.render('beatle', 'J', choices=(('J', 'John'), ('P', 'Paul'), ('G', 'George'), ('R', 'Ringo')))

   614 >>> for inp in r:

   615 ...     print inp

   616 <label><input checked="checked" type="radio" name="beatle" value="J" /> John</label>

   617 <label><input type="radio" name="beatle" value="P" /> Paul</label>

   618 <label><input type="radio" name="beatle" value="G" /> George</label>

   619 <label><input type="radio" name="beatle" value="R" /> Ringo</label>

   620 >>> for inp in r:

   621 ...     print '%s<br />' % inp

   622 <label><input checked="checked" type="radio" name="beatle" value="J" /> John</label><br />

   623 <label><input type="radio" name="beatle" value="P" /> Paul</label><br />

   624 <label><input type="radio" name="beatle" value="G" /> George</label><br />

   625 <label><input type="radio" name="beatle" value="R" /> Ringo</label><br />

   626 >>> for inp in r:

   627 ...     print '<p>%s %s</p>' % (inp.tag(), inp.choice_label)

   628 <p><input checked="checked" type="radio" name="beatle" value="J" /> John</p>

   629 <p><input type="radio" name="beatle" value="P" /> Paul</p>

   630 <p><input type="radio" name="beatle" value="G" /> George</p>

   631 <p><input type="radio" name="beatle" value="R" /> Ringo</p>

   632 >>> for inp in r:

   633 ...     print '%s %s %s %s %s' % (inp.name, inp.value, inp.choice_value, inp.choice_label, inp.is_checked())

   634 beatle J J John True

   635 beatle J P Paul False

   636 beatle J G George False

   637 beatle J R Ringo False

   638 

   639 A RadioFieldRenderer object also allows index access to individual RadioInput

   640 objects.

   641 >>> w = RadioSelect()

   642 >>> r = w.render('beatle', 'J', choices=(('J', 'John'), ('P', 'Paul'), ('G', 'George'), ('R', 'Ringo')))

   643 >>> print r[1]

   644 <label><input type="radio" name="beatle" value="P" /> Paul</label>

   645 >>> print r[0]

   646 <label><input checked="checked" type="radio" name="beatle" value="J" /> John</label>

   647 >>> r[0].is_checked()

   648 True

   649 >>> r[1].is_checked()

   650 False

   651 >>> r[1].name, r[1].value, r[1].choice_value, r[1].choice_label

   652 ('beatle', u'J', u'P', u'Paul')

   653 >>> r[10]

   654 Traceback (most recent call last):

   655 ...

   656 IndexError: list index out of range

   657 

   658 >>> w = RadioSelect()

   659 >>> unicode(w.render('email', 'ŠĐĆŽćžšđ', choices=[('ŠĐĆŽćžšđ', 'ŠĐabcĆŽćžšđ'), ('ćžšđ', 'abcćžšđ')]))

   660 u'<ul>\n<li><label><input checked="checked" type="radio" name="email" value="\u0160\u0110\u0106\u017d\u0107\u017e\u0161\u0111" /> \u0160\u0110abc\u0106\u017d\u0107\u017e\u0161\u0111</label></li>\n<li><label><input type="radio" name="email" value="\u0107\u017e\u0161\u0111" /> abc\u0107\u017e\u0161\u0111</label></li>\n</ul>'

   661 

   662 # CheckboxSelectMultiple Widget ###############################################

   663 

   664 >>> w = CheckboxSelectMultiple()

   665 >>> print w.render('beatles', ['J'], choices=(('J', 'John'), ('P', 'Paul'), ('G', 'George'), ('R', 'Ringo')))

   666 <ul>

   667 <li><label><input checked="checked" type="checkbox" name="beatles" value="J" /> John</label></li>

   668 <li><label><input type="checkbox" name="beatles" value="P" /> Paul</label></li>

   669 <li><label><input type="checkbox" name="beatles" value="G" /> George</label></li>

   670 <li><label><input type="checkbox" name="beatles" value="R" /> Ringo</label></li>

   671 </ul>

   672 >>> print w.render('beatles', ['J', 'P'], choices=(('J', 'John'), ('P', 'Paul'), ('G', 'George'), ('R', 'Ringo')))

   673 <ul>

   674 <li><label><input checked="checked" type="checkbox" name="beatles" value="J" /> John</label></li>

   675 <li><label><input checked="checked" type="checkbox" name="beatles" value="P" /> Paul</label></li>

   676 <li><label><input type="checkbox" name="beatles" value="G" /> George</label></li>

   677 <li><label><input type="checkbox" name="beatles" value="R" /> Ringo</label></li>

   678 </ul>

   679 >>> print w.render('beatles', ['J', 'P', 'R'], choices=(('J', 'John'), ('P', 'Paul'), ('G', 'George'), ('R', 'Ringo')))

   680 <ul>

   681 <li><label><input checked="checked" type="checkbox" name="beatles" value="J" /> John</label></li>

   682 <li><label><input checked="checked" type="checkbox" name="beatles" value="P" /> Paul</label></li>

   683 <li><label><input type="checkbox" name="beatles" value="G" /> George</label></li>

   684 <li><label><input checked="checked" type="checkbox" name="beatles" value="R" /> Ringo</label></li>

   685 </ul>

   686 

   687 If the value is None, none of the options are selected:

   688 >>> print w.render('beatles', None, choices=(('J', 'John'), ('P', 'Paul'), ('G', 'George'), ('R', 'Ringo')))

   689 <ul>

   690 <li><label><input type="checkbox" name="beatles" value="J" /> John</label></li>

   691 <li><label><input type="checkbox" name="beatles" value="P" /> Paul</label></li>

   692 <li><label><input type="checkbox" name="beatles" value="G" /> George</label></li>

   693 <li><label><input type="checkbox" name="beatles" value="R" /> Ringo</label></li>

   694 </ul>

   695 

   696 If the value corresponds to a label (but not to an option value), none of the options are selected:

   697 >>> print w.render('beatles', ['John'], choices=(('J', 'John'), ('P', 'Paul'), ('G', 'George'), ('R', 'Ringo')))

   698 <ul>

   699 <li><label><input type="checkbox" name="beatles" value="J" /> John</label></li>

   700 <li><label><input type="checkbox" name="beatles" value="P" /> Paul</label></li>

   701 <li><label><input type="checkbox" name="beatles" value="G" /> George</label></li>

   702 <li><label><input type="checkbox" name="beatles" value="R" /> Ringo</label></li>

   703 </ul>

   704 

   705 If multiple values are given, but some of them are not valid, the valid ones are selected:

   706 >>> print w.render('beatles', ['J', 'G', 'foo'], choices=(('J', 'John'), ('P', 'Paul'), ('G', 'George'), ('R', 'Ringo')))

   707 <ul>

   708 <li><label><input checked="checked" type="checkbox" name="beatles" value="J" /> John</label></li>

   709 <li><label><input type="checkbox" name="beatles" value="P" /> Paul</label></li>

   710 <li><label><input checked="checked" type="checkbox" name="beatles" value="G" /> George</label></li>

   711 <li><label><input type="checkbox" name="beatles" value="R" /> Ringo</label></li>

   712 </ul>

   713 

   714 The value is compared to its str():

   715 >>> print w.render('nums', [2], choices=[('1', '1'), ('2', '2'), ('3', '3')])

   716 <ul>

   717 <li><label><input type="checkbox" name="nums" value="1" /> 1</label></li>

   718 <li><label><input checked="checked" type="checkbox" name="nums" value="2" /> 2</label></li>

   719 <li><label><input type="checkbox" name="nums" value="3" /> 3</label></li>

   720 </ul>

   721 >>> print w.render('nums', ['2'], choices=[(1, 1), (2, 2), (3, 3)])

   722 <ul>

   723 <li><label><input type="checkbox" name="nums" value="1" /> 1</label></li>

   724 <li><label><input checked="checked" type="checkbox" name="nums" value="2" /> 2</label></li>

   725 <li><label><input type="checkbox" name="nums" value="3" /> 3</label></li>

   726 </ul>

   727 >>> print w.render('nums', [2], choices=[(1, 1), (2, 2), (3, 3)])

   728 <ul>

   729 <li><label><input type="checkbox" name="nums" value="1" /> 1</label></li>

   730 <li><label><input checked="checked" type="checkbox" name="nums" value="2" /> 2</label></li>

   731 <li><label><input type="checkbox" name="nums" value="3" /> 3</label></li>

   732 </ul>

   733 

   734 The 'choices' argument can be any iterable:

   735 >>> def get_choices():

   736 ...     for i in range(5):

   737 ...         yield (i, i)

   738 >>> print w.render('nums', [2], choices=get_choices())

   739 <ul>

   740 <li><label><input type="checkbox" name="nums" value="0" /> 0</label></li>

   741 <li><label><input type="checkbox" name="nums" value="1" /> 1</label></li>

   742 <li><label><input checked="checked" type="checkbox" name="nums" value="2" /> 2</label></li>

   743 <li><label><input type="checkbox" name="nums" value="3" /> 3</label></li>

   744 <li><label><input type="checkbox" name="nums" value="4" /> 4</label></li>

   745 </ul>

   746 

   747 You can also pass 'choices' to the constructor:

   748 >>> w = CheckboxSelectMultiple(choices=[(1, 1), (2, 2), (3, 3)])

   749 >>> print w.render('nums', [2])

   750 <ul>

   751 <li><label><input type="checkbox" name="nums" value="1" /> 1</label></li>

   752 <li><label><input checked="checked" type="checkbox" name="nums" value="2" /> 2</label></li>

   753 <li><label><input type="checkbox" name="nums" value="3" /> 3</label></li>

   754 </ul>

   755 

   756 If 'choices' is passed to both the constructor and render(), then they'll both be in the output:

   757 >>> print w.render('nums', [2], choices=[(4, 4), (5, 5)])

   758 <ul>

   759 <li><label><input type="checkbox" name="nums" value="1" /> 1</label></li>

   760 <li><label><input checked="checked" type="checkbox" name="nums" value="2" /> 2</label></li>

   761 <li><label><input type="checkbox" name="nums" value="3" /> 3</label></li>

   762 <li><label><input type="checkbox" name="nums" value="4" /> 4</label></li>

   763 <li><label><input type="checkbox" name="nums" value="5" /> 5</label></li>

   764 </ul>

   765 

   766 >>> w.render('nums', ['ŠĐĆŽćžšđ'], choices=[('ŠĐĆŽćžšđ', 'ŠĐabcĆŽćžšđ'), ('ćžšđ', 'abcćžšđ')])

   767 u'<ul>\n<li><label><input type="checkbox" name="nums" value="1" /> 1</label></li>\n<li><label><input type="checkbox" name="nums" value="2" /> 2</label></li>\n<li><label><input type="checkbox" name="nums" value="3" /> 3</label></li>\n<li><label><input checked="checked" type="checkbox" name="nums" value="\u0160\u0110\u0106\u017d\u0107\u017e\u0161\u0111" /> \u0160\u0110abc\u0106\u017d\u0107\u017e\u0161\u0111</label></li>\n<li><label><input type="checkbox" name="nums" value="\u0107\u017e\u0161\u0111" /> abc\u0107\u017e\u0161\u0111</label></li>\n</ul>'

   768 

   769 # MultiWidget #################################################################

   770 

   771 >>> class MyMultiWidget(MultiWidget):

   772 ...     def decompress(self, value):

   773 ...         if value:

   774 ...             return value.split('__')

   775 ...         return ['', '']

   776 ...     def format_output(self, rendered_widgets):

   777 ...         return u'<br />'.join(rendered_widgets)

   778 >>> w = MyMultiWidget(widgets=(TextInput(attrs={'class': 'big'}), TextInput(attrs={'class': 'small'})))

   779 >>> w.render('name', ['john', 'lennon'])

   780 u'<input type="text" class="big" value="john" name="name_0" /><br /><input type="text" class="small" value="lennon" name="name_1" />'

   781 >>> w.render('name', 'john__lennon')

   782 u'<input type="text" class="big" value="john" name="name_0" /><br /><input type="text" class="small" value="lennon" name="name_1" />'

   783 

   784 # SplitDateTimeWidget #########################################################

   785 

   786 >>> w = SplitDateTimeWidget()

   787 >>> w.render('date', '')

   788 u'<input type="text" name="date_0" /><input type="text" name="date_1" />'

   789 >>> w.render('date', None)

   790 u'<input type="text" name="date_0" /><input type="text" name="date_1" />'

   791 >>> w.render('date', datetime.datetime(2006, 1, 10, 7, 30))

   792 u'<input type="text" name="date_0" value="2006-01-10" /><input type="text" name="date_1" value="07:30:00" />'

   793 >>> w.render('date', [datetime.date(2006, 1, 10), datetime.time(7, 30)])

   794 u'<input type="text" name="date_0" value="2006-01-10" /><input type="text" name="date_1" value="07:30:00" />'

   795 

   796 You can also pass 'attrs' to the constructor. In this case, the attrs will be

   797 included on both widgets.

   798 >>> w = SplitDateTimeWidget(attrs={'class': 'pretty'})

   799 >>> w.render('date', datetime.datetime(2006, 1, 10, 7, 30))

   800 u'<input type="text" class="pretty" value="2006-01-10" name="date_0" /><input type="text" class="pretty" value="07:30:00" name="date_1" />'

   801 

   802 ##########

   803 # Fields #

   804 ##########

   805 

   806 Each Field class does some sort of validation. Each Field has a clean() method,

   807 which either raises django.newforms.ValidationError or returns the "clean"

   808 data -- usually a Unicode object, but, in some rare cases, a list.

   809 

   810 Each Field's __init__() takes at least these parameters:

   811     required -- Boolean that specifies whether the field is required.

   812                 True by default.

   813     widget -- A Widget class, or instance of a Widget class, that should be

   814               used for this Field when displaying it. Each Field has a default

   815               Widget that it'll use if you don't specify this. In most cases,

   816               the default widget is TextInput.

   817     label -- A verbose name for this field, for use in displaying this field in

   818              a form. By default, Django will use a "pretty" version of the form

   819              field name, if the Field is part of a Form.

   820     initial -- A value to use in this Field's initial display. This value is

   821                *not* used as a fallback if data isn't given.

   822 

   823 Other than that, the Field subclasses have class-specific options for

   824 __init__(). For example, CharField has a max_length option.

   825 

   826 # CharField ###################################################################

   827 

   828 >>> f = CharField()

   829 >>> f.clean(1)

   830 u'1'

   831 >>> f.clean('hello')

   832 u'hello'

   833 >>> f.clean(None)

   834 Traceback (most recent call last):

   835 ...

   836 ValidationError: [u'This field is required.']

   837 >>> f.clean('')

   838 Traceback (most recent call last):

   839 ...

   840 ValidationError: [u'This field is required.']

   841 >>> f.clean([1, 2, 3])

   842 u'[1, 2, 3]'

   843 

   844 >>> f = CharField(required=False)

   845 >>> f.clean(1)

   846 u'1'

   847 >>> f.clean('hello')

   848 u'hello'

   849 >>> f.clean(None)

   850 u''

   851 >>> f.clean('')

   852 u''

   853 >>> f.clean([1, 2, 3])

   854 u'[1, 2, 3]'

   855 

   856 CharField accepts an optional max_length parameter:

   857 >>> f = CharField(max_length=10, required=False)

   858 >>> f.clean('12345')

   859 u'12345'

   860 >>> f.clean('1234567890')

   861 u'1234567890'

   862 >>> f.clean('1234567890a')

   863 Traceback (most recent call last):

   864 ...

   865 ValidationError: [u'Ensure this value has at most 10 characters.']

   866 

   867 CharField accepts an optional min_length parameter:

   868 >>> f = CharField(min_length=10, required=False)

   869 >>> f.clean('')

   870 u''

   871 >>> f.clean('12345')

   872 Traceback (most recent call last):

   873 ...

   874 ValidationError: [u'Ensure this value has at least 10 characters.']

   875 >>> f.clean('1234567890')

   876 u'1234567890'

   877 >>> f.clean('1234567890a')

   878 u'1234567890a'

   879 

   880 >>> f = CharField(min_length=10, required=True)

   881 >>> f.clean('')

   882 Traceback (most recent call last):

   883 ...

   884 ValidationError: [u'This field is required.']

   885 >>> f.clean('12345')

   886 Traceback (most recent call last):

   887 ...

   888 ValidationError: [u'Ensure this value has at least 10 characters.']

   889 >>> f.clean('1234567890')

   890 u'1234567890'

   891 >>> f.clean('1234567890a')

   892 u'1234567890a'

   893 

   894 # IntegerField ################################################################

   895 

   896 >>> f = IntegerField()

   897 >>> f.clean('')

   898 Traceback (most recent call last):

   899 ...

   900 ValidationError: [u'This field is required.']

   901 >>> f.clean(None)

   902 Traceback (most recent call last):

   903 ...

   904 ValidationError: [u'This field is required.']

   905 >>> f.clean('1')

   906 1

   907 >>> isinstance(f.clean('1'), int)

   908 True

   909 >>> f.clean('23')

   910 23

   911 >>> f.clean('a')

   912 Traceback (most recent call last):

   913 ...

   914 ValidationError: [u'Enter a whole number.']

   915 >>> f.clean('1 ')

   916 1

   917 >>> f.clean(' 1')

   918 1

   919 >>> f.clean(' 1 ')

   920 1

   921 >>> f.clean('1a')

   922 Traceback (most recent call last):

   923 ...

   924 ValidationError: [u'Enter a whole number.']

   925 

   926 >>> f = IntegerField(required=False)

   927 >>> f.clean('')

   928 >>> repr(f.clean(''))

   929 'None'

   930 >>> f.clean(None)

   931 >>> repr(f.clean(None))

   932 'None'

   933 >>> f.clean('1')

   934 1

   935 >>> isinstance(f.clean('1'), int)

   936 True

   937 >>> f.clean('23')

   938 23

   939 >>> f.clean('a')

   940 Traceback (most recent call last):

   941 ...

   942 ValidationError: [u'Enter a whole number.']

   943 >>> f.clean('1 ')

   944 1

   945 >>> f.clean(' 1')

   946 1

   947 >>> f.clean(' 1 ')

   948 1

   949 >>> f.clean('1a')

   950 Traceback (most recent call last):

   951 ...

   952 ValidationError: [u'Enter a whole number.']

   953 

   954 IntegerField accepts an optional max_value parameter:

   955 >>> f = IntegerField(max_value=10)

   956 >>> f.clean(None)

   957 Traceback (most recent call last):

   958 ...

   959 ValidationError: [u'This field is required.']

   960 >>> f.clean(1)

   961 1

   962 >>> f.clean(10)

   963 10

   964 >>> f.clean(11)

   965 Traceback (most recent call last):

   966 ...

   967 ValidationError: [u'Ensure this value is less than or equal to 10.']

   968 >>> f.clean('10')

   969 10

   970 >>> f.clean('11')

   971 Traceback (most recent call last):

   972 ...

   973 ValidationError: [u'Ensure this value is less than or equal to 10.']

   974 

   975 IntegerField accepts an optional min_value parameter:

   976 >>> f = IntegerField(min_value=10)

   977 >>> f.clean(None)

   978 Traceback (most recent call last):

   979 ...

   980 ValidationError: [u'This field is required.']

   981 >>> f.clean(1)

   982 Traceback (most recent call last):

   983 ...

   984 ValidationError: [u'Ensure this value is greater than or equal to 10.']

   985 >>> f.clean(10)

   986 10

   987 >>> f.clean(11)

   988 11

   989 >>> f.clean('10')

   990 10

   991 >>> f.clean('11')

   992 11

   993 

   994 min_value and max_value can be used together:

   995 >>> f = IntegerField(min_value=10, max_value=20)

   996 >>> f.clean(None)

   997 Traceback (most recent call last):

   998 ...

   999 ValidationError: [u'This field is required.']

  1000 >>> f.clean(1)

  1001 Traceback (most recent call last):

  1002 ...

  1003 ValidationError: [u'Ensure this value is greater than or equal to 10.']

  1004 >>> f.clean(10)

  1005 10

  1006 >>> f.clean(11)

  1007 11

  1008 >>> f.clean('10')

  1009 10

  1010 >>> f.clean('11')

  1011 11

  1012 >>> f.clean(20)

  1013 20

  1014 >>> f.clean(21)

  1015 Traceback (most recent call last):

  1016 ...

  1017 ValidationError: [u'Ensure this value is less than or equal to 20.']

  1018 

  1019 # DateField ###################################################################

  1020 

  1021 >>> import datetime

  1022 >>> f = DateField()

  1023 >>> f.clean(datetime.date(2006, 10, 25))

  1024 datetime.date(2006, 10, 25)

  1025 >>> f.clean(datetime.datetime(2006, 10, 25, 14, 30))

  1026 datetime.date(2006, 10, 25)

  1027 >>> f.clean(datetime.datetime(2006, 10, 25, 14, 30, 59))

  1028 datetime.date(2006, 10, 25)

  1029 >>> f.clean(datetime.datetime(2006, 10, 25, 14, 30, 59, 200))

  1030 datetime.date(2006, 10, 25)

  1031 >>> f.clean('2006-10-25')

  1032 datetime.date(2006, 10, 25)

  1033 >>> f.clean('10/25/2006')

  1034 datetime.date(2006, 10, 25)

  1035 >>> f.clean('10/25/06')

  1036 datetime.date(2006, 10, 25)

  1037 >>> f.clean('Oct 25 2006')

  1038 datetime.date(2006, 10, 25)

  1039 >>> f.clean('October 25 2006')

  1040 datetime.date(2006, 10, 25)

  1041 >>> f.clean('October 25, 2006')

  1042 datetime.date(2006, 10, 25)

  1043 >>> f.clean('25 October 2006')

  1044 datetime.date(2006, 10, 25)

  1045 >>> f.clean('25 October, 2006')

  1046 datetime.date(2006, 10, 25)

  1047 >>> f.clean('2006-4-31')

  1048 Traceback (most recent call last):

  1049 ...

  1050 ValidationError: [u'Enter a valid date.']

  1051 >>> f.clean('200a-10-25')

  1052 Traceback (most recent call last):

  1053 ...

  1054 ValidationError: [u'Enter a valid date.']

  1055 >>> f.clean('25/10/06')

  1056 Traceback (most recent call last):

  1057 ...

  1058 ValidationError: [u'Enter a valid date.']

  1059 >>> f.clean(None)

  1060 Traceback (most recent call last):

  1061 ...

  1062 ValidationError: [u'This field is required.']

  1063 

  1064 >>> f = DateField(required=False)

  1065 >>> f.clean(None)

  1066 >>> repr(f.clean(None))

  1067 'None'

  1068 >>> f.clean('')

  1069 >>> repr(f.clean(''))

  1070 'None'

  1071 

  1072 DateField accepts an optional input_formats parameter:

  1073 >>> f = DateField(input_formats=['%Y %m %d'])

  1074 >>> f.clean(datetime.date(2006, 10, 25))

  1075 datetime.date(2006, 10, 25)

  1076 >>> f.clean(datetime.datetime(2006, 10, 25, 14, 30))

  1077 datetime.date(2006, 10, 25)

  1078 >>> f.clean('2006 10 25')

  1079 datetime.date(2006, 10, 25)

  1080 

  1081 The input_formats parameter overrides all default input formats,

  1082 so the default formats won't work unless you specify them:

  1083 >>> f.clean('2006-10-25')

  1084 Traceback (most recent call last):

  1085 ...

  1086 ValidationError: [u'Enter a valid date.']

  1087 >>> f.clean('10/25/2006')

  1088 Traceback (most recent call last):

  1089 ...

  1090 ValidationError: [u'Enter a valid date.']

  1091 >>> f.clean('10/25/06')

  1092 Traceback (most recent call last):

  1093 ...

  1094 ValidationError: [u'Enter a valid date.']

  1095 

  1096 # TimeField ###################################################################

  1097 

  1098 >>> import datetime

  1099 >>> f = TimeField()

  1100 >>> f.clean(datetime.time(14, 25))

  1101 datetime.time(14, 25)

  1102 >>> f.clean(datetime.time(14, 25, 59))

  1103 datetime.time(14, 25, 59)

  1104 >>> f.clean('14:25')

  1105 datetime.time(14, 25)

  1106 >>> f.clean('14:25:59')

  1107 datetime.time(14, 25, 59)

  1108 >>> f.clean('hello')

  1109 Traceback (most recent call last):

  1110 ...

  1111 ValidationError: [u'Enter a valid time.']

  1112 >>> f.clean('1:24 p.m.')

  1113 Traceback (most recent call last):

  1114 ...

  1115 ValidationError: [u'Enter a valid time.']

  1116 

  1117 TimeField accepts an optional input_formats parameter:

  1118 >>> f = TimeField(input_formats=['%I:%M %p'])

  1119 >>> f.clean(datetime.time(14, 25))

  1120 datetime.time(14, 25)

  1121 >>> f.clean(datetime.time(14, 25, 59))

  1122 datetime.time(14, 25, 59)

  1123 >>> f.clean('4:25 AM')

  1124 datetime.time(4, 25)

  1125 >>> f.clean('4:25 PM')

  1126 datetime.time(16, 25)

  1127 

  1128 The input_formats parameter overrides all default input formats,

  1129 so the default formats won't work unless you specify them:

  1130 >>> f.clean('14:30:45')

  1131 Traceback (most recent call last):

  1132 ...

  1133 ValidationError: [u'Enter a valid time.']

  1134 

  1135 # DateTimeField ###############################################################