Running YAML Based Applications

The pyoxy run-yaml command enables you to run a Python interpreter given a configuration defined in a YAML file.

Usage

Run pyoxy help run-yaml to see full documentation.

The high-level operation is:

pyoxy run-yaml [FILE] [-- <args>...]

You give the command the path to a YAML file to parse and optional additional arguments following a --. e.g.:

pyoxy run-yaml myapp.yaml
pyoxy run-yaml myapp.yaml -- --arg true

File Parsing

We use a customized mechanism for parsing the specified content for a YAML config. The rules are as follows:

  • The file MUST be UTF-8. (YAML allows encodings other than UTF-8. We do not yet support alternative encodings, such as UTF-16.)

  • The content of the file up to a line beginning with --- is ignored.

  • Parsing stops when a line beginning with ... is encountered.

  • All content between the initial line beginning with --- and either a) the first line beginning with ... or b) the end of the file is parsed as YAML.

YAML Configuration

The YAML document attempts to deserialize to a pyembed::OxidizedPythonInterpreterConfig Rust struct. This type and its fields are extensively documented at OxidizedPythonInterpreterConfig Struct.

Some of the most important fields in the configuration data structure define what to run when the interpreter starts. e.g.

---
interpreter_config:
  run_command: 'print("hello, world")'
...

---
interpreter_config:
  run_module: 'mypackage.__main__'
...

Portable Invocation Using a Shell Shebang

On UNIX-like platforms, files containing an embedded YAML config can be made to execute with pyoxy run-yaml by using a specially crafted shebang (leading #! line) and making the file executable.

For example, say you distribute the pyoxy binary in the same directory as your executable myapp file. Here’s what myapp would look like:

#!/bin/sh
"exec" "`dirname $0`/pyoxy" run-yaml "$0" -- "$@"
---
# YAML configuration.
...

This file defines a shell script which simply calls exec to invoke pyoxy run-yaml, giving it the path to the current file and additional arguments passed to the original invocation. Because our custom YAML parsing ignores content up to the first line beginning with ---, the shebang and shell script content is ignored and the file evaluates as if those initial lines did not exist.