nextmv 0.39.0.dev1__py3-none-any.whl → 1.0.0__py3-none-any.whl

nextmv/cli/cloud/run/get.py

@@ -0,0 +1,199 @@
+"""
+This module defines the cloud run get command for the Nextmv CLI.
+"""
+
+import json
+from typing import Annotated
+
+import typer
+
+from nextmv.cli.configuration.config import build_app
+from nextmv.cli.message import in_progress, print_json, success
+from nextmv.cli.options import AppIDOption, ProfileOption, RunIDOption
+from nextmv.cloud.application import Application
+from nextmv.output import OutputFormat
+from nextmv.polling import PollingOptions, default_polling_options
+
+# Set up subcommand application.
+app = typer.Typer()
+
+
+@app.command()
+def get(
+    app_id: AppIDOption,
+    run_id: RunIDOption,
+    output: Annotated[
+        str | None,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Waits for the run to complete and save the output to this location. "
+            "A file or directory will be created depending on content format.",
+            metavar="OUTPUT_PATH",
+        ),
+    ] = None,
+    timeout: Annotated[
+        int,
+        typer.Option(
+            help="The maximum time in seconds to wait for results when polling. Poll indefinitely if not set.",
+            metavar="TIMEOUT_SECONDS",
+        ),
+    ] = -1,
+    wait: Annotated[
+        bool,
+        typer.Option(
+            "--wait",
+            "-w",
+            help="Wait for the run to complete. Run result is printed to [magenta]stdout[/magenta] for "
+            "[magenta]json[/magenta], to a dir for [magenta]multi-file[/magenta]. "
+            "Specify output location with --output.",
+        ),
+    ] = False,
+    profile: ProfileOption = None,
+) -> None:
+    """
+    Get the result (output) of a Nextmv Cloud application run.
+
+    Use the --wait flag to wait for the run to complete, polling
+    for results. Using the --output flag will also activate
+    waiting, and allows you to specify a destination (file or dir) for the
+    output, depending on the content type.
+
+    [bold][underline]Examples[/underline][/bold]
+
+    - Get the results of a run with ID [magenta]burrow-123[/magenta], belonging to an app with ID
+      [magenta]hare-app[/magenta].
+        $ [dim]nextmv cloud run get --app-id hare-app --run-id burrow-123[/dim]
+
+    - Get the results of a run with ID [magenta]burrow-123[/magenta], belonging to an app with ID
+      [magenta]hare-app[/magenta]. Wait for the run to complete if necessary.
+        $ [dim]nextmv cloud run get --app-id hare-app --run-id burrow-123 --wait[/dim]
+
+    - Get the results of a run with ID [magenta]burrow-123[/magenta], belonging to an app with ID
+      [magenta]hare-app[/magenta]. The app is a [magenta]json[/magenta] app.
+      Save the results to a [magenta]results.json[/magenta] file.
+        $ [dim]nextmv cloud run get --app-id hare-app --run-id burrow-123 --output results.json[/dim]
+
+    - Get the results of a run with ID [magenta]burrow-123[/magenta], belonging to an app with ID
+      [magenta]hare-app[/magenta]. The app is a [magenta]multi-file[/magenta] app.
+      Save the results to the [magenta]results[/magenta] dir.
+        $ [dim]nextmv cloud run get --app-id hare-app --run-id burrow-123 --output results[/dim]
+
+    - Get the results of a run with ID [magenta]burrow-123[/magenta], belonging to an app with ID
+      [magenta]hare-app[/magenta]. Use the profile named [magenta]hare[/magenta].
+        $ [dim]nextmv cloud run get --app-id hare-app --run-id burrow-123 --profile hare[/dim]
+    """
+
+    cloud_app = build_app(app_id=app_id, profile=profile)
+
+    # Build the polling options.
+    polling_options = default_polling_options()
+    polling_options.max_duration = timeout
+
+    handle_outputs(
+        cloud_app=cloud_app,
+        run_id=run_id,
+        wait=wait,
+        output=output,
+        polling_options=polling_options,
+        skip_wait_check=True,
+    )
+
+
+def handle_outputs(
+    cloud_app: Application,
+    run_id: str,
+    wait: bool,
+    output: str | None,
+    polling_options: PollingOptions,
+    skip_wait_check: bool = False,
+) -> None:
+    """
+    Handle retrieving and outputting the results from a run.
+
+    If ``wait`` is False and ``output`` is not specified, this function returns
+    early without doing anything. Otherwise, results are retrieved using
+    polling (since the run may not yet be complete) and output accordingly.
+
+    The output behavior depends on the content type:
+
+    - **JSON/TEXT**: If ``output`` is specified, writes to the given file path.
+      Otherwise, prints to stdout.
+    - **MULTI_FILE/CSV_ARCHIVE**: Downloads files to a directory. If ``output``
+      is specified, uses that as the directory name. Otherwise, uses the
+      ``run_id`` as the directory name.
+
+    Parameters
+    ----------
+    cloud_app : Application
+        The cloud application instance used to interact with the Nextmv Cloud
+        API.
+    run_id : str
+        The unique identifier of the run to retrieve results for.
+    wait : bool
+        Whether to wait for the run to complete. If False and ``output`` is not
+        specified, the function returns early without retrieving results.
+    output : str | None
+        The location to write the output. For JSON/TEXT formats, this is a file
+        path. For MULTI_FILE/CSV_ARCHIVE formats, this is a directory path. If
+        None, JSON/TEXT output is printed to stdout and MULTI_FILE/CSV_ARCHIVE
+        output uses the ``run_id`` as the directory name.
+    polling_options : PollingOptions
+        Configuration options for polling behavior, including timeout and
+        interval settings.
+    skip_wait_check : bool, optional
+        If True, skips the early return check when both `wait` is False and
+        `output` is not specified. Default is False.
+    """
+
+    # If we don't need to wait, no output is specified, and we're not skipping
+    # the wait check, return early.
+    if not wait and (output is None or output == "") and not skip_wait_check:
+        return
+
+    # Get the run metadata to determine how to operate with the output.
+    run_info = cloud_app.run_metadata(run_id=run_id)
+    content_format = run_info.metadata.format.format_output.output_type
+
+    # Build kwargs for the result retrieval.
+    kwargs = {"run_id": run_id}
+
+    # For MULTI_FILE and CSV_ARCHIVE, we need output_dir_path.
+    if content_format not in {OutputFormat.JSON, OutputFormat.TEXT}:
+        output_dir = f"{run_id}-output" if output is None or output == "" else output
+        kwargs["output_dir_path"] = output_dir
+
+    # Always poll for results since we can't guarantee the run is done.
+    # If the run is already complete, polling returns immediately.
+    in_progress(msg="Getting run results...")
+    wait = wait or (output is not None and output != "")
+    if wait:
+        kwargs["polling_options"] = polling_options
+        run_result = cloud_app.run_result_with_polling(**kwargs)
+    else:
+        run_result = cloud_app.run_result(**kwargs)
+
+    # Handle the case where output is embedded directly in the result: json and text.
+    if content_format in {OutputFormat.JSON, OutputFormat.TEXT}:
+        if output is None or output == "":
+            print_json(run_result.to_dict())
+        else:
+            with open(output, "w") as f:
+                json.dump(run_result.to_dict(), f, indent=2)
+
+            success(f"Run output written to [magenta]{output}[/magenta].")
+
+        return
+
+    # At this point, we know that the output is multi-file or csv-archive.
+    result_dict = run_result.to_dict()
+    if "output" in result_dict and run_result.metadata.run_is_finalized():
+        del result_dict["output"]
+        success(f"Run outputs downloaded to [magenta]{output_dir}[/magenta]. Here is the metadata.")
+    else:
+        success(
+            f"Run is not finalized (status: [magenta]{run_result.metadata.status_v2.value}[/magenta]). "
+            "Here is the metadata."
+        )
+
+    print_json(result_dict)

nextmv/cli/cloud/run/input.py

@@ -0,0 +1,86 @@
+"""
+This module defines the cloud run input command for the Nextmv CLI.
+"""
+
+import json
+from typing import Annotated
+
+import typer
+
+from nextmv.cli.configuration.config import build_app
+from nextmv.cli.message import in_progress, print_json, success
+from nextmv.cli.options import AppIDOption, ProfileOption, RunIDOption
+from nextmv.output import OutputFormat
+
+# Set up subcommand application.
+app = typer.Typer()
+
+
+@app.command()
+def input(
+    app_id: AppIDOption,
+    run_id: RunIDOption,
+    output: Annotated[
+        str | None,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Saves the input to this location.",
+            metavar="OUTPUT_PATH",
+        ),
+    ] = None,
+    profile: ProfileOption = None,
+) -> None:
+    """
+    Get the input of a Nextmv Cloud application run.
+
+    By default, the input is fetched and printed to [magenta]stdout[/magenta].
+    Use the --output flag to save the input to a file.
+
+    [bold][underline]Examples[/underline][/bold]
+
+    - Get the input of a run with ID [magenta]burrow-123[/magenta], belonging to an app with ID
+      [magenta]hare-app[/magenta]. Input is printed to [magenta]stdout[/magenta].
+        $ [dim]nextmv cloud run input --app-id hare-app --run-id burrow-123[/dim]
+
+    - Get the input of a run with ID [magenta]burrow-123[/magenta], belonging to an app with ID
+      [magenta]hare-app[/magenta]. Save the input to a [magenta]input.json[/magenta] file.
+        $ [dim]nextmv cloud run input --app-id hare-app --run-id burrow-123 --output input.json[/dim]
+
+    - Get the input of a run with ID [magenta]burrow-123[/magenta], belonging to an app with ID
+      [magenta]hare-app[/magenta]. Use the profile named [magenta]hare[/magenta].
+        $ [dim]nextmv cloud run input --app-id hare-app --run-id burrow-123 --profile hare[/dim]
+    """
+
+    cloud_app = build_app(app_id=app_id, profile=profile)
+    in_progress(msg="Getting run input...")
+
+    # First get the content type to check what we should do with the input,
+    # based on its format.
+    run_info = cloud_app.run_metadata(run_id)
+
+    # If the input is multi-file, we need to provide an `output_dir_path` to
+    # save the files to.
+    if run_info.metadata.format.format_input.input_type not in {OutputFormat.JSON, OutputFormat.TEXT}:
+        # If no output path is provided, use the run ID as the directory name.
+        output = f"{run_id}-input" if output is None or output == "" else output
+        cloud_app.run_input(run_id=run_id, output_dir_path=output)
+        success(msg=f"Run input saved to [magenta]{output}[/magenta].")
+
+        return
+
+    # At this point, we know the input is JSON or text, so we can fetch it
+    # normally. The method internally will take care of large inputs.
+    run_input = cloud_app.run_input(run_id=run_id)
+
+    # If an output path is provided, save the input to that file.
+    if output is not None and output != "":
+        with open(output, "w") as f:
+            json.dump(run_input, f, indent=2)
+
+        success(msg=f"Run input saved to [magenta]{output}[/magenta].")
+
+        return
+
+    # Otherwise, print the input to stdout.
+    print_json(data=run_input)

nextmv/cli/cloud/run/list.py

@@ -0,0 +1,80 @@
+"""
+This module defines the cloud run list command for the Nextmv CLI.
+"""
+
+import json
+from typing import Annotated
+
+import typer
+
+from nextmv.cli.configuration.config import build_app
+from nextmv.cli.message import enum_values, in_progress, print_json, success
+from nextmv.cli.options import AppIDOption, ProfileOption
+from nextmv.status import StatusV2
+
+# Set up subcommand application.
+app = typer.Typer()
+
+
+@app.command()
+def list(
+    app_id: AppIDOption,
+    output: Annotated[
+        str | None,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Saves the list of runs to this location.",
+            metavar="OUTPUT_PATH",
+        ),
+    ] = None,
+    status: Annotated[
+        StatusV2 | None,
+        typer.Option(
+            "--status",
+            "-s",
+            help=f"Filter runs by their status. Allowed values are: {enum_values(StatusV2)}.",
+            metavar="STATUS",
+        ),
+    ] = None,
+    profile: ProfileOption = None,
+) -> None:
+    """
+    Get the list of runs for a Nextmv Cloud application.
+
+    By default, the list of runs is fetched and printed to [magenta]stdout[/magenta].
+    Use the --output flag to save the list to a file.
+
+    You can use the optional --status flag to filter runs by their status.
+
+    [bold][underline]Examples[/underline][/bold]
+
+    - Get the list of runs for an app with ID [magenta]hare-app[/magenta]. List is printed to [magenta]stdout[/magenta].
+        $ [dim]nextmv cloud run list --app-id hare-app[/dim]
+
+    - Get the list of runs for an app with ID [magenta]hare-app[/magenta]. Save the list to a
+      [magenta]runs.json[/magenta] file.
+        $ [dim]nextmv cloud run list --app-id hare-app --output runs.json[/dim]
+
+    - Get the list of runs for an app with ID [magenta]hare-app[/magenta].
+      Use the profile named [magenta]hare[/magenta].
+        $ [dim]nextmv cloud run list --app-id hare-app --profile hare[/dim]
+
+    - Get the list of [magenta]queued[/magenta] runs for an app with ID [magenta]hare-app[/magenta].
+        $ [dim]nextmv cloud run list --app-id hare-app --status queued[/dim]
+    """
+
+    cloud_app = build_app(app_id=app_id, profile=profile)
+    in_progress(msg="Listing app runs...")
+    runs = cloud_app.list_runs(status=status)
+    runs_dicts = [run.to_dict() for run in runs]
+
+    if output is not None and output != "":
+        with open(output, "w") as f:
+            json.dump(runs_dicts, f, indent=2)
+
+        success(msg=f"Run list saved to [magenta]{output}[/magenta].")
+
+        return
+
+    print_json(runs_dicts)

nextmv/cli/cloud/run/logs.py

@@ -0,0 +1,166 @@
+"""
+This module defines the cloud run logs command for the Nextmv CLI.
+"""
+
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import rich
+import typer
+
+from nextmv.cli.configuration.config import build_app
+from nextmv.cli.message import in_progress, success
+from nextmv.cli.options import AppIDOption, ProfileOption, RunIDOption
+from nextmv.cloud.application import Application
+from nextmv.polling import PollingOptions, default_polling_options
+
+# Set up subcommand application.
+app = typer.Typer()
+
+
+@app.command()
+def logs(
+    app_id: AppIDOption,
+    run_id: RunIDOption,
+    output: Annotated[
+        str | None,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Waits for the run to complete and saves the logs to this location.",
+            metavar="OUTPUT_PATH",
+        ),
+    ] = None,
+    tail: Annotated[
+        bool,
+        typer.Option(
+            "--tail",
+            "-t",
+            help="Tail the logs until the run completes. Logs are streamed to [magenta]stderr[/magenta]. "
+            "Specify log output location with --output.",
+        ),
+    ] = False,
+    timeout: Annotated[
+        int,
+        typer.Option(
+            help="The maximum time in seconds to wait for results when polling. Poll indefinitely if not set.",
+            metavar="TIMEOUT_SECONDS",
+        ),
+    ] = -1,
+    profile: ProfileOption = None,
+) -> None:
+    """
+    Get the logs of a Nextmv Cloud application run.
+
+    By default, the logs are fetched and printed to [magenta]stderr[/magenta].
+    Use the --tail flag to stream logs to [magenta]stderr[/magenta] until the
+    run completes. Using the --output flag will also activate waiting, and
+    allows you to specify a file to write the logs to.
+
+    [bold][underline]Examples[/underline][/bold]
+
+    - Get the logs of a run with ID [magenta]burrow-123[/magenta], belonging to an app with ID
+      [magenta]hare-app[/magenta]. Logs are printed to [magenta]stderr[/magenta].
+        $ [dim]nextmv cloud run logs --app-id hare-app --run-id burrow-123[/dim]
+
+    - Get the logs of a run with ID [magenta]burrow-123[/magenta], belonging to an app with ID
+      [magenta]hare-app[/magenta]. Tail the logs until the run completes.
+        $ [dim]nextmv cloud run logs --app-id hare-app --run-id burrow-123 --tail[/dim]
+
+    - Get the logs of a run with ID [magenta]burrow-123[/magenta], belonging to an app with ID
+      [magenta]hare-app[/magenta]. Save the logs to a [magenta]logs.log[/magenta] file.
+        $ [dim]nextmv cloud run logs --app-id hare-app --run-id burrow-123 --output logs.log[/dim]
+
+    - Get the logs of a run with ID [magenta]burrow-123[/magenta], belonging to an app with ID
+      [magenta]hare-app[/magenta]. Tail the logs and save them to a [magenta]logs.log[/magenta] file.
+        $ [dim]nextmv cloud run logs --app-id hare-app --run-id burrow-123 --tail --output logs.log[/dim]
+
+    - Get the logs of a run with ID [magenta]burrow-123[/magenta], belonging to an app with ID
+      [magenta]hare-app[/magenta]. Use the profile named [magenta]hare[/magenta].
+        $ [dim]nextmv cloud run logs --app-id hare-app --run-id burrow-123 --profile hare[/dim]
+    """
+
+    cloud_app = build_app(app_id=app_id, profile=profile)
+
+    # Build the polling options.
+    polling_options = default_polling_options()
+    polling_options.max_duration = timeout
+
+    handle_logs(
+        cloud_app=cloud_app,
+        run_id=run_id,
+        tail=tail,
+        logs=output,
+        polling_options=polling_options,
+        file_output=output is not None,
+    )
+
+
+def handle_logs(
+    cloud_app: Application,
+    run_id: str,
+    tail: bool,
+    logs: str | None,
+    polling_options: PollingOptions,
+    file_output: bool,
+) -> None:
+    """
+    Handle retrieving and outputting logs from a run.
+
+    If neither `tail` is True nor `logs` is specified, this function
+    returns early without doing anything. Otherwise, logs are retrieved and
+    optionally written to a file.
+
+    When `tail` is True, logs are streamed in real-time to stderr as the run
+    executes. When `logs` is specified (without tailing), the function waits
+    for the run to complete and then fetches all logs at once. In both cases,
+    if a `logs` file path is provided, the logs are persisted to that file.
+
+    Parameters
+    ----------
+    cloud_app : Application
+        The cloud application instance used to interact with the Nextmv Cloud
+        API.
+    run_id : str
+        The unique identifier of the run to retrieve logs for.
+    tail : bool
+        If True, streams logs in real-time to stderr as the run executes.
+    logs : str | None
+        The file path where logs should be written. If None, logs are only
+        displayed to stderr (when tailing) and not persisted to a file.
+    polling_options : PollingOptions
+        Configuration options for polling behavior, including timeout and
+        interval settings.
+    file_output : bool
+        Indicates whether logs should be written to a file. If False, logs are
+        only printed to stderr, no matter the status of the run.
+    """
+
+    if tail:
+        in_progress(msg="Tailing logs...")
+        fetched_logs = cloud_app.run_logs_with_polling(
+            run_id=run_id,
+            polling_options=polling_options,
+            verbose=True,
+            rich_print=True,
+        )
+        if logs is None:
+            return
+
+        log_content = "".join(log_entry.log for log_entry in fetched_logs)
+    elif logs is not None and logs != "" and file_output:
+        in_progress(msg="Getting run logs...")
+        cloud_app.run_result_with_polling(run_id=run_id, polling_options=polling_options)
+        run_logs = cloud_app.run_logs(run_id=run_id)
+        log_content = run_logs.log
+    elif not file_output:
+        in_progress(msg="Getting run logs...")
+        run_logs = cloud_app.run_logs(run_id=run_id)
+        rich.print(run_logs.log, file=sys.stderr)
+        return
+    else:
+        return
+
+    Path(logs).write_text(log_content)
+    success(f"Run logs written to [magenta]{logs}[/magenta].")

nextmv/cli/cloud/run/metadata.py

@@ -0,0 +1,67 @@
+"""
+This module defines the cloud run metadata command for the Nextmv CLI.
+"""
+
+import json
+from typing import Annotated
+
+import typer
+
+from nextmv.cli.configuration.config import build_app
+from nextmv.cli.message import in_progress, print_json, success
+from nextmv.cli.options import AppIDOption, ProfileOption, RunIDOption
+
+# Set up subcommand application.
+app = typer.Typer()
+
+
+@app.command()
+def metadata(
+    app_id: AppIDOption,
+    run_id: RunIDOption,
+    output: Annotated[
+        str | None,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Saves the metadata to this location.",
+            metavar="OUTPUT_PATH",
+        ),
+    ] = None,
+    profile: ProfileOption = None,
+) -> None:
+    """
+    Get the metadata of a Nextmv Cloud application run.
+
+    By default, the metadata is fetched and printed to [magenta]stdout[/magenta].
+    Use the --output flag to save the metadata to a file.
+
+    [bold][underline]Examples[/underline][/bold]
+
+    - Get the metadata of a run with ID [magenta]burrow-123[/magenta], belonging to an app with ID
+      [magenta]hare-app[/magenta]. Metadata is printed to [magenta]stdout[/magenta].
+        $ [dim]nextmv cloud run metadata --app-id hare-app --run-id burrow-123[/dim]
+
+    - Get the metadata of a run with ID [magenta]burrow-123[/magenta], belonging to an app with ID
+      [magenta]hare-app[/magenta]. Save the metadata to a [magenta]metadata.json[/magenta] file.
+        $ [dim]nextmv cloud run metadata --app-id hare-app --run-id burrow-123 --output metadata.json[/dim]
+
+    - Get the metadata of a run with ID [magenta]burrow-123[/magenta], belonging to an app with ID
+      [magenta]hare-app[/magenta]. Use the profile named [magenta]hare[/magenta].
+        $ [dim]nextmv cloud run metadata --app-id hare-app --run-id burrow-123 --profile hare[/dim]
+    """
+
+    cloud_app = build_app(app_id=app_id, profile=profile)
+    in_progress(msg="Getting run metadata...")
+    run_info = cloud_app.run_metadata(run_id)
+    info_dict = run_info.to_dict()
+
+    if output is not None and output != "":
+        with open(output, "w") as f:
+            json.dump(info_dict, f, indent=2)
+
+        success(msg=f"Run metadata saved to [magenta]{output}[/magenta].")
+
+        return
+
+    print_json(info_dict)