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

nextmv/cloud/community.py

@@ -0,0 +1,446 @@
+"""
+This module contains functionality for working with Nextmv community apps.
+
+Community apps are pre-built decision models. They are maintained in the
+following GitHub repository: https://github.com/nextmv-io/community-apps
+
+Classes
+-------
+CommunityApp
+    Representation of a Nextmv Cloud Community App.
+
+Functions
+---------
+list_community_apps
+    List the available Nextmv community apps.
+clone_community_app
+    Clone a community app locally.
+"""
+
+import os
+import shutil
+import sys
+import tarfile
+import tempfile
+from collections.abc import Callable
+from typing import Any
+
+import requests
+import rich
+import yaml
+from pydantic import AliasChoices, Field
+
+from nextmv.base_model import BaseModel
+from nextmv.cloud.client import Client
+from nextmv.logger import log
+
+# Helpful constants.
+LATEST_VERSION = "latest"
+
+
+class CommunityApp(BaseModel):
+    """
+    Information about a Nextmv community app.
+
+    You can import the `CommunityApp` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import CommunityApp
+    ```
+
+    Parameters
+    ----------
+    app_versions : list[str]
+        Available versions of the community app.
+    description : str
+        Description of the community app.
+    latest_app_version : str
+        The latest version of the community app.
+    latest_marketplace_version : str
+        The latest version of the community app in the Nextmv Marketplace.
+    marketplace_versions : list[str]
+        Available versions of the community app in the Nextmv Marketplace.
+    name : str
+        Name of the community app.
+    app_type : str
+        Type of the community app.
+    """
+
+    description: str
+    """Description of the community app."""
+    name: str
+    """Name of the community app."""
+    app_type: str = Field(
+        serialization_alias="type",
+        validation_alias=AliasChoices("type", "app_type"),
+    )
+    """Type of the community app."""
+
+    app_versions: list[str] | None = None
+    """Available versions of the community app."""
+    latest_app_version: str | None = None
+    """The latest version of the community app."""
+    latest_marketplace_version: str | None = None
+    """The latest version of the community app in the Nextmv Marketplace."""
+    marketplace_versions: list[str] | None = None
+    """Available versions of the community app in the Nextmv Marketplace."""
+
+    def has_version(self, version: str) -> bool:
+        """
+        Check if the community app has the specified version.
+
+        Parameters
+        ----------
+        version : str
+            The version to check.
+
+        Returns
+        -------
+        bool
+            True if the app has the specified version, False otherwise.
+        """
+
+        if version == LATEST_VERSION:
+            version = self.latest_app_version
+
+        if self.app_versions is not None and version in self.app_versions:
+            return True
+
+        return False
+
+
+def list_community_apps(client: Client) -> list[CommunityApp]:
+    """
+    List the available Nextmv community apps.
+
+    You can import the `list_community_apps` function directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import list_community_apps
+    ```
+
+    Parameters
+    ----------
+    client : Client
+        The Nextmv Cloud client to use for the request.
+
+    Returns
+    -------
+    list[CommunityApp]
+        A list of available community apps.
+    """
+
+    manifest = _download_manifest(client)
+    dict_apps = manifest.get("apps", [])
+    apps = [CommunityApp.from_dict(app) for app in dict_apps]
+
+    return apps
+
+
+def clone_community_app(
+    client: Client,
+    app: str,
+    directory: str | None = None,
+    version: str | None = LATEST_VERSION,
+    verbose: bool = False,
+    rich_print: bool = False,
+) -> None:
+    """
+    Clone a community app locally.
+
+    By default, the `latest` version will be used. You can
+    specify a version with the `version` parameter, and customize the output
+    directory with the `directory` parameter. If you want to list the available
+    apps, use the `list_community_apps` function.
+
+    You can import the `clone_community_app` function directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import clone_community_app
+    ```
+
+    Parameters
+    ----------
+    client : Client
+        The Nextmv Cloud client to use for the request.
+    app : str
+        The name of the community app to clone.
+    directory : str | None, optional
+        The directory in which to clone the app. Default is the name of the app at current directory.
+    version : str | None, optional
+        The version of the community app to clone. Default is `latest`.
+    verbose : bool, optional
+        Whether to print verbose output.
+    rich_print : bool, optional
+        Whether to use rich printing for output messages.
+    """
+    comm_app = _find_app(client, app)
+
+    if version is not None and version == "":
+        raise ValueError("`version` cannot be an empty string.")
+
+    if not comm_app.has_version(version):
+        raise ValueError(f"Community app '{app}' does not have version '{version}'.")
+
+    original_version = version
+    if version == LATEST_VERSION:
+        version = comm_app.latest_app_version
+
+    # Clean and normalize directory path in an OS-independent way
+    if directory is not None and directory != "":
+        destination = os.path.normpath(directory)
+    else:
+        destination = app
+
+    full_destination = _get_valid_path(destination, os.stat)
+    os.makedirs(full_destination, exist_ok=True)
+
+    tarball = f"{app}_{version}.tar.gz"
+    s3_file_path = f"{app}/{version}/{tarball}"
+    downloaded_object = _download_object(
+        client=client,
+        file=s3_file_path,
+        path="community-apps",
+        output_dir=full_destination,
+        output_file=tarball,
+    )
+
+    # Extract the tarball to a temporary directory to handle nested structure
+    with tempfile.TemporaryDirectory() as temp_dir:
+        with tarfile.open(downloaded_object, "r:gz") as tar:
+            tar.extractall(path=temp_dir)
+
+        # Find the extracted directory (typically the app name)
+        extracted_items = os.listdir(temp_dir)
+        if len(extracted_items) == 1 and os.path.isdir(os.path.join(temp_dir, extracted_items[0])):
+            # Move contents from the extracted directory to full_destination
+            extracted_dir = os.path.join(temp_dir, extracted_items[0])
+            for item in os.listdir(extracted_dir):
+                shutil.move(os.path.join(extracted_dir, item), full_destination)
+        else:
+            # If structure is unexpected, move everything directly
+            for item in extracted_items:
+                shutil.move(os.path.join(temp_dir, item), full_destination)
+
+    # Remove the tarball after extraction
+    os.remove(downloaded_object)
+
+    if not verbose:
+        return
+
+    if rich_print:
+        rich.print(
+            f":white_check_mark: Successfully cloned the [magenta]{app}[/magenta] community app, "
+            f"using version [magenta]{original_version}[/magenta] in path: [magenta]{full_destination}[/magenta].",
+            file=sys.stderr,
+        )
+        return
+
+    log(
+        f"✅ Successfully cloned the {app} community app, using version {original_version} in path: {full_destination}."
+    )
+
+
+def _download_manifest(client: Client) -> dict[str, Any]:
+    """
+    Downloads and returns the community apps manifest.
+
+    Parameters
+    ----------
+    client : Client
+        The Nextmv Cloud client to use for the request.
+
+    Returns
+    -------
+    dict[str, Any]
+        The community apps manifest as a dictionary.
+
+    Raises
+    requests.HTTPError
+        If the response status code is not 2xx.
+    """
+
+    response = _download_file(client=client, directory="community-apps", file="manifest.yml")
+    manifest = yaml.safe_load(response.text)
+
+    return manifest
+
+
+def _download_file(
+    client: Client,
+    directory: str,
+    file: str,
+) -> requests.Response:
+    """
+    Gets a file from an internal bucket and return it.
+
+    Parameters
+    ----------
+    client : Client
+        The Nextmv Cloud client to use for the request.
+    directory : str
+        The directory in the bucket where the file is located.
+    file : str
+        The name of the file to download.
+
+    Returns
+    -------
+    requests.Response
+        The response object containing the file data.
+
+    Raises
+    requests.HTTPError
+        If the response status code is not 2xx.
+    """
+
+    # Request the download URL for the file.
+    response = client.request(
+        method="GET",
+        endpoint="v0/internal/tools",
+        headers=client.headers | {"request-source": "cli"},  # Pass `client.headers` to preserve auth.
+        query_params={"file": f"{directory}/{file}"},
+    )
+
+    # Use the URL obtained to download the file.
+    body = response.json()
+    download_response = client.request(
+        method="GET",
+        endpoint=body.get("url"),
+        headers={"Content-Type": "application/json"},
+    )
+
+    return download_response
+
+
+def _download_object(client: Client, file: str, path: str, output_dir: str, output_file: str) -> str:
+    """
+    Downloads an object from the internal bucket and saves it to the specified
+    output directory.
+
+    Parameters
+    ----------
+    client : Client
+        The Nextmv Cloud client to use for the request.
+    file : str
+        The name of the file to download.
+    path : str
+        The directory in the bucket where the file is located.
+    output_dir : str
+        The local directory where the file will be saved.
+    output_file : str
+        The name of the output file.
+
+    Returns
+    -------
+    str
+        The path to the downloaded file.
+    """
+
+    response = _download_file(client=client, directory=path, file=file)
+    file_name = os.path.join(output_dir, output_file)
+
+    with open(file_name, "wb") as f:
+        f.write(response.content)
+
+    return file_name
+
+
+def _get_valid_path(path: str, stat_fn: Callable[[str], os.stat_result], ending: str = "") -> str:
+    """
+    Validates and returns a non-existing path. If the path exists,
+    it will append a number to the path and return it. If the path does not
+    exist, it will return the path as is.
+
+    The ending parameter is used to check if the path ends with a specific
+    string. This is useful to specify if it is a file (like foo.json, in which
+    case the next iteration is foo-1.json) or a directory (like foo, in which
+    case the next iteration is foo-1).
+
+    Parameters
+    ----------
+    path : str
+        The initial path to validate.
+    stat_fn : Callable[[str], os.stat_result]
+        A function that takes a path and returns its stat result.
+    ending : str, optional
+        The expected ending of the path (e.g., file extension), by default "".
+
+    Returns
+    -------
+    str
+        A valid, non-existing path.
+
+    Raises
+    ------
+    RuntimeError
+        If an unexpected error occurs during path validation
+    """
+    base_name = os.path.basename(path)
+    name_without_ending = base_name.removesuffix(ending) if ending else base_name
+
+    while True:
+        try:
+            stat_fn(path)
+            # If we get here, the path exists
+            # Get folder/file name number, increase it and create new path
+            name = os.path.basename(path)
+
+            # Get folder/file name number
+            parts = name.split("-")
+            last = parts[-1].removesuffix(ending) if ending else parts[-1]
+
+            # Save last folder name index to be changed
+            i = path.rfind(name)
+
+            try:
+                num = int(last)
+                # Increase number and create new path
+                if ending:
+                    temp_path = path[:i] + f"{name_without_ending}-{num + 1}{ending}"
+                else:
+                    temp_path = path[:i] + f"{base_name}-{num + 1}"
+                path = temp_path
+            except ValueError:
+                # If there is no number, add it
+                if ending:
+                    temp_path = path[:i] + f"{name_without_ending}-1{ending}"
+                else:
+                    temp_path = path[:i] + f"{name}-1"
+                path = temp_path
+
+        except FileNotFoundError:
+            # Path doesn't exist, we can use it
+            return path
+        except Exception as e:
+            # Re-raise unexpected errors
+            raise RuntimeError(f"An unexpected error occurred while validating the path: {path} ") from e
+
+
+def _find_app(client: Client, app: str) -> CommunityApp:
+    """
+    Finds and returns a community app from the manifest by its name.
+
+    Parameters
+    ----------
+    client : Client
+        The Nextmv Cloud client to use for the request.
+    app : str
+        The name of the community app to find.
+
+    Returns
+    -------
+    CommunityApp
+        The community app if found.
+
+    Raises
+    ------
+    ValueError
+        If the community app is not found.
+    """
+
+    comm_apps = list_community_apps(client)
+    for comm_app in comm_apps:
+        if comm_app.name == app:
+            return comm_app
+
+    raise ValueError(f"Community app '{app}' not found.")

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

@@ -225,12 +225,12 @@ class Integration(BaseModel):
     def new(  # noqa: C901
         cls,
         client: Client,
-        name: str,
         integration_type: IntegrationType | str,
         exec_types: list[ManifestType | str],
         provider: IntegrationProvider | str,
         provider_config: dict[str, Any],
         integration_id: str | None = None,
+        name: str | None = None,
         description: str | None = None,
         is_global: bool = False,
         application_ids: list[str] | None = None,
@@ -243,8 +243,6 @@ class Integration(BaseModel):
         ----------
         client : Client
             Client to use for interacting with the Nextmv Cloud API.
-        name : str
-            The name of the integration.
         integration_type : IntegrationType | str
             The type of the integration. Please refer to the `IntegrationType`
             enum for possible values.
@@ -259,6 +257,9 @@ class Integration(BaseModel):
         integration_id : str, optional
             The unique identifier of the integration. If not provided,
             it will be generated automatically.
+        name : str | None, optional
+            The name of the integration. If not provided, the integration ID
+            will be used as the name.
         description : str, optional
             An optional description of the integration.
         is_global : bool, optional, default=False
@@ -302,8 +303,10 @@ class Integration(BaseModel):
         elif not is_global and application_ids is None:
             raise ValueError("A non-global integration must have specific application IDs.")
 
-        if integration_id is None:
+        if integration_id is None or integration_id == "":
             integration_id = safe_id("integration")
+        if name is None or name == "":
+            name = integration_id
 
         if exist_ok:
             try:
@@ -429,7 +432,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

nextmv/cloud/package.py

@@ -6,9 +6,12 @@ import platform
 import re
 import shutil
 import subprocess
+import sys
 import tarfile
 import tempfile
 
+import rich
+
 from nextmv.logger import log
 from nextmv.manifest import MANIFEST_FILE_NAME, Manifest, ManifestBuild, ManifestType
 from nextmv.model import Model, ModelConfiguration, _cleanup_python_model
@@ -21,18 +24,19 @@ _MANDATORY_FILES_PER_TYPE = {
 }
 
 
-def _package(
+def _package(  # noqa: C901 # complexity attributed to printing.
     app_dir: str,
     manifest: Manifest,
     model: Model | None = None,
     model_configuration: ModelConfiguration | None = None,
     verbose: bool = False,
+    rich_print: bool = False,
 ) -> tuple[str, str]:
     """Package the app into a tarball."""
 
     with tempfile.TemporaryDirectory(prefix="nextmv-temp-") as temp_dir:
         if manifest.type == ManifestType.PYTHON:
-            __handle_python(app_dir, temp_dir, manifest, model, model_configuration, verbose)
+            __handle_python(app_dir, temp_dir, manifest, model, model_configuration, verbose, rich_print)
 
         found, missing, files = __find_files(app_dir, manifest.files)
         __confirm_mandatory_files(manifest, found)
@@ -55,7 +59,13 @@ def _package(
                 raise Exception(f"error copying asset files {file['absolute_path']}: {e}") from e
 
         if verbose:
-            log(f'📋 Copied files listed in "{MANIFEST_FILE_NAME}" manifest.')
+            if rich_print:
+                rich.print(
+                    f":clipboard: Copied files listed in [magenta]{MANIFEST_FILE_NAME}[/magenta] manifest.",
+                    file=sys.stderr,
+                )
+            else:
+                log(f'📋 Copied files listed in "{MANIFEST_FILE_NAME}" manifest.')
 
         if manifest.type == ManifestType.PYTHON:
             _cleanup_python_model(app_dir, model_configuration, verbose)
@@ -66,9 +76,22 @@ def _package(
         if verbose:
             try:
                 size = __human_friendly_file_size(tar_file)
-                log(f"📦 Packaged application ({file_count_msg}, {size}).")
+                if rich_print:
+                    rich.print(
+                        ":package: Packaged application "
+                        f"([magenta]{file_count_msg}[/magenta], [magenta]{size}[/magenta]).",
+                        file=sys.stderr,
+                    )
+                else:
+                    log(f"📦 Packaged application ({file_count_msg}, {size}).")
             except Exception:
-                log(f"📦 Packaged application ({file_count_msg}).")
+                if rich_print:
+                    rich.print(
+                        f":package: Packaged application ([magenta]{file_count_msg}[/magenta]).",
+                        file=sys.stderr,
+                    )
+                else:
+                    log(f"📦 Packaged application ({file_count_msg}).")
 
         return tar_file, output_dir
 
@@ -77,6 +100,7 @@ def _run_build_command(
     app_dir: str,
     manifest_build: ManifestBuild | None = None,
     verbose: bool = False,
+    rich_print: bool = False,
 ) -> None:
     """Run the build command specified in the manifest."""
 
@@ -85,7 +109,12 @@ def _run_build_command(
 
     elements = manifest_build.command.split(" ")
     command_str = " ".join(elements)
-    log(f'🚧 Running build command: "{command_str}"')
+
+    if verbose:
+        if rich_print:
+            rich.print(f":construction: Running build command: [magenta]{command_str}[/magenta]", file=sys.stderr)
+        else:
+            log(f'🚧 Running build command: "{command_str}"')
     try:
         result = subprocess.run(
             elements,
@@ -120,6 +149,7 @@ def _run_pre_push_command(
     app_dir: str,
     pre_push_command: str | None = None,
     verbose: bool = False,
+    rich_print: bool = False,
 ) -> None:
     """Run the pre-push command specified in the manifest."""
 
@@ -129,7 +159,11 @@ def _run_pre_push_command(
     elements = _get_shell_command_elements(pre_push_command)
 
     command_str = " ".join(elements)
-    log(f'🔨 Running pre-push command: "{command_str}"')
+    if verbose:
+        if rich_print:
+            rich.print(f":hammer: Running pre-push command: [magenta]{command_str}[/magenta]", file=sys.stderr)
+        else:
+            log(f'🔨 Running pre-push command: "{command_str}"')
     try:
         result = subprocess.run(
             elements,
@@ -227,16 +261,23 @@ def __handle_python(
     model: Model | None = None,
     model_configuration: ModelConfiguration | None = None,
     verbose: bool = False,
+    rich_print: bool = False,
 ) -> None:
     """Handles the Python-specific packaging logic."""
 
     if model is not None and model_configuration is not None:
         if verbose:
-            log("🔮 Encoding Python model.")
+            if rich_print:
+                rich.print(":crystal_ball: Encoding Python model.", file=sys.stderr)
+            else:
+                log("🔮 Encoding Python model.")
         model.save(app_dir, model_configuration)
 
     if verbose:
-        log("🐍 Bundling Python dependencies.")
+        if rich_print:
+            rich.print(":snake: Bundling Python dependencies.", file=sys.stderr)
+        else:
+            log("🐍 Bundling Python dependencies.")
     __install_dependencies(manifest, app_dir, temp_dir)