nextmv 0.27.0__py3-none-any.whl → 0.28.0__py3-none-any.whl

nextmv/cloud/package.py

@@ -10,7 +10,7 @@ import tarfile
 import tempfile
 from typing import Optional
 
-from nextmv.cloud.manifest import FILE_NAME, Manifest, ManifestBuild, ManifestType
+from nextmv.cloud.manifest import MANIFEST_FILE_NAME, Manifest, ManifestBuild, ManifestType
 from nextmv.logger import log
 from nextmv.model import Model, ModelConfiguration, _cleanup_python_model
 
@@ -55,7 +55,7 @@ def _package(
                 raise Exception(f"error copying asset files {file['absolute_path']}: {e}") from e
 
         if verbose:
-            log(f'📋 Copied files listed in "{FILE_NAME}" manifest.')
+            log(f'📋 Copied files listed in "{MANIFEST_FILE_NAME}" manifest.')
 
         if manifest.type == ManifestType.PYTHON:
             _cleanup_python_model(app_dir, model_configuration, verbose)

nextmv/cloud/run.py

@@ -1,4 +1,43 @@
-"""This module contains definitions for an app run."""
+"""This module contains definitions for an app run.
+
+Classes
+-------
+Metadata
+    Metadata of a run, whether it was successful or not.
+RunInformation
+    Information of a run.
+ErrorLog
+    Error log of a run, when it was not successful.
+RunResult
+    Result of a run, whether it was successful or not.
+RunLog
+    Log of a run.
+FormatInput
+    Input format for a run configuration.
+Format
+    Format for a run configuration.
+RunType
+    The actual type of the run.
+RunTypeConfiguration
+    Defines the configuration for the type of the run that is being executed
+    on an application.
+RunQueuing
+    RunQueuing configuration for a run.
+RunConfiguration
+    Configuration for an app run.
+ExternalRunResult
+    Result of a run used to configure a new application run as an
+    external one.
+TrackedRunStatus
+    The status of a tracked run.
+TrackedRun
+    An external run that is tracked in the Nextmv platform.
+
+Functions
+---------
+run_duration(start, end)
+    Calculate the duration of a run in milliseconds.
+"""
 
 import json
 from dataclasses import dataclass
@@ -14,19 +53,22 @@ from nextmv.input import Input, InputFormat
 from nextmv.output import Output, OutputFormat
 
 
-def run_duration(
-    start: Union[datetime, float],
-    end: Union[datetime, float],
-) -> int:
+def run_duration(start: Union[datetime, float], end: Union[datetime, float]) -> int:
     """
     Calculate the duration of a run in milliseconds.
 
+    You can import the `run_duration` function directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import run_duration
+    ```
+
     Parameters
     ----------
-    start : Union[datetime, float]
+    start : datetime or float
         The start time of the run. Can be a datetime object or a float
         representing the start time in seconds since the epoch.
-    end : Union[datetime, float]
+    end : datetime or float
         The end time of the run. Can be a datetime object or a float
         representing the end time in seconds since the epoch.
 
@@ -34,20 +76,73 @@ def run_duration(
     -------
     int
         The duration of the run in milliseconds.
+
+    Raises
+    ------
+    ValueError
+        If the start time is after the end time.
+    TypeError
+        If start and end are not both datetime objects or both float numbers.
+
+    Examples
+    --------
+    >>> from datetime import datetime, timedelta
+    >>> start_dt = datetime(2023, 1, 1, 12, 0, 0)
+    >>> end_dt = datetime(2023, 1, 1, 12, 0, 1)
+    >>> run_duration(start_dt, end_dt)
+    1000
+
+    >>> start_float = 1672574400.0  # Corresponds to 2023-01-01 12:00:00
+    >>> end_float = 1672574401.0    # Corresponds to 2023-01-01 12:00:01
+    >>> run_duration(start_float, end_float)
+    1000
     """
     if isinstance(start, float) and isinstance(end, float):
         if start > end:
             raise ValueError("Start time must be before end time.")
         return int(round((end - start) * 1000))
+
     if isinstance(start, datetime) and isinstance(end, datetime):
         if start > end:
             raise ValueError("Start time must be before end time.")
         return int(round((end - start).total_seconds() * 1000))
+
     raise TypeError("Start and end must be either datetime or float.")
 
 
 class Metadata(BaseModel):
-    """Metadata of a run, whether it was successful or not."""
+    """
+    Metadata of a run, whether it was successful or not.
+
+    You can import the `Metadata` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import Metadata
+    ```
+
+    Parameters
+    ----------
+    application_id : str
+        ID of the application where the run was submitted to.
+    application_instance_id : str
+        ID of the instance where the run was submitted to.
+    application_version_id : str
+        ID of the version of the application where the run was submitted to.
+    created_at : datetime
+        Date and time when the run was created.
+    duration : float
+        Duration of the run in milliseconds.
+    error : str
+        Error message if the run failed.
+    input_size : float
+        Size of the input in bytes.
+    output_size : float
+        Size of the output in bytes.
+    status : Status
+        Deprecated: use status_v2.
+    status_v2 : StatusV2
+        Status of the run.
+    """
 
     application_id: str
     """ID of the application where the run was submitted to."""
@@ -72,7 +167,30 @@ class Metadata(BaseModel):
 
 
 class RunInformation(BaseModel):
-    """Information of a run."""
+    """
+    Information of a run.
+
+    You can import the `RunInformation` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import RunInformation
+    ```
+
+    Parameters
+    ----------
+    description : str
+        Description of the run.
+    id : str
+        ID of the run.
+    metadata : Metadata
+        Metadata of the run.
+    name : str
+        Name of the run.
+    user_email : str
+        Email of the user who submitted the run.
+    console_url : str, optional
+        URL to the run in the Nextmv console. Defaults to "".
+    """
 
     description: str
     """Description of the run."""
@@ -88,7 +206,24 @@ class RunInformation(BaseModel):
 
 
 class ErrorLog(BaseModel):
-    """Error log of a run, when it was not successful."""
+    """
+    Error log of a run, when it was not successful.
+
+    You can import the `ErrorLog` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import ErrorLog
+    ```
+
+    Parameters
+    ----------
+    error : str, optional
+        Error message. Defaults to None.
+    stdout : str, optional
+        Standard output. Defaults to None.
+    stderr : str, optional
+        Standard error. Defaults to None.
+    """
 
     error: Optional[str] = None
     """Error message."""
@@ -99,7 +234,24 @@ class ErrorLog(BaseModel):
 
 
 class RunResult(RunInformation):
-    """Result of a run, whether it was successful or not."""
+    """
+    Result of a run, whether it was successful or not.
+
+    You can import the `RunResult` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import RunResult
+    ```
+
+    Parameters
+    ----------
+    error_log : ErrorLog, optional
+        Error log of the run. Only available if the run failed. Defaults to
+        None.
+    output : dict[str, Any], optional
+        Output of the run. Only available if the run succeeded. Defaults to
+        None.
+    """
 
     error_log: Optional[ErrorLog] = None
     """Error log of the run. Only available if the run failed."""
@@ -108,14 +260,40 @@ class RunResult(RunInformation):
 
 
 class RunLog(BaseModel):
-    """Log of a run."""
+    """
+    Log of a run.
+
+    You can import the `RunLog` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import RunLog
+    ```
+
+    Parameters
+    ----------
+    log : str
+        Log of the run.
+    """
 
     log: str
     """Log of the run."""
 
 
 class FormatInput(BaseModel):
-    """Input format for a run configuration."""
+    """
+    Input format for a run configuration.
+
+    You can import the `FormatInput` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import FormatInput
+    ```
+
+    Parameters
+    ----------
+    input_type : InputFormat, optional
+        Type of the input format. Defaults to `InputFormat.JSON`.
+    """
 
     input_type: InputFormat = Field(
         serialization_alias="type",
@@ -126,7 +304,20 @@ class FormatInput(BaseModel):
 
 
 class Format(BaseModel):
-    """Format for a run configuration."""
+    """
+    Format for a run configuration.
+
+    You can import the `Format` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import Format
+    ```
+
+    Parameters
+    ----------
+    format_input : FormatInput
+        Input format for the run configuration.
+    """
 
     format_input: FormatInput = Field(
         serialization_alias="input",
@@ -136,7 +327,24 @@ class Format(BaseModel):
 
 
 class RunType(str, Enum):
-    """The actual type of the run."""
+    """
+    The actual type of the run.
+
+    You can import the `RunType` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import RunType
+    ```
+
+    Parameters
+    ----------
+    STANDARD : str
+        Standard run type.
+    EXTERNAL : str
+        External run type.
+    ENSEMBLE : str
+        Ensemble run type.
+    """
 
     STANDARD = "standard"
     """Standard run type."""
@@ -147,8 +355,25 @@ class RunType(str, Enum):
 
 
 class RunTypeConfiguration(BaseModel):
-    """Defines the configuration for the type of the run that is being executed
-    on an application."""
+    """
+    Defines the configuration for the type of the run that is being executed
+    on an application.
+
+    You can import the `RunTypeConfiguration` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import RunTypeConfiguration
+    ```
+
+    Parameters
+    ----------
+    run_type : RunType
+        Type of the run.
+    definition_id : str, optional
+        ID of the definition for the run type. Defaults to None.
+    reference_id : str, optional
+        ID of the reference for the run type. Defaults to None.
+    """
 
     run_type: RunType = Field(
         serialization_alias="type",
@@ -162,7 +387,24 @@ class RunTypeConfiguration(BaseModel):
 
 
 class RunQueuing(BaseModel):
-    """RunQueuing configuration for a run."""
+    """
+    RunQueuing configuration for a run.
+
+    You can import the `RunQueuing` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import RunQueuing
+    ```
+
+    Parameters
+    ----------
+    priority : int, optional
+        Priority of the run in the queue. 1 is the highest priority, 9 is the
+        lowest priority. Defaults to None.
+    disabled : bool, optional
+        Whether the run should be queued, or not. If True, the run will not be
+        queued. If False, the run will be queued. Defaults to None.
+    """
 
     priority: Optional[int] = None
     """
@@ -176,7 +418,15 @@ class RunQueuing(BaseModel):
     """
 
     def __post_init_post_parse__(self):
-        """Validations done after parsing the model."""
+        """
+        Validations done after parsing the model.
+
+        Raises
+        ------
+        ValueError
+            If priority is not between 1 and 9, or if disabled is not a
+            boolean value.
+        """
 
         if self.priority is not None and (self.priority < 1 or self.priority > 9):
             raise ValueError("Priority must be between 1 and 9.")
@@ -186,7 +436,28 @@ class RunQueuing(BaseModel):
 
 
 class RunConfiguration(BaseModel):
-    """Configuration for an app run."""
+    """
+    Configuration for an app run.
+
+    You can import the `RunConfiguration` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import RunConfiguration
+    ```
+
+    Parameters
+    ----------
+    execution_class : str, optional
+        Execution class for the instance. Defaults to None.
+    format : Format, optional
+        Format for the run configuration. Defaults to None.
+    run_type : RunTypeConfiguration, optional
+        Run type configuration for the run. Defaults to None.
+    secrets_collection_id : str, optional
+        ID of the secrets collection to use for the run. Defaults to None.
+    queuing : RunQueuing, optional
+        Queuing configuration for the run. Defaults to None.
+    """
 
     execution_class: Optional[str] = None
     """Execution class for the instance."""
@@ -201,8 +472,29 @@ class RunConfiguration(BaseModel):
 
 
 class ExternalRunResult(BaseModel):
-    """Result of a run used to configure a new application run as an
-    external one."""
+    """
+    Result of a run used to configure a new application run as an
+    external one.
+
+    You can import the `ExternalRunResult` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import ExternalRunResult
+    ```
+
+    Parameters
+    ----------
+    output_upload_id : str, optional
+        ID of the output upload. Defaults to None.
+    error_upload_id : str, optional
+        ID of the error upload. Defaults to None.
+    status : str, optional
+        Status of the run. Must be "succeeded" or "failed". Defaults to None.
+    error_message : str, optional
+        Error message of the run. Defaults to None.
+    execution_duration : int, optional
+        Duration of the run, in milliseconds. Defaults to None.
+    """
 
     output_upload_id: Optional[str] = None
     """ID of the output upload."""
@@ -216,7 +508,14 @@ class ExternalRunResult(BaseModel):
     """Duration of the run, in milliseconds."""
 
     def __post_init_post_parse__(self):
-        """Validations done after parsing the model."""
+        """
+        Validations done after parsing the model.
+
+        Raises
+        ------
+        ValueError
+            If the status value is not "succeeded" or "failed".
+        """
 
         valid_statuses = {"succeeded", "failed"}
         if self.status is not None and self.status not in valid_statuses:
@@ -227,7 +526,13 @@ class TrackedRunStatus(str, Enum):
     """
     The status of a tracked run.
 
-    Attributes
+    You can import the `TrackedRunStatus` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import TrackedRunStatus
+    ```
+
+    Parameters
     ----------
     SUCCEEDED : str
         The run succeeded.
@@ -246,28 +551,41 @@ class TrackedRun:
     """
     An external run that is tracked in the Nextmv platform.
 
-    Attributes
+    You can import the `TrackedRun` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import TrackedRun
+    ```
+
+    Parameters
     ----------
-    input : Union[Input, dict[str, Any], str]
+    input : Input or dict[str, Any] or str
         The input of the run being tracked. Please note that if the input
         format is JSON, then the input data must be JSON serializable. This
         field is required.
-    output : Union[Output, dict[str, Any], str]
+    output : Output or dict[str, Any] or str
         The output of the run being tracked. Please note that if the output
         format is JSON, then the output data must be JSON serializable. This
-        field is required.
+        field is required. Only JSON output_format is supported.
     status : TrackedRunStatus
         The status of the run being tracked. This field is required.
-    duration : Optional[int]
-        The duration of the run being tracked, in seconds. This field is
-        optional.
-    error : Optional[str]
+    duration : int, optional
+        The duration of the run being tracked, in milliseconds. This field is
+        optional. Defaults to None.
+    error : str, optional
         An error message if the run failed. You should only specify this if the
         run failed (the `status` is `TrackedRunStatus.FAILED`), otherwise an
-        exception will be raised. This field is optional.
-    logs : Optional[list[str]]
+        exception will be raised. This field is optional. Defaults to None.
+    logs : list[str], optional
         The logs of the run being tracked. Each element of the list is a line in
-        the log. This field is optional.
+        the log. This field is optional. Defaults to None.
+
+    Raises
+    ------
+    ValueError
+        If the status value is invalid, if an error message is provided for a
+        successful run, or if input/output formats are not JSON or
+        input/output dicts are not JSON serializable.
     """
 
     input: Union[Input, dict[str, Any], str]
@@ -287,7 +605,16 @@ class TrackedRun:
     the log."""
 
     def __post_init__(self):  # noqa: C901
-        """Validations done after parsing the model."""
+        """
+        Validations done after parsing the model.
+
+        Raises
+        ------
+        ValueError
+            If the status value is invalid, if an error message is provided for
+            a successful run, or if input/output formats are not JSON or
+            input/output dicts are not JSON serializable.
+        """
 
         valid_statuses = {TrackedRunStatus.SUCCEEDED, TrackedRunStatus.FAILED}
         if self.status not in valid_statuses:
@@ -318,14 +645,18 @@ class TrackedRun:
         """
         Returns the logs as a single string.
 
-        Parameters
-        ----------
-        None
+        Each log entry is separated by a newline character.
 
         Returns
         -------
         str
-            The logs as a single string.
+            The logs as a single string. If no logs are present, an empty
+            string is returned.
+
+        Raises
+        ------
+        TypeError
+            If `self.logs` is not a string or a list of strings.
         """
 
         if self.logs is None:
@@ -335,6 +666,6 @@ class TrackedRun:
             return self.logs
 
         if isinstance(self.logs, list):
-            return "\n".join(self.logs)
+            return "\\n".join(self.logs)
 
         raise TypeError("Logs must be a string or a list of strings.")

nextmv/cloud/safe.py

@@ -11,27 +11,27 @@ INDEX_TAG_CHAR_COUNT: int = 3  # room reserved for “-001”, “-xyz”, etc.
 RE_NON_ALNUM = re.compile(r"[^A-Za-z0-9]+")
 
 
-def kebab_case(value: str) -> str:
+def _kebab_case(value: str) -> str:
     """Convert arbitrary text to `kebab-case` (lower-case, hyphen-separated)."""
 
     cleaned = RE_NON_ALNUM.sub(" ", value).strip()
     return "-".join(word.lower() for word in cleaned.split())
 
 
-def start_case(value: str) -> str:
+def _start_case(value: str) -> str:
     """Convert `kebab-case` (or any hyphen/underscore string) to `Start Case`."""
 
     cleaned = re.sub(r"[-_]+", " ", value)
     return " ".join(word.capitalize() for word in cleaned.split())
 
 
-def nanoid(size: int = 8, alphabet: str = string.ascii_lowercase + string.digits) -> str:
+def _nanoid(size: int = 8, alphabet: str = string.ascii_lowercase + string.digits) -> str:
     """Simple nanoid clone using the std-lib `secrets` module."""
 
     return "".join(secrets.choice(alphabet) for _ in range(size))
 
 
-def name_and_id(prefix: str, entity_id: str) -> tuple[str, str]:
+def _name_and_id(prefix: str, entity_id: str) -> tuple[str, str]:
     """
     Generate a safe ID and human-readable name from a prefix and user-supplied
     identifier.
@@ -53,8 +53,8 @@ def name_and_id(prefix: str, entity_id: str) -> tuple[str, str]:
     if not prefix or not entity_id:
         return "", ""
 
-    safe_user_defined_id = kebab_case(entity_id)
-    random_slug = nanoid(8)
+    safe_user_defined_id = _kebab_case(entity_id)
+    random_slug = _nanoid(8)
 
     # Space available for user text once prefix, random slug and separator "-"
     # are accounted for
@@ -78,6 +78,6 @@ def name_and_id(prefix: str, entity_id: str) -> tuple[str, str]:
         safe_id_parts.append(safe_slug)
 
     safe_id = "-".join(filter(None, safe_id_parts)) + f"-{random_slug}"
-    safe_name = start_case(safe_id)
+    safe_name = _start_case(safe_id)
 
     return safe_name, safe_id