nextmv 1.0.0.dev2__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

@@ -204,3 +204,17 @@ ShadowTestIDOption = Annotated[
         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

@@ -95,6 +95,11 @@ 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

@@ -42,6 +42,7 @@ 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
@@ -102,6 +103,7 @@ class Application(
     ApplicationInputSetMixin,
     ApplicationManagedInputMixin,
     ApplicationShadowMixin,
+    ApplicationSwitchbackMixin,
 ):
     """
     A published decision model that can be executed.

nextmv/cloud/application/_switchback.py

@@ -0,0 +1,315 @@
+"""
+Application mixin for managing switchback tests.
+"""
+
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+from nextmv.cloud.switchback import SwitchbackTest, SwitchbackTestMetadata, TestComparisonSingle
+from nextmv.run import Run
+from nextmv.safe import safe_id
+
+if TYPE_CHECKING:
+    from . import Application
+
+
+class ApplicationSwitchbackMixin:
+    """
+    Mixin class for managing switchback tests within an application.
+    """
+
+    def switchback_test(self: "Application", switchback_test_id: str) -> SwitchbackTest:
+        """
+        Get a switchback test. This method also returns the runs of the switchback
+        test under the `.runs` attribute.
+
+        Parameters
+        ----------
+        switchback_test_id : str
+            ID of the switchback test.
+
+        Returns
+        -------
+        SwitchbackTest
+            The requested switchback test details.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> switchback_test = app.switchback_test("switchback-123")
+        >>> print(switchback_test.name)
+        'My Switchback Test'
+        """
+
+        response = self.client.request(
+            method="GET",
+            endpoint=f"{self.experiments_endpoint}/switchback/{switchback_test_id}",
+        )
+
+        exp = SwitchbackTest.from_dict(response.json())
+
+        runs_response = self.client.request(
+            method="GET",
+            endpoint=f"{self.experiments_endpoint}/switchback/{switchback_test_id}/runs",
+        )
+
+        runs = [Run.from_dict(run) for run in runs_response.json().get("runs", [])]
+        exp.runs = runs
+
+        return exp
+
+    def switchback_test_metadata(self: "Application", switchback_test_id: str) -> SwitchbackTestMetadata:
+        """
+        Get metadata for a switchback test.
+
+        Parameters
+        ----------
+        switchback_test_id : str
+            ID of the switchback test.
+
+        Returns
+        -------
+        SwitchbackTestMetadata
+            The requested switchback test metadata.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> metadata = app.switchback_test_metadata("switchback-123")
+        >>> print(metadata.name)
+        'My Switchback Test'
+        """
+
+        response = self.client.request(
+            method="GET",
+            endpoint=f"{self.experiments_endpoint}/switchback/{switchback_test_id}/metadata",
+        )
+
+        return SwitchbackTestMetadata.from_dict(response.json())
+
+    def delete_switchback_test(self: "Application", switchback_test_id: str) -> None:
+        """
+        Delete a switchback test.
+
+        Deletes a switchback test along with all the associated information,
+        such as its runs.
+
+        Parameters
+        ----------
+        switchback_test_id : str
+            ID of the switchback test to delete.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> app.delete_switchback_test("switchback-123")
+        """
+
+        _ = self.client.request(
+            method="DELETE",
+            endpoint=f"{self.experiments_endpoint}/switchback/{switchback_test_id}",
+        )
+
+    def list_switchback_tests(self: "Application") -> list[SwitchbackTest]:
+        """
+        List all switchback tests.
+
+        Returns
+        -------
+        list[SwitchbackTest]
+            List of switchback tests.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+        """
+
+        response = self.client.request(
+            method="GET",
+            endpoint=f"{self.experiments_endpoint}/switchback",
+        )
+
+        return [SwitchbackTest.from_dict(switchback_test) for switchback_test in response.json().get("items", [])]
+
+    def new_switchback_test(
+        self: "Application",
+        comparison: TestComparisonSingle,
+        unit_duration_minutes: float,
+        units: int,
+        switchback_test_id: str | None = None,
+        name: str | None = None,
+        description: str | None = None,
+        start: datetime | None = None,
+    ) -> SwitchbackTest:
+        """
+        Create a new switchback test in draft mode. Switchback tests are
+        experiments that alternate between different instances over specified
+        time intervals.
+
+        Use the `comparison` parameter to define how to set up the instance
+        comparison. The test will alternate between the baseline and candidate
+        instances defined in the comparison.
+
+        You may specify `start` to make the switchback test start at a
+        specific time. Alternatively, you may use the `start_switchback_test`
+        method to start the test.
+
+        Parameters
+        ----------
+        comparison : TestComparisonSingle
+            Comparison defining the baseline and candidate instances.
+        unit_duration_minutes : float
+            Duration of each interval in minutes.
+        units : int
+            Total number of intervals in the switchback test.
+        switchback_test_id : Optional[str], default=None
+            Optional ID for the switchback test. Will be generated if not
+            provided.
+        name : Optional[str], default=None
+            Optional name of the switchback test. If not provided, the ID will
+            be used as the name.
+        description : Optional[str], default=None
+            Optional description of the switchback test.
+        start : Optional[datetime], default=None
+            Optional scheduled start time for the switchback test.
+
+        Returns
+        -------
+        SwitchbackTest
+            The created switchback test.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+        """
+
+        # Generate ID if not provided
+        if switchback_test_id is None:
+            switchback_test_id = safe_id("switchback")
+
+        # Use ID as name if name not provided
+        if name is None:
+            name = switchback_test_id
+
+        payload = {
+            "id": id,
+            "name": name,
+            "comparison": comparison,
+            "generate_random_plan": {
+                "unit_duration_minutes": unit_duration_minutes,
+                "units": units,
+            },
+        }
+
+        if description is not None:
+            payload["description"] = description
+        if start is not None:
+            payload["generate_random_plan"]["start"] = start.isoformat()
+
+        response = self.client.request(
+            method="POST",
+            endpoint=f"{self.experiments_endpoint}/switchback",
+            payload=payload,
+        )
+
+        return SwitchbackTest.from_dict(response.json())
+
+    def start_switchback_test(self: "Application", switchback_test_id: str) -> None:
+        """
+        Start a switchback test. Create a switchback test in draft mode using the
+        `new_switchback_test` method, then use this method to start the test.
+
+        Parameters
+        ----------
+        switchback_test_id : str
+            ID of the switchback test to start.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+        """
+
+        _ = self.client.request(
+            method="PUT",
+            endpoint=f"{self.experiments_endpoint}/switchback/{switchback_test_id}/start",
+        )
+
+    def stop_switchback_test(self: "Application", switchback_test_id: str) -> None:
+        """
+        Stop a switchback test. The test should already have started before using
+        this method.
+
+        Parameters
+        ----------
+        switchback_test_id : str
+            ID of the switchback test to stop.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+        """
+
+        _ = self.client.request(
+            method="PUT",
+            endpoint=f"{self.experiments_endpoint}/switchback/{switchback_test_id}/stop",
+        )
+
+    def update_switchback_test(
+        self: "Application",
+        switchback_test_id: str,
+        name: str | None = None,
+        description: str | None = None,
+    ) -> SwitchbackTest:
+        """
+        Update a switchback test.
+
+        Parameters
+        ----------
+        switchback_test_id : str
+            ID of the switchback test to update.
+        name : Optional[str], default=None
+            Optional name of the switchback test.
+        description : Optional[str], default=None
+            Optional description of the switchback test.
+
+        Returns
+        -------
+        SwitchbackTest
+            The information with the updated switchback 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}/switchback/{switchback_test_id}",
+            payload=payload,
+        )
+
+        return SwitchbackTest.from_dict(response.json())

nextmv/cloud/switchback.py

@@ -0,0 +1,189 @@
+"""
+Classes for working with Nextmv Cloud switchback tests.
+
+This module provides classes for interacting with switchback tests in Nextmv Cloud.
+It details the core data structures for these types of experiments.
+
+Classes
+-------
+TestComparisonSingle
+    A structure to define a single comparison for tests.
+SwitchbackPlanUnit
+    A structure to define a single unit in the switchback plan.
+SwitchbackPlan
+    A structure to define the switchback plan for tests.
+SwitchbackTestMetadata
+    Metadata for a Nextmv Cloud switchback test.
+SwitchbackTest
+    A Nextmv Cloud switchback test definition.
+"""
+
+from datetime import datetime
+
+from pydantic import AliasChoices, Field
+
+from nextmv.base_model import BaseModel
+from nextmv.cloud.batch_experiment import ExperimentStatus
+from nextmv.run import Run
+
+
+class TestComparisonSingle(BaseModel):
+    """
+    A structure to define a single comparison for tests.
+
+    You can import the `TestComparisonSingle` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import TestComparisonSingle
+    ```
+
+    Parameters
+    ----------
+    baseline_instance_id : str
+        ID of the baseline instance for comparison.
+    candidate_instance_id : str
+        ID of the candidate instance for comparison.
+    """
+
+    baseline_instance_id: str
+    """ID of the baseline instance for comparison."""
+    candidate_instance_id: str
+    """ID of the candidate instance for comparison."""
+
+
+class SwitchbackPlanUnit(BaseModel):
+    """
+    A structure to define a single unit in the switchback plan.
+
+    You can import the `SwitchbackPlanUnit` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import SwitchbackPlanUnit
+    ```
+
+    Parameters
+    ----------
+    duration_minutes : float
+        Duration of this interval in minutes.
+    instance_id : str
+        ID of the instance to run during this unit.
+    index : int
+        Index of this unit in the switchback plan.
+    """
+
+    duration_minutes: float
+    """Duration of this interval in minutes."""
+    instance_id: str
+    """ID of the instance to run during this unit."""
+    index: int
+    """Index of this unit in the switchback plan."""
+
+
+class SwitchbackPlan(BaseModel):
+    """
+    A structure to define the switchback plan for tests.
+
+    You can import the `SwitchbackPlan` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import SwitchbackPlan
+    ```
+
+    Parameters
+    ----------
+    interval_duration_seconds : int
+        Duration of each interval in seconds.
+    total_intervals : int
+        Total number of intervals in the switchback test.
+    """
+
+    start: datetime | None = None
+    """Start time of the switchback test."""
+    units: list[SwitchbackPlanUnit] | None = None
+    """List of switchback plan units."""
+
+
+class SwitchbackTestMetadata(BaseModel):
+    """
+    Metadata for a Nextmv Cloud switchback test.
+
+    You can import the `SwitchbackTestMetadata` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import SwitchbackTestMetadata
+    ```
+
+    Parameters
+    ----------
+    switchback_test_id : str, optional
+        The unique identifier of the switchback test.
+    name : str, optional
+        Name of the switchback test.
+    description : str, optional
+        Description of the switchback test.
+    app_id : str, optional
+        ID of the application to which the switchback test belongs.
+    created_at : datetime, optional
+        Creation date of the switchback test.
+    updated_at : datetime, optional
+        Last update date of the switchback test.
+    status : ExperimentStatus, optional
+        The current status of the switchback test.
+    """
+
+    switchback_test_id: str | None = Field(
+        serialization_alias="id",
+        validation_alias=AliasChoices("id", "switchback_test_id"),
+        default=None,
+    )
+    """The unique identifier of the switchback test."""
+    name: str | None = None
+    """Name of the switchback test."""
+    description: str | None = None
+    """Description of the switchback test."""
+    app_id: str | None = None
+    """ID of the application to which the switchback test belongs."""
+    created_at: datetime | None = None
+    """Creation date of the switchback test."""
+    updated_at: datetime | None = None
+    """Last update date of the switchback test."""
+    status: ExperimentStatus | None = None
+    """The current status of the switchback test."""
+
+
+class SwitchbackTest(SwitchbackTestMetadata):
+    """
+    A Nextmv Cloud switchback test definition.
+
+    A switchback test is a type of experiment where runs are executed in
+    sequential intervals, alternating between different instances to compare
+    their performance.
+
+    You can import the `SwitchbackTest` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import SwitchbackTest
+    ```
+
+    Parameters
+    ----------
+    completed_at : datetime, optional
+        Completion date of the switchback test, if applicable.
+    comparison : TestComparisonSingle, optional
+        Test comparison defined in the switchback test.
+    start_events : StartEvents, optional
+        Start events for the switchback test.
+    termination_events : TerminationEvents, optional
+        Termination events for the switchback test.
+    """
+
+    started_at: datetime | None = None
+    """Start date of the switchback test, if applicable."""
+    completed_at: datetime | None = None
+    """Completion date of the switchback test, if applicable."""
+    comparison: TestComparisonSingle | None = None
+    """Test comparison defined in the switchback test."""
+    plan: SwitchbackPlan | None = None
+    """Switchback plan defining the intervals and instance switching."""
+    runs: list[Run] | None = None
+    """List of runs in the switchback test."""

{nextmv-1.0.0.dev2.dist-info → nextmv-1.0.0.dev3.dist-info}/METADATA

@@ -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/