[ml] Update miscellaneous ref docs (Azure#31057)

* Update job operations docstrings

* Update MLClient docstring

* Rename auth samples file and update README

* Update docstrings and add examples for mlclient, load functions, asset, model, input/output

* Update CodeConfiguration, DistributionType docstrings

* Update docstrings and add examples and exclude samples from interrogate

* Update workspace info

* Add comment to pyproject.toml interrogate section

* Update docstrings and increase interrogate threshold to 75%

* Update docstrings and add examples

* Update docstrings and add examples

* Address formatting issues

* Address formatting issues

* Update docstrings and add examples

* Address formatting issues

* Fix paths to examples to relative and add note to samples README

* Update docstrings per comments

* Make another pass to get missed formatting issues and address comments

* Remove :class: tip from admonition

* Address docstring- formatting warnings from azure-pylint-guidelines-checker

Author: diondrapeck

sdk/ml/azure-ai-ml/.pre-commit-config.yaml

@@ -10,7 +10,8 @@ repos:
   hooks:
   - id: interrogate
     types_or: [python]
-    exclude: ^(sdk/ml/azure-ai-ml/tests/|sdk/ml/azure-ai-ml/scripts/|sdk/ml/azure-ai-ml/azure/ai/ml/_restclient|sdk/ml/azure-ai-ml/setup.py)
+    args: [--ignore-init-method, --ignore-private, --ignore-semiprivate, --ignore-magic]
+    exclude: ^(sdk/ml/azure-ai-ml/tests/|sdk/ml/azure-ai-ml/samples/|sdk/ml/azure-ai-ml/scripts/|sdk/ml/azure-ai-ml/azure/ai/ml/_restclient|sdk/ml/azure-ai-ml/setup.py)
     # exclude defined here because exclude in pyproject.toml is not being respected
 - repo: https://github.com/streetsidesoftware/cspell-cli
   rev: v6.31.0

sdk/ml/azure-ai-ml/azure/ai/ml/_ml_client.py

@@ -3,11 +3,13 @@
 # ---------------------------------------------------------
 from enum import Enum
 
-from azure.ai.ml._utils._experimental import experimental
 from azure.core import CaseInsensitiveEnumMeta
 
+from azure.ai.ml._utils._experimental import experimental
+
 
 @experimental
 class IPProtectionLevel(str, Enum, metaclass=CaseInsensitiveEnumMeta):
+    "Intellectual property protection level."
     ALL = "all"
     NONE = "none"

sdk/ml/azure-ai-ml/azure/ai/ml/constants/_assets.py

@@ -4,10 +4,7 @@
 from enum import Enum
 
 # pylint: disable=unused-import
-from azure.ai.ml._restclient.v2023_04_01_preview.models import (
-    NlpLearningRateScheduler,
-    TrainingMode,
-)
+from azure.ai.ml._restclient.v2023_04_01_preview.models import NlpLearningRateScheduler, TrainingMode
 from azure.ai.ml._utils._experimental import experimental
 
 
@@ -95,7 +92,8 @@ class ImageInstanceSegmentationModelNames(Enum):
 
 
 class NlpModels(Enum):
-    # Model names for NLP tasks.
+    """Model names that are supported for NLP (Natural Language Processing) tasks."""
+
     BERT_BASE_CASED = "bert-base-cased"
     BERT_BASE_UNCASED = "bert-base-uncased"
     BERT_BASE_MULTILINGUAL_CASED = "bert-base-multilingual-cased"

sdk/ml/azure-ai-ml/azure/ai/ml/constants/_job/automl.py

@@ -9,6 +9,8 @@
 
 
 class StorageAccountType(str, Enum, metaclass=CaseInsensitiveEnumMeta):
+    """Storage account types."""
+
     STANDARD_LRS = "Standard_LRS".lower()
     STANDARD_GRS = "Standard_GRS".lower()
     STANDARD_RAGRS = "Standard_RAGRS".lower()
@@ -21,6 +23,8 @@ class StorageAccountType(str, Enum, metaclass=CaseInsensitiveEnumMeta):
 
 # When will other values be allowed?
 class AcrAccountSku(str, Enum, metaclass=CaseInsensitiveEnumMeta):
+    """Azure Container Registry SKUs."""
+
     PREMIUM = "Premium".lower()
 
 

sdk/ml/azure-ai-ml/azure/ai/ml/constants/_registry.py

@@ -83,7 +83,7 @@ def pipeline(
     :type kwargs: dict
 
     .. admonition:: Example:
-        :class: tip
+
         .. literalinclude:: ../../../../samples/ml_samples_pipeline_job_configurations.py
             :start-after: [START configure_pipeline]
             :end-before: [END configure_pipeline]

sdk/ml/azure-ai-ml/azure/ai/ml/dsl/_pipeline_decorator.py

@@ -6,46 +6,38 @@
 
 from os import PathLike
 from pathlib import Path
-from typing import IO, AnyStr, List, Dict, Optional, Union
-
-
-from azure.ai.ml._restclient.v2023_02_01_preview.models import (
-    PackageRequest,
-    PackageResponse,
-    ModelPackageInput as RestModelPackageInput,
-    PackageInputPathId as RestPackageInputPathId,
-    PackageInputPathVersion as RestPackageInputPathVersion,
-    PackageInputPathUrl as RestPackageInputPathUrl,
-    CodeConfiguration,
-)
-
-from azure.ai.ml.entities._resource import Resource
+from typing import IO, AnyStr, Dict, List, Optional, Union
+
+from azure.ai.ml._restclient.v2023_02_01_preview.models import CodeConfiguration
+from azure.ai.ml._restclient.v2023_02_01_preview.models import ModelPackageInput as RestModelPackageInput
+from azure.ai.ml._restclient.v2023_02_01_preview.models import PackageInputPathId as RestPackageInputPathId
+from azure.ai.ml._restclient.v2023_02_01_preview.models import PackageInputPathUrl as RestPackageInputPathUrl
+from azure.ai.ml._restclient.v2023_02_01_preview.models import PackageInputPathVersion as RestPackageInputPathVersion
+from azure.ai.ml._restclient.v2023_02_01_preview.models import PackageRequest, PackageResponse
 from azure.ai.ml._schema.assets.package.model_package import ModelPackageSchema
-from azure.ai.ml.entities._util import load_from_dict
-from azure.ai.ml.constants._common import (
-    BASE_PATH_CONTEXT_KEY,
-    PARAMS_OVERRIDE_KEY,
-)
-from azure.ai.ml._utils.utils import snake_to_pascal, dump_yaml_to_file
 from azure.ai.ml._utils._experimental import experimental
-from .model_configuration import ModelConfiguration
-from .inferencing_server import AzureMLOnlineInferencingServer, AzureMLBatchInferencingServer
+from azure.ai.ml._utils.utils import dump_yaml_to_file, snake_to_pascal
+from azure.ai.ml.constants._common import BASE_PATH_CONTEXT_KEY, PARAMS_OVERRIDE_KEY
+from azure.ai.ml.entities._resource import Resource
+from azure.ai.ml.entities._util import load_from_dict
+
 from .base_environment_source import BaseEnvironment
+from .inferencing_server import AzureMLBatchInferencingServer, AzureMLOnlineInferencingServer
+from .model_configuration import ModelConfiguration
 
 
 @experimental
 class PackageInputPathId:
+    """Package input path specified with a resource ID.
 
-    """Package input path specified with a resource id.
-
-    :param input_path_type: The type of the input path. Possible values include: "Url", "PathId", "PathVersion".
-    :type input_path_type: str
-    :param resource_id: The resource id of the input path. e.g. azureml://subscriptions/<>/resourceGroups/
-    <>/providers/Microsoft.MachineLearningServices/workspaces/<>/data/<>/versions/<>
-    :type resource_id: str
+    :param input_path_type: The type of the input path. Accepted values are "Url", "PathId", and "PathVersion".
+    :type input_path_type: Optional[str]
+    :param resource_id: The resource ID of the input path. e.g. "azureml://subscriptions/<>/resourceGroups/
+        <>/providers/Microsoft.MachineLearningServices/workspaces/<>/data/<>/versions/<>".
+    :type resource_id: Optional[str]
     """
 
-    def __init__(self, *, input_path_type: Optional[str] = None, resource_id: Optional[str] = None):
+    def __init__(self, *, input_path_type: Optional[str] = None, resource_id: Optional[str] = None) -> None:
         self.input_path_type = input_path_type
         self.resource_id = resource_id
 
@@ -67,12 +59,12 @@ def _from_rest_object(cls, package_input_path_id_rest_object: RestPackageInputPa
 class PackageInputPathVersion:
     """Package input path specified with a resource name and version.
 
-    :param input_path_type: The type of the input path. Possible values include: "Url", "PathId", "PathVersion".
-    :type input_path_type: str
+    :param input_path_type: The type of the input path. Accepted values are "Url", "PathId", and "PathVersion".
+    :type input_path_type: Optional[str]
     :param resource_name: The resource name of the input path.
-    :type resource_name: str
+    :type resource_name: Optional[str]
     :param resource_version: The resource version of the input path.
-    :type resource_version: str
+    :type resource_version: Optional[str]
     """
 
     def __init__(
@@ -81,7 +73,7 @@ def __init__(
         input_path_type: Optional[str] = None,
         resource_name: Optional[str] = None,
         resource_version: Optional[str] = None,
-    ):
+    ) -> None:
         self.input_path_type = input_path_type
         self.resource_name = resource_name
         self.resource_version = resource_version
@@ -108,14 +100,14 @@ def _from_rest_object(
 class PackageInputPathUrl:
     """Package input path specified with a url.
 
-    :param input_path_type: The type of the input path. Possible values include: "Url", "PathId", "PathVersion".
-    :type input_path_type: str
-    :param url: The url of the input path. e.g. azureml://subscriptions/<>/resourceGroups/
-    <>/providers/Microsoft.MachineLearningServices/workspaces/data/<>/versions/<>
-    :type url: str
+    :param input_path_type: The type of the input path. Accepted values are "Url", "PathId", and "PathVersion".
+    :type input_path_type: Optional[str]
+    :param url: The url of the input path. e.g. "azureml://subscriptions/<>/resourceGroups/
+        <>/providers/Microsoft.MachineLearningServices/workspaces/data/<>/versions/<>".
+    :type url: Optional[str]
     """
 
-    def __init__(self, *, input_path_type: Optional[str] = None, url: Optional[str] = None):
+    def __init__(self, *, input_path_type: Optional[str] = None, url: Optional[str] = None) -> None:
         self.input_path_type = input_path_type
         self.url = url
 
@@ -138,14 +130,14 @@ class ModelPackageInput:
     """Model package input.
 
     :param type: The type of the input.
-    :type type: str
+    :type type: Optional[str]
     :param path: The path of the input.
-    :type path: azure.ai.ml.entities.PackageInputPathId
-     or azure.ai.ml.entities.PackageInputPathUrl or azure.ai.ml.entities.PackageInputPathVersion
-    :param mode: The mode of the input.
-    :type mode: str
-    :param mount_path: The mount path of the input.
-    :type mount_path: str
+    :type path: Optional[Union[~azure.ai.ml.entities.PackageInputPathId, ~azure.ai.ml.entities.PackageInputPathUrl,
+        ~azure.ai.ml.entities.PackageInputPathVersion]]
+    :param mode: The input mode.
+    :type mode: Optional[str]
+    :param mount_path: The mount path for the input.
+    :type mount_path: Optional[str]
     """
 
     def __init__(
@@ -155,7 +147,7 @@ def __init__(
         path: Optional[Union[PackageInputPathId, PackageInputPathUrl, PackageInputPathVersion]] = None,
         mode: Optional[str] = None,
         mount_path: Optional[str] = None,
-    ):
+    ) -> None:
         self.type = type
         self.path = path
         self.mode = mode
@@ -183,22 +175,23 @@ def _from_rest_object(cls, model_package_input_rest_object: RestModelPackageInpu
 class ModelPackage(Resource, PackageRequest):
     """Model package.
 
-    :param target_environment_name: The name of the model package.
+    :param target_environment_name: The target environment name for the model package.
     :type target_environment_name: str
     :param inferencing_server: The inferencing server of the model package.
-    :type inferencing_server: azure.ai.ml.entities.InferencingServer
+    :type inferencing_server: Union[~azure.ai.ml.entities.AzureMLOnlineInferencingServer,
+        ~azure.ai.ml.entities.AzureMLBatchInferencingServer]
     :param base_environment_source: The base environment source of the model package.
-    :type base_environment_source: azure.ai.ml.entities.BaseEnvironmentSource
+    :type base_environment_source: Optional[~azure.ai.ml.entities.BaseEnvironment]
     :param target_environment_version: The version of the model package.
-    :type target_environment_version: str
+    :type target_environment_version: Optional[str]
     :param environment_variables: The environment variables of the model package.
-    :type environment_variables: dict
+    :type environment_variables: Optional[dict[str, str]]
     :param inputs: The inputs of the model package.
-    :type inputs: list[azure.ai.ml.entities.ModelPackageInput]
-    :param model_configuration: The model configuration of the model package.
-    :type model_configuration: azure.ai.ml.entities.ModelConfiguration
+    :type inputs: Optional[list[~azure.ai.ml.entities.ModelPackageInput]]
+    :param model_configuration: The model configuration.
+    :type model_configuration: Optional[~azure.ai.ml.entities.ModelConfiguration]
     :param tags: The tags of the model package.
-    :type tags: dict
+    :type tags: Optiona[dict[str, str]]
     """
 
     def __init__(
@@ -212,7 +205,7 @@ def __init__(
         inputs: Optional[List[ModelPackageInput]] = None,
         model_configuration: Optional[ModelConfiguration] = None,
         tags: Optional[Dict[str, str]] = None,
-    ):
+    ) -> None:
         super().__init__(
             name=target_environment_name,
             target_environment_name=target_environment_name,
@@ -246,12 +239,16 @@ def dump(
         dest: Union[str, PathLike, IO[AnyStr]],
         **kwargs,  # pylint: disable=unused-argument
     ) -> None:
-        """Dump the model package spec into a file in yaml format.
-
-        :param dest: Either
-          * A path to a local file
-          * A writeable file-like object
-        :type dest: Union[str, PathLike, IO[AnyStr]]
+        """Dumps the job content into a file in YAML format.
+
+        :param dest: The local path or file stream to write the YAML content to.
+            If dest is a file path, a new file will be created.
+            If dest is an open file, the file will be written to directly.
+        :type dest: Union[PathLike, str, IO[AnyStr]]
+        :param kwargs: Additional arguments to pass to the YAML serializer.
+        :type kwargs: Optional[dict]
+        :raises FileExistsError: Raised if dest is a file path and the file already exists.
+        :raises IOError: Raised if dest is an open file and the file is not writable.
         """
         yaml_serialized = self._to_dict()
         dump_yaml_to_file(dest, yaml_serialized, default_flow_style=False)

sdk/ml/azure-ai-ml/azure/ai/ml/entities/_assets/_artifacts/_package/model_package.py

@@ -22,42 +22,50 @@
     AssetTypes,
 )
 from azure.ai.ml.entities._assets import Artifact
+from azure.ai.ml.entities._assets.intellectual_property import IntellectualProperty
 from azure.ai.ml.entities._system_data import SystemData
 from azure.ai.ml.entities._util import get_md5_string, load_from_dict
-from azure.ai.ml.entities._assets.intellectual_property import IntellectualProperty
 
 from .artifact import ArtifactStorageInfo
 
 
 class Model(Artifact):  # pylint: disable=too-many-instance-attributes
     """Model for training and scoring.
 
-    :param name: Name of the resource.
-    :type name: str
-    :param version: Version of the resource.
-    :type version: str
-    :param type: The storage format for this entity. Used for NCD. Possible values include:
-     "custom_model", "mlflow_model", "triton_model".
-    :type type: str
-    :param utc_time_created: Date and time when the model was created, in
-        UTC ISO 8601 format. (e.g. '2020-10-19 17:44:02.096572')
-    :type utc_time_created: str
-    :param flavors: The flavors in which the model can be interpreted.
-        e.g. {sklearn: {sklearn_version: 0.23.2}, python_function: {loader_module: office.plrmodel, python_version: 3.6}
-    :type flavors: Dict[str, Any]
-    :param path: A remote uri or a local path pointing at a model.
-        Example: "azureml://subscriptions/{}/resourcegroups/{}/workspaces/{}/datastores/{}/paths/path_on_datastore/"
-    :type path: str
-    :param description: Description of the resource.
-    :type description: str
-    :param tags: Tag dictionary. Tags can be added, removed, and updated.
-    :type tags: dict[str, str]
-    :param properties: The asset property dictionary.
-    :type properties: dict[str, str]
-    :param stage: The stage of the resource.
-    :type stage: str
+    :param name: The name of the model. Defaults to a random GUID.
+    :type name: Optional[str]
+    :param version: The version of the model. Defaults to "1" if either no name or an unregistered name is provided.
+        Otherwise, defaults to autoincrement from the last registered version of the model with that name.
+    :type version: Optional[str]
+    :param type: The storage format for this entity, used for NCD (Novel Class Discovery). Accepted values are
+        "custom_model", "mlflow_model", or "triton_model". Defaults to "custom_model".
+    :type type: Optional[str]
+    :param utc_time_created: The date and time when the model was created, in
+        UTC ISO 8601 format. (e.g. '2020-10-19 17:44:02.096572').
+    :type utc_time_created: Optional[str]
+    :param flavors: The flavors in which the model can be interpreted. Defaults to None.
+    :type flavors: Optional[dict[str, Any]]
+    :param path: A remote uri or a local path pointing to a model. Defaults to None.
+    :type path: Optional[str]
+    :param description: The description of the resource. Defaults to None
+    :type description: Optional[str]
+    :param tags: Tag dictionary. Tags can be added, removed, and updated. Defaults to None.
+    :type tags: Optional[dict[str, str]]
+    :param properties: The asset property dictionary. Defaults to None.
+    :type properties: Optional[dict[str, str]]
+    :param stage: The stage of the resource. Defaults to None.
+    :type stage: Optional[str]
     :param kwargs: A dictionary of additional configuration parameters.
-    :type kwargs: dict
+    :type kwargs: Optional[dict]
+
+    .. admonition:: Example:
+
+        .. literalinclude:: ../../../../../../samples/ml_samples_misc.py
+            :start-after: [START model_entity_create]
+            :end-before: [END model_entity_create]
+            :language: python
+            :dedent: 8
+            :caption: Creating a Model object.
     """
 
     def __init__(
@@ -74,7 +82,7 @@ def __init__(
         properties: Optional[Dict] = None,
         stage: Optional[str] = None,
         **kwargs,
-    ):
+    ) -> None:
         self.job_name = kwargs.pop("job_name", None)
         self._intellectual_property = kwargs.pop("intellectual_property", None)
         super().__init__(