pause

pause

Pause and modify commands for Marianne CLI.

This module implements the mzt pause and mzt modify commands for gracefully pausing running jobs and updating their configuration.

★ Insight ───────────────────────────────────── 1. Signal-based pause mechanism: Rather than interrupting execution directly, Marianne uses a file-based signal (.marianne-pause-{job_id}). The runner polls for this file at sheet boundaries, enabling clean checkpoints without data loss.

1. Atomic state transitions: The pause command only works on RUNNING jobs, and modify can handle RUNNING, PAUSED, or FAILED states. This state machine prevents race conditions and invalid state transitions.

2. Modify as composition: The modify command is essentially pause + resume composed together with config validation in between. This pattern keeps the individual commands focused while providing a convenient compound operation. ─────────────────────────────────────────────────

Classes

Functions

pause

pause(job_id=Argument(..., help='Score ID to pause'), wait=Option(False, '--wait', help='Wait for score to acknowledge pause signal'), timeout=Option(60, '--timeout', '-t', help='Timeout in seconds when using --wait'), json_output=Option(False, '--json', '-j', help='Output result as JSON'), force=Option(False, '--force', '-f', help='Force-cancel the score immediately (does not wait for sheet boundary)'))

Pause a running Marianne score gracefully.

Creates a pause signal that the job will detect at the next sheet boundary. The job saves its state and can be resumed with mzt resume.

Use --force to cancel the job immediately without waiting for a sheet boundary (equivalent to mzt cancel).

Examples:

mzt pause my-job mzt pause my-job --wait --timeout 30 mzt pause my-job --json mzt pause my-job --force

Source code in src/marianne/cli/commands/pause.py

def pause(
    job_id: str = typer.Argument(..., help="Score ID to pause"),
    wait: bool = typer.Option(
        False,
        "--wait",
        help="Wait for score to acknowledge pause signal",
    ),
    timeout: int = typer.Option(
        60,
        "--timeout",
        "-t",
        help="Timeout in seconds when using --wait",
    ),
    json_output: bool = typer.Option(
        False,
        "--json",
        "-j",
        help="Output result as JSON",
    ),
    force: bool = typer.Option(
        False,
        "--force",
        "-f",
        help="Force-cancel the score immediately (does not wait for sheet boundary)",
    ),
) -> None:
    """Pause a running Marianne score gracefully.

    Creates a pause signal that the job will detect at the next sheet boundary.
    The job saves its state and can be resumed with `mzt resume`.

    Use --force to cancel the job immediately without waiting for a sheet
    boundary (equivalent to `mzt cancel`).

    Examples:
        mzt pause my-job
        mzt pause my-job --wait --timeout 30
        mzt pause my-job --json
        mzt pause my-job --force
    """
    from ._shared import validate_job_id

    job_id = validate_job_id(job_id)
    if force:
        from .cancel import _cancel_job
        asyncio.run(_cancel_job(job_id, json_output))
        return

    asyncio.run(_pause_job(job_id, wait, timeout, json_output))

modify

modify(job_id=Argument(..., help='Score ID to modify'), config=Option(..., '--config', '-c', help='New configuration file', exists=True, readable=True), resume_flag=Option(False, '--resume', '-r', help='Immediately resume with new config after pausing'), wait=Option(False, '--wait', help='Wait for score to pause before resuming (when --resume)'), timeout=Option(60, '--timeout', '-t', help='Timeout in seconds for pause acknowledgment'), json_output=Option(False, '--json', '-j', help='Output result as JSON'))

Apply a new configuration to a score and optionally resume execution.

This is a convenience command that combines pause + config update. If the score is running, it will be paused first. Use --resume to immediately resume with the new configuration.

Examples:

mzt modify my-job --config updated.yaml mzt modify my-job -c new-config.yaml --resume mzt modify my-job -c updated.yaml -r --wait

Source code in src/marianne/cli/commands/pause.py

def modify(
    job_id: str = typer.Argument(..., help="Score ID to modify"),
    config: Path = typer.Option(
        ...,
        "--config",
        "-c",
        help="New configuration file",
        exists=True,
        readable=True,
    ),
    resume_flag: bool = typer.Option(
        False,
        "--resume",
        "-r",
        help="Immediately resume with new config after pausing",
    ),
    wait: bool = typer.Option(
        False,
        "--wait",
        help="Wait for score to pause before resuming (when --resume)",
    ),
    timeout: int = typer.Option(
        60,
        "--timeout",
        "-t",
        help="Timeout in seconds for pause acknowledgment",
    ),
    json_output: bool = typer.Option(
        False,
        "--json",
        "-j",
        help="Output result as JSON",
    ),
) -> None:
    """Apply a new configuration to a score and optionally resume execution.

    This is a convenience command that combines pause + config update.
    If the score is running, it will be paused first.
    Use --resume to immediately resume with the new configuration.

    Examples:
        mzt modify my-job --config updated.yaml
        mzt modify my-job -c new-config.yaml --resume
        mzt modify my-job -c updated.yaml -r --wait
    """
    from ._shared import validate_job_id

    job_id = validate_job_id(job_id)
    asyncio.run(
        _modify_job(job_id, config, resume_flag, wait, timeout, json_output)
    )