Update the reference documentation for onlinedeployment and segregate… (

Azure#27854)

* Update the reference documentation for onlinedeployment and segregate the code and samples for MLClient.

* Update the path for samples

* Remove the subscription Id

* Removing keyword from MLClient docstring

* fix pylint issue

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

@@ -86,21 +86,7 @@
 class MLClient(object):
     """A client class to interact with Azure ML services.
 
-    Use this client to manage Azure ML resources, e.g. workspaces, jobs,
-    models and so on.
-    """
-
-    # pylint: disable=client-method-missing-type-annotations
-    def __init__(
-        self,
-        credential: TokenCredential,
-        subscription_id: str = None,
-        resource_group_name: str = None,
-        workspace_name: str = None,
-        registry_name: str = None,
-        **kwargs: Any,
-    ):
-        """Initiate Azure ML client.
+    Use this client to manage Azure ML resources, e.g. workspaces, jobs, models and so on.
 
         :param credential: Credential to use for authentication.
         :type credential: TokenCredential
@@ -121,40 +107,26 @@ def __init__(
             For e.g. kwargs = {"cloud": "AzureUSGovernment"}
         :type kwargs: dict
 
-        .. note::
-
-                The cloud parameter in kwargs in this class is what gets
-                the MLClient to work for non-standard Azure Clouds,
-                e.g. AzureUSGovernment, AzureChinaCloud
-
-                The following pseudo-code shows how to get a list of workspaces using MLClient.
-        .. code-block:: python
-
-                    from azure.identity import DefaultAzureCredential, AzureAuthorityHosts
-                    from azure.ai.ml import MLClient
-                    from azure.ai.ml.entities import Workspace
+        .. admonition:: Example:
 
-                    # Enter details of your subscription
-                    subscription_id = "AZURE_SUBSCRIPTION_ID"
-                    resource_group = "RESOURCE_GROUP_NAME"
-
-                    # When using sovereign domains (that is, any cloud other than AZURE_PUBLIC_CLOUD),
-                    # you must use an authority with DefaultAzureCredential.
-                    # Default authority value : AzureAuthorityHosts.AZURE_PUBLIC_CLOUD
-                    # Expected values for authority for sovereign clouds:
-                    # AzureAuthorityHosts.AZURE_CHINA or AzureAuthorityHosts.AZURE_GOVERNMENT
-                    credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_CHINA)
-
-                    # When using sovereign domains (that is, any cloud other than AZURE_PUBLIC_CLOUD),
-                    # you must pass in the cloud name in kwargs. Default cloud is AzureCloud
-                    kwargs = {"cloud": "AzureChinaCloud"}
-                    # get a handle to the subscription
-                    ml_client = MLClient(credential, subscription_id, resource_group, **kwargs)
+            .. literalinclude:: ../../samples/ml_samples_authentication_sovereign_cloud.py
+                :start-after: [START create_ml_client_default_credential]
+                :end-before: [END create_ml_client_default_credential]
+                :language: python
+                :dedent: 8
+                :caption: Creating the MLClient with Azure Identity credentials.
+    """
 
-                    # Get a list of workspaces in a resource group
-                    for ws in ml_client.workspaces.list():
-                        print(ws.name, ":", ws.location, ":", ws.description)
-        """
+    # pylint: disable=client-method-missing-type-annotations
+    def __init__(
+        self,
+        credential: TokenCredential,
+        subscription_id: str = None,
+        resource_group_name: str = None,
+        workspace_name: str = None,
+        registry_name: str = None,
+        **kwargs: Any,
+    ):
 
         if credential is None:
             raise ValueError("credential can not be None")

sdk/ml/azure-ai-ml/azure/ai/ml/entities/_deployment/online_deployment.py

@@ -60,65 +60,65 @@ class OnlineDeployment(Deployment):
     :param name: Name of the resource.
     :type name: str
     :param tags: Tag dictionary. Tags can be added, removed, and updated.
-    :type tags: dict[str, str]
+    :type tags: Dict[str, str]
     :param properties: The asset property dictionary.
-    :type properties: Dict[str, Any], optional
+    :type properties: Dict[str, Any]
     :param description: Description of the resource.
-    :type description: str, optional
+    :type description: str
     :param model: Model entity for the endpoint deployment, defaults to None
-    :type model: Union[str, Model], optional
-    :param code_configuration: defaults to None
-    :type code_configuration: CodeConfiguration, optional
+    :type model: Union[str, ~azure.ai.ml.entities.Model]
+    :param code_configuration: Default value is None.
+    :type code_configuration: CodeConfiguration
     :param environment: Environment entity for the endpoint deployment, defaults to None
-    :type environment: Union[str, Environment], optional
-    :param app_insights_enabled: defaults to False
-    :type app_insights_enabled: bool, optional
+    :type environment: Union[str, Environment]
+    :param app_insights_enabled: Default value is False
+    :type app_insights_enabled: bool
     :param scale_settings: How the online deployment will scale.
-    :type scale_settings: OnlineScaleSettings, optional
-    :param request_settings: defaults to RequestSettings()
-    :type request_settings: OnlineRequestSettings, optional
+    :type scale_settings: OnlineScaleSettings
+    :param request_settings: Default value is RequestSettings()
+    :type request_settings: OnlineRequestSettings
     :param liveness_probe: Liveness probe settings.
-    :type liveness_probe: ProbeSettings, optional
+    :type liveness_probe: ProbeSettings
     :param readiness_probe: Readiness probe settings.
-    :type readiness_probe: ProbeSettings, optional
+    :type readiness_probe: ProbeSettings
     :param environment_variables: Environment variables that will be set in deployment.
-    :type environment_variables: dict, optional
+    :type environment_variables: Dict[str, str]
     :param instance_count: The instance count used for this deployment.
     :type instance_count: int
     :param instance_type: Azure compute sku.
     :type instance_type: str
     :param model_mount_path: The path to mount the model in custom container..
     :type model_mount_path: str
     :param code_path: Equivalent to code_configuration.code, will be ignored if code_configuration is present.
-    :type code_path: Union[str, PathLike], optional
+    :type code_path: Union[str, PathLike]
     :param scoring_script: Equivalent to code_configuration.code.scoring_script
         Will be ignored if code_configuration is present.
-    :type scoring_script: Union[str, PathLike], optional
+    :type scoring_script: Union[str, PathLike]
     """
 
     def __init__(
         self,
         name: str,
         *,
-        endpoint_name: str = None,
-        tags: Dict[str, Any] = None,
-        properties: Dict[str, Any] = None,
-        description: str = None,
-        model: Union[str, "Model"] = None,
-        code_configuration: CodeConfiguration = None,
-        environment: Union[str, "Environment"] = None,
-        app_insights_enabled: bool = False,
-        scale_settings: OnlineScaleSettings = None,
-        request_settings: OnlineRequestSettings = None,
-        liveness_probe: ProbeSettings = None,
-        readiness_probe: ProbeSettings = None,
-        environment_variables: Dict[str, str] = None,
-        instance_count: int = None,
-        instance_type: str = None,
-        model_mount_path: str = None,
-        code_path: Union[str, PathLike] = None,  # promoted property from code_configuration.code
-        scoring_script: Union[str, PathLike] = None,  # promoted property from code_configuration.scoring_script
-        **kwargs,
+        endpoint_name: Optional[str] = None,
+        tags: Optional[Dict[str, Any]] = None,
+        properties: Optional[Dict[str, Any]] = None,
+        description: Optional[str] = None,
+        model: Optional[Union[str, "Model"]] = None,
+        code_configuration: Optional[CodeConfiguration] = None,
+        environment: Optional[Union[str, "Environment"]] = None,
+        app_insights_enabled: Optional[bool] = False,
+        scale_settings: Optional[OnlineScaleSettings] = None,
+        request_settings: Optional[OnlineRequestSettings] = None,
+        liveness_probe: Optional[ProbeSettings] = None,
+        readiness_probe: Optional[ProbeSettings] = None,
+        environment_variables: Optional[Dict[str, str]] = None,
+        instance_count: Optional[int] = None,
+        instance_type: Optional[str] = None,
+        model_mount_path: Optional[str] = None,
+        code_path:  Optional[Union[str, PathLike]] = None,  # promoted property from code_configuration.code
+        scoring_script:  Optional[Union[str, PathLike]] = None, # promoted property code_configuration.scoring_script
+        **kwargs: Any,
     ):
         self._provisioning_state = kwargs.pop("provisioning_state", None)
 

sdk/ml/azure-ai-ml/samples/README.md

@@ -0,0 +1,45 @@
+---
+page_type: sample
+languages:
+  - python
+products:
+  - azure
+  - azure-ai-ml
+urlFragment: ml-samples
+---
+
+# Azure Machine Learning Client Library for Python Samples
+
+These are code samples that show common scenario operations with the Azure Machine Learning Client Library for Python.
+
+These samples provide example code for additional scenarios commonly encountered while working with Machine Learning Library:
+
+* [ml_samples_authentication_sovereign_cloud.py](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/ml/azure-ai-ml/samples/ml_samples_authentication_sovereign_cloud.py) - Examples for creating MLClient for non public cloud:
+  * Set up a MLClient
+  * List workspaces in the subscription.
+
+## Prerequisites
+
+* Python 3.7 or later is required to use this package
+* You must have an [Azure subscription](https://azure.microsoft.com/free/) to run these samples.
+
+## Setup
+
+1. Install the Azure Machine Learning Client Library for Python with [pip](https://pypi.org/project/pip/):
+
+   ```bash
+    pip install azure-ai-ml
+    ```
+
+2. Clone or download this sample repository
+3. Open the sample folder in Visual Studio Code or your IDE of choice.
+
+## Running the samples
+
+1. Open a terminal window and `cd` to the directory that the samples are saved in.
+2. Set the environment variables specified in the sample file you wish to run.
+3. Follow the usage described in the file, e.g. `python ml_samples_authentication_sovereign_cloud.py`
+
+## Next steps
+
+Check out the [API reference documentation](https://learn.microsoft.com/python/api/overview/azure/ai-ml-readme?view=azure-python) to learn more about what you can do with the Azure Machine Learning Client Library.

sdk/ml/azure-ai-ml/samples/ml_samples_authentication_sovereign_cloud.py

@@ -0,0 +1,59 @@
+# coding: utf-8
+
+# -------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for
+# license information.
+# --------------------------------------------------------------------------
+
+"""
+FILE: ml_samples_authentication_sovereign_cloud.py
+DESCRIPTION:
+    These samples demonstrate authenticating a client for multiple clouds.
+USAGE:
+    python ml_samples_authentication_sovereign_cloud.py
+
+"""
+
+import os
+
+class MLClientSamples(object):
+
+    def ml_auth_azure_default_credential(self):
+        # [START create_ml_client_default_credential]
+        # Get a credential for authentication
+        # Default Azure Credentials attempt a chained set of authentication methods, per documentation here: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity
+        # Alternately, one can specify the AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_CLIENT_SECRET to use the EnvironmentCredentialClass.
+        # The docs above specify all mechanisms which the defaultCredential internally support.
+        # Enter details of your subscription
+        subscription_id = "AZURE_SUBSCRIPTION_ID"
+        resource_group = "RESOURCE_GROUP_NAME"
+
+        # Instantiate a MLClient
+        from azure.identity import DefaultAzureCredential, AzureAuthorityHosts
+        from azure.ai.ml import MLClient
+
+        # When using sovereign domains (that is, any cloud other than AZURE_PUBLIC_CLOUD),
+        # you must use an authority with DefaultAzureCredential.
+        # Default authority value : AzureAuthorityHosts.AZURE_PUBLIC_CLOUD
+        # Expected values for authority for sovereign clouds:
+        # AzureAuthorityHosts.AZURE_CHINA or AzureAuthorityHosts.AZURE_GOVERNMENT
+        # credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_CHINA)
+        credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_PUBLIC_CLOUD)
+
+        # When using sovereign domains (that is, any cloud other than AZURE_PUBLIC_CLOUD),
+        # you must pass in the cloud name in kwargs. Default cloud is AzureCloud
+        kwargs = {"cloud": "AzureCloud"}
+        # get a handle to the subscription
+        ml_client = MLClient(credential, subscription_id, resource_group, **kwargs)
+        # [END create_ml_client_default_credential]
+
+        from azure.ai.ml.entities import Workspace
+        # Get a list of workspaces in a resource group
+        for ws in ml_client.workspaces.list():
+            print(ws.name, ":", ws.location, ":", ws.description)
+
+
+if __name__ == '__main__':
+    sample = MLClientSamples()
+    sample.ml_auth_azure_default_credential()