nextmv 0.26.3__py3-none-any.whl → 0.28.0__py3-none-any.whl

nextmv/cloud/scenario.py

@@ -1,4 +1,16 @@
-"""This module contains definitions for scenario tests."""
+"""This module contains definitions for scenario tests.
+
+Classes
+-------
+ScenarioConfiguration
+    Configuration for a scenario with multiple option values.
+ScenarioInputType
+    Enumeration of input types for a scenario.
+ScenarioInput
+    Input to be processed in a scenario.
+Scenario
+    A test case for comparing a decision model with inputs and configurations.
+"""
 
 import itertools
 from dataclasses import dataclass
@@ -11,6 +23,12 @@ class ScenarioConfiguration:
     """
     Configuration for a scenario.
 
+    You can import the `ScenarioConfiguration` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import ScenarioConfiguration
+    ```
+
     You can define multiple values for a single option, which will result in
     multiple runs being created. For example, if you have a configuration
     option "x" with values [1, 2], and a configuration option "y" with values
@@ -20,12 +38,17 @@ class ScenarioConfiguration:
     - x=2, y=3
     - x=2, y=4
 
-    Attributes
+    Parameters
     ----------
     name : str
         Name of the configuration option.
     values : list[str]
         List of values for the configuration option.
+
+    Examples
+    --------
+    >>> from nextmv.cloud import ScenarioConfiguration
+    >>> config = ScenarioConfiguration(name="solver", values=["simplex", "interior-point"])
     """
 
     name: str
@@ -36,6 +59,11 @@ class ScenarioConfiguration:
     def __post_init__(self):
         """
         Post-initialization method to ensure that the values are unique.
+
+        Raises
+        ------
+        ValueError
+            If the configuration values list is empty.
         """
         if len(self.values) <= 0:
             raise ValueError("Configuration values must be non-empty.")
@@ -46,7 +74,13 @@ class ScenarioInputType(str, Enum):
     Type of input for a scenario. This is used to determine how the input
     should be processed.
 
-    Attributes
+    You can import the `ScenarioInputType` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import ScenarioInputType
+    ```
+
+    Parameters
     ----------
     INPUT_SET : str
         The data in the scenario is an input set.
@@ -54,6 +88,11 @@ class ScenarioInputType(str, Enum):
         The data in the scenario is an input.
     NEW : str
         The data in the scenario is new data.
+
+    Examples
+    --------
+    >>> from nextmv.cloud import ScenarioInputType
+    >>> input_type = ScenarioInputType.INPUT_SET
     """
 
     INPUT_SET = "input_set"
@@ -67,12 +106,20 @@ class ScenarioInputType(str, Enum):
 @dataclass
 class ScenarioInput:
     """
-    Input to be processed in a scenario. The type of input is determined by
-    the `scenario_input_type` attribute. The input can be a single input set
-    ID, a list of input IDs, or raw data. The data itself of the scenario input
-    is tracked by the `scenario_input_data` attribute.
+    Input to be processed in a scenario.
 
-    Attributes
+    You can import the `ScenarioInput` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import ScenarioInput
+    ```
+
+    The type of input is determined by the `scenario_input_type` attribute.
+    The input can be a single input set ID, a list of input IDs, or raw data.
+    The data itself of the scenario input is tracked by the `scenario_input_data`
+    attribute.
+
+    Parameters
     ----------
     scenario_input_type : ScenarioInputType
         Type of input for the scenario. This is used to determine how the input
@@ -85,6 +132,25 @@ class ScenarioInput:
         behavior occurs when providing raw data (`list[dict[str, Any]]`). All
         the entries in the list of raw dicts will be collected to create a new
         input set.
+
+    Examples
+    --------
+    >>> from nextmv.cloud import ScenarioInput, ScenarioInputType
+    >>> # Using an existing input set
+    >>> input_set = ScenarioInput(
+    ...     scenario_input_type=ScenarioInputType.INPUT_SET,
+    ...     scenario_input_data="input-set-id-123"
+    ... )
+    >>> # Using a list of inputs
+    >>> inputs = ScenarioInput(
+    ...     scenario_input_type=ScenarioInputType.INPUT,
+    ...     scenario_input_data=["input-id-1", "input-id-2"]
+    ... )
+    >>> # Using raw data
+    >>> raw_data = ScenarioInput(
+    ...     scenario_input_type=ScenarioInputType.NEW,
+    ...     scenario_input_data=[{"id": 1, "value": "data1"}, {"id": 2, "value": "data2"}]
+    ... )
     """
 
     scenario_input_type: ScenarioInputType
@@ -105,6 +171,13 @@ class ScenarioInput:
     def __post_init__(self):
         """
         Post-initialization method to ensure that the input data is valid.
+
+        Raises
+        ------
+        ValueError
+            If the scenario input type and data type don't match:
+            - When using INPUT_SET, scenario_input_data must be a string
+            - When using INPUT or NEW, scenario_input_data must be a list
         """
         if self.scenario_input_type == ScenarioInputType.INPUT_SET and not isinstance(self.scenario_input_data, str):
             raise ValueError("Scenario input type must be a string when using an input set.")
@@ -120,19 +193,55 @@ class Scenario:
     A scenario is a test case that is used to compare a decision model being
     executed with a set of inputs and configurations.
 
-    Attributes
+    You can import the `Scenario` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import Scenario
+    ```
+
+    A scenario encapsulates all the necessary information to run a test case
+    against a decision model. Each scenario includes input data, an instance ID,
+    and can optionally include configuration options that define different
+    variations of the run.
+
+    Parameters
     ----------
     scenario_input : ScenarioInput
         Input for the scenario. The input is composed of a type and data. Make
         sure you use the `ScenarioInput` class to create the input.
+    instance_id : str
+        ID of the instance to be used for the scenario.
     scenario_id : Optional[str]
         Optional ID of the scenario. The default value will be set as
         `scenario-<index>` if not set.
-    instance_id : str
-        ID of the instance to be used for the scenario.
-    configuration : Optional[ScenarioConfiguration]
+    configuration : Optional[list[ScenarioConfiguration]]
         Optional configuration for the scenario. Use this attribute to
         configure variation of options for the scenario.
+
+    Examples
+    --------
+    >>> from nextmv.cloud import Scenario, ScenarioInput, ScenarioInputType, ScenarioConfiguration
+    >>> # Creating a simple scenario with an input set
+    >>> input_data = ScenarioInput(
+    ...     scenario_input_type=ScenarioInputType.INPUT_SET,
+    ...     scenario_input_data="input-set-id-123"
+    ... )
+    >>> scenario = Scenario(
+    ...     scenario_input=input_data,
+    ...     instance_id="instance-id-456",
+    ...     scenario_id="my-test-scenario"
+    ... )
+    >>>
+    >>> # Creating a scenario with configuration options
+    >>> config_options = [
+    ...     ScenarioConfiguration(name="solver", values=["simplex", "interior-point"]),
+    ...     ScenarioConfiguration(name="timeout", values=["10", "30", "60"])
+    ... ]
+    >>> scenario_with_config = Scenario(
+    ...     scenario_input=input_data,
+    ...     instance_id="instance-id-456",
+    ...     configuration=config_options
+    ... )
     """
 
     scenario_input: ScenarioInput
@@ -156,14 +265,36 @@ class Scenario:
     def option_combinations(self) -> list[dict[str, str]]:
         """
         Creates the combination of options that are derived from the
-        `configuration` property. The cross-product of the configuration
-        options is created to generate all possible combinations of options.
+        `configuration` property.
+
+        This method calculates the cross-product of all configuration
+        options to generate all possible combinations. If no configuration
+        is provided, it returns a list with an empty dictionary.
 
         Returns
         -------
         list[dict[str, str]]
             A list of dictionaries where each dictionary represents a set of
             options derived from the configuration.
+
+        Examples
+        --------
+        >>> from nextmv.cloud import Scenario, ScenarioInput, ScenarioInputType, ScenarioConfiguration
+        >>> input_data = ScenarioInput(
+        ...     scenario_input_type=ScenarioInputType.INPUT_SET,
+        ...     scenario_input_data="input-set-id"
+        ... )
+        >>> config = [
+        ...     ScenarioConfiguration(name="x", values=["1", "2"]),
+        ...     ScenarioConfiguration(name="y", values=["3", "4"])
+        ... ]
+        >>> scenario = Scenario(
+        ...     scenario_input=input_data,
+        ...     instance_id="instance-id",
+        ...     configuration=config
+        ... )
+        >>> scenario.option_combinations()
+        [{'x': '1', 'y': '3'}, {'x': '1', 'y': '4'}, {'x': '2', 'y': '3'}, {'x': '2', 'y': '4'}]
         """
 
         if self.configuration is None or len(self.configuration) == 0:
@@ -177,9 +308,12 @@ class Scenario:
 
 def _option_sets(scenarios: list[Scenario]) -> dict[str, dict[str, dict[str, str]]]:
     """
-    Creates options sets that are derived from `scenarios`. The options sets
-    are grouped by scenario ID. The cross-product of the configuration
-    options is created to generate all possible combinations of options.
+    Creates options sets that are derived from `scenarios`.
+
+    The options sets are grouped by scenario ID. The cross-product of the
+    configuration options is created to generate all possible combinations
+    of options. Each combination is given a unique key based on the scenario ID
+    and a combination index.
 
     Parameters
     ----------
@@ -193,6 +327,23 @@ def _option_sets(scenarios: list[Scenario]) -> dict[str, dict[str, dict[str, str
         dictionaries of option sets. Each option set is a dictionary where the
         keys are option names and the values are the corresponding option
         values.
+
+    Examples
+    --------
+    >>> from nextmv.cloud import Scenario, ScenarioInput, ScenarioInputType, ScenarioConfiguration
+    >>> input_data = ScenarioInput(
+    ...     scenario_input_type=ScenarioInputType.INPUT_SET,
+    ...     scenario_input_data="input-set-id"
+    ... )
+    >>> config = [ScenarioConfiguration(name="x", values=["1", "2"])]
+    >>> scenario = Scenario(
+    ...     scenario_input=input_data,
+    ...     instance_id="instance-id",
+    ...     scenario_id="test-scenario",
+    ...     configuration=config
+    ... )
+    >>> _option_sets([scenario])
+    {'test-scenario': {'test-scenario_0': {'x': '1'}, 'test-scenario_1': {'x': '2'}}}
     """
 
     sets_by_scenario = {}
@@ -210,9 +361,43 @@ def _option_sets(scenarios: list[Scenario]) -> dict[str, dict[str, dict[str, str
 
 def _scenarios_by_id(scenarios: list[Scenario]) -> dict[str, Scenario]:
     """
-    This function maps a scenario to its ID. A scenario ID is created if it
-    wasn’t defined. This function also checks that there are no duplicate
-    scenario IDs.
+    Maps scenarios to their IDs.
+
+    This function builds a dictionary that maps each scenario to its ID.
+    If a scenario doesn't have an ID defined, one is created using the format
+    "scenario-{index}". The function also checks that there are no duplicate
+    scenario IDs in the provided list.
+
+    Parameters
+    ----------
+    scenarios : list[Scenario]
+        List of scenarios to be mapped.
+
+    Returns
+    -------
+    dict[str, Scenario]
+        A dictionary where keys are scenario IDs and values are the corresponding
+        Scenario objects.
+
+    Raises
+    ------
+    ValueError
+        If duplicate scenario IDs are found in the list.
+
+    Examples
+    --------
+    >>> from nextmv.cloud import Scenario, ScenarioInput, ScenarioInputType
+    >>> input_data = ScenarioInput(
+    ...     scenario_input_type=ScenarioInputType.INPUT_SET,
+    ...     scenario_input_data="input-set-id"
+    ... )
+    >>> scenarios = [
+    ...     Scenario(scenario_input=input_data, instance_id="instance-1", scenario_id="test-1"),
+    ...     Scenario(scenario_input=input_data, instance_id="instance-2")
+    ... ]
+    >>> result = _scenarios_by_id(scenarios)
+    >>> sorted(list(result.keys()))
+    ['scenario-2', 'test-1']
     """
 
     scenario_by_id = {}

nextmv/cloud/secrets.py

@@ -1,4 +1,17 @@
-"""This module contains the declarations for secrets management."""
+"""This module contains the declarations for secrets management.
+
+Classes
+-------
+SecretsCollectionSummary
+    Summary of a secrets collection in Nextmv Cloud.
+SecretType
+    Enumeration of available secret types.
+Secret
+    Representation of a sensitive piece of information.
+SecretsCollection
+    Collection of secrets hosted in the Nextmv Cloud.
+
+"""
 
 from datetime import datetime
 from enum import Enum
@@ -9,8 +22,48 @@ from nextmv.base_model import BaseModel
 
 
 class SecretsCollectionSummary(BaseModel):
-    """The summary of a secrets collection, which is a mechanism for hosting
-    secrets securely in the Nextmv Cloud."""
+    """The summary of a secrets collection in the Nextmv Cloud.
+
+    You can import the `SecretsCollectionSummary` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import SecretsCollectionSummary
+    ```
+
+    A secrets collection is a mechanism for hosting secrets securely in the
+    Nextmv Cloud. This class provides summary information about such a collection.
+
+    Parameters
+    ----------
+    collection_id : str
+        ID of the secrets collection. This is aliased from `id` for
+        serialization and validation.
+    application_id : str
+        ID of the application to which the secrets collection belongs.
+    name : str
+        Name of the secrets collection.
+    description : str
+        Description of the secrets collection.
+    created_at : datetime
+        Creation date of the secrets collection.
+    updated_at : datetime
+        Last update date of the secrets collection.
+
+    Examples
+    --------
+    >>> from datetime import datetime
+    >>> collection_summary = SecretsCollectionSummary(
+    ...     collection_id="col_123",
+    ...     application_id="app_456",
+    ...     name="My API Credentials",
+    ...     description="Collection of API keys for external services",
+    ...     created_at=datetime.now(),
+    ...     updated_at=datetime.now()
+    ... )
+    >>> print(collection_summary.name)
+    My API Credentials
+
+    """
 
     collection_id: str = Field(
         serialization_alias="id",
@@ -30,7 +83,37 @@ class SecretsCollectionSummary(BaseModel):
 
 
 class SecretType(str, Enum):
-    """Type of the secret that is stored in the Nextmv Cloud."""
+    """Type of the secret that is stored in the Nextmv Cloud.
+
+    You can import the `SecretType` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import SecretType
+    ```
+
+    This enumeration defines the types of secrets that can be managed.
+
+    Attributes
+    ----------
+    ENV : str
+        Represents an environment variable secret. The value of the secret
+        will be available as an environment variable in the execution
+        environment.
+    FILE : str
+        Represents a file-based secret. The value of the secret will be
+        written to a file, and the path to this file will be available
+        via the `location` attribute of the `Secret`.
+
+    Examples
+    --------
+    >>> secret_type_env = SecretType.ENV
+    >>> print(secret_type_env.value)
+    env
+    >>> secret_type_file = SecretType.FILE
+    >>> print(secret_type_file.value)
+    file
+
+    """
 
     ENV = "env"
     """Environment variable secret type."""
@@ -40,7 +123,49 @@ class SecretType(str, Enum):
 
 class Secret(BaseModel):
     """A secret is a piece of sensitive information that is stored securely in
-    the Nextmv Cloud."""
+    the Nextmv Cloud.
+
+    You can import the `Secret` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import Secret
+    ```
+
+    This class represents an individual secret, detailing its type, location
+    (if applicable), and value.
+
+    Parameters
+    ----------
+    secret_type : SecretType
+        The type of the secret, indicating how it should be handled (e.g.,
+        as an environment variable or a file). This is aliased from `type`
+        for serialization and validation.
+    location : str
+        The location where the secret will be made available. For `ENV`
+        type secrets, this is the name of the environment variable. For
+        `FILE` type secrets, this is the path where the file will be
+        created.
+    value : str
+        The actual content of the secret.
+
+    Examples
+    --------
+    >>> env_secret = Secret(
+    ...     secret_type=SecretType.ENV,
+    ...     location="API_KEY",
+    ...     value="supersecretapikey123"
+    ... )
+    >>> print(env_secret.location)
+    API_KEY
+    >>> file_secret = Secret(
+    ...     secret_type=SecretType.FILE,
+    ...     location="/mnt/secrets/config.json",
+    ...     value=\'\'\'{"user": "admin", "pass": "secure"}\'\'\'
+    ... )
+    >>> print(file_secret.secret_type)
+    SecretType.FILE
+
+    """
 
     secret_type: SecretType = Field(
         serialization_alias="type",
@@ -55,7 +180,55 @@ class Secret(BaseModel):
 
 class SecretsCollection(SecretsCollectionSummary, BaseModel):
     """A secrets collection is a mechanism for hosting secrets securely in the
-    Nextmv Cloud."""
+    Nextmv Cloud.
+
+    You can import the `SecretsCollection` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import SecretsCollection
+    ```
+
+    This class extends `SecretsCollectionSummary` by including the actual list
+    of secrets contained within the collection.
+
+    Parameters
+    ----------
+    secrets : list[Secret]
+        A list of `Secret` objects that are part of this collection.
+    *args
+        Variable length argument list for `SecretsCollectionSummary`.
+    **kwargs
+        Arbitrary keyword arguments for `SecretsCollectionSummary`.
+
+
+    Examples
+    --------
+    >>> from datetime import datetime
+    >>> secret1 = Secret(
+    ...     secret_type=SecretType.ENV,
+    ...     location="DATABASE_USER",
+    ...     value="nextmv_user"
+    ... )
+    >>> secret2 = Secret(
+    ...     secret_type=SecretType.FILE,
+    ...     location="/etc/app/license.key",
+    ...     value="longlicensekeystring"
+    ... )
+    >>> full_collection = SecretsCollection(
+    ...     collection_id="col_789",
+    ...     application_id="app_000",
+    ...     name="Full App Secrets",
+    ...     description="All secrets required by the main application",
+    ...     created_at=datetime.now(),
+    ...     updated_at=datetime.now(),
+    ...     secrets=[secret1, secret2]
+    ... )
+    >>> print(full_collection.name)
+    Full App Secrets
+    >>> print(len(full_collection.secrets))
+    2
+
+    """
 
     secrets: list[Secret]
     """List of secrets in the collection."""

nextmv/cloud/status.py

@@ -1,8 +1,59 @@
+"""
+Provides status enums for Nextmv Cloud runs.
+
+This module defines enumerations for representing the status of a run in
+Nextmv Cloud. It includes a deprecated `Status` enum and the current `StatusV2`
+enum.
+
+Classes
+-------
+Status
+    Deprecated status of a run.
+StatusV2
+    Represents the status of a run.
+"""
+
 from enum import Enum
 
 
 class Status(str, Enum):
-    """Status of a run. Deprecated: use StatusV2."""
+    """
+    !!! warning
+        `Status` is deprecated, use `StatusV2` instead.
+
+    Status of a run.
+
+    You can import the `Status` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import Status
+    ```
+
+    This enum represents the possible states of a run. It is deprecated and
+    `StatusV2` should be used for new implementations.
+
+    Attributes
+    ----------
+    failed : str
+        Run failed.
+    running : str
+        Run is running.
+    succeeded : str
+        Run succeeded.
+
+    Examples
+    --------
+    >>> from nextmv.cloud import Status
+    >>> current_status = Status.running
+    >>> if current_status == Status.succeeded:
+    ...     print("Run completed successfully.")
+    ... elif current_status == Status.failed:
+    ...     print("Run failed.")
+    ... else:
+    ...     print(f"Run is currently {current_status.value}.")
+    Run is currently running.
+
+    """
 
     failed = "failed"
     """Run failed."""
@@ -13,7 +64,49 @@ class Status(str, Enum):
 
 
 class StatusV2(str, Enum):
-    """Status of a run."""
+    """
+    Status of a run.
+
+    You can import the `StatusV2` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import StatusV2
+    ```
+
+    This enum represents the comprehensive set of possible states for a run
+    in Nextmv Cloud.
+
+    Attributes
+    ----------
+    canceled : str
+        Run was canceled.
+    failed : str
+        Run failed.
+    none : str
+        Run has no status.
+    queued : str
+        Run is queued.
+    running : str
+        Run is running.
+    succeeded : str
+        Run succeeded.
+
+    Examples
+    --------
+    >>> from nextmv.cloud import StatusV2
+    >>> run_status = StatusV2.queued
+    >>> print(f"The run status is: {run_status.value}")
+    The run status is: queued
+
+    >>> if run_status == StatusV2.succeeded:
+    ...     print("Processing complete.")
+    ... elif run_status in [StatusV2.queued, StatusV2.running]:
+    ...     print("Processing in progress.")
+    ... else:
+    ...     print("Processing has not started or has ended with issues.")
+    Processing in progress.
+
+    """
 
     canceled = "canceled"
     """Run was canceled."""