yamlhttpforms/README.md

# 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'}>
```