nextmv 0.18.0__py3-none-any.whl → 1.0.0.dev2__py3-none-any.whl

nextmv/cli/cloud/instance/create.py

@@ -0,0 +1,290 @@
+"""
+This module defines the cloud instance create command for the Nextmv CLI.
+"""
+
+from typing import Annotated
+
+import typer
+
+from nextmv.cli.configuration.config import build_app
+from nextmv.cli.message import enum_values, error, in_progress, print_json
+from nextmv.cli.options import AppIDOption, ProfileOption, VersionIDOption
+from nextmv.cloud.instance import InstanceConfiguration
+from nextmv.input import InputFormat
+from nextmv.run import Format, FormatInput, RunQueuing
+
+# Set up subcommand application.
+app = typer.Typer()
+
+
+@app.command()
+def create(
+    # Options for creating the instance.
+    app_id: AppIDOption,
+    version_id: VersionIDOption,
+    description: Annotated[
+        str | None,
+        typer.Option(
+            "--description",
+            "-d",
+            help="An optional description for the instance.",
+            metavar="DESCRIPTION",
+        ),
+    ] = None,
+    exist_ok: Annotated[
+        bool,
+        typer.Option(
+            "--exist-ok",
+            "-e",
+            help="If an instance with the given ID already exists, do not raise an error, and simply return it.",
+        ),
+    ] = False,
+    instance_id: Annotated[
+        str | None,
+        typer.Option(
+            "--instance-id",
+            "-i",
+            help="The ID to assign to the new instance. If not provided, a random ID will be generated.",
+            envvar="NEXTMV_INSTANCE_ID",
+            metavar="INSTANCE_ID",
+        ),
+    ] = None,
+    name: Annotated[
+        str | None,
+        typer.Option(
+            "--name",
+            "-n",
+            help="A name for the instance. If a name is not provided, the instance ID will be used as the name.",
+            metavar="NAME",
+        ),
+    ] = None,
+    # Options for configuring the instance.
+    content_format: Annotated[
+        InputFormat | None,
+        typer.Option(
+            "--content-format",
+            "-c",
+            help=f"The content format of the instance to create. Allowed values are: {enum_values(InputFormat)}.",
+            metavar="CONTENT_FORMAT",
+            rich_help_panel="Instance configuration",
+        ),
+    ] = None,
+    execution_class: Annotated[
+        str | None,
+        typer.Option(
+            "--execution-class",
+            "-x",
+            help="The execution class to use for the instance.",
+            metavar="EXECUTION_CLASS",
+            rich_help_panel="Instance configuration",
+        ),
+    ] = None,
+    integration_id: Annotated[
+        str | None,
+        typer.Option(
+            help="The integration ID to use for the runs of the instance, if applicable.",
+            metavar="INTEGRATION_ID",
+            rich_help_panel="Instance configuration",
+        ),
+    ] = None,
+    no_queuing: Annotated[
+        bool,
+        typer.Option(
+            "--no-queuing",
+            help="Do not queue when running the instance. Default is [magenta]False[/magenta], "
+            "meaning the instance's run [italic]will[/italic] be queued.",
+            rich_help_panel="Instance configuration",
+        ),
+    ] = False,
+    options: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--options",
+            "-o",
+            help="Options to always use when running the instance. Format: [magenta]key=value[/magenta]. "
+            "Pass multiple options by repeating the flag, or separating with commas.",
+            metavar="KEY=VALUE",
+            rich_help_panel="Instance configuration",
+        ),
+    ] = None,
+    priority: Annotated[
+        int,
+        typer.Option(
+            help="The priority of the runs in the instance. "
+            "Priority is between 1 and 10, with 1 being the highest priority.",
+            metavar="PRIORITY",
+            rich_help_panel="Instance configuration",
+        ),
+    ] = 6,
+    secret_collection_id: Annotated[
+        str | None,
+        typer.Option(
+            "--secret-collection-id",
+            "-s",
+            help="The secret collection ID to use for the instance, if applicable.",
+            metavar="SECRET_COLLECTION_ID",
+            rich_help_panel="Instance configuration",
+        ),
+    ] = None,
+    profile: ProfileOption = None,
+) -> None:
+    """
+    Create a new Nextmv Cloud application instance.
+
+    Use the [code]--exist-ok[/code] flag to avoid errors when creating an
+    instance with an ID that already exists. This is useful for scripts that
+    need to ensure an instance exists without worrying about whether it was
+    created previously.
+
+    [bold][underline]Examples[/underline][/bold]
+
+    - Create an instance for application [magenta]hare-app[/magenta] version [magenta]v1[/magenta].
+        $ [green]nextmv cloud instance create --app-id hare-app --version-id v1 --instance-id prod[/green]
+
+    - Create an instance with a specific name.
+        $ [green]nextmv cloud instance create --app-id hare-app --version-id v1 \\
+            --instance-id prod --name "Production Instance"[/green]
+
+    - Create an instance with a name and description.
+        $ [green]nextmv cloud instance create --app-id hare-app --version-id v1 \\
+            --instance-id prod --name "Production Instance" \\
+            --description "Instance for production routing jobs"[/green]
+
+    - Create an instance, or get it if it already exists.
+        $ [green]nextmv cloud instance create --app-id hare-app --version-id v1 \\
+            --instance-id prod --exist-ok[/green]
+
+    - Create an instance with configuration options.
+        $ [green]nextmv cloud instance create --app-id hare-app --version-id v1 \\
+            --instance-id prod --execution-class 6c9500mb870s --priority 1[/green]
+
+    - Create an instance with runtime options.
+        $ [green]nextmv cloud instance create --app-id hare-app --version-id v1 \\
+            --instance-id prod --options max_duration=30 --options timeout=60[/green]
+    """
+
+    cloud_app = build_app(app_id=app_id, profile=profile)
+    if exist_ok:
+        in_progress(msg="Creating or getting instance...")
+    else:
+        in_progress(msg="Creating instance...")
+
+    # Build the instance options from the CLI options
+    instance_options = build_options(options)
+
+    # Build the instance configuration
+    instance_config = build_config(
+        priority=priority,
+        no_queuing=no_queuing,
+        content_format=content_format,
+        execution_class=execution_class,
+        integration_id=integration_id,
+        options=instance_options,
+        secret_collection_id=secret_collection_id,
+    )
+
+    instance = cloud_app.new_instance(
+        version_id=version_id,
+        id=instance_id,
+        name=name,
+        description=description,
+        configuration=instance_config,
+        exist_ok=exist_ok,
+    )
+    print_json(instance.to_dict())
+
+
+def build_options(options: list[str] | None) -> dict[str, str] | None:
+    """
+    Builds the instance options. One can pass options by either using the flag
+    multiple times or by separating with commas in the same flag. A
+    combination of both is also possible.
+
+    Parameters
+    ----------
+    options : list[str] | None
+        The list of instance options as strings.
+
+    Returns
+    -------
+    dict[str, str]
+        The built instance options.
+    """
+
+    if options is None:
+        return None
+
+    instance_options = {}
+    for opt in options:
+        # It is possible to pass multiple options separated by commas. The
+        # default way though is to use the flag multiple times to specify
+        # different options.
+        sub_opts = opt.split(",")
+        for sub_opt in sub_opts:
+            key_value = sub_opt.split("=", 1)
+            if len(key_value) != 2:
+                error(f"Invalid option format: {sub_opt}. Expected format is [magenta]key=value[/magenta].")
+
+            key, value = key_value
+            instance_options[key] = value
+
+    return instance_options
+
+
+def build_config(
+    priority: int,
+    no_queuing: bool,
+    content_format: InputFormat | None = None,
+    execution_class: str | None = None,
+    integration_id: str | None = None,
+    options: dict | None = None,
+    secret_collection_id: str | None = None,
+) -> InstanceConfiguration:
+    """
+    Builds the instance configuration for the new instance.
+
+    Parameters
+    ----------
+    priority : int
+        The priority of the instance.
+    no_queuing : bool
+        Whether to disable queuing for the instance.
+    content_format : InputFormat | None
+        The content format for the instance, if applicable.
+    execution_class : str | None
+        The execution class to use for the instance, if applicable.
+    integration_id : str | None
+        The integration ID to use for the instance, if applicable.
+    options : dict | None
+        The runtime options for the instance, if applicable.
+    secret_collection_id : str | None
+        The secret collection ID to use for the instance, if applicable.
+
+    Returns
+    -------
+    InstanceConfiguration
+        The built instance configuration.
+    """
+
+    config = InstanceConfiguration(
+        queuing=RunQueuing(
+            priority=priority,
+            disabled=no_queuing,
+        ),
+    )
+    if execution_class is not None:
+        config.execution_class = execution_class
+    if options is not None:
+        config.options = options
+    if secret_collection_id is not None:
+        config.secrets_collection_id = secret_collection_id
+    if integration_id is not None:
+        config.integration_id = integration_id
+    if content_format is not None:
+        config.format = Format(
+            format_input=FormatInput(
+                input_type=InputFormat(content_format),
+            ),
+        )
+
+    return config

nextmv/cli/cloud/instance/delete.py

@@ -0,0 +1,62 @@
+"""
+This module defines the cloud instance delete command for the Nextmv CLI.
+"""
+
+from typing import Annotated
+
+import typer
+from rich.prompt import Confirm
+
+from nextmv.cli.configuration.config import build_app
+from nextmv.cli.message import info, success
+from nextmv.cli.options import AppIDOption, InstanceIDOption, ProfileOption
+
+# Set up subcommand application.
+app = typer.Typer()
+
+
+@app.command()
+def delete(
+    app_id: AppIDOption,
+    instance_id: InstanceIDOption,
+    yes: Annotated[
+        bool,
+        typer.Option(
+            "--yes",
+            "-y",
+            help="Agree to deletion confirmation prompt. Useful for non-interactive sessions.",
+        ),
+    ] = False,
+    profile: ProfileOption = None,
+) -> None:
+    """
+    Deletes a Nextmv Cloud application instance.
+
+    This action is permanent and cannot be undone. Use the [code]--yes[/code]
+    flag to skip the confirmation prompt.
+
+    [bold][underline]Examples[/underline][/bold]
+
+    - Delete the instance with the ID [magenta]prod[/magenta] from application [magenta]hare-app[/magenta].
+        $ [green]nextmv cloud instance delete --app-id hare-app --instance-id prod[/green]
+
+    - Delete the instance without confirmation prompt.
+        $ [green]nextmv cloud instance delete --app-id hare-app --instance-id prod --yes[/green]
+    """
+
+    if not yes:
+        confirm = Confirm.ask(
+            f"Are you sure you want to delete instance [magenta]{instance_id}[/magenta] "
+            f"from application [magenta]{app_id}[/magenta]? This action cannot be undone.",
+            default=False,
+        )
+
+        if not confirm:
+            info(msg=f"Instance [magenta]{instance_id}[/magenta] will not be deleted.", emoji=":bulb:")
+            return
+
+    cloud_app = build_app(app_id=app_id, profile=profile)
+    cloud_app.delete_instance(instance_id=instance_id)
+    success(
+        f"Instance [magenta]{instance_id}[/magenta] deleted successfully from application [magenta]{app_id}[/magenta]."
+    )

nextmv/cli/cloud/instance/exists.py

@@ -0,0 +1,39 @@
+"""
+This module defines the cloud instance exists command for the Nextmv CLI.
+"""
+
+import typer
+
+from nextmv.cli.configuration.config import build_app
+from nextmv.cli.message import in_progress, print_json
+from nextmv.cli.options import AppIDOption, InstanceIDOption, ProfileOption
+
+# Set up subcommand application.
+app = typer.Typer()
+
+
+@app.command()
+def exists(
+    app_id: AppIDOption,
+    instance_id: InstanceIDOption,
+    profile: ProfileOption = None,
+) -> None:
+    """
+    Check if a Nextmv Cloud application instance exists.
+
+    This command is useful in scripting applications to verify the existence of
+    a Nextmv Cloud application instance by its ID.
+
+    [bold][underline]Examples[/underline][/bold]
+
+    - Check if the instance with the ID [magenta]prod[/magenta] exists in application [magenta]hare-app[/magenta].
+        $ [green]nextmv cloud instance exists --app-id hare-app --instance-id prod[/green]
+
+    - Check if the instance exists using the profile named [magenta]hare[/magenta].
+        $ [green]nextmv cloud instance exists --app-id hare-app --instance-id prod --profile hare[/green]
+    """
+
+    cloud_app = build_app(app_id=app_id, profile=profile)
+    in_progress(msg="Checking if instance exists...")
+    ok = cloud_app.instance_exists(instance_id=instance_id)
+    print_json({"exists": ok})

nextmv/cli/cloud/instance/get.py

@@ -0,0 +1,62 @@
+"""
+This module defines the cloud instance 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, InstanceIDOption, ProfileOption
+
+# Set up subcommand application.
+app = typer.Typer()
+
+
+@app.command()
+def get(
+    app_id: AppIDOption,
+    instance_id: InstanceIDOption,
+    output: Annotated[
+        str | None,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Saves the instance information to this location.",
+            metavar="OUTPUT_PATH",
+        ),
+    ] = None,
+    profile: ProfileOption = None,
+) -> None:
+    """
+    Get a Nextmv Cloud application instance.
+
+    This command is useful to get the attributes of an existing Nextmv Cloud
+    application instance by its ID.
+
+    [bold][underline]Examples[/underline][/bold]
+
+    - Get the instance with the ID [magenta]prod[/magenta] from application [magenta]hare-app[/magenta].
+        $ [green]nextmv cloud instance get --app-id hare-app --instance-id prod[/green]
+
+    - Get the instance with the ID [magenta]prod[/magenta] and save the information to a
+      [magenta]instance.json[/magenta] file.
+        $ [green]nextmv cloud instance get --app-id hare-app --instance-id prod --output instance.json[/green]
+    """
+
+    cloud_app = build_app(app_id=app_id, profile=profile)
+    in_progress(msg="Getting instance...")
+    instance = cloud_app.instance(instance_id=instance_id)
+    instance_dict = instance.to_dict()
+
+    if output is not None and output != "":
+        with open(output, "w") as f:
+            json.dump(instance_dict, f, indent=2)
+
+        success(msg=f"Instance information saved to [magenta]{output}[/magenta].")
+
+        return
+
+    print_json(instance_dict)

nextmv/cli/cloud/instance/list.py

@@ -0,0 +1,60 @@
+"""
+This module defines the cloud instance 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 in_progress, print_json, success
+from nextmv.cli.options import AppIDOption, ProfileOption
+
+# 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 instance list information to this location.",
+            metavar="OUTPUT_PATH",
+        ),
+    ] = None,
+    profile: ProfileOption = None,
+) -> None:
+    """
+    List all instances of a Nextmv Cloud application.
+
+    [bold][underline]Examples[/underline][/bold]
+
+    - List all instances of application [magenta]hare-app[/magenta].
+        $ [green]nextmv cloud instance list --app-id hare-app[/green]
+
+    - List all instances using the profile named [magenta]hare[/magenta].
+        $ [green]nextmv cloud instance list --app-id hare-app --profile hare[/green]
+
+    - List all instances and save the information to a [magenta]instances.json[/magenta] file.
+        $ [green]nextmv cloud instance list --app-id hare-app --output instances.json[/green]
+    """
+
+    cloud_app = build_app(app_id=app_id, profile=profile)
+    in_progress(msg="Listing instances...")
+    instances = cloud_app.list_instances()
+    instances_dicts = [instance.to_dict() for instance in instances]
+
+    if output is not None and output != "":
+        with open(output, "w") as f:
+            json.dump(instances_dicts, f, indent=2)
+
+        success(msg=f"Instance list information saved to [magenta]{output}[/magenta].")
+
+        return
+
+    print_json(instances_dicts)