daniil-berg/yamlhttpforms
1
0
Fork 0
Code Issues Pull Requests Projects Releases 1 Wiki Activity

updated readme

Browse Source
This commit is contained in:
Daniil Fajnberg 2022-01-05 15:07:25 +01:00
parent e6c5076e39
commit 8bd14228d7
1 changed files with 12 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
README.md
View File

@ -6,11 +6,11 @@ This module allows creating simple interfaces to forms/payloads for use in HTTP
A form is defined by its fields. 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. 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 a **default** value, value **options** (as `<select>` tags do), and may be declared **required** (i.e. non-optional). 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 aliases as top-level keys, and the corresponding fields' definitions as key-value-pairs below them. 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 ## Example
@ -18,19 +18,16 @@ A form definition in YAML format will consist of the field aliases as top-level
```yaml ```yaml
# definition.yaml # definition.yaml
field1: way_too_long_field_name:
name: payload_param_1 alias: short_name
field2: foo:
name: payload_param_2
default: foo
choice_field: choice_field:
name: payload_param_3
options: options:
value1: text for option 1 value1: text for option 1
value2: text for option 2 value2: text for option 2
default: value1 default: value1
mandatory_field: mandatory_field:
name: payload_param_0 alias: special
required: true required: true
``` ```
@ -38,10 +35,11 @@ mandatory_field:
``` ```
>>> from yamlhttpforms import load_form >>> from yamlhttpforms import load_form
>>> form_interface = load_form('definition.yaml') >>> form_interface = load_form('definition.yaml')
>>> form_interface.get_payload(field1='abc', field2='bar', mandatory_field='420') >>> form_interface.get_payload(short_name='abc', foo='bar', special='420')
{'payload_param_1': 'abc', 'payload_param_2': 'bar', 'payload_param_3': 'value1', 'payload_param_0': '420'} {'way_too_long_field_name': 'abc', 'foo': 'bar', 'choice_field': 'value1', 'mandatory_field': '420'}
>>> form_interface.get_payload(field1='abc', choice_field='baz', mandatory_field='420')
>>> form_interface.get_payload(short_name='abc', choice_field='baz', special='420')
Traceback (most recent call last): 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'}> 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'}>
``` ```