Merge pull request #4 from jannekem/utilities

Add utility functions

.gitignore

@@ -1 +1,3 @@
 node_modules/
+venv/
+__pycache__

README.md

@@ -71,3 +71,105 @@ jobs:
           SCRIPT_STDOUT: ${{ steps.script.outputs.stdout }}
           SCRIPT_STDERR: ${{ steps.script.outputs.stderr }} 
 ```
+
+## Utility functions
+
+The action comes bundled with utilities that you can use to interact with the workflow. If you want to disable these utilities you can set `util: false` as an input for the step. You can call these functions directly from your `script` without having to import anything.
+
+Example:
+
+```yaml
+- uses: jannekem/run-python-script-action@v1
+  with:
+    script: |
+      add_path("/usr/local/test")
+      set_env("HELLO", "WORLD")
+      group("Messages")
+      print("Sending a message")
+      warning("There might be an issue")
+      end_group()
+```
+
+### Add path
+
+**Signature**: `add_path(path)`
+
+Prepend to the system path. The change will affect later steps only.
+
+### Get input
+
+**Signature**: `get_input(name)`
+
+Returns the value of the given input as a string.
+
+### Set output
+
+**Signature**: `set_output(name, value)`
+
+Sets an output parameter.
+
+### Set env
+
+**Signature**: `set_env(name, value)`
+
+Sets an environment variable for use in later steps.
+
+### Debug
+
+**Signature**: `debug(message)`
+
+Sends a debug message. The message will be visible only when [debug logging has been enabled](https://docs.github.com/en/actions/managing-workflow-runs/enabling-debug-logging).
+
+### Warning
+
+**Signature**: `warning(message)`
+
+Sends a warning message that will be highlighted with yellow color in the worklow log.
+
+### Error
+
+**Signature**: `error(message)`
+
+Sends an error message that will be higlighted with red color in the workflow log.
+
+### Group
+
+**Signature**: `group(title)`
+
+Creates an expandable group in the workflow log.
+
+### End group
+
+**Signature**: `end_group()`
+
+Ends a group. All printed lines before calling `end_group()` belong to the previously defined group.
+
+### Add mask
+
+**Signature**: `add_mask(value)`
+
+Masks out sensitive data and replaces it with `***`. The value can be a string ("my sensitive data"), or it can point to an environment variable ("$DB_PASSWORD").
+
+### Stop commands
+
+**Signature**: `stop_commands()`
+
+All commands will stop processing. It allows you to log anything without accidentally triggering workflow commands.
+
+### Resume commands
+
+**Signature**: `resume_commands()`
+
+Resume command processing.
+
+### Get state
+
+**Signature**: `get_state(name)`
+
+Share environment variables with your workflow's `pre:` and `post:` actions. See [official documentation](https://docs.github.com/en/actions/reference/workflow-commands-for-github-actions#sending-values-to-the-pre-and-post-actions) for more details.
+
+### Save state
+
+**Signature**: `save_state(name, value)`
+
+Saves a value as an environment variable with the `STATE_` prefix. See [official documentation](https://docs.github.com/en/actions/reference/workflow-commands-for-github-actions#sending-values-to-the-pre-and-post-actions) for more details.

action.yml

@@ -8,6 +8,10 @@ inputs:
     description: "Fail step if the return code from running the script is non-zero"
     required: false
     default: true
+  util:
+    description: "Include utility functions"
+    required: false
+    default: true
 outputs:
   stdout:
     description: "Program stdout"

dist/util.py

@@ -0,0 +1,63 @@
+import os
+
+
+def add_path(path):
+    with open(os.getenv("GITHUB_PATH"), "a") as github_path:
+        print(path, file=github_path)
+
+
+def get_input(name):
+    return os.getenv(f"INPUT_{name}".upper())
+
+
+def set_output(name, value):
+    print(f"::set-output name={name}::{_escape_data(value)}")
+
+
+def set_env(name, value):
+    with open(os.getenv("GITHUB_ENV"), "a") as env:
+        print(f"{name}={_escape_data(value)}", file=env)
+
+
+def debug(message):
+    print(f"::debug::{_escape_data(message)}")
+
+
+def warning(message):
+    print(f"::warning::{_escape_data(message)}")
+
+
+def error(message):
+    print(f"::error::{_escape_data(message)}")
+
+
+def group(title):
+    print(f"::group::{title}")
+
+
+def end_group():
+    print(f"::endgroup::")
+
+
+def add_mask(value):
+    print(f"::add-mask::{_escape_data(value)}")
+
+
+def stop_commands():
+    print(f"::stop-commands::pause-commands")
+
+
+def resume_commands():
+    print(f"::pause-commands::")
+
+
+def get_state(name):
+    return os.getenv(f"STATE_{name}")
+
+
+def save_state(name, value):
+    print(f"::save-state name={name}::{_escape_data(value)}")
+
+
+def _escape_data(value: str):
+    return value.replace("%", "%25").replace("\r", "%0D").replace("\n", "%0A")

index.js

@@ -3,9 +3,12 @@ const exec = require('@actions/exec');
 const fs = require('fs');
 const tmp = require('tmp');
 
+
 async function run() {
     const script = core.getInput("script");
+    const util = core.getInput("util") === "true";
     const failOnError = core.getInput("fail-on-error") === "true";
+    const utilityFunctions = fs.readFileSync(`${__dirname}/util.py`);
 
     let stdout = "";
     let stderr = "";
@@ -22,7 +25,7 @@ async function run() {
 
     tmp.setGracefulCleanup();
     const filename = tmp.tmpNameSync({postfix: '.py'});
-    fs.writeFileSync(filename, script);
+    fs.writeFileSync(filename, util ? utilityFunctions + script : script);
     try {
         await exec.exec('python', [filename], options);
     } catch (error) {