nextmv 0.39.0.dev1__py3-none-any.whl → 1.0.0__py3-none-any.whl

nextmv/cli/version.py

@@ -6,7 +6,7 @@ import typer
 
 from nextmv.__about__ import __version__
 
-# Version subcommand application.
+# Set up subcommand application.
 app = typer.Typer()
 
 
@@ -14,5 +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]
+    """
+
+    version_callback(True)
+
+
+def version_callback(value: bool):
+    """
+    Callback function to display the version.
+
+    Parameters
+    ----------
+    value : bool
+        If True, print the version and exit.
     """
-    print(__version__)
+    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

nextmv/cloud/account.py

@@ -15,16 +15,18 @@ Account
     The Nextmv Platform account with API access methods.
 """
 
-from dataclasses import dataclass
 from datetime import datetime
 
+from pydantic import AliasChoices, Field
+
 from nextmv.base_model import BaseModel
 from nextmv.cloud.client import Client
-from nextmv.status import Status, StatusV2
+from nextmv.status import StatusV2
 
 
 class QueuedRun(BaseModel):
-    """A run that is pending to be executed in the account.
+    """
+    A run that is pending to be executed in the account.
 
     You can import the `QueuedRun` class directly from `cloud`:
 
@@ -55,8 +57,6 @@ class QueuedRun(BaseModel):
         ID of the application version used for the run.
     execution_class : str
         Execution class used for the run.
-    status : Status
-        Deprecated: use status_v2.
     status_v2 : StatusV2
         Status of the run.
 
@@ -72,7 +72,6 @@ class QueuedRun(BaseModel):
     ...     "application_instance_id": "appins-123456",
     ...     "application_version_id": "appver-123456",
     ...     "execution_class": "standard",
-    ...     "status": "RUNNING",
     ...     "status_v2": "RUNNING"
     ... })
     >>> print(queued_run.name)
@@ -97,14 +96,13 @@ class QueuedRun(BaseModel):
     """ID of the application version used for the run."""
     execution_class: str
     """Execution class used for the run."""
-    status: Status
-    """Deprecated: use status_v2."""
     status_v2: StatusV2
     """Status of the run."""
 
 
 class Queue(BaseModel):
-    """A queue is a list of runs that are pending to be executed, or currently
+    """
+    A queue is a list of runs that are pending to be executed, or currently
     being executed, in the account.
 
     You can import the `Queue` class directly from `cloud`:
@@ -123,7 +121,9 @@ class Queue(BaseModel):
 
     Examples
     --------
-    >>> account = Account(client=Client(api_key="your-api-key"))
+    >>> from nextmv.cloud import Client, Account
+    >>> client = Client(api_key="your-api-key")
+    >>> account = Account.get(client=client, account_id="your-account-id")
     >>> queue = account.queue()
     >>> print(f"Number of runs in queue: {len(queue.runs)}")
     Number of runs in queue: 5
@@ -137,9 +137,54 @@ class Queue(BaseModel):
     """List of runs in the queue."""
 
 
-@dataclass
-class Account:
-    """The Nextmv Platform account.
+class AccountMember(BaseModel):
+    """
+    A member of a Nextmv Cloud account (organization).
+
+    You can import the `AccountMember` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import AccountMember
+    ```
+
+    Represents an individual member of an organization in Nextmv Cloud,
+    including their role and invitation status.
+
+    Attributes
+    ----------
+    email : str | None
+        Email of the account member.
+    role : str | None
+        Role of the account member.
+    pending_invite : bool | None
+        Whether the member has a pending invite.
+
+    Examples
+    --------
+    >>> member = AccountMember.from_dict({
+    ...     "email": "peter.rabbit@carrotexpress.com",
+    ...     "role": "admin",
+    ...     "pending_invite": False
+    ... })
+    >>> print(f"{member.email} - {member.role}")
+    peter.rabbit@carrotexpress.com - admin
+    """
+
+    email: str | None = None
+    """Email of the account member."""
+    role: str | None = None
+    """Role of the account member."""
+    pending_invite: bool | None = None
+    """Whether the member has a pending invite."""
+
+
+class Account(BaseModel):
+    """
+    The Nextmv Cloud account (organization).
+
+    To handle managed accounts, SSO must be configured for your organization.
+    Please contact [Nextmv support](https://www.nextmv.io/contact) for
+    assistance.
 
     You can import the `Account` class directly from `cloud`:
 
@@ -147,41 +192,191 @@ class Account:
     from nextmv.cloud import Account
     ```
 
-    This class provides access to account-level operations in the Nextmv Platform,
+    This class provides access to account-level operations in the Nextmv Cloud,
     such as retrieving the queue of runs.
 
-    Parameters
-    ----------
-    client : Client
-        Client to use for interacting with the Nextmv Cloud API.
-    endpoint : str, optional
-        Base endpoint for the account, by default "v1/account"
+    Note: It is recommended to use `Account.get()` or `Account.new()`
+    instead of direct initialization to ensure proper setup.
 
-    Attributes
+    Parameters
     ----------
     client : Client
         Client to use for interacting with the Nextmv Cloud API.
-    endpoint : str
-        Base endpoint for the account.
+    account_id : str, optional
+        ID of the account (organization).
+    name : str, optional
+        Name of the account (organization).
+    members : list[AccountMember], optional
+        List of members in the account (organization).
+    account_endpoint : str, default="v1/account"
+        Base endpoint for the account (SDK-specific).
+    organization_endpoint : str, default="v1/organization/{organization_id}"
+        Base endpoint for organization operations (SDK-specific).
 
     Examples
     --------
     >>> from nextmv.cloud import Client, Account
     >>> client = Client(api_key="your-api-key")
-    >>> account = Account(client=client)
+    >>> # Retrieve an existing account
+    >>> account = Account.get(client=client, account_id="your-account-id")
+    >>> print(f"Account name: {account.name}")
+    Account name: Bunny Logistics
+    >>> # Create a new account
+    >>> new_account = Account.new(client=client, name="Hare Delivery Co", admins=["admin@example.com"])
+    >>> # Get the queue of runs
     >>> queue = account.queue()
     >>> print(f"Number of runs in queue: {len(queue.runs)}")
     Number of runs in queue: 3
     """
 
-    client: Client
+    # Actual API attributes of an account.
+    account_id: str | None = Field(
+        serialization_alias="id",
+        validation_alias=AliasChoices("id", "account_id"),
+        default=None,
+    )
+    """ID of the account (organization)."""
+    name: str | None = None
+    """Name of the account (organization)."""
+    members: list[AccountMember] | None = None
+    """List of members in the account (organization)."""
+
+    # SDK-specific attributes for convenience when using methods.
+    client: Client = Field(exclude=True)
     """Client to use for interacting with the Nextmv Cloud API."""
-
-    endpoint: str = "v1/account"
+    account_endpoint: str = Field(exclude=True, default="v1/account")
     """Base endpoint for the account."""
+    organization_endpoint: str = Field(exclude=True, default="v1/organization/{organization_id}")
+
+    def model_post_init(self, __context) -> None:
+        """
+        Initialize the organization_endpoint attribute.
+
+        This method is automatically called after class initialization to
+        format the organization_endpoint URL with the account ID.
+        """
+
+        self.organization_endpoint = self.organization_endpoint.format(organization_id=self.account_id)
+
+    @classmethod
+    def get(cls, client: Client, account_id: str) -> "Account":
+        """
+        Retrieve an account directly from Nextmv Cloud.
+
+        This function is useful if you want to populate an `Account` class
+        by fetching the attributes directly from Nextmv Cloud.
+
+        Parameters
+        ----------
+        client : Client
+            Client to use for interacting with the Nextmv Cloud API.
+        account_id : str
+            ID of the account to retrieve.
+
+        Returns
+        -------
+        Account
+            The requested account.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> from nextmv.cloud import Client, Account
+        >>> client = Client(api_key="your-api-key")
+        >>> account = Account.get(client=client, account_id="bunny-logistics")
+        >>> print(f"Account: {account.name}")
+        Account: Bunny Logistics
+        >>> print(f"Members: {len(account.members)}")
+        Members: 3
+        """
+
+        response = client.request(
+            method="GET",
+            endpoint=f"v1/organization/{account_id}",
+        )
+
+        return cls.from_dict({"client": client} | response.json())
+
+    @classmethod
+    def new(
+        cls,
+        client: Client,
+        name: str,
+        admins: list[str],
+    ) -> "Account":
+        """
+        Create a new account (organization) directly in Nextmv Cloud.
+
+        To create managed accounts, SSO must be configured for your
+        organization. Please contact [Nextmv
+        support](https://www.nextmv.io/contact) for assistance.
+
+        Parameters
+        ----------
+        client : Client
+            Client to use for interacting with the Nextmv Cloud API.
+        name : str
+            Name of the new account.
+        admins : list[str]
+            List of admin user emails for the new account.
+
+        Returns
+        -------
+        Account
+            The newly created account.
+
+        Examples
+        --------
+        >>> from nextmv.cloud import Client
+        >>> client = Client(api_key="your-api-key")
+        >>> account = Account.new(client=client, name="My New Account", admins=["admin@example.com"])
+        """
+
+        if len(admins) == 0:
+            raise ValueError("at least one admin email must be provided to create an account")
+
+        payload = {
+            "name": name,
+            "admins": admins,
+        }
+
+        response = client.request(
+            method="POST",
+            endpoint="v1/organization",
+            payload=payload,
+        )
+
+        return cls.from_dict({"client": client} | response.json())
+
+    def delete(self) -> None:
+        """
+        Delete the account.
+
+        Permanently removes the account (organization) from Nextmv Cloud. You
+        must have the administrator role on that account in order to delete it.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> account.delete()  # Permanently deletes the account
+        """
+
+        _ = self.client.request(
+            method="DELETE",
+            endpoint=self.organization_endpoint,
+        )
 
     def queue(self) -> Queue:
-        """Get the queue of runs in the account.
+        """
+        Get the queue of runs in the account.
 
         Retrieves the current list of runs that are pending or being executed
         in the Nextmv account.
@@ -198,7 +393,9 @@ class Account:
 
         Examples
         --------
-        >>> account = Account(client=Client(api_key="your-api-key"))
+        >>> from nextmv.cloud import Client, Account
+        >>> client = Client(api_key="your-api-key")
+        >>> account = Account.get(client=client, account_id="your-account-id")
         >>> queue = account.queue()
         >>> for run in queue.runs:
         ...     print(f"Run {run.id}: {run.name} - Status: {run.status_v2}")
@@ -207,7 +404,49 @@ class Account:
         """
         response = self.client.request(
             method="GET",
-            endpoint=self.endpoint + "/queue",
+            endpoint=self.account_endpoint + "/queue",
         )
 
         return Queue.from_dict(response.json())
+
+    def update(self, name: str) -> "Account":
+        """
+        Update the account.
+
+        Parameters
+        ----------
+        name : str
+            Name of the account.
+
+        Returns
+        -------
+        Account
+            The updated account.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> from nextmv.cloud import Client, Account
+        >>> client = Client(api_key="your-api-key")
+        >>> account = Account.get(client=client, account_id="bunny-logistics")
+        >>> updated_account = account.update(name="Bunny Express Logistics")
+        >>> print(updated_account.name)
+        Bunny Express Logistics
+        """
+
+        account = self.get(client=self.client, account_id=self.account_id)
+        account_dict = account.to_dict()
+        payload = account_dict.copy()
+        payload["name"] = name
+
+        response = self.client.request(
+            method="PUT",
+            endpoint=self.organization_endpoint,
+            payload=payload,
+        )
+
+        return Account.from_dict({"client": self.client} | response.json())