nextmv 0.40.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

nextmv/cli/message.py

@@ -0,0 +1,170 @@
+"""
+The message module is used to print messages to the user with pre-defined
+formatting. Logging, in general, is always printed to stderr.
+"""
+
+import sys
+from enum import Enum
+from typing import Any
+
+import rich
+import typer
+
+
+def message(msg: str, emoji: str | None = None) -> None:
+    """
+    Pretty-print a message. Your message should end with a period. The use of
+    emojis is encouraged to give context to the message. An emoji should be a
+    string as specified in:
+    https://rich.readthedocs.io/en/latest/markup.html#emoji.
+
+    Parameters
+    ----------
+    msg : str
+        The message to display.
+    emoji : str | None
+        An optional emoji to prefix the message. If None, no emoji is used. The
+        emoji should be a string as specified in:
+        https://rich.readthedocs.io/en/latest/markup.html#emoji. For example:
+        `:hourglass_flowing_sand:`.
+    """
+
+    msg = _format(msg)
+    if emoji:
+        rich.print(f"{emoji} {msg}", file=sys.stderr)
+        return
+
+    rich.print(msg, file=sys.stderr)
+
+
+def info(msg: str) -> None:
+    """
+    Pretty-print an informational message. Your message should end with a
+    period.
+
+    Parameters
+    ----------
+    msg : str
+        The informational message to display.
+    """
+
+    message(msg, emoji=":bulb:")
+
+
+def in_progress(msg: str) -> None:
+    """
+    Pretty-print an in-progress message with an hourglass emoji. Your message
+    should end with a period.
+
+    Parameters
+    ----------
+    msg : str
+        The in-progress message to display.
+    """
+
+    message(msg, emoji=":hourglass_flowing_sand:")
+
+
+def success(msg: str) -> None:
+    """
+    Pretty-print a success message. Your message should end with a period.
+
+    Parameters
+    ----------
+    msg : str
+        The success message to display.
+    """
+
+    message(msg, emoji=":white_check_mark:")
+
+
+def warning(msg: str) -> None:
+    """
+    Pretty-print a warning message. Your message should end with a period.
+
+    Parameters
+    ----------
+    msg : str
+        The warning message to display.
+    """
+
+    msg = _format(msg)
+    rich.print(f":construction: [yellow] Warning:[/yellow] {msg}", file=sys.stderr)
+
+
+def error(msg: str) -> None:
+    """
+    Pretty-print an error message and exit with code 1. Your message should end
+    with a period.
+
+    Parameters
+    ----------
+    msg : str
+        The error message to display.
+
+    Raises
+    ------
+    typer.Exit
+        Exits the program with code 1.
+    """
+
+    msg = _format(msg)
+    rich.print(f":x: [red]Error:[/red] {msg}", file=sys.stderr)
+
+    raise typer.Exit(code=1)
+
+
+def print_json(data: dict[str, Any] | list[dict[str, Any]]) -> None:
+    """
+    Pretty-print json-serializable data as JSON to stdout.
+
+    Parameters
+    ----------
+    data : dict[str, Any] | list[dict[str, Any]]
+        The data to print as JSON.
+    """
+
+    rich.print_json(data=data)
+
+
+def enum_values(enum_class: Enum) -> str:
+    """
+    Get a nicely formatted string of the values of an Enum class, using commas
+    and an oxford comma.
+
+    Parameters
+    ----------
+    enum_class : Enum
+        The Enum class to get the values from.
+
+    Returns
+    -------
+    str
+        A nicely formatted string of the values of the Enum class.
+    """
+
+    values = [f"[magenta]{member.value}[/magenta]" for member in enum_class]
+    if len(values) == 0:
+        return ""
+    if len(values) == 1:
+        return values[0]
+    if len(values) == 2:
+        return " and ".join(values)
+
+    return ", ".join(values[:-1]) + ", and " + values[-1]
+
+
+def _format(msg: str) -> str:
+    """
+    Format a message to ensure it ends with a period.
+
+    Parameters
+    ----------
+    msg : str
+        The message to format.
+    """
+    msg = msg.rstrip("\n")
+    if not msg.endswith("."):
+        msg += "."
+
+    return msg

nextmv/cli/options.py

@@ -22,3 +22,199 @@ ProfileOption = Annotated[
         metavar="PROFILE_NAME",
     ),
 ]
+
+# app_id option - can be used in any command that requires an application ID.
+# Define it as follows in commands or callbacks, as necessary:
+# app_id: AppIDOption
+AppIDOption = Annotated[
+    str,
+    typer.Option(
+        "--app-id",
+        "-a",
+        help="The Nextmv Cloud application ID to use for this action.",
+        envvar="NEXTMV_APP_ID",
+        metavar="APP_ID",
+    ),
+]
+
+# run_id option - can be used in any command that requires a run ID.
+# Define it as follows in commands or callbacks, as necessary:
+# run_id: RunIDOption
+RunIDOption = Annotated[
+    str,
+    typer.Option(
+        "--run-id",
+        "-r",
+        help="The Nextmv Cloud run ID to use for this action.",
+        envvar="NEXTMV_RUN_ID",
+        metavar="RUN_ID",
+    ),
+]
+
+# version_id option - can be used in any command that requires a version ID.
+# Define it as follows in commands or callbacks, as necessary:
+# version_id: VersionIDOption
+VersionIDOption = Annotated[
+    str,
+    typer.Option(
+        "--version-id",
+        "-v",
+        help="The Nextmv Cloud version ID to use for this action.",
+        envvar="NEXTMV_VERSION_ID",
+        metavar="VERSION_ID",
+    ),
+]
+
+# input_set_id option - can be used in any command that requires an input set ID.
+# Define it as follows in commands or callbacks, as necessary:
+# input_set_id: InputSetIDOption
+InputSetIDOption = Annotated[
+    str,
+    typer.Option(
+        "--input-set-id",
+        "-s",
+        help="The Nextmv Cloud input set ID to use for this action.",
+        envvar="NEXTMV_INPUT_SET_ID",
+        metavar="INPUT_SET_ID",
+    ),
+]
+
+# instance_id option - can be used in any command that requires an instance ID.
+# Define it as follows in commands or callbacks, as necessary:
+# instance_id: InstanceIDOption
+InstanceIDOption = Annotated[
+    str,
+    typer.Option(
+        "--instance-id",
+        "-i",
+        help="The Nextmv Cloud instance ID to use for this action.",
+        envvar="NEXTMV_INSTANCE_ID",
+        metavar="INSTANCE_ID",
+    ),
+]
+
+# managed_input_id option - can be used in any command that requires a managed input ID.
+# Define it as follows in commands or callbacks, as necessary:
+# managed_input_id: ManagedInputIDOption
+ManagedInputIDOption = Annotated[
+    str,
+    typer.Option(
+        "--managed-input-id",
+        "-m",
+        help="The Nextmv Cloud managed input ID to use for this action.",
+        envvar="NEXTMV_MANAGED_INPUT_ID",
+        metavar="MANAGED_INPUT_ID",
+    ),
+]
+
+# ensemble_definition_id option - can be used in any command that requires an ensemble definition ID.
+# Define it as follows in commands or callbacks, as necessary:
+# ensemble_definition_id: EnsembleDefinitionIDOption
+EnsembleDefinitionIDOption = Annotated[
+    str,
+    typer.Option(
+        "--ensemble-definition-id",
+        "-e",
+        help="The Nextmv Cloud ensemble definition ID to use for this action.",
+        envvar="NEXTMV_ENSEMBLE_DEFINITION_ID",
+        metavar="ENSEMBLE_DEFINITION_ID",
+    ),
+]
+
+# account_id option - can be used in any command that requires an account ID.
+# Define it as follows in commands or callbacks, as necessary:
+# account_id: AccountIDOption
+AccountIDOption = Annotated[
+    str,
+    typer.Option(
+        "--account-id",
+        "-a",
+        help="The Nextmv Cloud account ID to use for this action.",
+        envvar="NEXTMV_ACCOUNT_ID",
+        metavar="ACCOUNT_ID",
+    ),
+]
+
+# acceptance_test_id option - can be used in any command that requires an acceptance test ID.
+# Define it as follows in commands or callbacks, as necessary:
+# acceptance_test_id: AcceptanceTestIDOption
+AcceptanceTestIDOption = Annotated[
+    str,
+    typer.Option(
+        "--acceptance-test-id",
+        "-t",
+        help="The Nextmv Cloud acceptance test ID to use for this action.",
+        envvar="NEXTMV_ACCEPTANCE_TEST_ID",
+        metavar="ACCEPTANCE_TEST_ID",
+    ),
+]
+
+# batch_experiment_id option - can be used in any command that requires a batch experiment ID.
+# Define it as follows in commands or callbacks, as necessary:
+# batch_experiment_id: BatchExperimentIDOption
+BatchExperimentIDOption = Annotated[
+    str,
+    typer.Option(
+        "--batch-experiment-id",
+        "-b",
+        help="The Nextmv Cloud batch experiment ID to use for this action.",
+        envvar="NEXTMV_BATCH_EXPERIMENT_ID",
+        metavar="BATCH_EXPERIMENT_ID",
+    ),
+]
+
+# scenario_test_id option - can be used in any command that requires a scenario test ID.
+# Define it as follows in commands or callbacks, as necessary:
+# scenario_test_id: ScenarioTestIDOption
+ScenarioTestIDOption = Annotated[
+    str,
+    typer.Option(
+        "--scenario-test-id",
+        "-i",
+        help="The Nextmv Cloud scenario test ID to use for this action.",
+        envvar="NEXTMV_SCENARIO_TEST_ID",
+        metavar="SCENARIO_TEST_ID",
+    ),
+]
+
+# secrets_collection_id option - can be used in any command that requires a secrets collection ID.
+# Define it as follows in commands or callbacks, as necessary:
+# secrets_collection_id: SecretsCollectionIDOption
+SecretsCollectionIDOption = Annotated[
+    str,
+    typer.Option(
+        "--secrets-collection-id",
+        "-s",
+        help="The Nextmv Cloud secrets collection ID to use for this action.",
+        envvar="NEXTMV_SECRETS_COLLECTION_ID",
+        metavar="SECRETS_COLLECTION_ID",
+    ),
+]
+
+# shadow_test_id option - can be used in any command that requires a shadow test ID.
+# Define it as follows in commands or callbacks, as necessary:
+# shadow_test_id: ShadowTestIDOption
+ShadowTestIDOption = Annotated[
+    str,
+    typer.Option(
+        "--shadow-test-id",
+        "-s",
+        help="The Nextmv Cloud shadow test ID to use for this action.",
+        envvar="NEXTMV_SHADOW_TEST_ID",
+        metavar="SHADOW_TEST_ID",
+    ),
+]
+
+# switchback_test_id option - can be used in any command that requires a switchback test ID.
+# Define it as follows in commands or callbacks, as necessary:
+# switchback_test_id: SwitchbackTestIDOption
+SwitchbackTestIDOption = Annotated[
+    str,
+    typer.Option(
+        "--switchback-test-id",
+        "-s",
+        help="The Nextmv Cloud switchback test ID to use for this action.",
+        envvar="NEXTMV_SWITCHBACK_TEST_ID",
+        metavar="SWITCHBACK_TEST_ID",
+    ),
+]

nextmv/cli/version.py

@@ -14,6 +14,25 @@ app = typer.Typer()
 def version() -> None:
     """
     Show the current version of the Nextmv CLI.
+
+    [bold][underline]Examples[/underline][/bold]
+
+    - Show the version.
+        $ [dim]nextmv version[/dim]
     """
 
-    print(__version__)
+    version_callback(True)
+
+
+def version_callback(value: bool):
+    """
+    Callback function to display the version.
+
+    Parameters
+    ----------
+    value : bool
+        If True, print the version and exit.
+    """
+    if value:
+        print(__version__)
+        raise typer.Exit()

nextmv/cloud/__init__.py

@@ -1,41 +1,5 @@
 """Functionality for interacting with the Nextmv Cloud."""
 
-# These imports are kept for backwards compatibility but the preferred import path is
-# from nextmv directly. These imports will be removed in a future release.
-from nextmv.manifest import MANIFEST_FILE_NAME as MANIFEST_FILE_NAME
-from nextmv.manifest import Manifest as Manifest
-from nextmv.manifest import ManifestBuild as ManifestBuild
-from nextmv.manifest import ManifestContent as ManifestContent
-from nextmv.manifest import ManifestContentMultiFile as ManifestContentMultiFile
-from nextmv.manifest import ManifestContentMultiFileInput as ManifestContentMultiFileInput
-from nextmv.manifest import ManifestContentMultiFileOutput as ManifestContentMultiFileOutput
-from nextmv.manifest import ManifestOption as ManifestOption
-from nextmv.manifest import ManifestPython as ManifestPython
-from nextmv.manifest import ManifestPythonModel as ManifestPythonModel
-from nextmv.manifest import ManifestRuntime as ManifestRuntime
-from nextmv.manifest import ManifestType as ManifestType
-from nextmv.polling import PollingOptions as PollingOptions
-from nextmv.run import ErrorLog as ErrorLog
-from nextmv.run import ExternalRunResult as ExternalRunResult
-from nextmv.run import Format as Format
-from nextmv.run import FormatInput as FormatInput
-from nextmv.run import FormatOutput as FormatOutput
-from nextmv.run import Metadata as Metadata
-from nextmv.run import RunConfiguration as RunConfiguration
-from nextmv.run import RunInformation as RunInformation
-from nextmv.run import RunLog as RunLog
-from nextmv.run import RunQueuing as RunQueuing
-from nextmv.run import RunResult as RunResult
-from nextmv.run import RunType as RunType
-from nextmv.run import RunTypeConfiguration as RunTypeConfiguration
-from nextmv.run import TrackedRun as TrackedRun
-from nextmv.run import TrackedRunStatus as TrackedRunStatus
-from nextmv.run import run_duration as run_duration
-from nextmv.safe import safe_id as safe_id
-from nextmv.safe import safe_name_and_id as safe_name_and_id
-from nextmv.status import Status as Status
-from nextmv.status import StatusV2 as StatusV2
-
 from .acceptance_test import AcceptanceTest as AcceptanceTest
 from .acceptance_test import AcceptanceTestResults as AcceptanceTestResults
 from .acceptance_test import Comparison as Comparison
@@ -51,12 +15,13 @@ from .acceptance_test import MetricToleranceType as MetricToleranceType
 from .acceptance_test import MetricType as MetricType
 from .acceptance_test import ResultStatistics as ResultStatistics
 from .acceptance_test import StatisticType as StatisticType
-from .acceptance_test import ToleranceType as ToleranceType
 from .account import Account as Account
+from .account import AccountMember as AccountMember
 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 .application import ApplicationType as ApplicationType
+from .application import list_applications as list_applications
 from .assets import RunAsset as RunAsset
 from .batch_experiment import BatchExperiment as BatchExperiment
 from .batch_experiment import BatchExperimentInformation as BatchExperimentInformation
@@ -65,6 +30,9 @@ from .batch_experiment import BatchExperimentRun as BatchExperimentRun
 from .batch_experiment import ExperimentStatus as ExperimentStatus
 from .client import Client as Client
 from .client import get_size as get_size
+from .community import CommunityApp as CommunityApp
+from .community import clone_community_app as clone_community_app
+from .community import list_community_apps as list_community_apps
 from .ensemble import EnsembleDefinition as EnsembleDefinition
 from .ensemble import EvaluationRule as EvaluationRule
 from .ensemble import RuleObjective as RuleObjective
@@ -87,6 +55,17 @@ from .secrets import Secret as Secret
 from .secrets import SecretsCollection as SecretsCollection
 from .secrets import SecretsCollectionSummary as SecretsCollectionSummary
 from .secrets import SecretType as SecretType
+from .shadow import ShadowTest as ShadowTest
+from .shadow import ShadowTestMetadata as ShadowTestMetadata
+from .shadow import StartEvents as StartEvents
+from .shadow import StopIntent as StopIntent
+from .shadow import TerminationEvents as TerminationEvents
+from .shadow import TestComparison as TestComparison
+from .switchback import SwitchbackPlan as SwitchbackPlan
+from .switchback import SwitchbackPlanUnit as SwitchbackPlanUnit
+from .switchback import SwitchbackTest as SwitchbackTest
+from .switchback import SwitchbackTestMetadata as SwitchbackTestMetadata
+from .switchback import TestComparisonSingle as TestComparisonSingle
 from .url import DownloadURL as DownloadURL
 from .url import UploadURL as UploadURL
 from .version import Version as Version

nextmv/cloud/acceptance_test.py

@@ -13,7 +13,7 @@ StatisticType : Enum
     Type of statistical process for collapsing multiple values of a metric.
 Comparison : Enum
     Comparison operators to use for comparing two metrics.
-ToleranceType : Enum
+MetricToleranceType : Enum
     Type of tolerance used for a metric.
 ExperimentStatus : Enum
     Status of an acceptance test experiment.
@@ -46,7 +46,6 @@ from enum import Enum
 
 from nextmv.base_model import BaseModel
 from nextmv.cloud.batch_experiment import ExperimentStatus
-from nextmv.deprecated import deprecated
 
 
 class MetricType(str, Enum):
@@ -212,69 +211,6 @@ class Comparison(str, Enum):
     """Not equal to metric type."""
 
 
-class ToleranceType(str, Enum):
-    """
-    !!! warning
-        `ToleranceType` is deprecated, use `MetricToleranceType` instead.
-
-    Type of tolerance used for a metric.
-
-    You can import the `ToleranceType` class directly from `cloud`:
-
-    ```python
-    from nextmv.cloud import ToleranceType
-    ```
-
-    This enumeration defines the different types of tolerances that can be used
-    when comparing metrics in acceptance tests.
-
-    Attributes
-    ----------
-    undefined : str
-        Undefined tolerance type (empty string).
-    absolute : str
-        Absolute tolerance type, using a fixed value.
-    relative : str
-        Relative tolerance type, using a percentage.
-
-    Examples
-    --------
-    >>> from nextmv.cloud import ToleranceType
-    >>> tol_type = ToleranceType.absolute
-    >>> tol_type
-    <ToleranceType.absolute: 'absolute'>
-    """
-
-    undefined = ""
-    """ToleranceType is deprecated, please use MetricToleranceType instead.
-    Undefined tolerance type."""
-    absolute = "absolute"
-    """ToleranceType is deprecated, please use MetricToleranceType instead.
-    Absolute tolerance type."""
-    relative = "relative"
-    """ToleranceType is deprecated, please use MetricToleranceType instead.
-    Relative tolerance type."""
-
-
-# Override __getattribute__ to emit deprecation warnings when enum values are accessed
-_original_getattribute = ToleranceType.__class__.__getattribute__
-
-
-def _deprecated_getattribute(cls, name: str):
-    # Only emit deprecation warning if this is specifically the ToleranceType class
-    if cls is ToleranceType and name in ("undefined", "absolute", "relative"):
-        deprecated(
-            f"ToleranceType.{name}",
-            "ToleranceType is deprecated and will be removed in a future version. "
-            "Please use MetricToleranceType instead",
-        )
-
-    return _original_getattribute(cls, name)
-
-
-ToleranceType.__class__.__getattribute__ = _deprecated_getattribute
-
-
 class MetricToleranceType(str, Enum):
     """
     Type of tolerance used for a metric.
@@ -888,20 +824,20 @@ class AcceptanceTest(BaseModel):
         Name of the acceptance test.
     description : str
         Description of the acceptance test.
-    app_id : str
+    created_at : datetime
+        Creation date of the acceptance test.
+    updated_at : datetime
+        Last update date of the acceptance test.
+    app_id : str, optional
         ID of the app that owns the acceptance test.
-    experiment_id : str
+    experiment_id : str, optional
         ID of the batch experiment underlying the acceptance test.
-    control : ComparisonInstance
+    control : ComparisonInstance, optional
         Control instance of the acceptance test.
-    candidate : ComparisonInstance
+    candidate : ComparisonInstance, optional
         Candidate instance of the acceptance test.
-    metrics : list[Metric]
+    metrics : list[Metric], optional
         Metrics to evaluate in the acceptance test.
-    created_at : datetime
-        Creation date of the acceptance test.
-    updated_at : datetime
-        Last update date of the acceptance test.
     status : ExperimentStatus, optional
         Status of the acceptance test.
     results : AcceptanceTestResults, optional
@@ -942,20 +878,21 @@ class AcceptanceTest(BaseModel):
     """Name of the acceptance test."""
     description: str
     """Description of the acceptance test."""
-    app_id: str
+    created_at: datetime
+    """Creation date of the acceptance test."""
+    updated_at: datetime
+    """Last update date of the acceptance test."""
+
+    app_id: str | None = None
     """ID of the app that owns the acceptance test."""
-    experiment_id: str
+    experiment_id: str | None = None
     """ID of the batch experiment underlying in the acceptance test."""
-    control: ComparisonInstance
+    control: ComparisonInstance | None = None
     """Control instance of the acceptance test."""
-    candidate: ComparisonInstance
+    candidate: ComparisonInstance | None = None
     """Candidate instance of the acceptance test."""
-    metrics: list[Metric]
+    metrics: list[Metric] | None = None
     """Metrics of the acceptance test."""
-    created_at: datetime
-    """Creation date of the acceptance test."""
-    updated_at: datetime
-    """Last update date of the acceptance test."""
     status: ExperimentStatus | None = ExperimentStatus.UNKNOWN
     """Status of the acceptance test."""
     results: AcceptanceTestResults | None = None