Gear Building Tutorial Part 4: The Run Script

Introduction

In this part, we will cover how to create a basic run file for our example gear. The run file is the file that will contain our run script.  This is essentially the "main" section of our code. This file can be used to call other files and processes, but it must contain all commands necessary to complete execution of the gear.

Instruction Steps

• Step 1. Identify the Purpose of the Gear
• Step 2. Create your Run File
• Step 3. Running the script locally

Step 1. Identify the Purpose of the Gear

The first step in building any gear is to identify exactly what the gear is going to do, what input(s) it requires, and what output file(s) it should generate.  For this example gear, we are going to create a simple test script.  

A typical test program is one that simply says "Hello, World!".  Only, "Hello, World!" is a little too simple. To give us some experience with inputs and configuration settings, we'll have it say "Hello, !", and print the message a number of times as determined by a config setting. We will also have it print out "Hello, !" the desired number of times to an output text file.

Finally, to add one more level of complexity, we will create a custom message in a text file and have the gear print that message after all the Hellos.  Let's consider these inputs and outputs in the context of a gear:

Input values passed to the function:

1. Your name
2. The number of times to say hello
3. A message.txt file

As a bit of a preview of the next part in this tutorial series, there are two ways we can pass these inputs to our gear: as gear config parameters or as gear inputs. Since "your name" and the "number of times to say hello" are simple key-value pairs (e.g., "your name" is the value we want to pass to a variable inside our function), we will consider these as gear config parameters. Our message file is an actual file, however, so it is considered a gear input in Flywheel.

Output generated by function:

1. Text print of Hellos and contents of message file
2. A hello.txt file

Let's get started by creating a run file in our Gear-Building-Tutorial directory. 

Step 2. Create Your Run File

We'll start with a simple python script that takes a name and echos "Hello !" a specified number of times to both the terminal and an output text file called hello.txt:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

#!/usr/bin/env python
# The Shebang tells the computer what interpreter/executable to use when running the file. 

# Specify config options
# The name we want to say hello to
my_name = "Lisa Simpson" 
# The number of times to say hello
num_rep = 3 

# While the num_rep variable is greater than zero
while (num_rep > 0):
  # Open the file hello.txt with the intent to append
  with open('hello.txt', 'a') as f:
    # Write "Hello, <my_name>! to the file every loop
    f.write("Hello, {}!\n".format(my_name))

  # Print "Hello, <my_name>!" to the terminal every loop
  print("Hello, {}!".format(my_name))

  # Decrease the num_rep variable by one
  num_rep -= 1

That takes care of the "Hello" message portion of our run script. 

Now we need to add the following lines to read in and print our custom message. First, write the following code to read in a file and print the message:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# Specify /path/to/message.txt file
# Since we are creating our message.txt file inside our Gear-Building-Tutorial 
# directory, we can just specify the path as the name of the file.
custom_message = "message.txt"

# Now read the custom message:
# Open the file with the intent to read
message_file = open(custom_message,'r') 
# Print a blank line to separate the message from the "hello's"
print('\n')                               
# Read and print the file
print(message_file.read())                

Save this file as run.py in your Gear-Building-Tutorial directory.

Next, let's create the custom message our script will print out:

1. Create a file called message.txt
2. Write any simple text message in it
3. Save this file to your Gear-Building-Tutorial directory

If you want to follow along exactly with this tutorial, the custom message we are using is included below.

1
2
3
4
5

This is a special message saved in the "message.txt" file.
Anyone can change this message by changing the "message.txt" file.
Oh, I see it's your birthday.  Happy birthday! 
It's probably not your birthday...
But that's going to freak someone out :)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

#!/usr/bin/env python
# The Shebang tells the computer what interpreter/executable to use when running the file.

# Specify config options
# The name we want to say hello to
my_name = "Lisa Simpson" 
# The number of times to say hello
num_rep = 3 

# Specify /path/to/message.txt file
# Since we are creating our message.txt file inside our Gear-Building-Tutorial 
# directory, we can just specify the path as the name of the file.
custom_message = "message.txt"

# While the num_rep variable is greater than zero
while (num_rep > 0):
  # Open the file hello.txt with the intent to append
  with open('hello.txt', 'a') as f:
    # Write "Hello, <my_name>! to the file every loop
    f.write("Hello, {}!\n".format(my_name))

  # Print "Hello, <my_name>!" to the terminal every loop
  print("Hello, {}!".format(my_name))

  # Decrease the num_rep variable by one
  num_rep -= 1

# Now read the custom message:
# Open the file with the intent to read
message_file = open(custom_message,'r') 
# Print a blank line to separate the message from the "hello's"
print('\n')                               
# Read and print the file
print(message_file.read())

Step 3. Running the script locally

Now we should be able to run this script.  In a terminal window, navigate to the gear directory, and enter:  python run.py

We should see the following output:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

Hello, Lisa Simpson!
Hello, Lisa Simpson!
Hello, Lisa Simpson!


This is a special message saved in the "message.txt" file.
Anyone can change this message by changing the "message.txt" file.
Oh, I see it's your birthday.  Happy birthday! 
It's probably not your birthday...
But that's going to freak someone out :)

We should also see a new text file, hello.txt, saved in our gear directory.

Wrapping up with creating our run file

At this point, we have a working run script.  However, if we make this our gear, we'll have no way of changing our name, the number of times to say hello, or the custom message file.  To make this program more flexible and run for various inputs and settings, we need to make some modifications. We want to change this script so that the user can input ANY name, set the script to repeat ANY number of times, and have it read ANY .txt file as the custom message.  Making these modifications will require some knowledge about the manifest file.

We'll work these modifications in as we go through Part 5 The Manifest.

Navigation

Previous: Part 3 The Flywheel Environment

Next: Part 5 The Manifest