yaml

Load YAML strings into Pydantic models with nicer validation errors

yaml_string ="""
quartodoc:
  style: pkgdown
  dir: api
  package: quartodoc
  sidebar: "api/_sidebar.yml"
  sections:
    - title: Preperation Functions
      desc: |
        These functions fetch and analyze python objects, including parsing docstrings.
        They prepare a basic representation of your doc site that can be rendered and built.
      contents:
        - Auto
        - blueprint
        - collect
        - get_object
        - preview
"""

---

source

QuartoDoc

 QuartoDoc (style:str, dir:str, package:str, sidebar:str,
            sections:List[__main__.Section])

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

---

source

YamlModel

 YamlModel ()

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

---

source

Section

 Section (title:str, desc:str, contents:List[str])

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

QuartoDoc has a from_dict method so that you can load a dict that corresponds to a yaml file into a Pydantic data model:

yaml_dict = yaml2d(yaml_string)['quartodoc']
QuartoDoc.from_dict(yaml_dict)

QuartoDoc(style='pkgdown', dir='api', package='quartodoc', sidebar='api/_sidebar.yml', sections=[Section(title='Preperation Functions', desc='These functions fetch and analyze python objects, including parsing docstrings.\nThey prepare a basic representation of your doc site that can be rendered and built.\n', contents=['Auto', 'blueprint', 'collect', 'get_object', 'preview'])])

Error Validation

Missing Section

In the below yaml, there are two things missing:

• The contents field is missing from sections.
• The root of the quartodoc config is missing a dir field.

invalid_section = """
quartodoc:
  style: pkgdown
  package: quartodoc
  sidebar: "api/_sidebar.yml"
  sections:
    - title: Preperation Functions
      desc: |
        These functions fetch and analyze python objects, including parsing docstrings.
        They prepare a basic representation of your doc site that can be rendered and built.
"""

yaml_dict = yaml2d(invalid_section)['quartodoc']

If we try to load the yaml in invalid_section we get the following error message:

QuartoDoc.from_dict(yaml_dict)

ValueError: Configuration error(s) for YAML:
 - Missing field from root level: `dir`
 - Missing field `contents` for element 0 in the list for `sections`

Invalid Type

In the below yaml we will erroneously set the contents field to false, when it is supposed to be a list:

yaml_string ="""
quartodoc:
  style: pkgdown
  dir: api
  package: quartodoc
  sidebar: "api/_sidebar.yml"
  sections:
    - title: Preperation Functions
      desc: |
        These functions fetch and analyze python objects, including parsing docstrings.
        They prepare a basic representation of your doc site that can be rendered and built.
      contents: false
"""

yaml_dict = yaml2d(yaml_string)['quartodoc']

We get the following human readable error message:

yml = QuartoDoc.from_dict(yaml_dict)

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

In the below yaml we errenously set dir to a list when it should be a str:

yaml_string ="""
quartodoc:
  style: pkgdown
  dir:
      - folder1
      - folder2
  package: quartodoc
  sidebar: "api/_sidebar.yml"
  sections:
    - title: Preperation Functions
      desc: |
        These functions fetch and analyze python objects, including parsing docstrings.
        They prepare a basic representation of your doc site that can be rendered and built.
      contents:
          - item 1
          - item 2
"""

yaml_dict = yaml2d(yaml_string)['quartodoc']

yml = QuartoDoc.from_dict(yaml_dict)

ValueError: Configuration error(s) for YAML:
 - str type expected: from root level: `dir`