48 lines
1.7 KiB
Markdown
48 lines
1.7 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 an **alias** (for internal use) and the field's **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 a **default** value, value **options** (as `<select>` tags do), and may be declared **required** (i.e. non-optional).
|
|
|
|
A form definition in YAML format will consist of the field aliases as top-level keys, and the corresponding fields' definitions as key-value-pairs below them.
|
|
|
|
## Example
|
|
|
|
### Definition
|
|
```yaml
|
|
# definition.yaml
|
|
|
|
field1:
|
|
name: payload_param_1
|
|
field2:
|
|
name: payload_param_2
|
|
default: foo
|
|
choice_field:
|
|
name: payload_param_3
|
|
options:
|
|
value1: text for option 1
|
|
value2: text for option 2
|
|
default: value1
|
|
mandatory_field:
|
|
name: payload_param_0
|
|
required: true
|
|
```
|
|
|
|
### Usage
|
|
```
|
|
>>> from yamlhttpforms import load_form
|
|
>>> form_interface = load_form('definition.yaml')
|
|
>>> form_interface.get_payload(field1='abc', field2='bar', mandatory_field='420')
|
|
{'payload_param_1': 'abc', 'payload_param_2': 'bar', 'payload_param_3': 'value1', 'payload_param_0': '420'}
|
|
>>> form_interface.get_payload(field1='abc', choice_field='baz', mandatory_field='420')
|
|
Traceback (most recent call last):
|
|
...
|
|
ValueError: "baz" is not a valid option for <SelectField: name="payload_param_3", default="value1", options={'value1': 'text for option 1', 'value2': 'text for option 2'}>
|
|
```
|