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

nextmv/cloud/application/_switchback.py

@@ -0,0 +1,332 @@
+"""
+Application mixin for managing switchback tests.
+"""
+
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+from nextmv.cloud.shadow import StopIntent
+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 or name == "":
+            name = switchback_test_id
+
+        payload = {
+            "id": switchback_test_id,
+            "name": name,
+            "comparison": comparison.to_dict(),
+            "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, intent: StopIntent) -> 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.
+
+        intent : StopIntent
+            Intent for stopping the switchback test.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+        """
+
+        payload = {
+            "intent": intent.value,
+        }
+
+        _ = self.client.request(
+            method="PUT",
+            endpoint=f"{self.experiments_endpoint}/switchback/{switchback_test_id}/stop",
+            payload=payload,
+        )
+
+    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/_utils.py

@@ -0,0 +1,54 @@
+"""
+Module for general utility methods for Application.
+
+Avoid abusing this module, as you should try to keep domain-specific
+functionality together and not rely on generic utilities.
+"""
+
+import requests
+
+
+def _is_not_exist_error(e: requests.HTTPError) -> bool:
+    """
+    Check if the error is a known 404 Not Found error.
+
+    This is an internal helper function that examines HTTPError objects to determine
+    if they represent a "Not Found" (404) condition, either directly or through a
+    nested exception.
+
+    Parameters
+    ----------
+    e : requests.HTTPError
+        The HTTP error to check.
+
+    Returns
+    -------
+    bool
+        True if the error is a 404 Not Found error, False otherwise.
+
+    Examples
+    --------
+    >>> try:
+    ...     response = requests.get('https://api.example.com/nonexistent')
+    ...     response.raise_for_status()
+    ... except requests.HTTPError as err:
+    ...     if _is_not_exist_error(err):
+    ...         print("Resource does not exist")
+    ...     else:
+    ...         print("Another error occurred")
+    Resource does not exist
+    """
+    if (
+        # Check whether the error is caused by a 404 status code - meaning the app does not exist.
+        (hasattr(e, "response") and hasattr(e.response, "status_code") and e.response.status_code == 404)
+        or
+        # Check a possibly nested exception as well.
+        (
+            hasattr(e, "__cause__")
+            and hasattr(e.__cause__, "response")
+            and hasattr(e.__cause__.response, "status_code")
+            and e.__cause__.response.status_code == 404
+        )
+    ):
+        return True
+    return False

nextmv/cloud/application/_version.py

@@ -0,0 +1,304 @@
+"""
+Application mixin for managing app versions.
+"""
+
+from typing import TYPE_CHECKING
+
+import requests
+
+from nextmv.cloud.application._utils import _is_not_exist_error
+from nextmv.cloud.version import Version
+from nextmv.safe import safe_id
+
+if TYPE_CHECKING:
+    from . import Application
+
+
+class ApplicationVersionMixin:
+    """
+    Mixin class for managing app versions within an application.
+    """
+
+    def delete_version(self: "Application", version_id: str) -> None:
+        """
+        Delete a version.
+
+        Permanently removes the specified version from the application.
+
+        Parameters
+        ----------
+        version_id : str
+            ID of the version to delete.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> app.delete_version("v1.0.0")  # Permanently deletes the version
+        """
+
+        _ = self.client.request(
+            method="DELETE",
+            endpoint=f"{self.endpoint}/versions/{version_id}",
+        )
+
+    def list_versions(self: "Application") -> list[Version]:
+        """
+        List all versions.
+
+        Returns
+        -------
+        list[Version]
+            List of all versions associated with this application.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> versions = app.list_versions()
+        >>> for version in versions:
+        ...     print(version.name)
+        'v1.0.0'
+        'v1.1.0'
+        """
+
+        response = self.client.request(
+            method="GET",
+            endpoint=f"{self.endpoint}/versions",
+        )
+
+        return [Version.from_dict(version) for version in response.json()]
+
+    def new_version(
+        self: "Application",
+        id: str | None = None,
+        name: str | None = None,
+        description: str | None = None,
+        exist_ok: bool = False,
+    ) -> Version:
+        """
+        Create a new version using the latest pushed executable.
+
+        This method creates a new version of the application using the current development
+        binary. Application versions represent different iterations of your application's
+        code and configuration that can be deployed.
+
+        Parameters
+        ----------
+        id : Optional[str], default=None
+            ID of the version. If not provided, a unique ID will be generated.
+        name : Optional[str], default=None
+            Name of the version. If not provided, a name will be generated.
+        description : Optional[str], default=None
+            Description of the version. If not provided, a description will be generated.
+        exist_ok : bool, default=False
+            If True and a version with the same ID already exists,
+            return the existing version instead of creating a new one.
+            If True, the 'id' parameter must be provided.
+
+        Returns
+        -------
+        Version
+            The newly created (or existing) version.
+
+        Raises
+        ------
+        ValueError
+            If exist_ok is True and id is None.
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> # Create a new version
+        >>> version = app.new_version(
+        ...     id="v1.0.0",
+        ...     name="Initial Release",
+        ...     description="First stable version"
+        ... )
+        >>> print(version.id)
+        'v1.0.0'
+
+        >>> # Get or create a version with exist_ok
+        >>> version = app.new_version(
+        ...     id="v1.0.0",
+        ...     exist_ok=True
+        ... )
+        """
+
+        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 or id == "":
+            id = safe_id(prefix="version")
+
+        if name is None or name == "":
+            name = id
+
+        payload = {
+            "id": id,
+            "name": name,
+        }
+
+        if description is not None:
+            payload["description"] = description
+
+        response = self.client.request(
+            method="POST",
+            endpoint=f"{self.endpoint}/versions",
+            payload=payload,
+        )
+
+        return Version.from_dict(response.json())
+
+    def update_version(
+        self: "Application",
+        version_id: str,
+        name: str | None = None,
+        description: str | None = None,
+    ) -> Version:
+        """
+        Update a version.
+
+        This method updates a specific version of the application. It mimics a
+        PATCH operation by allowing you to update only the name and/or description
+        fields while preserving all other fields.
+
+        Parameters
+        ----------
+        version_id : str
+            ID of the version to update.
+        name : Optional[str], default=None
+            Optional new name for the version.
+        description : Optional[str], default=None
+            Optional new description for the version.
+
+        Returns
+        -------
+        Version
+            The updated version object.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> # Update a version's name
+        >>> updated = app.update_version("v1.0.0", name="Version 1.0")
+        >>> print(updated.name)
+        'Version 1.0'
+
+        >>> # Update a version's description
+        >>> updated = app.update_version("v1.0.0", description="Initial release")
+        >>> print(updated.description)
+        'Initial release'
+        """
+
+        version = self.version(version_id=version_id)
+        version_dict = version.to_dict()
+        payload = version_dict.copy()
+
+        if name is not None:
+            payload["name"] = name
+        if description is not None:
+            payload["description"] = description
+
+        response = self.client.request(
+            method="PUT",
+            endpoint=f"{self.endpoint}/versions/{version_id}",
+            payload=payload,
+        )
+
+        return Version.from_dict(response.json())
+
+    def version(self: "Application", version_id: str) -> Version:
+        """
+        Get a version.
+
+        Retrieves a specific version of the application by its ID. Application versions
+        represent different iterations of your application's code and configuration.
+
+        Parameters
+        ----------
+        version_id : str
+            ID of the version to retrieve.
+
+        Returns
+        -------
+        Version
+            The version object containing details about the requested application version.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> # Retrieve a specific version
+        >>> version = app.version("v1.0.0")
+        >>> print(version.id)
+        'v1.0.0'
+        >>> print(version.name)
+        'Initial Release'
+        """
+
+        response = self.client.request(
+            method="GET",
+            endpoint=f"{self.endpoint}/versions/{version_id}",
+        )
+
+        return Version.from_dict(response.json())
+
+    def version_exists(self: "Application", version_id: str) -> bool:
+        """
+        Check if a version exists.
+
+        This method checks if a specific version of the application exists by
+        attempting to retrieve it. It handles HTTP errors for non-existent versions
+        and returns a boolean indicating existence.
+
+        Parameters
+        ----------
+        version_id : str
+            ID of the version to check for existence.
+
+        Returns
+        -------
+        bool
+            True if the version exists, False otherwise.
+
+        Raises
+        ------
+        requests.HTTPError
+            If an HTTP error occurs that is not related to the non-existence
+            of the version.
+
+        Examples
+        --------
+        >>> # Check if a version exists
+        >>> exists = app.version_exists("v1.0.0")
+        >>> if exists:
+        ...     print("Version exists!")
+        ... else:
+        ...     print("Version does not exist.")
+        """
+
+        try:
+            self.version(version_id=version_id)
+            return True
+        except requests.HTTPError as e:
+            if _is_not_exist_error(e):
+                return False
+            raise e

nextmv/cloud/batch_experiment.py

@@ -30,7 +30,9 @@ class ExperimentStatus(str, Enum):
 
     You can import the `ExperimentStatus` class directly from `cloud`:
 
-    ```python from nextmv.cloud import ExperimentStatus ```
+    ```python
+    from nextmv.cloud import ExperimentStatus
+    ```
 
     This enum represents the comprehensive set of possible states for an
     experiment in Nextmv Cloud.
@@ -223,7 +225,9 @@ class BatchExperimentRun(BaseModel):
     Parameters
     ----------
     input_id : str
-        ID of the input used for the experiment.
+        ID of the input used for the experiment. If a managed input is used,
+        this should be the ID of the managed input. If `input_set_id` is provided
+        for the run, this should be the ID of an input within that input set.
     option_set : str
         Option set used for the experiment. Defaults to None.
     instance_id : str, optional