How to clean up after ctrl-c?

[prjemian]

Users want to be able to interrupt any plan using the ctrl-c keyboard interrupt. After choosing one of the options that ends the run, the interrupt should call some code that will clean up and return the instrument to a known state.

The RunEngine provides support for ctrl-c interrupts from the user. Our challenge is when a lower-level plan is written that absorbs the ^C keyboard interrupts, such as:

try:
    yield from some_plan_a_user_might_interrupt_with_control_c()
except Exception:  # includes the ^C from the keyboard ...
    pass # ... and ignores the problem

We need general guidance to write effective try..except clauses in plans that preserve the RunEngine's handling of ctrl-c keyboard interrupts. And guidance about the clean-up plans.

Must consider cases when interrupting from

• a lower-level plan that implements some try..except handling
• a sequence of plans during a single call to RE
• a sequence of plans during a sequence of calls to RE

attn: @qzhang234, @sureshnaps, @jilavsky (who has a similar request)

[prjemian]

Should generalize for any APS beamline, per duplicate issue BCDA-APS/bluesky_training#22

[prjemian]

One common problem is when a plan uses the try..except..finally structure, it handles the KeyboardInterrupt with all other exceptions, such as:

8id-bits/src/id8_i/plans/nexus_acq_rigaku_zdt_fly.py

Lines 116 to 119 in 4a4c005

	except Exception as e:
	print(f"Error occurred during measurement: {e}")
	finally:
	pass

Another case occurs when the KeyboardInterrupt is handled but converted to a different exception that evades the RunEngine's handling of KeyboardInterrupt exceptions, such as:

8id-bits/src/id8_i/plans/master_plan.py

Lines 100 to 104 in 4a4c005

	except KeyboardInterrupt:
	raise RuntimeError("\n Bluesky plan stopped by user (Ctrl+C).")
	except Exception as e:
	print(f"Error occurred during measurement: {e}")
	finally:

[prjemian]

This code:

8id-bits/src/id8_i/plans/nexus_acq_rigaku_zdt_fly.py

Lines 116 to 119 in 4a4c005

	except Exception as e:
	print(f"Error occurred during measurement: {e}")
	finally:
	pass

might be rewritten as:

    except KeyboardInterrupt as e:
        raise KeyboardInterrupt("User interrupted measurement.") from e
    except Exception as e:
        print(f"Error occurred during measurement: {e}")
    finally:
        pass

KeyboardInterrupt Handling:

• The first except block catches a KeyboardInterrupt, which occurs when the user interrupts the program (usually by pressing Ctrl+C).
• The raise statement re-raises the KeyboardInterrupt with a custom message: "User interrupted measurement.".
• The from e syntax is used to maintain the context of the original exception, which is useful for debugging. It shows that the new exception is a direct result of the original one.

General Exception Handling:

• The second except block catches any other exceptions that may occur during the execution of the code in the try block.
  It prints an error message that includes the exception message, which helps in understanding what went wrong.

[prjemian]

Similarly, this code:

8id-bits/src/id8_i/plans/master_plan.py

Lines 100 to 105 in 4a4c005

	except KeyboardInterrupt:
	raise RuntimeError("\n Bluesky plan stopped by user (Ctrl+C).")
	except Exception as e:
	print(f"Error occurred during measurement: {e}")
	finally:
	pass

might be rewritten as:

    except KeyboardInterrupt as e:
        raise KeyboardInterrupt ("User interrupted plan with Ctrl+C") from e
    except Exception as e:
        print(f"Error occurred during measurement: {e}")
    finally:
        pass```

[prjemian]

Locating these two patterns and refactoring as shown should improve the ability of the RunEngine to handle Ctrl-C keyboard interrupts properly.

1. If the code handles Exception without first trying to handle KeyboardInterrupt, that should be changed as shown.
2. If the code handles KeyboardInterrupt but raises something else, that should be changed as shown.

[prjemian]

The RunEngine has its own special handling for KeyboardInterrupt exceptions.

At the core, any KeyboardInterrupt exceptions need to be handled first (or with higher priority than general exception handling) from any lower level plan (or stub) and passed along as KeyboardInterrupt using

    except KeyboardInterrupt as e:
        raise KeyboardInterrupt("some message") from e

Then, other exceptions can be handled with additional except ... clauses. This is how the RunEngine can receive the Ctrl-C from deep within a plan stack, yet handle it properly.

[prjemian]

After careful reading about the hierarchy of Python's various exception classes, this answer can be improved.