nextmv 0.40.0__py3-none-any.whl → 1.0.0.dev0__py3-none-any.whl

nextmv/cloud/application/_secrets.py

@@ -0,0 +1,294 @@
+"""
+Application mixin for managing app secrets.
+"""
+
+from typing import TYPE_CHECKING, Any
+
+from nextmv.cloud.secrets import Secret, SecretsCollection, SecretsCollectionSummary
+from nextmv.safe import safe_id
+
+if TYPE_CHECKING:
+    from . import Application
+
+
+class ApplicationSecretsMixin:
+    """
+    Mixin class for managing app secrets within an application.
+    """
+
+    def delete_secrets_collection(self: "Application", secrets_collection_id: str) -> None:
+        """
+        Delete a secrets collection.
+
+        Parameters
+        ----------
+        secrets_collection_id : str
+            ID of the secrets collection to delete.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> app.delete_secrets_collection("secrets-123")
+        """
+
+        _ = self.client.request(
+            method="DELETE",
+            endpoint=f"{self.endpoint}/secrets/{secrets_collection_id}",
+        )
+
+    def list_secrets_collections(self: "Application") -> list[SecretsCollectionSummary]:
+        """
+        List all secrets collections.
+
+        Returns
+        -------
+        list[SecretsCollectionSummary]
+            List of all secrets collections associated with this application.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> collections = app.list_secrets_collections()
+        >>> for collection in collections:
+        ...     print(collection.name)
+        'API Keys'
+        'Database Credentials'
+        """
+
+        response = self.client.request(
+            method="GET",
+            endpoint=f"{self.endpoint}/secrets",
+        )
+
+        return [SecretsCollectionSummary.from_dict(secrets) for secrets in response.json()["items"]]
+
+    def new_secrets_collection(
+        self: "Application",
+        secrets: list[Secret],
+        id: str | None = None,
+        name: str | None = None,
+        description: str | None = None,
+    ) -> SecretsCollectionSummary:
+        """
+        Create a new secrets collection.
+
+        This method creates a new secrets collection with the provided secrets.
+        A secrets collection is a group of key-value pairs that can be used by
+        your application instances during execution. If no secrets are
+        provided, a ValueError is raised. If the `id` or `name` parameters are
+        not provided, they will be generated based on a unique ID.
+
+        Parameters
+        ----------
+        secrets : list[Secret]
+            List of secrets to use for the secrets collection. Each secret
+            should be an instance of the Secret class containing a key and
+            value.
+        id : str | None, default=None
+            ID of the secrets collection. If not provided, a unique ID will be
+            generated.
+        name : str | None, default=None
+            Name of the secrets collection. If not provided, the ID will be
+            used.
+        description : Optional[str], default=None
+            Description of the secrets collection.
+
+        Returns
+        -------
+        SecretsCollectionSummary
+            Summary of the secrets collection including its metadata.
+
+        Raises
+        ------
+        ValueError
+            If no secrets are provided.
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> # Create a new secrets collection with API keys
+        >>> from nextmv.cloud import Secret
+        >>> secrets = [
+        ...     Secret(
+        ...          location="API_KEY",
+        ...          value="your-api-key",
+        ...          secret_type=SecretType.ENV,
+        ...     ),
+        ...     Secret(
+        ...          location="DATABASE_URL",
+        ...          value="your-database-url",
+        ...          secret_type=SecretType.ENV,
+        ...     ),
+        ... ]
+        >>> collection = app.new_secrets_collection(
+        ...     secrets=secrets,
+        ...     id="api-secrets",
+        ...     name="API Secrets",
+        ...     description="Collection of API secrets for external services"
+        ... )
+        >>> print(collection.id)
+        'api-secrets'
+        """
+
+        if len(secrets) == 0:
+            raise ValueError("secrets must be provided")
+
+        if id is None or id == "":
+            id = safe_id(prefix="secrets")
+        if name is None or name == "":
+            name = id
+
+        payload = {
+            "id": id,
+            "name": name,
+            "secrets": [secret.to_dict() for secret in secrets],
+        }
+
+        if description is not None:
+            payload["description"] = description
+
+        response = self.client.request(
+            method="POST",
+            endpoint=f"{self.endpoint}/secrets",
+            payload=payload,
+        )
+
+        return SecretsCollectionSummary.from_dict(response.json())
+
+    def secrets_collection(self: "Application", secrets_collection_id: str) -> SecretsCollection:
+        """
+        Get a secrets collection.
+
+        This method retrieves a secrets collection by its ID. A secrets collection
+        is a group of key-value pairs that can be used by your application
+        instances during execution.
+
+        Parameters
+        ----------
+        secrets_collection_id : str
+            ID of the secrets collection to retrieve.
+
+        Returns
+        -------
+        SecretsCollection
+            The requested secrets collection, including all secret values
+            and metadata.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> # Retrieve a secrets collection
+        >>> collection = app.secrets_collection("api-secrets")
+        >>> print(collection.name)
+        'API Secrets'
+        >>> print(len(collection.secrets))
+        2
+        >>> for secret in collection.secrets:
+        ...     print(secret.location)
+        'API_KEY'
+        'DATABASE_URL'
+        """
+
+        response = self.client.request(
+            method="GET",
+            endpoint=f"{self.endpoint}/secrets/{secrets_collection_id}",
+        )
+
+        return SecretsCollection.from_dict(response.json())
+
+    def update_secrets_collection(
+        self: "Application",
+        secrets_collection_id: str,
+        name: str | None = None,
+        description: str | None = None,
+        secrets: list[Secret | dict[str, Any]] | None = None,
+    ) -> SecretsCollectionSummary:
+        """
+        Update a secrets collection.
+
+        This method updates an existing secrets collection with new values for name,
+        description, and secrets. A secrets collection is a group of key-value pairs
+        that can be used by your application instances during execution.
+
+        Parameters
+        ----------
+        secrets_collection_id : str
+            ID of the secrets collection to update.
+        name : Optional[str], default=None
+            Optional new name for the secrets collection.
+        description : Optional[str], default=None
+            Optional new description for the secrets collection.
+        secrets : Optional[list[Secret | dict[str, Any]]], default=None
+            Optional list of secrets to update. Each secret should be an
+            instance of the Secret class containing a key and value.
+
+        Returns
+        -------
+        SecretsCollectionSummary
+            Summary of the updated secrets collection including its metadata.
+
+        Raises
+        ------
+        ValueError
+            If no secrets are provided.
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> # Update an existing secrets collection
+        >>> from nextmv.cloud import Secret
+        >>> updated_secrets = [
+        ...     Secret(key="API_KEY", value="new-api-key"),
+        ...     Secret(key="DATABASE_URL", value="new-database-url")
+        ... ]
+        >>> updated_collection = app.update_secrets_collection(
+        ...     secrets_collection_id="api-secrets",
+        ...     name="Updated API Secrets",
+        ...     description="Updated collection of API secrets",
+        ...     secrets=updated_secrets
+        ... )
+        >>> print(updated_collection.id)
+        'api-secrets'
+        """
+
+        collection = self.secrets_collection(secrets_collection_id)
+        collection_dict = collection.to_dict()
+        payload = collection_dict.copy()
+
+        if name is not None:
+            payload["name"] = name
+        if description is not None:
+            payload["description"] = description
+        if secrets is not None and len(secrets) > 0:
+            secrets_dicts = []
+            for ix, secret in enumerate(secrets):
+                if isinstance(secret, dict):
+                    secrets_dicts.append(secret)
+                elif isinstance(secret, Secret):
+                    secrets_dicts.append(secret.to_dict())
+                else:
+                    raise ValueError(f"secret at index {ix} must be either a Secret or dict object")
+
+            payload["secrets"] = secrets_dicts
+
+        response = self.client.request(
+            method="PUT",
+            endpoint=f"{self.endpoint}/secrets/{secrets_collection_id}",
+            payload=payload,
+        )
+
+        return SecretsCollectionSummary.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,303 @@
+"""
+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:
+            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:
+            id = safe_id(prefix="version")
+        if name is None:
+            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

@@ -223,7 +223,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

nextmv/cloud/instance.py

@@ -15,7 +15,7 @@ Instance
 from datetime import datetime
 
 from nextmv.base_model import BaseModel
-from nextmv.run import RunQueuing
+from nextmv.run import Format, RunQueuing
 
 
 class InstanceConfiguration(BaseModel):
@@ -54,6 +54,9 @@ class InstanceConfiguration(BaseModel):
 
     execution_class: str | None = None
     """Execution class for the instance."""
+    format: Format | None = None
+    """Input format for the instance, if applicable. When configuring an
+    instance, only the `format.format_input` attribute is used."""
     options: dict | None = None
     """Options of the app that the instance uses."""
     secrets_collection_id: str | None = None
@@ -82,6 +85,13 @@ class InstanceConfiguration(BaseModel):
 
         self.execution_class = integration_val
 
+        # Processes the format to ensure only format_input is set.
+        if self.format is not None and self.format.format_input is not None:
+            final_format = Format(format_input=self.format.format_input)
+        else:
+            final_format = None
+        self.format = final_format
+
 
 class Instance(BaseModel):
     """An instance of an application tied to a version with configuration.

nextmv/cloud/integration.py

@@ -429,7 +429,7 @@ class Integration(BaseModel):
 
         integration = self.get(client=self.client, integration_id=self.integration_id)
         integration_dict = integration.to_dict()
-        payload = integration_dict
+        payload = integration_dict.copy()
 
         if name is not None:
             payload["name"] = name