nextmv 1.0.0.dev2__tar.gz → 1.0.0.dev3__tar.gz

{nextmv-1.0.0.dev2 → nextmv-1.0.0.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nextmv
-Version: 1.0.0.dev2
+Version: 1.0.0.dev3
 Summary: The all-purpose Python SDK for Nextmv
 Project-URL: Homepage, https://www.nextmv.io
 Project-URL: Documentation, https://nextmv-py.docs.nextmv.io/en/latest/nextmv/

nextmv-1.0.0.dev3/nextmv/__about__.py

@@ -0,0 +1 @@
+__version__ = "v1.0.0.dev3"

{nextmv-1.0.0.dev2 → nextmv-1.0.0.dev3}/nextmv/cli/cloud/__init__.py

@@ -17,6 +17,7 @@ from nextmv.cli.cloud.run import app as run_app
 from nextmv.cli.cloud.scenario import app as scenario_app
 from nextmv.cli.cloud.secrets import app as secrets_app
 from nextmv.cli.cloud.shadow import app as shadow_app
+from nextmv.cli.cloud.switchback import app as switchback_app
 from nextmv.cli.cloud.upload import app as upload_app
 from nextmv.cli.cloud.version import app as version_app
 
@@ -35,6 +36,7 @@ app.add_typer(run_app, name="run")
 app.add_typer(scenario_app, name="scenario")
 app.add_typer(secrets_app, name="secrets")
 app.add_typer(shadow_app, name="shadow")
+app.add_typer(switchback_app, name="switchback")
 app.add_typer(upload_app, name="upload")
 app.add_typer(version_app, name="version")
 

{nextmv-1.0.0.dev2 → nextmv-1.0.0.dev3}/nextmv/cli/cloud/shadow/__init__.py

@@ -1,5 +1,5 @@
 """
-This module defines the cloud batch command tree for the Nextmv CLI.
+This module defines the cloud shadow command tree for the Nextmv CLI.
 """
 
 import typer

{nextmv-1.0.0.dev2 → nextmv-1.0.0.dev3}/nextmv/cli/cloud/shadow/create.py

@@ -115,7 +115,7 @@ def create(
     control over when the shadow test should terminate, after said number of
     runs. Alternatively, you may specify the [code]--termination-time[/code]
     option or use the [code]nextmv cloud shadow stop[/code] command to stop the
-    test
+    test.
 
     [bold][underline]Examples[/underline][/bold]
 
@@ -168,7 +168,7 @@ def create(
     except json.JSONDecodeError as e:
         error(f"Invalid comparisons format: [magenta]{comparisons}[/magenta]. Error: {e}")
 
-    in_progress(msg="Creating shadow test...")
+    in_progress(msg="Creating shadow test in draft mode...")
     shadow_test = cloud_app.new_shadow_test(
         comparisons=comparisons_dict,
         termination_events=TerminationEvents(

{nextmv-1.0.0.dev2 → nextmv-1.0.0.dev3}/nextmv/cli/cloud/shadow/stop.py

@@ -29,15 +29,15 @@ def stop(
 
     [bold][underline]Examples[/underline][/bold]
 
-    - Start the shadow test with the ID [magenta]hop-analysis[/magenta] from application
+    - Stop the shadow test with the ID [magenta]hop-analysis[/magenta] from application
       [magenta]hare-app[/magenta].
-        $ [green]nextmv cloud shadow start --app-id hare-app --shadow-test-id hop-analysis[/green]
+        $ [green]nextmv cloud shadow stop --app-id hare-app --shadow-test-id hop-analysis[/green]
     """
 
-    in_progress(msg="Starting shadow test...")
+    in_progress(msg="Stopping shadow test...")
     cloud_app = build_app(app_id=app_id, profile=profile)
-    cloud_app.start_shadow_test(shadow_test_id=shadow_test_id)
+    cloud_app.stop_shadow_test(shadow_test_id=shadow_test_id)
     success(
-        f"Shadow test [magenta]{shadow_test_id}[/magenta] started successfully "
+        f"Shadow test [magenta]{shadow_test_id}[/magenta] stopped successfully "
         f"in application [magenta]{app_id}[/magenta]."
     )

{nextmv-1.0.0.dev2 → nextmv-1.0.0.dev3}/nextmv/cli/cloud/shadow/update.py

@@ -90,6 +90,7 @@ def update(
             json.dump(shadow_test_dict, f, indent=2)
 
         success(msg=f"Updated shadow test information saved to [magenta]{output}[/magenta].")
+
         return
 
     print_json(shadow_test_dict)

nextmv-1.0.0.dev3/nextmv/cli/cloud/switchback/__init__.py

@@ -0,0 +1,33 @@
+"""
+This module defines the cloud switchback command tree for the Nextmv CLI.
+"""
+
+import typer
+
+from nextmv.cli.cloud.switchback.create import app as create_app
+from nextmv.cli.cloud.switchback.delete import app as delete_app
+from nextmv.cli.cloud.switchback.get import app as get_app
+from nextmv.cli.cloud.switchback.list import app as list_app
+from nextmv.cli.cloud.switchback.metadata import app as metadata_app
+from nextmv.cli.cloud.switchback.start import app as start_app
+from nextmv.cli.cloud.switchback.stop import app as stop_app
+from nextmv.cli.cloud.switchback.update import app as update_app
+
+# Set up subcommand application.
+app = typer.Typer()
+app.add_typer(create_app)
+app.add_typer(delete_app)
+app.add_typer(get_app)
+app.add_typer(list_app)
+app.add_typer(metadata_app)
+app.add_typer(start_app)
+app.add_typer(stop_app)
+app.add_typer(update_app)
+
+
+@app.callback()
+def callback() -> None:
+    """
+    Create and manage Nextmv Cloud switchback tests.
+    """
+    pass

nextmv-1.0.0.dev3/nextmv/cli/cloud/switchback/create.py

@@ -0,0 +1,147 @@
+"""
+This module defines the cloud switchback create command for the Nextmv CLI.
+"""
+
+from datetime import datetime
+from typing import Annotated
+
+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, ProfileOption
+from nextmv.cloud.switchback import TestComparisonSingle
+
+# Set up subcommand application.
+app = typer.Typer()
+
+
+@app.command()
+def create(
+    app_id: AppIDOption,
+    baseline_instance_id: Annotated[
+        str,
+        typer.Option(
+            "--baseline-instance-id",
+            "-b",
+            help="ID of the baseline instance for the switchback test.",
+            metavar="BASELINE_INSTANCE_ID",
+        ),
+    ],
+    candidate_instance_id: Annotated[
+        str,
+        typer.Option(
+            "--candidate-instance-id",
+            "-c",
+            help="ID of the candidate instance for the switchback test.",
+            metavar="CANDIDATE_INSTANCE_ID",
+        ),
+    ],
+    unit_duration_minutes: Annotated[
+        float,
+        typer.Option(
+            "--unit-duration-minutes",
+            "-u",
+            help="Duration of each interval in minutes.",
+            metavar="UNIT_DURATION_MINUTES",
+        ),
+    ],
+    units: Annotated[
+        int,
+        typer.Option(
+            "--units",
+            "-t",
+            help="Total number of intervals in the switchback test.",
+            metavar="UNITS",
+        ),
+    ],
+    description: Annotated[
+        str | None,
+        typer.Option(
+            "--description",
+            "-d",
+            help="Description of the switchback test.",
+            metavar="DESCRIPTION",
+        ),
+    ] = None,
+    name: Annotated[
+        str | None,
+        typer.Option(
+            "--name",
+            "-n",
+            help="Name of the switchback test. If not provided, the ID will be used as the name.",
+            metavar="NAME",
+        ),
+    ] = None,
+    switchback_test_id: Annotated[
+        str | None,
+        typer.Option(
+            "--switchback-test-id",
+            "-s",
+            help="ID for the switchback test. Will be generated if not provided.",
+            envvar="NEXTMV_SWITCHBACK_TEST_ID",
+            metavar="SWITCHBACK_TEST_ID",
+        ),
+    ] = None,
+    start: Annotated[
+        datetime | None,
+        typer.Option(
+            "--start",
+            "-r",
+            formats=["%Y-%m-%dT%H:%M:%S%z"],
+            help="Scheduled time for switchback test start in [magenta]RFC 3339[/magenta] format. "
+            "Example: [magenta]'2024-01-01T00:00:00Z'[/magenta]",
+            metavar="START",
+        ),
+    ] = None,
+    profile: ProfileOption = None,
+) -> None:
+    """
+    Create a new Nextmv Cloud switchback test in draft mode.
+
+    The test will alternate between the [code]--baseline-instance-id[/code] and
+    [code]--candidate-instance-id[/code] over specified time intervals.
+
+    You may specify the [code]--start[/code] option to make the switchback
+    test start at a specific time. Alternatively, you may use the
+    [code]nextmv cloud switchback start[/code] command to start the test.
+
+    Use the [code]nextmv cloud switchback stop[/code] command to stop the test.
+
+    [bold][underline]Examples[/underline][/bold]
+
+    - Create a switchback test alternating between two bunny instances:
+        $ [green]nextmv cloud switchback create --app-id hare-app --switchback-test-id bunny-switch-hop \\
+            --name "Bunny Switch Hop" --baseline-instance-id fluffy-bunny-baseline \\
+            --candidate-instance-id speedy-cottontail --unit-duration-minutes 15 --units 10[/green]
+
+    - Create a switchback test with a scheduled start time:
+        $ [green]nextmv cloud switchback create --app-id hare-app --switchback-test-id sunrise-switch \\
+            --name "Sunrise Switch Test" --baseline-instance-id wise-old-rabbit \\
+            --candidate-instance-id burrow-master --unit-duration-minutes 30 --units 8 \\
+            --start '2026-01-23T10:00:00Z'[/green]
+
+    - Create a switchback test with a description:
+        $ [green]nextmv cloud switchback create --app-id hare-app --switchback-test-id carrot-switch \\
+            --name "Carrot Switch" --baseline-instance-id fluffy-bunny-baseline \\
+            --candidate-instance-id hopping-candidate-ears --unit-duration-minutes 20 --units 12 \\
+            --description "Which bunny hops best for carrots?"[/green]
+    """
+
+    cloud_app = build_app(app_id=app_id, profile=profile)
+
+    in_progress(msg="Creating switchback test in draft mode...")
+    switchback_test = cloud_app.new_switchback_test(
+        comparison=TestComparisonSingle(
+            baseline_instance_id=baseline_instance_id,
+            candidate_instance_id=candidate_instance_id,
+        ),
+        unit_duration_minutes=unit_duration_minutes,
+        units=units,
+        switchback_test_id=switchback_test_id,
+        name=name,
+        description=description,
+        start=start,
+    )
+
+    print_json(switchback_test.to_dict())

nextmv-1.0.0.dev3/nextmv/cli/cloud/switchback/delete.py

@@ -0,0 +1,68 @@
+"""
+This module defines the cloud switchback 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, ProfileOption, SwitchbackTestIDOption
+
+# Set up subcommand application.
+app = typer.Typer()
+
+
+@app.command()
+def delete(
+    app_id: AppIDOption,
+    switchback_test_id: SwitchbackTestIDOption,
+    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 switchback test.
+
+    This action is permanent and cannot be undone. The switchback test and all
+    associated data, including runs, will be deleted. Use the [code]--yes[/code]
+    flag to skip the confirmation prompt.
+
+    [bold][underline]Examples[/underline][/bold]
+
+    - Delete the switchback test with the ID [magenta]hop-analysis[/magenta] from application
+      [magenta]hare-app[/magenta].
+        $ [green]nextmv cloud switchback delete --app-id hare-app --switchback-test-id hop-analysis[/green]
+
+    - Delete the switchback test without confirmation prompt.
+        $ [green]nextmv cloud switchback delete --app-id hare-app --switchback-test-id carrot-routes --yes[/green]
+    """
+
+    if not yes:
+        confirm = Confirm.ask(
+            f"Are you sure you want to delete switchback test [magenta]{switchback_test_id}[/magenta] "
+            f"from application [magenta]{app_id}[/magenta]? This action cannot be undone.",
+            default=False,
+        )
+
+        if not confirm:
+            info(
+                msg=f"Switchback test [magenta]{switchback_test_id}[/magenta] will not be deleted.",
+                emoji=":bulb:",
+            )
+            return
+
+    cloud_app = build_app(app_id=app_id, profile=profile)
+    cloud_app.delete_switchback_test(switchback_test_id=switchback_test_id)
+    success(
+        f"Switchback test [magenta]{switchback_test_id}[/magenta] deleted successfully "
+        f"from application [magenta]{app_id}[/magenta]."
+    )

nextmv-1.0.0.dev3/nextmv/cli/cloud/switchback/get.py

@@ -0,0 +1,62 @@
+"""
+This module defines the cloud switchback 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, SwitchbackTestIDOption
+
+# Set up subcommand application.
+app = typer.Typer()
+
+
+@app.command()
+def get(
+    app_id: AppIDOption,
+    switchback_test_id: SwitchbackTestIDOption,
+    output: Annotated[
+        str | None,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Saves the results to this location.",
+            metavar="OUTPUT_PATH",
+        ),
+    ] = None,
+    profile: ProfileOption = None,
+) -> None:
+    """
+    Get a Nextmv Cloud switchback test, including its runs.
+
+    [bold][underline]Examples[/underline][/bold]
+
+    - Get the switchback test with ID [magenta]carrot-optimization[/magenta] from application
+      [magenta]hare-app[/magenta].
+        $ [green]nextmv cloud switchback get --app-id hare-app --switchback-test-id carrot-optimization[/green]
+
+    - Get the switchback test using a specific profile.
+        $ [green]nextmv cloud switchback get --app-id hare-app --switchback-test-id lettuce-routes \\
+            --profile prod[/green]
+    """
+
+    cloud_app = build_app(app_id=app_id, profile=profile)
+    in_progress(msg="Getting switchback test...")
+    switchback_test = cloud_app.switchback_test(switchback_test_id=switchback_test_id)
+
+    switchback_test_dict = switchback_test.to_dict()
+
+    # Handle output
+    if output is not None and output != "":
+        with open(output, "w") as f:
+            json.dump(switchback_test_dict, f, indent=2)
+
+        success(msg=f"Switchback test output saved to [magenta]{output}[/magenta].")
+
+        return
+
+    print_json(switchback_test_dict)

nextmv-1.0.0.dev3/nextmv/cli/cloud/switchback/list.py

@@ -0,0 +1,63 @@
+"""
+This module defines the cloud switchback 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 list of switchback tests to this location.",
+            metavar="OUTPUT_PATH",
+        ),
+    ] = None,
+    profile: ProfileOption = None,
+) -> None:
+    """
+    List all Nextmv Cloud switchback tests for an application.
+
+    This command retrieves all switchback tests associated with the specified
+    application.
+
+    [bold][underline]Examples[/underline][/bold]
+
+    - List all switchback tests for application [magenta]hare-app[/magenta].
+        $ [green]nextmv cloud switchback list --app-id hare-app[/green]
+
+    - List all switchback tests and save to a file.
+        $ [green]nextmv cloud switchback list --app-id hare-app --output tests.json[/green]
+
+    - List all switchback tests using a specific profile.
+        $ [green]nextmv cloud switchback list --app-id hare-app --profile prod[/green]
+    """
+
+    cloud_app = build_app(app_id=app_id, profile=profile)
+    in_progress(msg="Listing switchback tests...")
+    switchback_tests = cloud_app.list_switchback_tests()
+    switchback_tests_dict = [test.to_dict() for test in switchback_tests]
+
+    if output is not None and output != "":
+        with open(output, "w") as f:
+            json.dump(switchback_tests_dict, f, indent=2)
+
+        success(msg=f"Switchback tests list saved to [magenta]{output}[/magenta].")
+
+        return
+
+    print_json(switchback_tests_dict)

nextmv-1.0.0.dev3/nextmv/cli/cloud/switchback/metadata.py

@@ -0,0 +1,68 @@
+"""
+This module defines the cloud switchback 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, SwitchbackTestIDOption
+
+# Set up subcommand application.
+app = typer.Typer()
+
+
+@app.command()
+def metadata(
+    app_id: AppIDOption,
+    switchback_test_id: SwitchbackTestIDOption,
+    output: Annotated[
+        str | None,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Saves the switchback test metadata to this location.",
+            metavar="OUTPUT_PATH",
+        ),
+    ] = None,
+    profile: ProfileOption = None,
+) -> None:
+    """
+    Get metadata for a Nextmv Cloud switchback test.
+
+    This command retrieves metadata for a specific switchback test, including
+    status, creation date, and other high-level information without the full
+    run details.
+
+    [bold][underline]Examples[/underline][/bold]
+
+    - Get metadata for switchback test [magenta]bunny-warren-optimization[/magenta] from application
+      [magenta]hare-app[/magenta].
+        $ [green]nextmv cloud switchback metadata --app-id hare-app \\
+            --switchback-test-id bunny-warren-optimization[/green]
+
+    - Get metadata and save to a file.
+        $ [green]nextmv cloud switchback metadata --app-id hare-app --switchback-test-id lettuce-delivery \\
+            --output metadata.json[/green]
+
+    - Get metadata using a specific profile.
+        $ [green]nextmv cloud switchback metadata --app-id hare-app --switchback-test-id hop-schedule \\
+            --profile prod[/green]
+    """
+
+    cloud_app = build_app(app_id=app_id, profile=profile)
+    in_progress(msg="Getting switchback test metadata...")
+    switchback_metadata = cloud_app.switchback_test_metadata(switchback_test_id=switchback_test_id)
+    switchback_metadata_dict = switchback_metadata.to_dict()
+
+    if output is not None and output != "":
+        with open(output, "w") as f:
+            json.dump(switchback_metadata_dict, f, indent=2)
+
+        success(msg=f"Switchback test metadata saved to [magenta]{output}[/magenta].")
+        return
+
+    print_json(switchback_metadata_dict)

nextmv-1.0.0.dev3/nextmv/cli/cloud/switchback/start.py

@@ -0,0 +1,43 @@
+"""
+This module defines the cloud switchback start command for the Nextmv CLI.
+"""
+
+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, SwitchbackTestIDOption
+
+# Set up subcommand application.
+app = typer.Typer()
+
+
+@app.command()
+def start(
+    app_id: AppIDOption,
+    switchback_test_id: SwitchbackTestIDOption,
+    profile: ProfileOption = None,
+) -> None:
+    """
+    Starts a Nextmv Cloud switchback test.
+
+    Before starting a switchback test, it must be created in draft state. You
+    may use the [code]nextmv cloud switchback create[/code] command to create a
+    new switchback test. Alternatively, define a [code]--start[/code] when
+    using the [code]nextmv cloud switchback create[/code] command to have the
+    switchback test start automatically at a specific time.
+
+    [bold][underline]Examples[/underline][/bold]
+
+    - Start the switchback test with the ID [magenta]hop-analysis[/magenta] from application
+      [magenta]hare-app[/magenta].
+        $ [green]nextmv cloud switchback start --app-id hare-app --switchback-test-id hop-analysis[/green]
+    """
+
+    in_progress(msg="Starting switchback test...")
+    cloud_app = build_app(app_id=app_id, profile=profile)
+    cloud_app.start_switchback_test(switchback_test_id=switchback_test_id)
+    success(
+        f"Switchback test [magenta]{switchback_test_id}[/magenta] started successfully "
+        f"in application [magenta]{app_id}[/magenta]."
+    )

nextmv-1.0.0.dev3/nextmv/cli/cloud/switchback/stop.py

@@ -0,0 +1,43 @@
+"""
+This module defines the cloud switchback stop command for the Nextmv CLI.
+"""
+
+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, SwitchbackTestIDOption
+
+# Set up subcommand application.
+app = typer.Typer()
+
+
+@app.command()
+def stop(
+    app_id: AppIDOption,
+    switchback_test_id: SwitchbackTestIDOption,
+    profile: ProfileOption = None,
+) -> None:
+    """
+    Stops a Nextmv Cloud switchback test.
+
+    Before stopping a switchback test, it must be in a started state. You may
+    use the [code]nextmv cloud switchback start[/code] command to start a
+    switchback test. Alternatively, define a [code]--start[/code] when using
+    the [code]nextmv cloud switchback create[/code] command to have the
+    switchback test start automatically at a specific time.
+
+    [bold][underline]Examples[/underline][/bold]
+
+    - Stop the switchback test with the ID [magenta]hop-analysis[/magenta] from application
+      [magenta]hare-app[/magenta].
+        $ [green]nextmv cloud switchback stop --app-id hare-app --switchback-test-id hop-analysis[/green]
+    """
+
+    in_progress(msg="Stopping switchback test...")
+    cloud_app = build_app(app_id=app_id, profile=profile)
+    cloud_app.stop_switchback_test(switchback_test_id=switchback_test_id)
+    success(
+        f"Switchback test [magenta]{switchback_test_id}[/magenta] stopped successfully "
+        f"in application [magenta]{app_id}[/magenta]."
+    )