Hello Example

How To Examples
1

Overview

This example illustrates basic Guild configuration.

Project files:
guild.yml Project Guild file
say.py Prints a greeting
cat.py Prints contents of a file
hello.txt Sample file used by hello-file operation

Operations

hello

The hello operation prints a message defined by a msg global. It illustrates Guild’s integration with global variables.

hello as defined in guild.yml as follows:

The main attribute indicates that the operation is implemented by the Python say module.

Here’s say.py:

Guild auto-detects that say uses global variables rather than command line arguments. Guild checks for the use of argparse by the module. If the module doesn’t import argparse, Guild assumes that flags are defined as global variables.

NOTE
To set this explicitly, use flags-dest: globals operation attribute. For example:

hello:
  ...
  flags-dest: globals
  flags-import:
    - msg

The flags-import attribute tells Guild to import only the msg flag. An alternative is to import all flags by specifying either all or yes:

hello:
  ...
  flags-import: all  # will detect `msg` as the only supported flag

Run hello with default flag values:

guild run hello

You are about to run hello
  msg: Hello Guild!
Continue? (Y/n)

The operation prints the following output:

Hello Guild!

Run with a different flag value:

guild run hello msg="Hello custom flag!"

You are about to run hello
  msg: Hello custom flag!
Continue? (Y/n)

The operation prints:

Hello custom flag!

View information for the latest run using guild runs info. This shows the run metadata including flags.

guild runs info

List files associated with the latest run using guild ls. This list is empty because the operation doesn’t generate files.

guild ls

To view run output use cat with the --output option:

guild cat --output

Hello custom flag!

To view output for the original run:

$ guild cat --output 2

The value 2 indicates that the run with index 2 from guild runs should be used. You can alternatively specify the run ID to ensure you’re viewing output for a particular run.

hello-file

The hello-file operation prints a message from a file. It illustrates the use of a user-defined file as input to an operation.

Here’s the definition of hello-file:

The operation is implemented in cat.py.

The file flag is used to specify the file used as input to the operation. The file is a dependency and must be configured in the requires operation attribute.

From the example directory, run:

guild run hello-file

You can specify the file to use:

guild run hello-file file=hello.txt

The file requirement is named file to improve the message printed when resolving the resource.

For example:

Resolving file dependency
Using hello.txt for file resource
Reading message from hello.txt
Hello, from a file!

hello-op

The hello-op operation shows how the result from an operation can be used by another operation.

By convention Guild refers to the required operation as upstream and the requiring operation as downstream.

hello-op requires output from hello-file. In this case, hello-file is the upstream operation and hello-op is the downstream operation.

Here’s the definition of hello-op:

When you run hello-op, Guild looks for a hello-file run. Guild creates links from hello-file in the run directory for the hello-op run.

To use a standard file name for input, the operation renames the upstream file to hello.txt. (This scheme assumes that hello-file contains a single file. If the run happens has more than one file, the first file, sorted in lexicographic ascending order, is renamed and subsequent files are skipped with a warning message.)

By default, Guild selects the latest non-error run for hello-file. You can specify an alternative run using the hello-file resource name:

guild run hello-op hello-file=<run ID>