diff options
Diffstat (limited to 'src/mailman/rest/docs/helpers.rst')
| -rw-r--r-- | src/mailman/rest/docs/helpers.rst | 64 |
1 files changed, 35 insertions, 29 deletions
diff --git a/src/mailman/rest/docs/helpers.rst b/src/mailman/rest/docs/helpers.rst index 0acbb5f45..5bcf5cad4 100644 --- a/src/mailman/rest/docs/helpers.rst +++ b/src/mailman/rest/docs/helpers.rst @@ -62,19 +62,19 @@ dictionary after tagging, since that's almost always what you want. neil : drums -POST unpacking -============== +POST and PUT unpacking +====================== -Another helper unpacks ``POST`` request variables, validating and converting -their values. +Another helper unpacks ``POST`` and ``PUT`` request variables, validating and +converting their values. :: >>> from mailman.rest.validator import Validator >>> validator = Validator(one=int, two=unicode, three=bool) >>> class FakeRequest: - ... POST = {} - >>> FakeRequest.POST = dict(one='1', two='two', three='yes') + ... params = None + >>> FakeRequest.params = dict(one='1', two='two', three='yes') On valid input, the validator can be used as a ``**keyword`` argument. @@ -85,7 +85,7 @@ On valid input, the validator can be used as a ``**keyword`` argument. On invalid input, an exception is raised. - >>> FakeRequest.POST['one'] = 'hello' + >>> FakeRequest.params['one'] = 'hello' >>> print_request(**validator(FakeRequest)) Traceback (most recent call last): ... @@ -93,7 +93,7 @@ On invalid input, an exception is raised. On missing input, an exception is raised. - >>> del FakeRequest.POST['one'] + >>> del FakeRequest.params['one'] >>> print_request(**validator(FakeRequest)) Traceback (most recent call last): ... @@ -101,7 +101,7 @@ On missing input, an exception is raised. If more than one key is missing, it will be reflected in the error message. - >>> del FakeRequest.POST['two'] + >>> del FakeRequest.params['two'] >>> print_request(**validator(FakeRequest)) Traceback (most recent call last): ... @@ -109,8 +109,8 @@ If more than one key is missing, it will be reflected in the error message. Extra keys are also not allowed. - >>> FakeRequest.POST = dict(one='1', two='two', three='yes', - ... four='', five='') + >>> FakeRequest.params = dict(one='1', two='two', three='yes', + ... four='', five='') >>> print_request(**validator(FakeRequest)) Traceback (most recent call last): ... @@ -123,25 +123,25 @@ However, if optional keys are missing, it's okay. ... four=int, five=int, ... _optional=('four', 'five')) - >>> FakeRequest.POST = dict(one='1', two='two', three='yes', - ... four='4', five='5') + >>> FakeRequest.params = dict(one='1', two='two', three='yes', + ... four='4', five='5') >>> def print_request(one, two, three, four=None, five=None): ... print(repr(one), repr(two), repr(three), repr(four), repr(five)) >>> print_request(**validator(FakeRequest)) 1 u'two' True 4 5 - >>> del FakeRequest.POST['four'] + >>> del FakeRequest.params['four'] >>> print_request(**validator(FakeRequest)) 1 u'two' True None 5 - >>> del FakeRequest.POST['five'] + >>> del FakeRequest.params['five'] >>> print_request(**validator(FakeRequest)) 1 u'two' True None None But if the optional values are present, they must of course also be valid. - >>> FakeRequest.POST = dict(one='1', two='two', three='yes', - ... four='no', five='maybe') + >>> FakeRequest.params = dict(one='1', two='two', three='yes', + ... four='no', five='maybe') >>> print_request(**validator(FakeRequest)) Traceback (most recent call last): ... @@ -157,12 +157,17 @@ such form data. Specifically, when a key shows up multiple times in the form data, a list is given to the validator. :: - # Of course we can't use a normal dictionary, but webob has a useful data - # type we can use. - >>> from webob.multidict import MultiDict - >>> form_data = MultiDict(one='1', many='3') - >>> form_data.add('many', '4') - >>> form_data.add('many', '5') + # We can't use a normal dictionary because we'll have multiple keys, but + # the validator only wants to call .items() on the object. + >>> class MultiDict: + ... def __init__(self, *params): self.values = list(params) + ... def items(self): return iter(self.values) + >>> form_data = MultiDict( + ... ('one', '1'), + ... ('many', '3'), + ... ('many', '4'), + ... ('many', '5'), + ... ) This is a validation function that ensures the value is a list. @@ -181,7 +186,7 @@ This is a validation function that ensure the value is *not* a list. And a validator to pull it all together. >>> validator = Validator(one=must_be_scalar, many=must_be_list) - >>> FakeRequest.POST = form_data + >>> FakeRequest.params = form_data >>> values = validator(FakeRequest) >>> print(values['one']) 1 @@ -191,11 +196,12 @@ And a validator to pull it all together. The list values are guaranteed to be in the same order they show up in the form data. - >>> from webob.multidict import MultiDict - >>> form_data = MultiDict(one='1', many='3') - >>> form_data.add('many', '5') - >>> form_data.add('many', '4') - >>> FakeRequest.POST = form_data + >>> FakeRequest.params = MultiDict( + ... ('one', '1'), + ... ('many', '3'), + ... ('many', '5'), + ... ('many', '4'), + ... ) >>> values = validator(FakeRequest) >>> print(values['one']) 1 |