nextmv 1.0.0.dev2__py3-none-any.whl → 1.0.0.dev4__py3-none-any.whl

nextmv/cloud/application/_switchback.py

@@ -0,0 +1,323 @@
+"""
+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. The value must be between 1
+            and 10080.
+        units : int
+            Total number of intervals in the switchback test. The value must be
+            between 1 and 1000.
+        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.
+        """
+
+        if unit_duration_minutes < 1 or unit_duration_minutes > 10080:
+            raise ValueError("unit_duration_minutes must be between 1 and 10080")
+
+        if units < 1 or units > 1000:
+            raise ValueError("units must be between 1 and 1000")
+
+        # 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": switchback_test_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/application/_version.py

@@ -132,14 +132,15 @@ class ApplicationVersionMixin:
         ... )
         """
 
-        if exist_ok and id is None:
+        if exist_ok and (id is None or id == ""):
             raise ValueError("If exist_ok is True, id must be provided")
 
         if exist_ok and self.version_exists(version_id=id):
             return self.version(version_id=id)
 
-        if id is None:
+        if id is None or id == "":
             id = safe_id(prefix="version")
+
         if name is None:
             name = id
 

nextmv/cloud/shadow.py

@@ -90,7 +90,7 @@ class TerminationEvents(BaseModel):
 
     maximum_runs: int
     """
-    Maximum number of runs for the test. Min should be 1, max should be 300.
+    Maximum number of runs for the test. Value must be between 1 and 300.
     """
     time: datetime | None = None
     """
@@ -99,8 +99,8 @@ class TerminationEvents(BaseModel):
     """
 
     def model_post_init(self, __context):
-        if self.maximum_runs < 1:
-            raise ValueError("maximum_runs must be at least 1")
+        if self.maximum_runs < 1 or self.maximum_runs > 300:
+            raise ValueError("maximum_runs must be between 1 and 300")
 
 
 class ShadowTestMetadata(BaseModel):
@@ -151,7 +151,10 @@ class ShadowTestMetadata(BaseModel):
     """The current status of the shadow test."""
 
 
-class ShadowTest(ShadowTestMetadata):
+# This class uses some fields defined in ShadowTestMetadata. We are not
+# using inheritance to help the user understand the full structure when using
+# tools like intellisense.
+class ShadowTest(BaseModel):
     """
     A Nextmv Cloud shadow test definition.
 
@@ -166,6 +169,20 @@ class ShadowTest(ShadowTestMetadata):
 
     Parameters
     ----------
+    shadow_test_id : str, optional
+        The unique identifier of the shadow test.
+    name : str, optional
+        Name of the shadow test.
+    description : str, optional
+        Description of the shadow test.
+    app_id : str, optional
+        ID of the application to which the shadow test belongs.
+    created_at : datetime, optional
+        Creation date of the shadow test.
+    updated_at : datetime, optional
+        Last update date of the shadow test.
+    status : ExperimentStatus, optional
+        The current status of the shadow test.
     completed_at : datetime, optional
         Completion date of the shadow test, if applicable.
     comparisons : list[TestComparison], optional
@@ -174,8 +191,30 @@ class ShadowTest(ShadowTestMetadata):
         Start events for the shadow test.
     termination_events : TerminationEvents, optional
         Termination events for the shadow test.
+    grouped_distributional_summaries : list[dict[str, Any]], optional
+        Grouped distributional summaries of the shadow test.
+    runs : list[Run], optional
+        List of runs in the shadow test.
     """
 
+    shadow_test_id: str | None = Field(
+        serialization_alias="id",
+        validation_alias=AliasChoices("id", "shadow_test_id"),
+        default=None,
+    )
+    """The unique identifier of the shadow test."""
+    name: str | None = None
+    """Name of the shadow test."""
+    description: str | None = None
+    """Description of the shadow test."""
+    app_id: str | None = None
+    """ID of the application to which the shadow test belongs."""
+    created_at: datetime | None = None
+    """Creation date of the shadow test."""
+    updated_at: datetime | None = None
+    """Last update date of the shadow test."""
+    status: ExperimentStatus | None = None
+    """The current status of the shadow test."""
     completed_at: datetime | None = None
     """Completion date of the shadow test, if applicable."""
     comparisons: list[TestComparison] | None = None

nextmv/cloud/switchback.py

@@ -0,0 +1,226 @@
+"""
+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
+    ----------
+    start : datetime, optional
+        Start time of the switchback test.
+    units : list[SwitchbackPlanUnit], optional
+        List of switchback plan units.
+    """
+
+    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."""
+
+
+# This class uses some fields defined in SwitchbackTestMetadata. We are not
+# using inheritance to help the user understand the full structure when using
+# tools like intellisense.
+class SwitchbackTest(BaseModel):
+    """
+    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
+    ----------
+    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.
+    started_at : datetime, optional
+        Start date of the switchback test, if applicable.
+    completed_at : datetime, optional
+        Completion date of the switchback test, if applicable.
+    comparison : TestComparisonSingle, optional
+        Test comparison defined in the switchback test.
+    plan : SwitchbackPlan, optional
+        Switchback plan defining the intervals and instance switching.
+    runs : list[Run], optional
+        List of runs in 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."""
+    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.dev4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nextmv
-Version: 1.0.0.dev2
+Version: 1.0.0.dev4
 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/