[wip] add example for submit and wait

auto_examples/example_job_submit_wait.ipynb

@@ -0,0 +1,126 @@
+{
+  "cells": [
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "%matplotlib inline"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "\n# Introductory example - Job Submit and Wait\n\nTo programatically create and check the status for a group\nof jobs using the flux.job.FluxExecutor.\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "import os\nimport concurrent.futures\nfrom flux.job import JobspecV1\nfrom flux.job import JobspecV1, FluxExecutor"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Instead of directly creating a flux handle by importing flux and doing flux.Flux(),\nthis time we are going to use the flux.job.FluxExecutor. This will allow us to submit\njobs and then asynchronously wait for them to finish. As we did before, let's start\nwith a jobspec for a sleep job. We are fairly certain this will run with a return\ncode of 0 to indicate success.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "jobspec = JobspecV1.from_command(\n    command=[\"sleep\", \"1\"], num_tasks=2, num_nodes=1, cores_per_task=1\n)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Let's again set the working directory and current environment.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "jobspec.cwd = os.getcwd()\njobspec.environment = dict(os.environ)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "To mix things up a bit, let's run a command that we know will fail. The false\ncommand always returns a value of 1. This is a \"bad\" jobspec that will fail!\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "bad_jobspec = JobspecV1.from_command([\"/bin/false\"])"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Now we will demonstrate using the FluxExecutor (via a context) to submit both good\nand bad jobs, and wait for them to finish. We call a job that is marked as completed\na \"future\" and can inspect error code and exceptions to see details about the results!\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "# create an executor to submit jobs\nwith FluxExecutor() as executor:\n\n    # we will capture and keep each job future\n    futures = []\n\n    # submit half successful jobs\n    for _ in range(5):\n        futures.append(executor.submit(jobspec))\n        print(f\"submit: {id(futures[-1])} (good) jobspec\")\n\n    # and half failure jobs!\n    for _ in range(5):\n        futures.append(executor.submit(bad_jobspec))\n        print(f\"submit: {id(futures[-1])} (bad) jobspec\")\n\n    # We can now check on our job futures\n    for future in concurrent.futures.as_completed(futures):\n\n        # There was an exception!\n        if future.exception() is not None:\n            print(f\"\u26a0\ufe0f wait: {id(future)} Error: job raised error {future.exception()}\")\n\n        # Successful result, return code is zero\n        elif future.result() == 0:\n            print(f\"\ud83c\udfc6\ufe0f wait: {id(future)} Success\")\n\n        # Some other result\n        else:\n            print(f\"\u274c\ufe0f wait: {id(future)} Error: job returned exit code {future.result()}\")"
+      ]
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "codemirror_mode": {
+        "name": "ipython",
+        "version": 3
+      },
+      "file_extension": ".py",
+      "mimetype": "text/x-python",
+      "name": "python",
+      "nbconvert_exporter": "python",
+      "pygments_lexer": "ipython3",
+      "version": "3.8.10"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}

auto_examples/example_job_submit_wait.py

@@ -0,0 +1,72 @@
+# -*- coding: utf-8 -*-
+"""
+Introductory example - Job Submit and Wait
+==========================================
+
+To programatically create and check the status for a group
+of jobs using the flux.job.FluxExecutor.
+"""
+
+
+import os
+import concurrent.futures
+from flux.job import JobspecV1
+from flux.job import JobspecV1, FluxExecutor
+
+
+#%%
+# Instead of directly creating a flux handle by importing flux and doing flux.Flux(),
+# this time we are going to use the flux.job.FluxExecutor. This will allow us to submit
+# jobs and then asynchronously wait for them to finish. As we did before, let's start
+# with a jobspec for a sleep job. We are fairly certain this will run with a return
+# code of 0 to indicate success.
+
+jobspec = JobspecV1.from_command(
+    command=["sleep", "1"], num_tasks=2, num_nodes=1, cores_per_task=1
+)
+
+#%%
+# Let's again set the working directory and current environment.
+jobspec.cwd = os.getcwd()
+jobspec.environment = dict(os.environ)
+
+#%%
+# To mix things up a bit, let's run a command that we know will fail. The false
+# command always returns a value of 1. This is a "bad" jobspec that will fail!
+bad_jobspec = JobspecV1.from_command(["/bin/false"])
+
+#%%
+# Now we will demonstrate using the FluxExecutor (via a context) to submit both good
+# and bad jobs, and wait for them to finish. We call a job that is marked as completed
+# a "future" and can inspect error code and exceptions to see details about the results!
+
+# create an executor to submit jobs
+with FluxExecutor() as executor:
+
+    # we will capture and keep each job future
+    futures = []
+
+    # submit half successful jobs
+    for _ in range(5):
+        futures.append(executor.submit(jobspec))
+        print(f"submit: {id(futures[-1])} (good) jobspec")
+
+    # and half failure jobs!
+    for _ in range(5):
+        futures.append(executor.submit(bad_jobspec))
+        print(f"submit: {id(futures[-1])} (bad) jobspec")
+
+    # We can now check on our job futures
+    for future in concurrent.futures.as_completed(futures):
+
+        # There was an exception!
+        if future.exception() is not None:
+            print(f"⚠️ wait: {id(future)} Error: job raised error {future.exception()}")
+
+        # Successful result, return code is zero
+        elif future.result() == 0:
+            print(f"🏆️ wait: {id(future)} Success")
+
+        # Some other result
+        else:
+            print(f"❌️ wait: {id(future)} Error: job returned exit code {future.result()}")

auto_examples/example_job_submit_wait.py.md5

@@ -0,0 +1 @@
+a34c7c5d594deb1a871f9b331d920cd3