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

nextmv/cli/options.py

@@ -22,3 +22,171 @@ 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",
+    ),
+]

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.
+        $ [green]nextmv version[/green]
     """
 
-    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

@@ -15,6 +15,7 @@ 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.polling import poll as poll
 from nextmv.run import ErrorLog as ErrorLog
 from nextmv.run import ExternalRunResult as ExternalRunResult
 from nextmv.run import Format as Format
@@ -53,10 +54,12 @@ 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

nextmv/cloud/acceptance_test.py

@@ -888,20 +888,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 +942,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
 
 
 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`:
 
@@ -104,7 +106,8 @@ class QueuedRun(BaseModel):
 
 
 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 +126,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 +142,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 +197,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 +398,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 +409,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())