nextmv 0.20.1__py3-none-any.whl → 0.21.0__py3-none-any.whl

nextmv/__about__.py

@@ -1 +1 @@
-__version__ = "v0.20.1"
+__version__ = "v0.21.0"

nextmv/cloud/__init__.py

@@ -48,6 +48,8 @@ from .run import RunLog as RunLog
 from .run import RunResult as RunResult
 from .run import RunType as RunType
 from .run import RunTypeConfiguration as RunTypeConfiguration
+from .run import TrackedRun as TrackedRun
+from .run import TrackedRunStatus as TrackedRunStatus
 from .secrets import Secret as Secret
 from .secrets import SecretsCollection as SecretsCollection
 from .secrets import SecretsCollectionSummary as SecretsCollectionSummary

nextmv/cloud/application.py

@@ -18,12 +18,14 @@ from nextmv.cloud.client import Client, get_size
 from nextmv.cloud.input_set import InputSet
 from nextmv.cloud.instance import Instance, InstanceConfiguration
 from nextmv.cloud.manifest import Manifest
-from nextmv.cloud.run import ExternalRunResult, RunConfiguration, RunInformation, RunLog, RunResult
+from nextmv.cloud.run import ExternalRunResult, RunConfiguration, RunInformation, RunLog, RunResult, TrackedRun
 from nextmv.cloud.secrets import Secret, SecretsCollection, SecretsCollectionSummary
 from nextmv.cloud.status import StatusV2
 from nextmv.cloud.version import Version
+from nextmv.input import Input
 from nextmv.logger import log
 from nextmv.model import Model, ModelConfiguration
+from nextmv.output import Output
 
 _MAX_RUN_SIZE: int = 5 * 1024 * 1024
 """Maximum size of the run input/output. This value is used to determine
@@ -735,8 +737,8 @@ class Application:
     def new_instance(
         self,
         version_id: str,
-        id: Optional[str] = None,
-        name: Optional[str] = None,
+        id: str,
+        name: str,
         description: Optional[str] = None,
         configuration: Optional[InstanceConfiguration] = None,
     ) -> Instance:
@@ -934,8 +936,8 @@ class Application:
     def new_secrets_collection(
         self,
         secrets: list[Secret],
-        id: Optional[str] = None,
-        name: Optional[str] = None,
+        id: str,
+        name: str,
         description: Optional[str] = None,
     ) -> SecretsCollectionSummary:
         """
@@ -1284,6 +1286,107 @@ class Application:
 
         return self.__run_result(run_id=run_id, run_information=run_information)
 
+    def track_run(self, tracked_run: TrackedRun) -> str:
+        """
+        Track an external run.
+
+        This method allows you to register in Nextmv a run that happened
+        elsewhere, as though it were executed in the Nextmv platform. Having
+        information about a run in Nextmv is useful for things like
+        experimenting and testing.
+
+        Parameters
+        ----------
+        tracked_run : TrackedRun
+            The run to track.
+
+        Returns
+        -------
+        str
+            The ID of the run that was tracked.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+        ValueError
+            If the tracked run does not have an input or output.
+        """
+        url_input = self.upload_url()
+
+        upload_input = tracked_run.input
+        if isinstance(tracked_run.input, Input):
+            upload_input = tracked_run.input.to_dict()
+
+        self.upload_large_input(input=upload_input, upload_url=url_input)
+
+        url_output = self.upload_url()
+
+        upload_output = tracked_run.output
+        if isinstance(tracked_run.output, Output):
+            upload_output = tracked_run.output.to_dict()
+
+        self.upload_large_input(input=upload_output, upload_url=url_output)
+
+        external_result = ExternalRunResult(
+            output_upload_id=url_output.upload_id,
+            status=tracked_run.status.value,
+            execution_duration=tracked_run.duration,
+        )
+
+        if tracked_run.logs is not None:
+            url_stderr = self.upload_url()
+            self.upload_large_input(input=tracked_run.logs_text(), upload_url=url_stderr)
+            external_result.error_upload_id = url_stderr.upload_id
+
+        if tracked_run.error is not None and tracked_run.error != "":
+            external_result.error_message = tracked_run.error
+
+        return self.new_run(upload_id=url_input.upload_id, external_result=external_result)
+
+    def track_run_with_result(
+        self,
+        tracked_run: TrackedRun,
+        polling_options: PollingOptions = _DEFAULT_POLLING_OPTIONS,
+    ) -> RunResult:
+        """
+        Track an external run and poll for the result. This is a convenience
+        method that combines the `track_run` and `run_result_with_polling`
+        methods. It applies polling logic to check when the run was
+        successfully registered.
+
+        Parameters
+        ----------
+        tracked_run : TrackedRun
+            The run to track.
+        polling_options : PollingOptions
+            Options to use when polling for the run result.
+
+        Returns
+        -------
+        RunResult
+            Result of the run.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+        ValueError
+            If the tracked run does not have an input or output.
+        TimeoutError
+            If the run does not succeed after the polling strategy is
+            exhausted based on time duration.
+        RuntimeError
+            If the run does not succeed after the polling strategy is
+            exhausted based on number of tries.
+        """
+        run_id = self.track_run(tracked_run=tracked_run)
+
+        return self.run_result_with_polling(
+            run_id=run_id,
+            polling_options=polling_options,
+        )
+
     def update_instance(
         self,
         id: str,
@@ -1334,7 +1437,7 @@ class Application:
         name: str,
         description: str,
         secrets: list[Secret],
-    ) -> SecretsCollection:
+    ) -> SecretsCollectionSummary:
         """
         Update a secrets collection.
 

nextmv/cloud/run.py

@@ -1,14 +1,17 @@
 """This module contains definitions for an app run."""
 
+import json
+from dataclasses import dataclass
 from datetime import datetime
 from enum import Enum
-from typing import Any, Optional
+from typing import Any, Optional, Union
 
 from pydantic import AliasChoices, Field
 
 from nextmv.base_model import BaseModel
 from nextmv.cloud.status import Status, StatusV2
-from nextmv.input import InputFormat
+from nextmv.input import Input, InputFormat
+from nextmv.output import Output, OutputFormat
 
 
 class Metadata(BaseModel):
@@ -159,3 +162,114 @@ class ExternalRunResult(BaseModel):
         valid_statuses = {"succeeded", "failed"}
         if self.status is not None and self.status not in valid_statuses:
             raise ValueError("Invalid status value, must be one of: " + ", ".join(valid_statuses))
+
+
+class TrackedRunStatus(str, Enum):
+    """
+    The status of a tracked run.
+
+    Attributes
+    ----------
+    SUCCEEDED : str
+        The run succeeded.
+    FAILED : str
+        The run failed.
+    """
+
+    SUCCEEDED = "succeeded"
+    """The run succeeded."""
+    FAILED = "failed"
+    """The run failed."""
+
+
+@dataclass
+class TrackedRun:
+    """
+    An external run that is tracked in the Nextmv platform.
+
+    Attributes
+    ----------
+    input : Union[Input, dict[str, any], 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]
+        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.
+    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]
+        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]]
+        The logs of the run being tracked. Each element of the list is a line in
+        the log. This field is optional.
+    """
+
+    input: Union[Input, dict[str, any], str]
+    """The input of the run being tracked."""
+    output: Union[Output, dict[str, any], str]
+    """The output of the run being tracked. Only JSON output_format is supported."""
+    status: TrackedRunStatus
+    """The status of the run being tracked"""
+
+    duration: Optional[int] = None
+    """The duration of the run being tracked, in seconds."""
+    error: Optional[str] = None
+    """An error message if the run failed. You should only specify this if the
+    run failed, otherwise an exception will be raised."""
+    logs: Optional[list[str]] = None
+    """The logs of the run being tracked. Each element of the list is a line in
+    the log."""
+
+    def __post_init__(self):  # noqa: C901
+        """Validations done after parsing the model."""
+
+        valid_statuses = {TrackedRunStatus.SUCCEEDED, TrackedRunStatus.FAILED}
+        if self.status not in valid_statuses:
+            raise ValueError("Invalid status value, must be one of: " + ", ".join(valid_statuses))
+
+        if self.error is not None and self.error != "" and self.status != TrackedRunStatus.FAILED:
+            raise ValueError("Error message must be empty if the run succeeded.")
+
+        if isinstance(self.input, Input):
+            if self.input.input_format != InputFormat.JSON:
+                raise ValueError("Input.input_format must be JSON.")
+        elif isinstance(self.input, dict):
+            try:
+                _ = json.dumps(self.input)
+            except (TypeError, OverflowError) as e:
+                raise ValueError("Input is dict[str, any] but it is not JSON serializable") from e
+
+        if isinstance(self.output, Output):
+            if self.output.output_format != OutputFormat.JSON:
+                raise ValueError("Output.output_format must be JSON.")
+        elif isinstance(self.output, dict):
+            try:
+                _ = json.dumps(self.output)
+            except (TypeError, OverflowError) as e:
+                raise ValueError("Output is dict[str, any] but it is not JSON serializable") from e
+
+    def logs_text(self) -> str:
+        """
+        Returns the logs as a single string.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        str
+            The logs as a single string.
+        """
+
+        if self.logs is None:
+            return ""
+
+        return "\n".join(self.logs)

nextmv/input.py

@@ -91,6 +91,26 @@ class Input:
         new_options = copy.deepcopy(init_options)
         self.options = new_options
 
+    def to_dict(self) -> dict[str, any]:
+        """
+        Convert the input to a dictionary.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        dict[str, any]
+            The input as a dictionary.
+        """
+
+        return {
+            "data": self.data,
+            "input_format": self.input_format.value,
+            "options": self.options.to_dict() if self.options is not None else None,
+        }
+
 
 class InputLoader:
     """Base class for loading inputs."""

nextmv/output.py

@@ -322,6 +322,29 @@ class Output:
                 "output_format OutputFormat.CSV_ARCHIVE, supported type is `dict`"
             )
 
+    def to_dict(self) -> dict[str, any]:
+        """
+        Convert the `Output` object to a dictionary.
+
+        Returns
+        -------
+        dict[str, any]
+            The dictionary representation of the `Output` object.
+        """
+
+        output_dict = {
+            "options": self.options.to_dict() if self.options is not None else None,
+            "output_format": self.output_format,
+            "solution": self.solution,
+            "statistics": self.statistics.to_dict() if self.statistics is not None else None,
+            "assets": [asset.to_dict() for asset in self.assets] if self.assets is not None else None,
+        }
+
+        if self.output_format == OutputFormat.CSV_ARCHIVE:
+            output_dict["csv_configurations"] = self.csv_configurations
+
+        return output_dict
+
 
 class OutputWriter:
     """Base class for writing outputs."""

{nextmv-0.20.1.dist-info → nextmv-0.21.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nextmv
-Version: 0.20.1
+Version: 0.21.0
 Summary: The all-purpose Python SDK for Nextmv
 Project-URL: Homepage, https://www.nextmv.io
 Project-URL: Documentation, https://www.nextmv.io/docs/python-sdks/nextmv/installation

{nextmv-0.20.1.dist-info → nextmv-0.21.0.dist-info}/RECORD

@@ -1,27 +1,27 @@
-nextmv/__about__.py,sha256=KqK0kkAlPQdD5W8qM68QyM56Jy5p0vIV7skZlBkTMMo,24
+nextmv/__about__.py,sha256=cVvubA2yQRXFVwQqlSnbiwiGxtKCAPt8AmgS0WPjXVw,24
 nextmv/__entrypoint__.py,sha256=o6xYGBBUgCY_htteW-qNJfp-S3Th8dzS4RreJcDCnzM,1333
 nextmv/__init__.py,sha256=rz9oP7JGyFQJdUtYX4j9xx4Gv4LMGfNvXoEID5qUqig,1354
 nextmv/base_model.py,sha256=mdaBe-epNK1cFgP4TxbOtn3So4pCi1vMTOrIBkCBp7A,1050
-nextmv/input.py,sha256=ukP9R8o1zh6viP_Hv0jBivdPQ3K7Fy-PgUbxikUBpKg,12279
+nextmv/input.py,sha256=tYjiD9KM37Phqzm4faO4QLem8IXnU6HS160c1E-Yhc8,12732
 nextmv/logger.py,sha256=5qQ7E3Aaw3zzkIeiUuwYGzTcB7VhVqIzNZm5PHmdpUI,852
 nextmv/model.py,sha256=rwBdgmKSEp1DPv43zF0azj3QnbHO6O6wKs0PIGvVS40,9861
 nextmv/options.py,sha256=DZmjNxZyaTwnG2MEEKbIiBx3hI5F2DG70rY7DdeX44M,17336
-nextmv/output.py,sha256=YgRs9I7SEhpKzJPALfy09ew9wdVRX-uhwBsVsnB0bL4,19276
-nextmv/cloud/__init__.py,sha256=inttQhr3SEibNebMDNJzfVrvOLc4_fAR6zmwabjb7QQ,3209
+nextmv/output.py,sha256=cxw7Z0dTj5u42w2MQLOz2gesj046tvYFSWmhSZtRSXU,20082
+nextmv/cloud/__init__.py,sha256=ojgA2vQRQnR8QO2tJme1TbGrjhr9yq9LIauxKJ5F40U,3305
 nextmv/cloud/acceptance_test.py,sha256=NtqGhj-UYibxGBbU2kfjr-lYcngojb_5VMvK2WZwibI,6620
 nextmv/cloud/account.py,sha256=mZUGzV-uMGBA5BC_FPtsiCMFuz5jxEZ3O1BbELZIm18,1841
-nextmv/cloud/application.py,sha256=a_fuG_qyjCwjjx9elMHXM_2qkRniOOyMSMGcsLkzdeM,52409
+nextmv/cloud/application.py,sha256=cmgXz9J9pdugPVqTioqzXh_1iidY0Gcbr11e_JLat3E,55765
 nextmv/cloud/batch_experiment.py,sha256=UxrMNAm2c7-RZ9TWRhZBtiVyEeUG1pjsLNhYkoT5Jog,2236
 nextmv/cloud/client.py,sha256=E4C8wOGOdgyMf-DCDt4YfI7ib8HwmUhAtKMdrSBJc2M,9004
 nextmv/cloud/input_set.py,sha256=ovkP17-jYs0yWrbqTM6Nl5ubWQabD_UrDqAHNo8aE2s,672
 nextmv/cloud/instance.py,sha256=UfyfZXfL1ugCGAB6zwZJIAi8qxI1JCUGsluwaGdjfN4,1223
 nextmv/cloud/manifest.py,sha256=Fdjw4c14_ph20ASOzBs2mLslyLs1jGSxWThipGFp8rk,7458
 nextmv/cloud/package.py,sha256=Y3RethLiXXW7Y6_QBJDJdd7mFNaYaSBMyasIeGLav8o,12287
-nextmv/cloud/run.py,sha256=93o5SJMvN2b-Qd2ZGoXuelAHafKsGRt-DyOtE4srTsQ,4672
+nextmv/cloud/run.py,sha256=4hEANGXysDiOI1SQtfs7t_IVk-bxCldIs2TOvCI7a3E,8689
 nextmv/cloud/secrets.py,sha256=kqlN4ceww_L4kVTrAU8BZykRzXINO3zhMT_BLYea6tk,1764
 nextmv/cloud/status.py,sha256=C-ax8cLw0jPeh7CPsJkCa0s4ImRyFI4NDJJxI0_1sr4,602
 nextmv/cloud/version.py,sha256=sjVRNRtohHA97j6IuyM33_DSSsXYkZPusYgpb6hlcrc,1244
-nextmv-0.20.1.dist-info/METADATA,sha256=pv0uEyHcZehvo3sdsMhPfo1N1Vn0znpp7EbQUEpYJ98,14557
-nextmv-0.20.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-nextmv-0.20.1.dist-info/licenses/LICENSE,sha256=ZIbK-sSWA-OZprjNbmJAglYRtl5_K4l9UwAV3PGJAPc,11349
-nextmv-0.20.1.dist-info/RECORD,,
+nextmv-0.21.0.dist-info/METADATA,sha256=GYySweVUa_akR4revy2w1dgfgBoPJBD7q4AL95EiIeE,14557
+nextmv-0.21.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+nextmv-0.21.0.dist-info/licenses/LICENSE,sha256=ZIbK-sSWA-OZprjNbmJAglYRtl5_K4l9UwAV3PGJAPc,11349
+nextmv-0.21.0.dist-info/RECORD,,