Metadata-Version: 2.1
Name: pydantic-yaml-parser
Version: 0.0.4
Summary: parse yaml files with pydantic
Home-page: https://github.com/hamelsmu/pydantic-yaml-parser
Author: Hamel Husain
Author-email: hamel.husain@gmail.com
License: Apache Software License 2.0
Keywords: pydantic yaml
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: License :: OSI Approved :: Apache Software License
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Provides-Extra: dev
License-File: LICENSE

# pydantic-yaml-parser

<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

<div>

[![](https://github.com/hamelsmu/pydantic-yaml-parser/actions/workflows/test.yaml/badge.svg)](https://github.com/hamelsmu/pydantic-yaml-parser/actions/workflows/test.yaml)

</div>

## Install

``` sh
pip install pydantic_yaml_parser
```

## Background & Usage

### 1. Loading YAML into Pydantic models

To load YAML into a Pydantic model, you have to first convert the YAML
string to a dict. For example, given the below yaml file:

``` python
yaml_string="""
setting_1: Hello
setting_2:
    - kind: name
      sublist:
          - first
          - second
"""
```

You might define a Pydantic model to represent it like this:

``` python
from pydantic import BaseModel
from typing import List

class Setting2(BaseModel):
    kind: str
    sublist: List

class Test(BaseModel):
    setting_1: str
    setting_2: List[Setting2]
```

You can load the yaml file into a dict, and into the Pydantic model like
so using [pyyaml](https://pyyaml.org/wiki/PyYAMLDocumentation):

``` python
import yaml
yml_dict = yaml.safe_load(yaml_string)

# use `parse_obj` to load a dict
Test.parse_obj(yml_dict)
```

    Test(setting_1='Hello', setting_2=[Setting2(kind='name', sublist=['first', 'second'])])

### 2. The Pydantic validation error message

However, let’s say there is an error in your yaml file such that you
accidentally set `sublist` to `false`, instead of setting `sublist` to
`list` type, you will get an error message that looks like this:

``` python
yaml_string="""
setting_1: ok
setting_2:
    - kind: name
      sublist: false
"""
yaml_dict_error = yaml.safe_load(yaml_string)
```

``` python
Test.parse_obj(yaml_dict_error)
```

    ValidationError: 1 validation error for Test
    setting_2 -> 0 -> sublist
      value is not a valid list (type=type_error.list)

This error message is a bit confusing, especially for those with no
prior experience with pydantic!

### 3. Human readable error messages with `pydantic_yaml_parser`

When you use `pydantic_yaml_parser` you get an error message that is
much clearer:

``` python
from pydantic_yaml_parser.yaml import YamlModel

class Test(YamlModel):
    setting_1: str
    setting_2: List[Setting2]
```

``` python
Test.from_dict(yaml_dict_error)
```

    ValueError: Configuration error(s) for YAML:
     - value is not a valid list: `sublist` for element 0 in the list for `setting_2`

## Further Reading

For more examples of error validation see [these
docs](00_yaml.ipynb#error-validation).


