Simpervisor: Simple Async Process Supervisor

Warnings

• breaking The `loop` argument was removed from the `SupervisedProcess` constructor and its methods (`start`, `ready`, `terminate`, `kill`) in version 1.0.0. If you were explicitly passing an `asyncio` event loop, this code will break.
  Fix: Remove the `loop=...` argument from `SupervisedProcess` instantiation and method calls. `simpervisor` now automatically uses `asyncio.get_running_loop()`.
• gotcha Running `SupervisedProcess` on Windows has historically encountered issues, particularly related to process termination and signal handling. While some fixes have been introduced, full cross-platform compatibility for all subprocess scenarios (especially complex ones) may not be guaranteed.
  Fix: Thoroughly test `simpervisor` usage on Windows for your specific child processes. Consider alternative process management solutions for critical Windows deployments if issues persist.
• gotcha As `simpervisor` relies on `asyncio`, blocking the event loop within your async application (e.g., by calling synchronous I/O operations without `run_in_executor`) can prevent the supervisor from properly monitoring and managing child processes, leading to unresponsive behavior.
  Fix: Ensure all potentially blocking operations in your `asyncio` application are properly awaited or offloaded to a thread pool using `loop.run_in_executor()`.

Install

• pip install simpervisor Install with pip

Imports

• SupervisedProcess

  from simpervisor import SupervisedProcess

Quickstart

This example demonstrates how to use `SupervisedProcess` to start an asynchronous Python script as a child process, monitor its status with `ready()`, and gracefully terminate it using `terminate()`. The child process simulates some work before exiting or being cancelled. The `sys.executable` is used to ensure the same Python interpreter runs the child script.

import asyncio
import sys
import os
from simpervisor import SupervisedProcess

# Create a dummy script to supervise
dummy_script_content = """
import asyncio
import sys
import time

async def child_process_task():
    print(f"Child process {os.getpid()} started.")
    try:
        for i in range(5):
            print(f"Child process {os.getpid()}: Working... {i+1}/5")
            await asyncio.sleep(1)
        print(f"Child process {os.getpid()}: Done working, exiting.")
    except asyncio.CancelledError:
        print(f"Child process {os.getpid()}: Cancelled, cleaning up.")
    except Exception as e:
        print(f"Child process {os.getpid()}: Error - {e}")
    finally:
        print(f"Child process {os.getpid()} exiting gracefully.")

if __name__ == '__main__':
    asyncio.run(child_process_task())
"""

async def main():
    script_path = "./dummy_child_script.py"
    with open(script_path, "w") as f:
        f.write(dummy_script_content)

    print("Starting supervisor example...")

    # Supervise the dummy script using python as the executable
    # This assumes 'python' is in your PATH
    process = SupervisedProcess(
        [sys.executable, script_path], # Command to run the child process
        always_restart=False # For this example, don't restart automatically
    )

    await process.start()
    print(f"Supervisor: Process started with PID {process.pid}")

    await asyncio.sleep(2) # Give child some time to work

    if await process.ready():
        print("Supervisor: Child process reports ready (or has started).")
    else:
        print("Supervisor: Child process not yet ready.")

    await asyncio.sleep(3)

    print("Supervisor: Attempting to terminate child process...")
    await process.terminate()
    # await process.wait() # Can wait for termination if needed

    if not process.running:
        print("Supervisor: Child process terminated.")
    else:
        print("Supervisor: Child process is still running after terminate attempt.")

    os.remove(script_path)
    print("Supervisor: Example finished.")

if __name__ == '__main__':
    asyncio.run(main())