Package: pyaml-processor
Python YAMLLibrary for adding Python code in YAML processinghttps://github.com/gwww/pyamlExperimental- This library exists to try out ideas that enhance
and make simpler the management and creation of YAML files. In particular,
large YAML files, often seen when using Home Assistant Lovelace front-end.RequirementsPython 3.6 (or higher)DescriptionUsage documentation is below. More examples beyond what is here is in theexampledirectory or in the unit tests intest/test_pyaml.py.This lib is distinguished from other templating languages in that
indentation, crucial in YAML, is preserved oninclude,eval, andexecThis uses python'sevalandexecfunctions. Google about security concerns
around the use of those. Since this software is not accessing "unaudited" code the
security risk of usingevalandexecis viewed as low. Never accept/use
Python code without inspecting the code.Installation$pipinstallpyaml-processorOverviewpyamlreads a YAML file and runs the tagged code inside the YAML file. It
supports three processing tags:evalto run code,execto load code, andincludeto include other files in the context of the current file. All three
processors are aware of YAML indenting requirements.Evalevalis triggered in a YAML file using the tags@%to open anevaland%@to close aneval. Anything in between the two tags is passed to the Pythonevalfunction for processing. Whatever is returned from theevalis inserted into
the YAML stream. The starting character position of the opening tag is used as
the indent level prepended to everything returned.For the examples in this section assume that the following Python code
is in the moduleresources.pyand that file contains the following:from random import randrange

_PATH = "/local/cards/"

def resources(module, module_type):
    version = f"?v={randrange(1000000)}"
    # This works to, the lib can handle lists, dicts, etc as return values:
    # return [{'url': f"{_PATH}/{module}{version}", "type": module_type}]
    return f"url: {_PATH}/{module}{version}\ntype: {module_type}"Example 1:@+ from resources import resources +@
resources:
  - @% resources("layout-card", "module") %@
  - @% resources("card-mod", "module") %@Processing withpyamlresults in:resources:
  - url: /local/cards//layout-card?v=238120
    type: module
  - url: /local/cards//card-mod?v=885753
    type: moduleNotice that the indentation is preserved from the position on the line where
theevalwas invoked.Note that the space around the start and end tags is optional.Execexecis triggered in a YAML file using the tags@%to open anevaland%@to close anexec. Anything in between the two tags is passed to the Pythonexecfunction for processing. Whatever is returned from theexecis NOT inserted into
the YAML stream. The code inside theexectags isdedented meaning
common leading whitespace on each line is removed.Example 2:@+
def markdown_card(label):
    return \
f"""type: markdown
style: |
  ha-card {{background: purple}}
content: |
  ## {label}"""
+@

title: My awesome Lovelace config
views:
  - title: Home
    cards:
      - @%markdown_card("Kitchen")%@
      - @%markdown_card("Living room")%@Processing withpyamlresults in:title: My awesome Lovelace config
views:
  - title: Home
    cards:
      - type: markdown
        style: |
          ha-card {background: purple}
        content: |
          ## Kitchen
      - type: markdown
        style: |
          ha-card {background: purple}
        content: |
          ## Living roomNote: any type of Python code may exist between the tags, however,
it is likely more maintainable to put code, such the code in the
example above, into it's own Python module.IncludeIncludes the contents of the file into the YAML stream. The included file
may containevalandexecblocks. Include is trigged using the same
open and closing tag of@@.The advantage of usingpyamlinclude over the include processing from PyYAML
is thatpyamlpreserves indentation.For example ifexample3_include.yamlcontains:- zoo: tiger
- moo: cowAnd the following YAML file:big_pets:
  @@include some_file.yaml@@Processing withpyamlresults in:big_pets:
  - zoo: tiger
  - moo: cowRunningThere are two programs available to try out the library. In theexampledirectory there is a Python script calledsimple. This takes
a file name as a single parameter and writes the converted output to
standard out. The input file is a YAML file. While in theexampledirectory you could, for instance, type./simple example1.yamlto see the output of the first example in this README.The second program is calledpyamlis in the bin directory.
It's a slightly more featured. Run it with--helpfor additional details.DevelopmentThis project usespoetryfor development dependencies. Installation instructions are on their website.To get started developing:git clone https://github.com/gwww/pyaml.git
cd pyaml
poetry install
poetry shell # Or activate the created virtual environment
pytest # to ensure everything installed properlyThere is aMakefilein the root directory as well. Themakecommand
followed by one of the targets in theMakefilecan be used. If you don't
have or wish to usemaketheMakefileserves as examples of common
commands that can be run.