Mirakuru

Common errors

• mirakuru.exception.AlreadyRunning: Port 1234 is already in use.

  cause This error occurs when a `TCPExecutor` or `HTTPExecutor` attempts to start a process, but the specified `host` and `port` are already in use by another process on the system.
  fix Ensure that the port is free before starting the `mirakuru` executor, or configure your process to use a different available port. You can check port availability using tools like `lsof -i :PORT` (Linux/macOS) or `netstat -ano | findstr :PORT` (Windows).

• TimeoutError: Process did not become ready in X seconds.

  cause This error indicates that the process started by `mirakuru` did not meet its readiness criteria (e.g., producing a specific output, opening a TCP port, or responding to an HTTP request) within the allotted timeout period.
  fix Increase the `timeout` parameter when initializing the `Executor` (e.g., `executor = OutputExecutor('my_command', timeout=60)`), or investigate why your subprocess is taking longer to start or become ready. Ensure the readiness check parameters (e.g., `banner` for `OutputExecutor`, `port` for `TCPExecutor`, `url` for `HTTPExecutor`) are correctly configured.

• FileNotFoundError: [Errno 2] No such file or directory: 'non_existent_command'

  cause This error occurs when `mirakuru` tries to execute the command string or list you provided, but the executable specified in the `command` argument cannot be found in the system's PATH or at the specified absolute/relative path.
  fix Verify that the command string points to a valid executable, including its full path if it's not in the system's PATH. For example, if 'my_server' is in your current directory, use `'./my_server'` or the absolute path.

• OSError: [Errno 13] Permission denied: './my_script.sh'

  cause This error occurs when `mirakuru` attempts to execute a command, but the user running the Python script does not have sufficient permissions to execute the specified file or script.
  fix Ensure that the executable file or script passed to `mirakuru.Executor` has execute permissions for the user running the Python script. On Linux/macOS, you can grant execute permissions using `chmod +x ./my_script.sh`.

Warnings

• breaking Mirakuru 3.x requires Python >=3.10. Older Python versions (e.g., Python 2.x, 3.6-3.9) are not supported. Users migrating from older Mirakuru versions or older Python environments will need to upgrade their Python interpreter.
  Fix: Upgrade Python to version 3.10 or higher.
• gotcha Always ensure processes started by Mirakuru are properly stopped to prevent orphaned processes. This is best achieved by using executors as context managers (`with TCPExecutor(...) as executor:`) or by explicitly calling the `.stop()` method in a `finally` block.
  Fix: Employ context managers (`with`) or ensure `.stop()` is called in a `try...finally` block.
• gotcha When using `TCPExecutor` or `HTTPExecutor`, an `AlreadyRunning` exception will be raised if the target port is already in use by another process before Mirakuru attempts to start its own. This indicates a conflict or a lingering process.
  Fix: Ensure the target port is free before starting the executor, or handle the `AlreadyRunning` exception appropriately (e.g., by checking if the existing process is the intended one).
• gotcha Handling subprocesses, especially when `shell=True` is used, requires careful attention to ensure all child processes are terminated. While Mirakuru includes mechanisms for cleanup, complex shell commands or external processes that spawn their own children might require additional manual cleanup or OS-level process management.
  Fix: Prefer passing commands as a list of arguments rather than a single string with `shell=True` where possible. Verify process tree termination in integration tests for complex scenarios.

Install

• pip install mirakuru Install latest version

Imports

• TCPExecutor

  from mirakuru import TCPExecutor

• HTTPExecutor

  from mirakuru import HTTPExecutor

• OutputExecutor

  from mirakuru import OutputExecutor

• Executor
  wrong:

  from mirakuru import StartCheckExecutor

  correct:

  from mirakuru import Executor

  The `StartCheckExecutor` class was renamed to `Executor` in version 0.5.0. New code should use `Executor` as the base class for executors that verify process startup.
• SimpleExecutor
  wrong:

  from mirakuru import Executor

  correct:

  from mirakuru import SimpleExecutor

  The original `Executor` class, which only started/stopped a process without waiting for readiness, was renamed to `SimpleExecutor` in version 0.5.0.

Quickstart

This quickstart demonstrates how to use `TCPExecutor` to ensure a local HTTP server (simulated here with Python's built-in `http.server`) is ready to accept connections on a specific port before proceeding. It also shows proper cleanup. Mirakuru's executors can also be used as context managers for automatic startup and shutdown.

import subprocess
import time
from mirakuru import TCPExecutor

# This simulates a simple HTTP server. In a real scenario, this would be your external service.
server_process = None
try:
    # Start a simple Python HTTP server in the background
    server_process = subprocess.Popen(['python', '-m', 'http.server', '8000'], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
    
    # Use TCPExecutor to wait for the server to be ready on port 8000
    http_executor = TCPExecutor('echo server_started', host='localhost', port=8000)
    
    print("Waiting for HTTP server to start...")
    http_executor.start()
    print("HTTP server is ready on port 8000.")
    
    # Your application or test code that interacts with the server would go here.
    # For demonstration, we'll just wait a bit.
    time.sleep(2)
    
    print("Stopping HTTP server.")
    http_executor.stop()
    print("HTTP server stopped.")
finally:
    if server_process:
        server_process.terminate()
        server_process.wait()