nextmv 0.27.0__py3-none-any.whl → 0.28.1__py3-none-any.whl

nextmv/cloud/instance.py

@@ -1,4 +1,16 @@
-"""This module contains definitions for instances."""
+"""Classes for working with Nextmv Cloud Instances.
+
+This module provides classes for interacting with instances in Nextmv Cloud.
+It defines the core data structures for both instance configuration and the
+instance itself.
+
+Classes
+-------
+InstanceConfiguration
+    Configuration settings for a Nextmv Cloud instance.
+Instance
+    Representation of a Nextmv Cloud instance tied to an application version.
+"""
 
 from datetime import datetime
 from typing import Optional
@@ -7,7 +19,34 @@ from nextmv.base_model import BaseModel
 
 
 class InstanceConfiguration(BaseModel):
-    """Configuration for an instance."""
+    """Configuration for a Nextmv Cloud instance.
+
+    You can import the `InstanceConfiguration` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import InstanceConfiguration
+    ```
+
+    This class represents the configuration settings that can be applied to a
+    Nextmv Cloud instance, including execution class, options, and secrets.
+
+    Parameters
+    ----------
+    execution_class : str, optional
+        The execution class for the instance, which determines compute resources.
+    options : dict, optional
+        Runtime options/parameters for the application.
+    secrets_collection_id : str, optional
+        ID of the secrets collection to use with this instance.
+
+    Examples
+    --------
+    >>> config = InstanceConfiguration(
+    ...     execution_class="small",
+    ...     options={"max_runtime": 30},
+    ...     secrets_collection_id="sc_1234567890"
+    ... )
+    """
 
     execution_class: Optional[str] = None
     """Execution class for the instance."""
@@ -18,7 +57,54 @@ class InstanceConfiguration(BaseModel):
 
 
 class Instance(BaseModel):
-    """A instance of an application tied to a version and further configuration."""
+    """An instance of an application tied to a version with configuration.
+
+    You can import the `Instance` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import Instance
+    ```
+
+    A Nextmv Cloud instance represents a deployable configuration of an application
+    version. Instances have their own unique identity and can be used to run jobs
+    with specific configurations.
+
+    Parameters
+    ----------
+    id : str
+        The unique identifier of the instance.
+    application_id : str
+        ID of the application that this instance belongs to.
+    version_id : str
+        ID of the application version this instance uses.
+    name : str
+        Human-readable name of the instance.
+    description : str
+        Detailed description of the instance.
+    configuration : InstanceConfiguration
+        Configuration settings for this instance.
+    locked : bool
+        Whether the instance is locked for modifications.
+    created_at : datetime
+        Timestamp when the instance was created.
+    updated_at : datetime
+        Timestamp when the instance was last updated.
+
+    Examples
+    --------
+    >>> from nextmv.cloud import Instance, InstanceConfiguration
+    >>> instance = Instance(
+    ...     id="inst_1234567890",
+    ...     application_id="app_1234567890",
+    ...     version_id="ver_1234567890",
+    ...     name="Production Routing Instance",
+    ...     description="Instance for daily production routing jobs",
+    ...     configuration=InstanceConfiguration(execution_class="small"),
+    ...     locked=False,
+    ...     created_at=datetime.now(),
+    ...     updated_at=datetime.now()
+    ... )
+    """
 
     id: str
     """ID of the instance."""