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

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/shadow.py

@@ -0,0 +1,190 @@
+"""
+Classes for working with Nextmv Cloud shadow tests.
+
+This module provides classes for interacting with shadow tests in Nextmv Cloud.
+It details the core data structures for these types of experiments.
+
+Classes
+-------
+TestComparison
+    A structure to define comparison parameters for tests.
+StartEvents
+    A structure to define start events for tests.
+TerminationEvents
+    A structure to define termination events for tests.
+ShadowTestMetadata
+    Metadata for a Nextmv Cloud shadow test.
+ShadowTest
+    A Nextmv Cloud shadow test definition.
+"""
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import AliasChoices, Field
+
+from nextmv.base_model import BaseModel
+from nextmv.cloud.batch_experiment import ExperimentStatus
+from nextmv.run import Run
+
+
+class TestComparison(BaseModel):
+    """
+    A structure to define comparison parameters for tests.
+
+    You can import the `TestComparison` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import TestComparison
+    ```
+
+    Parameters
+    ----------
+    baseline_instance_id : str
+        ID of the baseline instance for comparison.
+    candidate_instance_ids : list[str]
+        List of candidate instance IDs to compare against the baseline.
+    """
+
+    baseline_instance_id: str
+    """ID of the baseline instance for comparison."""
+    candidate_instance_ids: list[str]
+    """List of candidate instance IDs to compare against the baseline."""
+
+
+class StartEvents(BaseModel):
+    """
+    A structure to define start events for tests.
+
+    You can import the `StartEvents` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import StartEvents
+    ```
+
+    Parameters
+    ----------
+    time : datetime, optional
+        Scheduled time for the test to start.
+    """
+
+    time: datetime | None = None
+    """Scheduled time for the test to start."""
+
+
+class TerminationEvents(BaseModel):
+    """
+    A structure to define termination events for tests.
+
+    You can import the `TerminationEvents` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import TerminationEvents
+    ```
+
+    Parameters
+    ----------
+    time : datetime, optional
+        Scheduled time for the test to terminate.
+    """
+
+    maximum_runs: int
+    """
+    Maximum number of runs for the test. Min should be 1, max should be 300.
+    """
+    time: datetime | None = None
+    """
+    Scheduled time for the test to terminate. A zero value means no
+    limit.
+    """
+
+    def model_post_init(self, __context):
+        if self.maximum_runs < 1:
+            raise ValueError("maximum_runs must be at least 1")
+
+
+class ShadowTestMetadata(BaseModel):
+    """
+    Metadata for a Nextmv Cloud shadow test.
+
+    You can import the `ShadowTestMetadata` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import 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.
+    """
+
+    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."""
+
+
+class ShadowTest(ShadowTestMetadata):
+    """
+    A Nextmv Cloud shadow test definition.
+
+    A shadow test is a type of experiment where runs are executed in parallel
+    to compare different instances.
+
+    You can import the `ShadowTest` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import ShadowTest
+    ```
+
+    Parameters
+    ----------
+    completed_at : datetime, optional
+        Completion date of the shadow test, if applicable.
+    comparisons : list[TestComparison], optional
+        List of test comparisons defined in the shadow test.
+    start_events : StartEvents, optional
+        Start events for the shadow test.
+    termination_events : TerminationEvents, optional
+        Termination events for the shadow test.
+    """
+
+    completed_at: datetime | None = None
+    """Completion date of the shadow test, if applicable."""
+    comparisons: list[TestComparison] | None = None
+    """List of test comparisons defined in the shadow test."""
+    start_events: StartEvents | None = None
+    """Start events for the shadow test."""
+    termination_events: TerminationEvents | None = None
+    """Termination events for the shadow test."""
+    grouped_distributional_summaries: list[dict[str, Any]] | None = None
+    """Grouped distributional summaries of the shadow test."""
+    runs: list[Run] | None = None
+    """List of runs in the shadow test."""

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.dev1.dist-info → nextmv-1.0.0.dev3.dist-info}/METADATA

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