nextmv 1.0.0.dev3__py3-none-any.whl → 1.0.0.dev5__py3-none-any.whl

nextmv/cloud/switchback.py

@@ -91,10 +91,10 @@ class SwitchbackPlan(BaseModel):
 
     Parameters
     ----------
-    interval_duration_seconds : int
-        Duration of each interval in seconds.
-    total_intervals : int
-        Total number of intervals in the switchback test.
+    start : datetime, optional
+        Start time of the switchback test.
+    units : list[SwitchbackPlanUnit], optional
+        List of switchback plan units.
     """
 
     start: datetime | None = None
@@ -151,7 +151,10 @@ class SwitchbackTestMetadata(BaseModel):
     """The current status of the switchback test."""
 
 
-class SwitchbackTest(SwitchbackTestMetadata):
+# This class uses some fields defined in SwitchbackTestMetadata. We are not
+# using inheritance to help the user understand the full structure when using
+# tools like intellisense.
+class SwitchbackTest(BaseModel):
     """
     A Nextmv Cloud switchback test definition.
 
@@ -167,16 +170,50 @@ class SwitchbackTest(SwitchbackTestMetadata):
 
     Parameters
     ----------
+    switchback_test_id : str, optional
+        The unique identifier of the switchback test.
+    name : str, optional
+        Name of the switchback test.
+    description : str, optional
+        Description of the switchback test.
+    app_id : str, optional
+        ID of the application to which the switchback test belongs.
+    created_at : datetime, optional
+        Creation date of the switchback test.
+    updated_at : datetime, optional
+        Last update date of the switchback test.
+    status : ExperimentStatus, optional
+        The current status of the switchback test.
+    started_at : datetime, optional
+        Start date of the switchback test, if applicable.
     completed_at : datetime, optional
         Completion date of the switchback test, if applicable.
     comparison : TestComparisonSingle, optional
         Test comparison defined in the switchback test.
-    start_events : StartEvents, optional
-        Start events for the switchback test.
-    termination_events : TerminationEvents, optional
-        Termination events for the switchback test.
+    plan : SwitchbackPlan, optional
+        Switchback plan defining the intervals and instance switching.
+    runs : list[Run], optional
+        List of runs in the switchback test.
     """
 
+    switchback_test_id: str | None = Field(
+        serialization_alias="id",
+        validation_alias=AliasChoices("id", "switchback_test_id"),
+        default=None,
+    )
+    """The unique identifier of the switchback test."""
+    name: str | None = None
+    """Name of the switchback test."""
+    description: str | None = None
+    """Description of the switchback test."""
+    app_id: str | None = None
+    """ID of the application to which the switchback test belongs."""
+    created_at: datetime | None = None
+    """Creation date of the switchback test."""
+    updated_at: datetime | None = None
+    """Last update date of the switchback test."""
+    status: ExperimentStatus | None = None
+    """The current status of the switchback test."""
     started_at: datetime | None = None
     """Start date of the switchback test, if applicable."""
     completed_at: datetime | None = None

nextmv/default_app/main.py

@@ -26,12 +26,10 @@ assets = create_visuals(name, input.data["radius"], input.data["distance"])
 output = nextmv.Output(
     options=options,
     solution={"message": message},
-    statistics=nextmv.Statistics(
-        result=nextmv.ResultStatistics(
-            value=1.23,
-            custom={"message": message},
-        ),
-    ),
+    metrics={
+        "value": 1.23,
+        "custom": {"message": message},
+    },
     assets=assets,
 )
 nextmv.write(output)

nextmv/deprecated.py

@@ -1,4 +1,5 @@
-"""Utilities for handling deprecated functionality within the Nextmv Python SDK.
+"""
+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
@@ -13,7 +14,8 @@ import warnings
 
 
 def deprecated(name: str, reason: str) -> None:
-    """Mark functionality as deprecated with a warning message.
+    """
+    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.
@@ -40,7 +42,7 @@ def deprecated(name: str, reason: str) -> None:
 
     warnings.simplefilter("always", DeprecationWarning)
     warnings.warn(
-        f"{name}: {reason}. This functionality will be removed in a future release",
+        f"{name}: {reason}. This functionality will be removed in the next major release.",
         category=DeprecationWarning,
         stacklevel=2,
     )

nextmv/input.py

@@ -38,7 +38,6 @@ from enum import Enum
 from typing import Any
 
 from nextmv._serialization import serialize_json
-from nextmv.deprecated import deprecated
 from nextmv.options import Options
 
 INPUTS_KEY = "inputs"
@@ -941,57 +940,6 @@ class LocalInputLoader(InputLoader):
         return data
 
 
-def load_local(
-    input_format: InputFormat | None = InputFormat.JSON,
-    options: Options | None = None,
-    path: str | None = None,
-    csv_configurations: dict[str, Any] | None = None,
-) -> Input:
-    """
-    !!! warning
-        `load_local` is deprecated, use `load` instead.
-
-    Load input data from local sources.
-
-    This is a convenience function for instantiating a `LocalInputLoader`
-    and calling its `load` method.
-
-    Parameters
-    ----------
-    input_format : InputFormat, optional
-        Format of the input data. Default is `InputFormat.JSON`.
-    options : Options, optional
-        Options for loading the input data.
-    path : str, optional
-        Path to the input data.
-    csv_configurations : dict[str, Any], optional
-        Configurations for loading CSV files. Custom kwargs for
-        Python's `csv.DictReader`.
-
-    Returns
-    -------
-    Input
-        The loaded input data in an Input object.
-
-    Raises
-    ------
-    ValueError
-        If the path is invalid or data format is incorrect.
-
-    See Also
-    --------
-    load : The recommended function to use instead.
-    """
-
-    deprecated(
-        name="load_local",
-        reason="`load_local` is deprecated, use `load` instead",
-    )
-
-    loader = LocalInputLoader()
-    return loader.load(input_format, options, path, csv_configurations)
-
-
 _LOCAL_INPUT_LOADER = LocalInputLoader()
 """Default instance of LocalInputLoader used by the load function."""
 

nextmv/local/executor.py

@@ -22,6 +22,8 @@ process_run_information
     Function to update run metadata including duration and status.
 process_run_logs
     Function to process and save run logs.
+process_run_metrics
+    Function to process and save run metrics.
 process_run_statistics
     Function to process and save run statistics.
 process_run_assets
@@ -57,7 +59,16 @@ from nextmv.local.local import (
 )
 from nextmv.local.plotly_handler import handle_plotly_visual
 from nextmv.manifest import Manifest, ManifestType
-from nextmv.output import ASSETS_KEY, OUTPUTS_KEY, SOLUTIONS_KEY, STATISTICS_KEY, Asset, OutputFormat, VisualSchema
+from nextmv.output import (
+    ASSETS_KEY,
+    METRICS_KEY,
+    OUTPUTS_KEY,
+    SOLUTIONS_KEY,
+    STATISTICS_KEY,
+    Asset,
+    OutputFormat,
+    VisualSchema,
+)
 from nextmv.status import StatusV2
 
 
@@ -305,7 +316,7 @@ def process_run_output(
 ) -> None:
     """
     Processes the result of the subprocess run. This function is in charge of
-    handling the run results, including solutions, statistics, logs, assets,
+    handling the run results, including solutions, statistics, metrics, logs, assets,
     and visuals.
 
     Parameters
@@ -347,6 +358,13 @@ def process_run_output(
         result=result,
         stdout_output=stdout_output,
     )
+    process_run_metrics(
+        temp_run_outputs_dir=temp_run_outputs_dir,
+        outputs_dir=outputs_dir,
+        stdout_output=stdout_output,
+        temp_src=temp_src,
+        manifest=manifest,
+    )
     process_run_statistics(
         temp_run_outputs_dir=temp_run_outputs_dir,
         outputs_dir=outputs_dir,
@@ -499,6 +517,65 @@ def process_run_logs(
 
         f.write(std_err)
 
+def process_run_metrics(
+    temp_run_outputs_dir: str,
+    outputs_dir: str,
+    stdout_output: str | dict[str, Any],
+    temp_src: str,
+    manifest: Manifest,
+) -> None:
+    """
+    Processes the metrics of the run. Checks for an outputs/metrics folder
+    or custom metrics file location from manifest. If found, copies to run
+    directory. Otherwise, attempts to extract metrics from stdout.
+
+    Parameters
+    ----------
+    temp_run_outputs_dir : str
+        The path to the temporary outputs directory.
+    outputs_dir : str
+        The path to the outputs directory in the run directory.
+    stdout_output : Union[str, dict[str, Any]]
+        The stdout output of the run, either as raw string or parsed dictionary.
+    temp_src : str
+        The path to the temporary source directory.
+    manifest : Manifest
+        The application manifest containing configuration and custom paths.
+    """
+
+    metrics_dst = os.path.join(outputs_dir, METRICS_KEY)
+    os.makedirs(metrics_dst, exist_ok=True)
+    metrics_file = f"{METRICS_KEY}.json"
+
+    # Check for custom location in manifest and override metrics_src if needed.
+    if (
+        manifest.configuration is not None
+        and manifest.configuration.content is not None
+        and manifest.configuration.content.format == OutputFormat.MULTI_FILE
+        and manifest.configuration.content.multi_file is not None
+    ):
+        metrics_src_file = os.path.join(temp_src, manifest.configuration.content.multi_file.output.metrics)
+
+        # If the custom metrics file exists, copy it to the metrics destination
+        if os.path.exists(metrics_src_file) and os.path.isfile(metrics_src_file):
+            metrics_dst_file = os.path.join(metrics_dst, metrics_file)
+            shutil.copy2(metrics_src_file, metrics_dst_file)
+            return
+
+    metrics_src = os.path.join(temp_run_outputs_dir, METRICS_KEY)
+    if os.path.exists(metrics_src) and os.path.isdir(metrics_src):
+        shutil.copytree(metrics_src, metrics_dst, dirs_exist_ok=True)
+        return
+
+    if not isinstance(stdout_output, dict):
+        return
+
+    if METRICS_KEY not in stdout_output:
+        return
+
+    with open(os.path.join(metrics_dst, metrics_file), "w") as f:
+        metrics = {METRICS_KEY: stdout_output[METRICS_KEY]}
+        json.dump(metrics, f, indent=2)
 
 def process_run_statistics(
     temp_run_outputs_dir: str,
@@ -508,6 +585,9 @@ def process_run_statistics(
     manifest: Manifest,
 ) -> None:
     """
+    !!! warning
+    `process_run_statistics` is deprecated, use `process_run_metrics` instead.
+
     Processes the statistics of the run. Checks for an outputs/statistics folder
     or custom statistics file location from manifest. If found, copies to run
     directory. Otherwise, attempts to extract statistics from stdout.
@@ -848,7 +928,7 @@ def _copy_new_or_modified_files(  # noqa: C901
     This function identifies files that are either new (not present in the original
     source) or have been modified (different content, checksum, or modification time)
     compared to the original source. It excludes files that exist in specified
-    exclusion directories to avoid copying input data, statistics, or assets as
+    exclusion directories to avoid copying input data, statistics, metrics, or assets as
     solution outputs.
 
     Parameters

nextmv/local/geojson_handler.py

@@ -111,7 +111,7 @@ def extract_coordinates(coords, all_coords) -> None:
       like Polygons and MultiPolygons
     """
     if isinstance(coords, list):
-        if len(coords) == 2 and isinstance(coords[0], (int, float)) and isinstance(coords[1], (int, float)):
+        if len(coords) == 2 and isinstance(coords[0], int | float) and isinstance(coords[1], int | float):
             # This is a coordinate pair [lon, lat]
             all_coords.append(coords)
         else:

nextmv/local/runner.py

@@ -204,7 +204,7 @@ def new_run(
     if description is None:
         description = f"Local run created at {created_at.isoformat().replace('+00:00', 'Z')}"
 
-    if name is None:
+    if name is None or name == "":
         name = f"local run {run_id}"
 
     information = RunInformation(

nextmv/manifest.py

@@ -829,7 +829,9 @@ class ManifestContentMultiFileOutput(BaseModel):
     Parameters
     ----------
     statistics : Optional[str], default=""
-        The path to the statistics file.
+        Deprecated: Use `metrics` instead. The path to the statistics file.
+    metrics : Optional[str], default=""
+        The path to the metrics file.
     assets : Optional[str], default=""
         The path to the assets file.
     solutions : Optional[str], default=""
@@ -839,16 +841,18 @@ class ManifestContentMultiFileOutput(BaseModel):
     --------
     >>> from nextmv import ManifestContentMultiFileOutput
     >>> output_config = ManifestContentMultiFileOutput(
-    ...     statistics="my-outputs/statistics.json",
+    ...     metrics="my-outputs/metrics.json",
     ...     assets="my-outputs/assets.json",
     ...     solutions="my-outputs/solutions/"
     ... )
-    >>> output_config.statistics
-    'my-outputs/statistics.json'
+    >>> output_config.metrics
+    'my-outputs/metrics.json'
     """
 
     statistics: str | None = ""
-    """The path to the statistics file."""
+    """Deprecated: Use `metrics` instead. The path to the statistics file."""
+    metrics: str | None = ""
+    """The path to the metrics file."""
     assets: str | None = ""
     """The path to the assets file."""
     solutions: str | None = ""
@@ -878,7 +882,7 @@ class ManifestContentMultiFile(BaseModel):
     >>> multi_file_config = ManifestContentMultiFile(
     ...     input=ManifestContentMultiFileInput(path="data/input/"),
     ...     output=ManifestContentMultiFileOutput(
-    ...         statistics="my-outputs/statistics.json",
+    ...         metrics="my-outputs/metrics.json",
     ...         assets="my-outputs/assets.json",
     ...         solutions="my-outputs/solutions/"
     ...     )
@@ -919,7 +923,7 @@ class ManifestContent(BaseModel):
     ...     multi_file=ManifestContentMultiFile(
     ...         input=ManifestContentMultiFileInput(path="data/input/"),
     ...         output=ManifestContentMultiFileOutput(
-    ...             statistics="my-outputs/statistics.json",
+    ...             metrics="my-outputs/metrics.json",
     ...             assets="my-outputs/assets.json",
     ...             solutions="my-outputs/solutions/"
     ...         )

nextmv/model.py

@@ -195,7 +195,7 @@ class Model:
     ...         return nextmv.Output(
     ...             options=input.options,
     ...             solution=nextroute_output.solutions[0].to_dict(),
-    ...             statistics=nextroute_output.statistics.to_dict(),
+    ...             metrics=nextroute_output.metrics.to_dict(),
     ...         )
     """
 
@@ -234,7 +234,7 @@ class Model:
         ...     return Output(
         ...         options=input.options,
         ...         solution=result,
-        ...         statistics={"processing_time": 0.5}
+        ...         metrics={"processing_time": 0.5}
         ...     )
         """