46 lines
1.6 KiB
Markdown
46 lines
1.6 KiB
Markdown
# HTTP forms defined in YAML
|
|
|
|
This module allows creating simple interfaces to forms/payloads for use in HTTP POST requests by defining them in highly readable and easily maintainable YAML files.
|
|
|
|
## Form definition
|
|
|
|
A form is defined by its fields.
|
|
|
|
A field is defined by its _name_, which is the parameter name in the payload sent during a `POST` request, and which typically corresponds to the `name` attribute of a `<select>` or `<input>` HTML tag.
|
|
|
|
Optionally, a field can have an _alias_ (for internal use), a _default_ value, value _options_ (as `<select>` tags do), and may be declared _required_.
|
|
|
|
A form definition in YAML format will consist of the field names as top-level keys, and either nothing/`null` or the corresponding fields' definitions as key-value-pairs below them.
|
|
|
|
## Example
|
|
|
|
### Definition
|
|
```yaml
|
|
# definition.yaml
|
|
|
|
way_too_long_field_name:
|
|
alias: short_name
|
|
foo:
|
|
choice_field:
|
|
options:
|
|
value1: text for option 1
|
|
value2: text for option 2
|
|
default: value1
|
|
mandatory_field:
|
|
alias: special
|
|
required: true
|
|
```
|
|
|
|
### Usage
|
|
```
|
|
>>> from yamlhttpforms import load_form
|
|
>>> form_interface = load_form('definition.yaml')
|
|
>>> form_interface.get_payload(short_name='abc', foo='bar', special='420')
|
|
{'way_too_long_field_name': 'abc', 'foo': 'bar', 'choice_field': 'value1', 'mandatory_field': '420'}
|
|
|
|
>>> form_interface.get_payload(short_name='abc', choice_field='baz', special='420')
|
|
Traceback (most recent call last):
|
|
...
|
|
ValueError: "baz" is not a valid option for <SelectField: name="choice_field", default="value1", options={'value1': 'text for option 1', 'value2': 'text for option 2'}>
|
|
```
|