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

nextmv/cloud/version.py

@@ -1,4 +1,20 @@
-"""This module contains definitions for versions."""
+"""Manages application versions within the Nextmv Cloud API.
+
+This module provides data models for representing application versions,
+their executables, and associated requirements. These models are used
+for interacting with version-related endpoints of the Nextmv Cloud API,
+allowing users to define, retrieve, and manage different versions of their
+decision applications.
+
+Classes
+-------
+VersionExecutableRequirements
+    Defines the requirements for a version's executable, such as type and runtime.
+VersionExecutable
+    Represents the executable artifact for a specific application version.
+Version
+    Represents a version of an application, linking to its executable and metadata.
+"""
 
 from datetime import datetime
 
@@ -6,7 +22,34 @@ from nextmv.base_model import BaseModel
 
 
 class VersionExecutableRequirements(BaseModel):
-    """Requirements for a version executable."""
+    """
+    Requirements for a version executable.
+
+    You can import the `VersionExecutableRequirements` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import VersionExecutableRequirements
+    ```
+
+    These requirements specify the environment and type of executable needed
+    to run a particular version of an application.
+
+    Parameters
+    ----------
+    executable_type : str
+        The type of the executable (e.g., "binary", "docker").
+    runtime : str
+        The runtime environment for the executable (e.g., "go", "python").
+
+    Examples
+    --------
+    >>> requirements = VersionExecutableRequirements(
+    ...     executable_type="binary",
+    ...     runtime="go1.x"
+    ... )
+    >>> print(requirements.executable_type)
+    binary
+    """
 
     executable_type: str
     """Type of the executable."""
@@ -15,7 +58,42 @@ class VersionExecutableRequirements(BaseModel):
 
 
 class VersionExecutable(BaseModel):
-    """Executable for a version."""
+    """
+    Executable for a version.
+
+    You can import the `VersionExecutable` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import VersionExecutable
+    ```
+
+    This class holds information about the actual executable file or image
+    associated with an application version, including who uploaded it and when.
+
+    Parameters
+    ----------
+    id : str
+        Unique identifier for the version executable.
+    user_email : str
+        Email of the user who uploaded the executable.
+    uploaded_at : datetime
+        Timestamp indicating when the executable was uploaded.
+    requirements : VersionExecutableRequirements
+        The specific requirements for this executable.
+
+    Examples
+    --------
+    >>> from datetime import datetime
+    >>> reqs = VersionExecutableRequirements(executable_type="docker", runtime="custom")
+    >>> executable = VersionExecutable(
+    ...     id="exec-123",
+    ...     user_email="user@example.com",
+    ...     uploaded_at=datetime.now(),
+    ...     requirements=reqs
+    ... )
+    >>> print(executable.id)
+    exec-123
+    """
 
     id: str
     """ID of the version."""
@@ -28,7 +106,57 @@ class VersionExecutable(BaseModel):
 
 
 class Version(BaseModel):
-    """A version of an application representing a code artifact or a compiled binary."""
+    """
+    A version of an application representing a code artifact or a compiled binary.
+
+    You can import the `Version` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import Version
+    ```
+
+    This class encapsulates all details of a specific version of an application,
+    including its metadata, associated executable, and timestamps.
+
+    Parameters
+    ----------
+    id : str
+        Unique identifier for the version.
+    application_id : str
+        Identifier of the application to which this version belongs.
+    name : str
+        User-defined name for the version (e.g., "v1.0.0", "feature-branch-build").
+    description : str
+        A more detailed description of the version and its changes.
+    executable : VersionExecutable
+        The executable artifact associated with this version.
+    created_at : datetime
+        Timestamp indicating when the version was created.
+    updated_at : datetime
+        Timestamp indicating when the version was last updated.
+
+    Examples
+    --------
+    >>> from datetime import datetime
+    >>> reqs = VersionExecutableRequirements(executable_type="binary", runtime="java11")
+    >>> exe = VersionExecutable(
+    ...     id="exec-abc",
+    ...     user_email="dev@example.com",
+    ...     uploaded_at=datetime.now(),
+    ...     requirements=reqs
+    ... )
+    >>> version_info = Version(
+    ...     id="ver-xyz",
+    ...     application_id="app-123",
+    ...     name="Initial Release",
+    ...     description="First stable release of the model.",
+    ...     executable=exe,
+    ...     created_at=datetime.now(),
+    ...     updated_at=datetime.now()
+    ... )
+    >>> print(version_info.name)
+    Initial Release
+    """
 
     id: str
     """ID of the version."""

nextmv/deprecated.py

@@ -1,8 +1,42 @@
+"""Utilities for handling deprecated functionality within the Nextmv Python SDK.
+
+This module provides tools to mark functions, methods, or features as deprecated,
+emitting appropriate warnings to users. These warnings inform users that the
+functionality will be removed in a future release and suggest alternative approaches.
+
+The main purpose of this module is to help with the smooth transition when
+API changes are necessary, giving users time to update their code before
+functionality is removed completely.
+"""
+
 import warnings
 
 
-def deprecated(name: str, reason: str):
-    """A very simple functon to mark something as deprecated."""
+def deprecated(name: str, reason: str) -> None:
+    """Mark functionality as deprecated with a warning message.
+
+    This function emits a DeprecationWarning when called, indicating that
+    the functionality will be removed in a future release.
+
+    Parameters
+    ----------
+    name : str
+        The name of the function, method, or feature being deprecated.
+    reason : str
+        The reason why the functionality is being deprecated, possibly
+        with suggestions for alternative approaches.
+
+    Notes
+    -----
+    This function temporarily changes the warning filter to ensure the
+    deprecation warning is shown, then resets it afterward.
+
+    Examples
+    --------
+    >>> def some_function():
+    ...     deprecated("feature_x", "Use feature_y instead")
+    ...     # function implementation
+    """
 
     warnings.simplefilter("always", DeprecationWarning)
     warnings.warn(