nextmv 0.10.3.dev0__py3-none-any.whl → 0.35.0__py3-none-any.whl

nextmv/cloud/url.py

@@ -0,0 +1,73 @@
+"""
+Module for declarations related to upload and download URLs in Nextmv Cloud.
+
+Classes
+-------
+DownloadURL
+    Represents a download URL for fetching content from Nextmv Cloud.
+UploadURL
+    Represents an upload URL for sending content to Nextmv Cloud.
+"""
+
+from nextmv.base_model import BaseModel
+
+
+class DownloadURL(BaseModel):
+    """
+    Result of getting a download URL.
+
+    You can import the `DownloadURL` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import DownloadURL
+    ```
+
+    This class represents a download URL that can be used to fetch content
+    from Nextmv Cloud, typically used for downloading large run results.
+
+    Attributes
+    ----------
+    url : str
+        URL to use for downloading the file.
+
+    Examples
+    --------
+    >>> download_url = DownloadURL(url="https://example.com/download")
+    >>> response = requests.get(download_url.url)
+    """
+
+    url: str
+    """URL to use for downloading the file."""
+
+
+class UploadURL(BaseModel):
+    """
+    Result of getting an upload URL.
+
+    You can import the `UploadURL` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import UploadURL
+    ```
+
+    This class represents an upload URL that can be used to send data to
+    Nextmv Cloud, typically used for uploading large inputs for runs.
+
+    Attributes
+    ----------
+    upload_id : str
+        ID of the upload, used to reference the uploaded content.
+    upload_url : str
+        URL to use for uploading the file.
+
+    Examples
+    --------
+    >>> upload_url = UploadURL(upload_id="123", upload_url="https://example.com/upload")
+    >>> with open("large_input.json", "rb") as f:
+    ...     requests.put(upload_url.upload_url, data=f)
+    """
+
+    upload_id: str
+    """ID of the upload."""
+    upload_url: str
+    """URL to use for uploading the file."""

nextmv/cloud/version.py

@@ -0,0 +1,174 @@
+"""Manages application versions within the Nextmv Cloud API.
+
+This module provides data models for representing application versions,
+their executables, and associated requirements. These models are used
+for interacting with version-related endpoints of the Nextmv Cloud API,
+allowing users to define, retrieve, and manage different versions of their
+decision applications.
+
+Classes
+-------
+VersionExecutableRequirements
+    Defines the requirements for a version's executable, such as type and runtime.
+VersionExecutable
+    Represents the executable artifact for a specific application version.
+Version
+    Represents a version of an application, linking to its executable and metadata.
+"""
+
+from datetime import datetime
+
+from nextmv.base_model import BaseModel
+
+
+class VersionExecutableRequirements(BaseModel):
+    """
+    Requirements for a version executable.
+
+    You can import the `VersionExecutableRequirements` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import VersionExecutableRequirements
+    ```
+
+    These requirements specify the environment and type of executable needed
+    to run a particular version of an application.
+
+    Parameters
+    ----------
+    executable_type : str
+        The type of the executable (e.g., "binary", "docker").
+    runtime : str
+        The runtime environment for the executable (e.g., "go", "python").
+
+    Examples
+    --------
+    >>> requirements = VersionExecutableRequirements(
+    ...     executable_type="binary",
+    ...     runtime="go1.x"
+    ... )
+    >>> print(requirements.executable_type)
+    binary
+    """
+
+    executable_type: str
+    """Type of the executable."""
+    runtime: str
+    """Runtime for the executable."""
+
+
+class VersionExecutable(BaseModel):
+    """
+    Executable for a version.
+
+    You can import the `VersionExecutable` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import VersionExecutable
+    ```
+
+    This class holds information about the actual executable file or image
+    associated with an application version, including who uploaded it and when.
+
+    Parameters
+    ----------
+    id : str
+        Unique identifier for the version executable.
+    user_email : str
+        Email of the user who uploaded the executable.
+    uploaded_at : datetime
+        Timestamp indicating when the executable was uploaded.
+    requirements : VersionExecutableRequirements
+        The specific requirements for this executable.
+
+    Examples
+    --------
+    >>> from datetime import datetime
+    >>> reqs = VersionExecutableRequirements(executable_type="docker", runtime="custom")
+    >>> executable = VersionExecutable(
+    ...     id="exec-123",
+    ...     user_email="user@example.com",
+    ...     uploaded_at=datetime.now(),
+    ...     requirements=reqs
+    ... )
+    >>> print(executable.id)
+    exec-123
+    """
+
+    id: str
+    """ID of the version."""
+    user_email: str
+    """Email of the user who uploaded the executable."""
+    uploaded_at: datetime
+    """Time the executable was uploaded."""
+    requirements: VersionExecutableRequirements
+    """Requirements for the executable."""
+
+
+class Version(BaseModel):
+    """
+    A version of an application representing a code artifact or a compiled binary.
+
+    You can import the `Version` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import Version
+    ```
+
+    This class encapsulates all details of a specific version of an application,
+    including its metadata, associated executable, and timestamps.
+
+    Parameters
+    ----------
+    id : str
+        Unique identifier for the version.
+    application_id : str
+        Identifier of the application to which this version belongs.
+    name : str
+        User-defined name for the version (e.g., "v1.0.0", "feature-branch-build").
+    description : str
+        A more detailed description of the version and its changes.
+    executable : VersionExecutable
+        The executable artifact associated with this version.
+    created_at : datetime
+        Timestamp indicating when the version was created.
+    updated_at : datetime
+        Timestamp indicating when the version was last updated.
+
+    Examples
+    --------
+    >>> from datetime import datetime
+    >>> reqs = VersionExecutableRequirements(executable_type="binary", runtime="java11")
+    >>> exe = VersionExecutable(
+    ...     id="exec-abc",
+    ...     user_email="dev@example.com",
+    ...     uploaded_at=datetime.now(),
+    ...     requirements=reqs
+    ... )
+    >>> version_info = Version(
+    ...     id="ver-xyz",
+    ...     application_id="app-123",
+    ...     name="Initial Release",
+    ...     description="First stable release of the model.",
+    ...     executable=exe,
+    ...     created_at=datetime.now(),
+    ...     updated_at=datetime.now()
+    ... )
+    >>> print(version_info.name)
+    Initial Release
+    """
+
+    id: str
+    """ID of the version."""
+    application_id: str
+    """ID of the application that this is a version of."""
+    name: str
+    """Name of the version."""
+    description: str
+    """Description of the version."""
+    executable: VersionExecutable
+    """Executable for the version."""
+    created_at: datetime
+    """Creation time of the version."""
+    updated_at: datetime
+    """Last update time of the version."""

nextmv/default_app/.gitignore

@@ -0,0 +1 @@
+.nextmv

nextmv/default_app/README.md

@@ -0,0 +1,32 @@
+# Nextmv Application
+
+This is the basic structure of a Nextmv application.
+
+```text
+├── app.yaml
+├── main.py
+├── README.md
+├── requirements.txt
+└── src
+```
+
+* `app.yaml`: App manifest, containing the configuration to run the app
+  remotely on Nextmv Cloud.
+* `main.py`: Entry point for the app.
+* `README.md`: Description of the app.
+* `requirements.txt`: Python dependencies for the app.
+* `src/`: Source code for the app.
+
+A sample input file is also provided as `input.json`.
+
+1. Install packages.
+
+    ```bash
+    pip3 install -r requirements.txt
+    ```
+
+2. Run the app.
+
+    ```bash
+    cat input.json | python3 main.py
+    ```

nextmv/default_app/app.yaml

@@ -0,0 +1,12 @@
+# This manifest holds the information the app needs to run on the Nextmv Cloud.
+type: python
+runtime: ghcr.io/nextmv-io/runtime/python:3.11
+python:
+  # All listed packages will get bundled with the app.
+  pip-requirements: requirements.txt
+
+# List all files/directories that should be included in the app. Globbing
+# (e.g.: configs/*.json) is supported.
+files:
+  - src/
+  - main.py

nextmv/default_app/input.json

@@ -0,0 +1,5 @@
+{
+  "name": "Patches",
+  "radius": 6378,
+  "distance": 147.6
+}

nextmv/default_app/main.py

@@ -0,0 +1,37 @@
+from src.visuals import create_visuals
+
+import nextmv
+
+# Read the input from stdin.
+input = nextmv.load()
+name = input.data["name"]
+
+options = nextmv.Options(
+    nextmv.Option("details", bool, True, "Print details to logs. Default true.", False),
+)
+
+##### Insert model here
+
+# Print logs that render in the run view in Nextmv Console.
+message = f"Hello, {name}"
+nextmv.log(message)
+
+if options.details:
+    detail = f"You are {input.data['distance']} million km from the sun"
+    nextmv.log(detail)
+
+assets = create_visuals(name, input.data["radius"], input.data["distance"])
+
+# Write output and statistics.
+output = nextmv.Output(
+    options=options,
+    solution={"message": message},
+    statistics=nextmv.Statistics(
+        result=nextmv.ResultStatistics(
+            value=1.23,
+            custom={"message": message},
+        ),
+    ),
+    assets=assets,
+)
+nextmv.write(output)

nextmv/default_app/requirements.txt

@@ -0,0 +1,2 @@
+nextmv>=0.29.3
+plotly>=6.2.0

nextmv/default_app/src/main.py

@@ -0,0 +1,37 @@
+from visuals import create_visuals
+
+import nextmv
+
+# Read the input from stdin.
+input = nextmv.load()
+name = input.data["name"]
+
+options = nextmv.Options(
+    nextmv.Option("details", bool, True, "Print details to logs. Default true.", False),
+)
+
+##### Insert model here
+
+# Print logs that render in the run view in Nextmv Console.
+message = f"Hello, {name}"
+nextmv.log(message)
+
+if options.details:
+    detail = f"You are {input.data['distance']} million km from the sun"
+    nextmv.log(detail)
+
+assets = create_visuals(name, input.data["radius"], input.data["distance"])
+
+# Write output and statistics.
+output = nextmv.Output(
+    options=options,
+    solution={"message": message},
+    statistics=nextmv.Statistics(
+        result=nextmv.ResultStatistics(
+            value=1.23,
+            custom={"message": message},
+        ),
+    ),
+    assets=assets,
+)
+nextmv.write(output)

nextmv/default_app/src/visuals.py

@@ -0,0 +1,36 @@
+import json
+
+import plotly.graph_objects as go
+
+import nextmv
+
+
+def create_visuals(name: str, radius: float, distance: float) -> list[nextmv.Asset]:
+    """Create a Plotly bar chart with radius and distance for a planet."""
+
+    fig = go.Figure()
+    fig.add_trace(
+        go.Bar(x=[name], y=[radius], name="Radius (km)", marker_color="red", opacity=0.5),
+    )
+    fig.add_trace(
+        go.Bar(x=[name], y=[distance], name="Distance (Millions km)", marker_color="blue", opacity=0.5),
+    )
+    fig.update_layout(
+        title="Radius and Distance by Planet", xaxis_title="Planet", yaxis_title="Values", barmode="group"
+    )
+    fig = fig.to_json()
+
+    assets = [
+        nextmv.Asset(
+            name="Plotly example",
+            content_type="json",
+            visual=nextmv.Visual(
+                visual_schema=nextmv.VisualSchema.PLOTLY,
+                visual_type="custom-tab",
+                label="Charts",
+            ),
+            content=[json.loads(fig)],
+        )
+    ]
+
+    return assets

nextmv/deprecated.py

@@ -0,0 +1,47 @@
+"""Utilities for handling deprecated functionality within the Nextmv Python SDK.
+
+This module provides tools to mark functions, methods, or features as deprecated,
+emitting appropriate warnings to users. These warnings inform users that the
+functionality will be removed in a future release and suggest alternative approaches.
+
+The main purpose of this module is to help with the smooth transition when
+API changes are necessary, giving users time to update their code before
+functionality is removed completely.
+"""
+
+import warnings
+
+
+def deprecated(name: str, reason: str) -> None:
+    """Mark functionality as deprecated with a warning message.
+
+    This function emits a DeprecationWarning when called, indicating that
+    the functionality will be removed in a future release.
+
+    Parameters
+    ----------
+    name : str
+        The name of the function, method, or feature being deprecated.
+    reason : str
+        The reason why the functionality is being deprecated, possibly
+        with suggestions for alternative approaches.
+
+    Notes
+    -----
+    This function temporarily changes the warning filter to ensure the
+    deprecation warning is shown, then resets it afterward.
+
+    Examples
+    --------
+    >>> def some_function():
+    ...     deprecated("feature_x", "Use feature_y instead")
+    ...     # function implementation
+    """
+
+    warnings.simplefilter("always", DeprecationWarning)
+    warnings.warn(
+        f"{name}: {reason}. This functionality will be removed in a future release",
+        category=DeprecationWarning,
+        stacklevel=2,
+    )
+    warnings.simplefilter("default", DeprecationWarning)