yamlhttpforms/README.md

46 lines
1.6 KiB
Markdown
Raw Normal View History

2021-12-18 21:09:40 +01:00
# 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.
2022-01-05 15:07:25 +01:00
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.
2022-01-05 15:07:25 +01:00
Optionally, a field can have an _alias_ (for internal use), a _default_ value, value _options_ (as `<select>` tags do), and may be declared _required_.
2022-01-05 15:07:25 +01:00
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
2022-01-05 15:07:25 +01:00
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:
2022-01-05 15:07:25 +01:00
alias: special
required: true
```
### Usage
```
>>> from yamlhttpforms import load_form
>>> form_interface = load_form('definition.yaml')
2022-01-05 15:07:25 +01:00
>>> 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):
...
2022-01-05 15:07:25 +01:00
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'}>
```