nextmv 1.0.0.dev1__py3-none-any.whl → 1.0.0.dev3__py3-none-any.whl

nextmv/cli/cloud/switchback/update.py

@@ -0,0 +1,96 @@
+"""
+This module defines the cloud switchback update 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 update(
+    app_id: AppIDOption,
+    switchback_test_id: SwitchbackTestIDOption,
+    description: Annotated[
+        str | None,
+        typer.Option(
+            "--description",
+            "-d",
+            help="Updated description of the switchback test.",
+            metavar="DESCRIPTION",
+        ),
+    ] = None,
+    name: Annotated[
+        str | None,
+        typer.Option(
+            "--name",
+            "-n",
+            help="Updated name of the switchback test.",
+            metavar="NAME",
+        ),
+    ] = None,
+    output: Annotated[
+        str | None,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Saves the updated switchback test information to this location.",
+            metavar="OUTPUT_PATH",
+        ),
+    ] = None,
+    profile: ProfileOption = None,
+) -> None:
+    """
+    Update a Nextmv Cloud switchback test.
+
+    Update the name and/or description of a switchback test. Any fields not
+    specified will remain unchanged.
+
+    [bold][underline]Examples[/underline][/bold]
+
+    - Update the name of a switchback test.
+        $ [green]nextmv cloud switchback update --app-id hare-app --switchback-test-id carrot-feast \\
+            --name "Spring Carrot Harvest"[/green]
+
+    - Update the description of a switchback test.
+        $ [green]nextmv cloud switchback update --app-id hare-app --switchback-test-id bunny-hop-routes \\
+            --description "Optimizing hop paths through the meadow"[/green]
+
+    - Update both name and description and save the result.
+        $ [green]nextmv cloud switchback update --app-id hare-app --switchback-test-id lettuce-delivery \\
+            --name "Warren Lettuce Express" --description "Fast lettuce delivery to all burrows" \\
+            --output updated-switchback-test.json[/green]
+    """
+
+    cloud_app = build_app(app_id=app_id, profile=profile)
+
+    in_progress(msg="Updating switchback test...")
+    switchback_test = cloud_app.update_switchback_test(
+        switchback_test_id=switchback_test_id,
+        name=name,
+        description=description,
+    )
+
+    switchback_test_dict = switchback_test.to_dict()
+    success(
+        f"Switchback test [magenta]{switchback_test_id}[/magenta] updated successfully "
+        f"in application [magenta]{app_id}[/magenta]."
+    )
+
+    if output is not None and output != "":
+        with open(output, "w") as f:
+            json.dump(switchback_test_dict, f, indent=2)
+
+        success(msg=f"Updated switchback test information saved to [magenta]{output}[/magenta].")
+
+        return
+
+    print_json(switchback_test_dict)

nextmv/cli/options.py

@@ -190,3 +190,31 @@ SecretsCollectionIDOption = Annotated[
         metavar="SECRETS_COLLECTION_ID",
     ),
 ]
+
+# shadow_test_id option - can be used in any command that requires a shadow test ID.
+# Define it as follows in commands or callbacks, as necessary:
+# shadow_test_id: ShadowTestIDOption
+ShadowTestIDOption = Annotated[
+    str,
+    typer.Option(
+        "--shadow-test-id",
+        "-s",
+        help="The Nextmv Cloud shadow test ID to use for this action.",
+        envvar="NEXTMV_SHADOW_TEST_ID",
+        metavar="SHADOW_TEST_ID",
+    ),
+]
+
+# switchback_test_id option - can be used in any command that requires a switchback test ID.
+# Define it as follows in commands or callbacks, as necessary:
+# switchback_test_id: SwitchbackTestIDOption
+SwitchbackTestIDOption = Annotated[
+    str,
+    typer.Option(
+        "--switchback-test-id",
+        "-s",
+        help="The Nextmv Cloud switchback test ID to use for this action.",
+        envvar="NEXTMV_SWITCHBACK_TEST_ID",
+        metavar="SWITCHBACK_TEST_ID",
+    ),
+]

nextmv/cloud/__init__.py

@@ -90,6 +90,16 @@ from .secrets import Secret as Secret
 from .secrets import SecretsCollection as SecretsCollection
 from .secrets import SecretsCollectionSummary as SecretsCollectionSummary
 from .secrets import SecretType as SecretType
+from .shadow import ShadowTest as ShadowTest
+from .shadow import ShadowTestMetadata as ShadowTestMetadata
+from .shadow import StartEvents as StartEvents
+from .shadow import TerminationEvents as TerminationEvents
+from .shadow import TestComparison as TestComparison
+from .switchback import SwitchbackPlan as SwitchbackPlan
+from .switchback import SwitchbackPlanUnit as SwitchbackPlanUnit
+from .switchback import SwitchbackTest as SwitchbackTest
+from .switchback import SwitchbackTestMetadata as SwitchbackTestMetadata
+from .switchback import TestComparisonSingle as TestComparisonSingle
 from .url import DownloadURL as DownloadURL
 from .url import UploadURL as UploadURL
 from .version import Version as Version

nextmv/cloud/application/__init__.py

@@ -41,6 +41,8 @@ from nextmv.cloud.application._instance import ApplicationInstanceMixin
 from nextmv.cloud.application._managed_input import ApplicationManagedInputMixin
 from nextmv.cloud.application._run import ApplicationRunMixin
 from nextmv.cloud.application._secrets import ApplicationSecretsMixin
+from nextmv.cloud.application._shadow import ApplicationShadowMixin
+from nextmv.cloud.application._switchback import ApplicationSwitchbackMixin
 from nextmv.cloud.application._utils import _is_not_exist_error
 from nextmv.cloud.application._version import ApplicationVersionMixin
 from nextmv.cloud.client import Client
@@ -100,6 +102,8 @@ class Application(
     ApplicationVersionMixin,
     ApplicationInputSetMixin,
     ApplicationManagedInputMixin,
+    ApplicationShadowMixin,
+    ApplicationSwitchbackMixin,
 ):
     """
     A published decision model that can be executed.

nextmv/cloud/application/_shadow.py

@@ -0,0 +1,314 @@
+"""
+Application mixin for managing shadow tests.
+"""
+
+from typing import TYPE_CHECKING
+
+from nextmv.cloud.shadow import ShadowTest, ShadowTestMetadata, StartEvents, TerminationEvents
+from nextmv.run import Run
+from nextmv.safe import safe_id
+
+if TYPE_CHECKING:
+    from . import Application
+
+
+class ApplicationShadowMixin:
+    """
+    Mixin class for managing shadow tests within an application.
+    """
+
+    def shadow_test(self: "Application", shadow_test_id: str) -> ShadowTest:
+        """
+        Get a shadow test. This method also returns the runs of the shadow
+        test under the `.runs` attribute.
+
+        Parameters
+        ----------
+        shadow_test_id : str
+            ID of the shadow test.
+
+        Returns
+        -------
+        ShadowTest
+            The requested shadow test details.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> shadow_test = app.shadow_test("shadow-123")
+        >>> print(shadow_test.name)
+        'My Shadow Test'
+        """
+
+        response = self.client.request(
+            method="GET",
+            endpoint=f"{self.experiments_endpoint}/shadow/{shadow_test_id}",
+        )
+
+        exp = ShadowTest.from_dict(response.json())
+
+        runs_response = self.client.request(
+            method="GET",
+            endpoint=f"{self.experiments_endpoint}/shadow/{shadow_test_id}/runs",
+        )
+
+        runs = [Run.from_dict(run) for run in runs_response.json().get("runs", [])]
+        exp.runs = runs
+
+        return exp
+
+    def shadow_test_metadata(self: "Application", shadow_test_id: str) -> ShadowTestMetadata:
+        """
+        Get metadata for a shadow test.
+
+        Parameters
+        ----------
+        shadow_test_id : str
+            ID of the shadow test.
+
+        Returns
+        -------
+        ShadowTestMetadata
+            The requested shadow test metadata.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> metadata = app.shadow_test_metadata("shadow-123")
+        >>> print(metadata.name)
+        'My Shadow Test'
+        """
+
+        response = self.client.request(
+            method="GET",
+            endpoint=f"{self.experiments_endpoint}/shadow/{shadow_test_id}/metadata",
+        )
+
+        return ShadowTestMetadata.from_dict(response.json())
+
+    def delete_shadow_test(self: "Application", shadow_test_id: str) -> None:
+        """
+        Delete a shadow test.
+
+        Deletes a shadow test along with all the associated information,
+        such as its runs.
+
+        Parameters
+        ----------
+        shadow_test_id : str
+            ID of the shadow test to delete.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> app.delete_shadow_test("shadow-123")
+        """
+
+        _ = self.client.request(
+            method="DELETE",
+            endpoint=f"{self.experiments_endpoint}/shadow/{shadow_test_id}",
+        )
+
+    def list_shadow_tests(self: "Application") -> list[ShadowTest]:
+        """
+        List all shadow tests.
+
+        Returns
+        -------
+        list[ShadowTest]
+            List of shadow tests.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+        """
+
+        response = self.client.request(
+            method="GET",
+            endpoint=f"{self.experiments_endpoint}/shadow",
+        )
+
+        return [ShadowTest.from_dict(shadow_test) for shadow_test in response.json()]
+
+    def new_shadow_test(
+        self: "Application",
+        comparisons: dict[str, list[str]],
+        termination_events: TerminationEvents,
+        shadow_test_id: str | None = None,
+        name: str | None = None,
+        description: str | None = None,
+        start_events: StartEvents | None = None,
+    ) -> ShadowTest:
+        """
+        Create a new shadow test in draft mode. Shadow tests are experiments
+        that run instances in parallel to compare their results.
+
+        Use the `comparisons` parameter to define how to set up instance
+        comparisons. The keys of the `comparisons` dictionary are the baseline
+        instance IDs, and the values are the candidate lists of instance IDs to
+        compare against the respective baseline.
+
+        You may specify `start_events` to make the shadow test start at a
+        specific time. Alternatively, you may use the `start_shadow_test`
+        method to start the test.
+
+        The `termination_events` parameter is required and provides control
+        over when the shadow test should terminate. Alternatively, you may use
+        the `stop_shadow_test` method to stop the test.
+
+        Parameters
+        ----------
+        comparisons : dict[str, list[str]]
+            Dictionary defining the baseline and candidate instance IDs for
+            comparison. The keys are baseline instance IDs, and the values are
+            lists of candidate instance IDs to compare against the respective
+            baseline.
+        termination_events : TerminationEvents
+            Termination events for the shadow test.
+        shadow_test_id : Optional[str]
+            ID of the shadow test. Will be generated if not provided.
+        name : Optional[str]
+            Name of the shadow test. If not provided, the ID will be used as
+            the name.
+        description : Optional[str]
+            Optional description of the shadow test.
+        start_events : Optional[StartEvents]
+            Start events for the shadow test.
+
+        Returns
+        -------
+        ShadowTest
+            The created shadow test.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+        """
+
+        # Generate ID if not provided
+        if shadow_test_id is None:
+            shadow_test_id = safe_id("shadow")
+
+        # Use ID as name if name not provided
+        if name is None:
+            name = shadow_test_id
+
+        payload = {
+            "id": id,
+            "name": name,
+            "comparisons": comparisons,
+            "termination_events": termination_events.to_dict(),
+        }
+
+        if description is not None:
+            payload["description"] = description
+        if start_events is not None:
+            payload["start_events"] = start_events.to_dict()
+
+        response = self.client.request(
+            method="POST",
+            endpoint=f"{self.experiments_endpoint}/shadow",
+            payload=payload,
+        )
+
+        return ShadowTest.from_dict(response.json())
+
+    def start_shadow_test(self: "Application", shadow_test_id: str) -> None:
+        """
+        Start a shadow test. Create a shadow test in draft mode using the
+        `new_shadow_test` method, then use this method to start the test.
+
+        Parameters
+        ----------
+        shadow_test_id : str
+            ID of the shadow test to start.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+        """
+
+        _ = self.client.request(
+            method="PUT",
+            endpoint=f"{self.experiments_endpoint}/shadow/{shadow_test_id}/start",
+        )
+
+    def stop_shadow_test(self: "Application", shadow_test_id: str) -> None:
+        """
+        Stop a shadow test. The test should already have started before using
+        this method.
+
+        Parameters
+        ----------
+        shadow_test_id : str
+            ID of the shadow test to stop.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+        """
+
+        _ = self.client.request(
+            method="PUT",
+            endpoint=f"{self.experiments_endpoint}/shadow/{shadow_test_id}/stop",
+        )
+
+    def update_shadow_test(
+        self: "Application",
+        shadow_test_id: str,
+        name: str | None = None,
+        description: str | None = None,
+    ) -> ShadowTest:
+        """
+        Update a shadow test.
+
+        Parameters
+        ----------
+        shadow_test_id : str
+            ID of the shadow test to update.
+        name : Optional[str], default=None
+            Optional name of the shadow test.
+        description : Optional[str], default=None
+            Optional description of the shadow test.
+
+        Returns
+        -------
+        ShadowTest
+            The information with the updated shadow test.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+        """
+
+        payload = {}
+
+        if name is not None:
+            payload["name"] = name
+        if description is not None:
+            payload["description"] = description
+
+        response = self.client.request(
+            method="PATCH",
+            endpoint=f"{self.experiments_endpoint}/shadow/{shadow_test_id}",
+            payload=payload,
+        )
+
+        return ShadowTest.from_dict(response.json())