Metadata-Version: 2.1
Name: yamlhttpforms
Version: 0.1.2
Summary: HTTP forms defined in YAML
Home-page: https://git.fajnberg.de/daniil/yamlhttpforms
Author: Daniil F.
Author-email: mail@placeholder123.to
License: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: PyYAML
Provides-Extra: aio
Requires-Dist: aiohttp ; extra == 'aio'
Requires-Dist: webutils-df @ git+https://git.fajnberg.de/daniil/webutils-df.git ; extra == 'aio'
Provides-Extra: html
Requires-Dist: beautifulsoup4 ; extra == 'html'
Provides-Extra: req
Requires-Dist: requests ; extra == 'req'
Provides-Extra: tests
Requires-Dist: coverage ; extra == 'tests'

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


