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.