Docstring.

notes/todo.md

@@ -40,7 +40,7 @@
   - [x] run log
 - [x] improve and clean up `State` enum
 
-- [ ] scheduled stop
+- [x] scheduled stop
   - [x] add stop method to program
   - [x] actually stop the program at the stop time
   - [x] go through _stopping_ state
@@ -53,8 +53,6 @@
   - [x] add stop time to run view
   - [x] docs
   - [x] refactor `apsis.stop` module
-  - [ ] update `_process_updates` to set the state for a stopping job
-    - clarify the rules for `run_state` updates
 - [ ] if `send_signal` raises, error the run
 
 - [ ] improve `apsis job` output style

python/apsis/apsis.py

@@ -597,6 +597,16 @@ async def rerun(self, run, *, time=None):
 
 
     async def stop_run(self, run):
+        """
+        Transitions `run` to stopping, and requests its program to stop in a
+        new task.
+
+        The `run` must be either running, or else stopping in which case
+        this is a no-op.
+
+        Adds `{"stopping": True}` to the run's run state when it transitions to
+        stopping.
+        """
         if run.state == State.stopping:
             log.info(f"run already stopping: {run.run_id}")
             return