Running YAML Based Applications¶
pyoxy run-yaml command enables you to run a Python interpreter given
a configuration defined in a YAML file.
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
pyoxy run-yaml myapp.yaml pyoxy run-yaml myapp.yaml -- --arg true
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
Parsing stops when a line beginning with
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.
The YAML document attempts to deserialize to a
Rust struct. This type and its fields are extensively documented at
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
#! 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.