nextmv 0.39.0.dev1__py3-none-any.whl → 1.0.0__py3-none-any.whl

nextmv/cloud/shadow.py

@@ -0,0 +1,254 @@
+"""
+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 enum import Enum
+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. Value must be between 1 and 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 or self.maximum_runs > 300:
+            raise ValueError("maximum_runs must be between 1 and 300")
+
+
+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."""
+
+
+# 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.
+
+    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
+    ----------
+    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
+        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.
+    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
+    """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."""
+
+
+class StopIntent(str, Enum):
+    """
+    Intent for stopping a shadow test.
+
+    You can import the `StopIntent` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import StopIntent
+    ```
+
+    Attributes
+    ----------
+    complete : str
+        The test is marked as complete.
+    cancel : str
+        The test is canceled.
+    """
+
+    complete = "complete"
+    """The test is marked as complete."""
+    cancel = "cancel"
+    """The test is canceled."""

nextmv/cloud/switchback.py

@@ -0,0 +1,228 @@
+"""
+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.
+    """
+
+    __test__ = False  # Prevents pytest from collecting this class as a test case
+
+    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/deprecated.py

@@ -1,4 +1,5 @@
-"""Utilities for handling deprecated functionality within the Nextmv Python SDK.
+"""
+Utilities for handling deprecated functionality within the Nextmv Python SDK.
 
 This module provides tools to mark functions, methods, or features as deprecated,
 emitting appropriate warnings to users. These warnings inform users that the
@@ -13,7 +14,8 @@ import warnings
 
 
 def deprecated(name: str, reason: str) -> None:
-    """Mark functionality as deprecated with a warning message.
+    """
+    Mark functionality as deprecated with a warning message.
 
     This function emits a DeprecationWarning when called, indicating that
     the functionality will be removed in a future release.
@@ -40,7 +42,7 @@ def deprecated(name: str, reason: str) -> None:
 
     warnings.simplefilter("always", DeprecationWarning)
     warnings.warn(
-        f"{name}: {reason}. This functionality will be removed in a future release",
+        f"{name}: {reason}. This functionality will be removed in the next major release.",
         category=DeprecationWarning,
         stacklevel=2,
     )