nextmv 0.37.1.dev0__py3-none-any.whl → 0.38.0__py3-none-any.whl

nextmv/__about__.py

@@ -1 +1 @@
-__version__ = "v0.37.1.dev.0"
+__version__ = "v0.38.0"

nextmv/cloud/__init__.py

@@ -57,6 +57,7 @@ from .account import Queue as Queue
 from .account import QueuedRun as QueuedRun
 from .application import Application as Application
 from .application import poll as poll
+from .assets import RunAsset as RunAsset
 from .batch_experiment import BatchExperiment as BatchExperiment
 from .batch_experiment import BatchExperimentInformation as BatchExperimentInformation
 from .batch_experiment import BatchExperimentMetadata as BatchExperimentMetadata

nextmv/cloud/application.py

@@ -22,8 +22,10 @@ poll
     Function to poll for results with configurable options.
 """
 
+import io
 import json
 import os
+import pathlib
 import shutil
 import tarfile
 import tempfile
@@ -37,6 +39,7 @@ from nextmv._serialization import deflated_serialize_json
 from nextmv.base_model import BaseModel
 from nextmv.cloud import package
 from nextmv.cloud.acceptance_test import AcceptanceTest, Metric
+from nextmv.cloud.assets import RunAsset
 from nextmv.cloud.batch_experiment import (
     BatchExperiment,
     BatchExperimentInformation,
@@ -2539,6 +2542,120 @@ class Application:
         except OSError as e:
             raise Exception(f"error deleting output directory: {e}") from e
 
+    def list_assets(self, run_id: str) -> list[RunAsset]:
+        """
+        List the assets of a run.
+
+        Retrieves a list of assets associated with a specific run. This method ONLY
+        returns the asset metadata, the content needs to be fetched via the
+        `download_asset_content` method.
+
+        Parameters
+        ----------
+        run_id : str
+            ID of the run to list assets for.
+
+        Returns
+        -------
+        list[RunAsset]
+            List of assets associated with the run.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> assets = app.list_assets("run-123")
+        >>> for asset in assets:
+        ...     print(asset.id, asset.name)
+        b459daa6-1c13-48c6-b4c3-a262ea94cd04 clustering_polygons
+        a1234567-89ab-cdef-0123-456789abcdef histogram
+        """
+        response = self.client.request(
+            method="GET",
+            endpoint=f"{self.endpoint}/runs/{run_id}/assets",
+        )
+        assets_data = response.json().get("items", [])
+        for asset_data in assets_data:
+            asset_data["run_id"] = run_id
+        return [RunAsset.from_dict(asset) for asset in assets_data]
+
+    def download_asset_content(
+        self,
+        asset: RunAsset,
+        destination: str | pathlib.Path | io.BytesIO | None = None,
+    ) -> Any | None:
+        """
+        Downloads an asset's content to a specified destination.
+
+        Parameters
+        ----------
+        asset : RunAsset
+            The asset to be downloaded.
+        destination : Union[str, pathlib.Path, io.BytesIO, None]
+            The destination where the asset will be saved. This can be a file path
+            (as a string or pathlib.Path) or an io.BytesIO object. If None, the asset
+            content will not be saved to a file, but returned immediately. If the asset
+            type is JSON, the content will be returned as a dict.
+
+        Returns
+        -------
+        Any or None
+            If `destination` is None, returns the asset content: for JSON assets, a
+            `dict` parsed from the JSON response; for other asset types, the raw
+            `bytes` content. If `destination` is provided, the content is written
+            to the given destination and the method returns `None`.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> assets = app.list_assets("run-123")
+        >>> asset = assets[0]  # Assume we want to download the first asset
+        >>> # Download to a file path
+        >>> app.download_asset_content(asset, "polygons.geojson")
+        >>> # Download to an in-memory bytes buffer
+        >>> import io
+        >>> buffer = io.BytesIO()
+        >>> app.download_asset_content(asset, buffer)
+        >>> # Download and get content directly (for JSON assets)
+        >>> content = app.download_asset_content(asset)
+        >>> print(content)
+        {'type': 'FeatureCollection', 'features': [...]}
+        """
+        # First, get the download_url for the asset.
+        download_url_response = self.client.request(
+            method="GET",
+            endpoint=f"{self.endpoint}/runs/{asset.run_id}/assets/{asset.id}",
+        ).json()
+        download_url = download_url_response["download_url"]
+        asset_type = download_url_response.get("type", "json")
+
+        # Now, download the asset content using the download_url.
+        download_response = self.client.request(
+            method="GET",
+            endpoint=download_url,
+            headers={"Content-Type": "application/json" if asset_type == "json" else "application/octet-stream"},
+        )
+
+        # Save the content to the specified destination.
+        if destination is None:
+            if asset_type == "json":
+                return download_response.json()
+            return download_response.content
+        elif isinstance(destination, io.BytesIO):
+            destination.write(download_response.content)
+            return None
+        else:
+            with open(destination, "wb") as file:
+                file.write(download_response.content)
+            return None
+
     def run_input(self, run_id: str) -> dict[str, Any]:
         """
         Get the input of a run.

nextmv/cloud/assets.py

@@ -0,0 +1,48 @@
+from nextmv.base_model import BaseModel
+from nextmv.output import Visual
+
+
+class RunAsset(BaseModel):
+    """
+    Represents an asset associated with a Nextmv Cloud run.
+
+    You can import the `RunAsset` class from `nextmv.cloud`:
+
+    ```python
+    from nextmv.cloud import RunAsset
+    ```
+
+    A run asset represents metadata about an asset associated with a Nextmv Cloud run.
+
+    Parameters
+    ----------
+    id : str
+        Unique identifier of the asset.
+    run_id : str
+        Identifier of the run associated with the asset.
+    name : str
+        Name of the asset.
+    created_at : str
+        Timestamp of when the asset was created.
+    size : int
+        Size of the asset content in bytes.
+    content_type : str
+        Content type of the asset. Only `json` is allowed at the moment.
+    visual : Visual | None, optional
+        Visual schema of the asset, by default None.
+    """
+
+    id: str
+    """Unique identifier of the asset."""
+    run_id: str
+    """Identifier of the run associated with the asset."""
+    name: str
+    """Name of the asset."""
+    created_at: str
+    """Timestamp of when the asset was created."""
+    size: int
+    """Size of the asset content in bytes."""
+    content_type: str
+    """Content type of the asset. Only `json` is allowed at the moment."""
+    visual: Visual | None = None
+    """Visual schema of the asset."""

nextmv/output.py

@@ -469,9 +469,17 @@ class Asset(BaseModel):
 
     name: str
     """Name of the asset."""
-    content: Any
-    """Content of the asset. The type must be serializable to JSON."""
 
+    id: str | None = None
+    """
+    The ID of the asset. This ID will be populated by the Nextmv platform and can be used
+    to download the asset later.
+    """
+    content: Any | None = None
+    """
+    Content of the asset. The type must be serializable to JSON. Can be empty when
+    fetching the asset metadata only (e.g.: via the asset list endpoint).
+    """
     content_type: str | None = "json"
     """Content type of the asset. Only `json` is allowed"""
     description: str | None = None

{nextmv-0.37.1.dev0.dist-info → nextmv-0.38.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nextmv
-Version: 0.37.1.dev0
+Version: 0.38.0
 Summary: The all-purpose Python SDK for Nextmv
 Project-URL: Homepage, https://www.nextmv.io
 Project-URL: Documentation, https://nextmv-py.docs.nextmv.io/en/latest/nextmv/

{nextmv-0.37.1.dev0.dist-info → nextmv-0.38.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-nextmv/__about__.py,sha256=jmJy02hqA-ohOlVowf2bmUsdVIOh5HJI-wmoH6yjah0,30
+nextmv/__about__.py,sha256=TdPLKw4e3k7e30CulJMVTdoN7MAhlwuoBr5ZI1SLWBI,24
 nextmv/__entrypoint__.py,sha256=dA0iwwHtrq6Z9w9FxmxKLoBGLyhe7jWtUAU-Y3PEgHg,1094
 nextmv/__init__.py,sha256=mC-gAzCdoZJ0BOVe2fDzKNdBtbXzx8XOxHP_7DdPMdQ,3857
 nextmv/_serialization.py,sha256=jYitMS1MU8ldsmObT-K_8V8P2Wx69tnDiEHCCgPGun4,2834
@@ -9,15 +9,16 @@ nextmv/logger.py,sha256=kNIbu46MisrzYe4T0hNMpWfRTKKacDVvbtQcNys_c_E,2513
 nextmv/manifest.py,sha256=v9En9zMZVKZn6G_HThoKUZowMtZr5hxzwWiK9wkVHPU,49023
 nextmv/model.py,sha256=9g-pAUg8E--CyUFU39J7e4MZcj0WrWtgIqfwGmoF7UA,14998
 nextmv/options.py,sha256=rfQV0F5_it-L27wjqrs902wr4Q7sgSN7dw5o0c5sdEg,37842
-nextmv/output.py,sha256=f7LZTs6vr8MEpzg2OFzZar0LOMVzglM3EpR7kYW-vrk,56007
+nextmv/output.py,sha256=kjGWfgXfsEL6Np9xDhJdKyXYA17bMGjuuthDAWHzl2M,56288
 nextmv/polling.py,sha256=Mka7tChVR7Ws-Hg9W-Yzo7wthhVg-Qp-FK54E70Fzdw,9711
 nextmv/run.py,sha256=qeT3a0eqVHKvbQiFxmX_2epaj-rz2GyfpdZJ4ROFC4U,53135
 nextmv/safe.py,sha256=VAK4fGEurbLNji4Pg5Okga5XQSbI4aI9JJf95_68Z20,3867
 nextmv/status.py,sha256=SCDLhh2om3yeO5FxO0x-_RShQsZNXEpjHNdCGdb3VUI,2787
-nextmv/cloud/__init__.py,sha256=4gV_w84BCenHlG5kTOWyGlg_I-kFxi4_XVb0K8No8vI,5295
+nextmv/cloud/__init__.py,sha256=n8laWdl0BjKmJOgGdPLHYUY_eaqhmXlW0-421A3SfwM,5336
 nextmv/cloud/acceptance_test.py,sha256=fZdp4O6pZrl7TaiUrTFPp7O4VJt-4R_W2yo4s8UAS5I,27691
 nextmv/cloud/account.py,sha256=jIdGNyI3l3dVh2PuriAwAOrEuWRM150WgzxcBMVBNRw,6058
-nextmv/cloud/application.py,sha256=VU3F9M8VqPhUZL-6g6am-NFh_LQQ9j3gZCRAhY0qU_o,139892
+nextmv/cloud/application.py,sha256=tJRi6lfzfsPemqe37p4MigpVEnvi5fSiufUmErLxKk4,144220
+nextmv/cloud/assets.py,sha256=alw634ub-DR0CHQXZy_ObeGvQthPXFLdgzgbvbH1SGY,1376
 nextmv/cloud/batch_experiment.py,sha256=VmKgjBW6BpkH4loO0afMGNXrwJ5whhijQ99pm94vBto,10349
 nextmv/cloud/client.py,sha256=Yj4FE4GKsLHkYijAYXcotlyNfhAWANMuWetHXsYPg1M,18101
 nextmv/cloud/ensemble.py,sha256=_hKPjSLtuGH1xGG70ZBsmY_IL5XinZqVHHwBxtX9Omw,8570
@@ -44,7 +45,7 @@ nextmv/local/geojson_handler.py,sha256=7FavJdkUonop-yskjis0x3qFGB8A5wZyoBUblw-bV
 nextmv/local/local.py,sha256=cp56UpI8h19Ob6Jvb_Ni0ceXH5Vv3ET_iPTDe6ftq3Y,2617
 nextmv/local/plotly_handler.py,sha256=bLb50e3AkVr_W-F6S7lXfeRdN60mG2jk3UElNmhoMWU,1930
 nextmv/local/runner.py,sha256=Fa-G4g5yaBgLeBfYU-ePs65Q3Ses_xYvXGhPtHpAkrU,8546
-nextmv-0.37.1.dev0.dist-info/METADATA,sha256=G1Emcy0_HHozlRmqPaOR8MW6SXPbFA8du6i5ocvXOPg,15995
-nextmv-0.37.1.dev0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-nextmv-0.37.1.dev0.dist-info/licenses/LICENSE,sha256=ZIbK-sSWA-OZprjNbmJAglYRtl5_K4l9UwAV3PGJAPc,11349
-nextmv-0.37.1.dev0.dist-info/RECORD,,
+nextmv-0.38.0.dist-info/METADATA,sha256=pwHkld0mBlgrNOibG0ruEVsRWDuJlC-rd1IyfuDGD3E,15990
+nextmv-0.38.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+nextmv-0.38.0.dist-info/licenses/LICENSE,sha256=ZIbK-sSWA-OZprjNbmJAglYRtl5_K4l9UwAV3PGJAPc,11349
+nextmv-0.38.0.dist-info/RECORD,,