fix: Resolve ApiVIEW comments about , optional and :paramtype: (#31679)

* fix: Remove `, optional` from :type: fields

    This seems to have been breaking ApiVIEW's type parser, and
    prevented type hints from appearing in the review tool.

    Sphinx may annotate this automatically.

* fix: Replace `:type:` with `:paramtype:` for `:keyword:` args

Author: kdestin

sdk/ml/azure-ai-ml/azure/ai/ml/_artifacts/_artifact_utilities.py

@@ -79,7 +79,7 @@ def get_datastore_info(
     :keyword credential: Local credential to use for authentication. If not provided, will try to get
         credentials from the datastore, which requires authorization to perform action
         'Microsoft.MachineLearningServices/workspaces/datastores/listSecrets/action' over target datastore.
-    :type credential: str
+    :paramtype credential: str
     :return: The dictionary with datastore info
     :rtype: Dict[Literal["storage_type", "storage_account", "account_url", "container_name"], str]
     """
@@ -217,17 +217,17 @@ def upload_artifact(
     :param datastore_name: The datastore name
     :type datastore_name: Optional[str]
     :param asset_hash: The asset hash
-    :type asset_hash: Optional[str], optional
+    :type asset_hash: Optional[str]
     :param show_progress: Whether to show progress on the console. Defaults to True.
-    :type show_progress: bool, optional
+    :type show_progress: bool
     :param asset_name: The asset name
-    :type asset_name: Optional[str], optional
+    :type asset_name: Optional[str]
     :param asset_version: The asset version
-    :type asset_version: Optional[str], optional
+    :type asset_version: Optional[str]
     :param ignore_file: The IgnoreFile determining which, if any, files to ignore when uploading
-    :type ignore_file: IgnoreFile, optional
+    :type ignore_file: IgnoreFile
     :param sas_uri: The sas uri to use for uploading
-    :type sas_uri: Optional[str], optional
+    :type sas_uri: Optional[str]
     :return: The artifact storage info
     :rtype: ArtifactStorageInfo
     """
@@ -280,7 +280,7 @@ def download_artifact(
     :param datastore_name: name of datastore
     :type datastore_name: Optional[str]
     :param datastore_info: the return value of invoking get_datastore_info
-    :type datastore_info: Optional[Dict], optional
+    :type datastore_info: Optional[Dict]
     :return: Path that files were written to
     :rtype: str
     """
@@ -465,13 +465,13 @@ def _check_and_upload_path(
     :param artifact_type: The artifact type
     :type artifact_type: str
     :param datastore_name: the name of the datastore to upload to
-    :type datastore_name: Optional[str], optional
+    :type datastore_name: Optional[str]
     :param sas_uri: the sas uri to use for uploading
-    :type sas_uri: Optional[str], optional
+    :type sas_uri: Optional[str]
     :param show_progress: Whether to show progress on the console. Defaults to True.
-    :type show_progress: bool, optional
+    :type show_progress: bool
     :param blob_uri: The storage account uri
-    :type blob_uri: Optional[str], optional
+    :type blob_uri: Optional[str]
     :return: A 2-tuple of the uploaded artifact, and the indicator file.
     :rtype: Tuple[T, Optional[str]]
     """

sdk/ml/azure-ai-ml/azure/ai/ml/_artifacts/_blob_storage_helper.py

@@ -81,11 +81,11 @@ def upload(
         :param version: The asset version
         :type version: str
         :param ignore_file: The IgnoreFile that specifies which files, if any, to ignore when uploading files
-        :type ignore_file: IgnoreFile, optional
+        :type ignore_file: IgnoreFile
         :param asset_hash: The asset hash
-        :type asset_hash: Optional[str], optional
+        :type asset_hash: Optional[str]
         :param show_progress: Whether to show progress on the console. Defaults to True.
-        :type show_progress: bool, optional
+        :type show_progress: bool
         :return: A dictionary containing info of the uploaded artifact
         :rtype: Dict[Literal["remote path", "name", "version", "indicator file"], str]
         """

sdk/ml/azure-ai-ml/azure/ai/ml/_artifacts/_fileshare_storage_helper.py

@@ -80,11 +80,11 @@ def upload(
         :param version: The asset version
         :type version: str
         :param ignore_file: The IgnoreFile that specifies which files, if any, to ignore when uploading files
-        :type ignore_file: IgnoreFile, optional
+        :type ignore_file: IgnoreFile
         :param asset_hash: The asset hash
-        :type asset_hash: Optional[str], optional
+        :type asset_hash: Optional[str]
         :param show_progress: Whether to show progress on the console. Defaults to True.
-        :type show_progress: bool, optional
+        :type show_progress: bool
         :return: A dictionary containing info of the uploaded artifact
         :rtype: Dict[Literal["remote path", "name", "version"], str]
         """
@@ -148,17 +148,17 @@ def upload_file(
         :param dest: The destination in the fileshare to upload to
         :type dest: str
         :param show_progress: Whether to show progress on the console. Defaults to False.
-        :type show_progress: bool, optional
+        :type show_progress: bool
         :param msg: Message to display on progress bar. Defaults to None.
-        :type msg: Optional[str], optional
+        :type msg: Optional[str]
         :param in_directory: Whether this function is being called by :attr:`FileStorageClient.upload_dir`. Defaults
             to False.
-        :type in_directory: bool, optional
+        :type in_directory: bool
         :param subdirectory_client: The subdirectory client.
-        :type subdirectory_client: Optional[ShareDirectoryClient], optional
+        :type subdirectory_client: Optional[ShareDirectoryClient]
         :param callback: A callback that receives the raw requests returned by the service during the upload process.
             Only used if `in_directory` and `show_progress` are True.
-        :type callback: Optional[Callable[[Dict], None]], optional
+        :type callback: Optional[Callable[[Dict], None]]
         """
         validate_content = os.stat(source).st_size > 0  # don't do checksum for empty files
 
@@ -294,11 +294,11 @@ def download(
         """Downloads all contents inside a specified fileshare directory.
 
         :param starts_with: The prefix used to filter files to download
-        :type starts_with: str, optional
+        :type starts_with: str
         :param destination: The destination to download to. Default to user's home directory.
-        :type destination: str, optional
+        :type destination: str
         :param max_concurrency: The maximum number of concurrent downloads. Defaults to 4.
-        :type max_concurrency: int, optional
+        :type max_concurrency: int
         """
         recursive_download(
             client=self.directory_client,
@@ -394,7 +394,7 @@ def recursive_download(
     :param max_concurrency: The maximum number of concurrent downloads
     :type max_concurrency: int
     :param starts_with: The prefix used to filter files to download. Defaults to ""
-    :type starts_with: str, optional
+    :type starts_with: str
     """
     try:
         items = list(client.list_directories_and_files(name_starts_with=starts_with))

sdk/ml/azure-ai-ml/azure/ai/ml/_artifacts/_gen2_storage_helper.py

@@ -71,11 +71,11 @@ def upload(
         :param version: The asset version
         :type version: str
         :param ignore_file: The IgnoreFile that specifies which files, if any, to ignore when uploading files
-        :type ignore_file: IgnoreFile, optional
+        :type ignore_file: IgnoreFile
         :param asset_hash: The asset hash
-        :type asset_hash: Optional[str], optional
+        :type asset_hash: Optional[str]
         :param show_progress: Whether to show progress on the console. Defaults to True.
-        :type show_progress: bool, optional
+        :type show_progress: bool
         :return: A dictionary containing info of the uploaded artifact
         :rtype: Dict[Literal["remote path", "name", "version", "indicator file"], str]
         """

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

@@ -123,9 +123,9 @@ def _get_base_url_from_metadata(cloud_name: Optional[str] = None, is_local_mfe:
     """Retrieve the base url for a cloud from the metadata in SDK.
 
     :param cloud_name: cloud name
-    :type cloud_name: Optional[str], optional
+    :type cloud_name: Optional[str]
     :param is_local_mfe: Whether is local Management Front End. Defaults to False.
-    :type is_local_mfe: bool, optional
+    :type is_local_mfe: bool
     :return: base url for a cloud
     :rtype: str
     """
@@ -142,7 +142,7 @@ def _get_aml_resource_id_from_metadata(cloud_name: Optional[str] = None) -> str:
     """Retrieve the aml_resource_id for a cloud from the metadata in SDK.
 
     :param cloud_name: cloud name
-    :type cloud_name: str, optional
+    :type cloud_name: str
     :return: aml_resource_id for a cloud
     :rtype: str
     """
@@ -155,7 +155,7 @@ def _get_active_directory_url_from_metadata(cloud_name: Optional[str] = None) ->
     """Retrieve the active_directory_url for a cloud from the metadata in SDK.
 
     :param cloud_name: cloud name
-    :type cloud_name: str, optional
+    :type cloud_name: str
     :return: active_directory for a cloud
     :rtype: str
     """
@@ -168,7 +168,7 @@ def _get_storage_endpoint_from_metadata(cloud_name: Optional[str] = None) -> str
     """Retrieve the storage_endpoint for a cloud from the metadata in SDK.
 
     :param cloud_name: cloud name
-    :type cloud_name: str, optional
+    :type cloud_name: str
     :return: storage_endpoint for a cloud
     :rtype: str
     """
@@ -181,7 +181,7 @@ def _get_azure_portal_id_from_metadata(cloud_name: Optional[str] = None) -> str:
     """Retrieve the azure_portal_id for a cloud from the metadata in SDK.
 
     :param cloud_name: cloud name
-    :type cloud_name: str, optional
+    :type cloud_name: str
     :return: azure_portal_id for a cloud
     :rtype: str
     """
@@ -194,7 +194,7 @@ def _get_cloud_information_from_metadata(cloud_name: Optional[str] = None, **kwa
     """Retrieve the cloud information from the metadata in SDK.
 
     :param cloud_name: cloud name
-    :type cloud_name: str, optional
+    :type cloud_name: str
     :return: A dictionary of additional configuration parameters required for passing in cloud information.
     :rtype: Dict
     """
@@ -213,7 +213,7 @@ def _get_registry_discovery_endpoint_from_metadata(cloud_name: Optional[str] = N
     """Retrieve the registry_discovery_endpoint for a cloud from the metadata in SDK.
 
     :param cloud_name: cloud name
-    :type cloud_name: str, optional
+    :type cloud_name: str
     :return: registry_discovery_endpoint for a cloud
     :rtype: str
     """

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

@@ -240,9 +240,9 @@ def format_create_validation_error(
     :param yaml_operation: Whether the exception was caused by yaml validation.
     :type yaml_operation: bool
     :param cli: Whether is invoked from Azure CLI AzureML Extension. Defaults to False
-    :type cli: bool, optional
+    :type cli: bool
     :param raw_error: The raw exception message
-    :type raw_error: Optional[str], optional
+    :type raw_error: Optional[str]
     :return: Formatted error message
     :rtype: str
     """

sdk/ml/azure-ai-ml/azure/ai/ml/_local_endpoints/dockerfile_resolver.py

@@ -82,7 +82,7 @@ def _construct(self, install_debugpy: bool = False) -> None:
         Constructs the Dockerfile instructions based on properties.
 
         :param install_debugpy: Whether to install debugpy. Defaults to False.
-        :type install_debugpy: bool, optional
+        :type install_debugpy: bool
         """
         self._instructions = []
         if self._docker_base_image:

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

@@ -113,12 +113,12 @@ class MLClient:
     :type registry_name: Optional[str]
     :keyword show_progress: Specifies whether or not to display progress bars for long-running operations (e.g.
         customers may consider setting this to False if not using this SDK in an interactive setup). Defaults to True.
-    :type show_progress: Optional[bool]
+    :paramtype show_progress: Optional[bool]
     :keyword enable_telemetry: Specifies whether or not to enable telemetry. Will be overridden to False if not in a
         Jupyter Notebook. Defaults to True if in a Jupyter Notebook.
-    :type enable_telemetry: Optional[bool]
+    :paramtype enable_telemetry: Optional[bool]
     :keyword cloud: The cloud name to use. Defaults to "AzureCloud".
-    :type cloud: Optional[str]
+    :paramtype cloud: Optional[str]
     :raises ValueError: Raised if credential is None.
     :raises ~azure.ai.ml.ValidationException: Raised if both workspace_name and registry_name are provided.
 
@@ -547,12 +547,12 @@ def from_config(
         :type credential: ~azure.core.credentials.TokenCredential
         :keyword path: The path to the configuration file or starting directory to search for the configuration file
             within. Defaults to None, indicating the current directory will be used.
-        :type path: Optional[Union[os.PathLike, str]]
+        :paramtype path: Optional[Union[os.PathLike, str]]
         :keyword file_name: The configuration file name to search for when path is a directory path. Defaults to
             "config.json".
-        :type file_name: Optional[str]
+        :paramtype file_name: Optional[str]
         :keyword cloud: The cloud name to use. Defaults to "AzureCloud".
-        :type cloud: Optional[str]
+        :paramtype cloud: Optional[str]
         :raises ~azure.ai.ml.exceptions.ValidationException: Raised if "config.json", or file_name if overridden,
             cannot be found in directory. Details will be provided in the error message.
         :returns: The client for an existing Azure ML Workspace.

sdk/ml/azure-ai-ml/azure/ai/ml/_schema/core/fields.py

@@ -648,7 +648,7 @@ def _deserialize(self, value, attr, data, **kwargs):
 def ComputeField(**kwargs) -> Field:
     """
     :keyword required: if set to True, it is not possible to pass None
-    :type required: bool
+    :paramtype required: bool
     :return: The compute field
     :rtype: Field
     """
@@ -667,7 +667,7 @@ def ComputeField(**kwargs) -> Field:
 def CodeField(**kwargs) -> Field:
     """
     :keyword required: if set to True, it is not possible to pass None
-    :type required: bool
+    :paramtype required: bool
     :return: The code field
     :rtype: Field
     """

sdk/ml/azure-ai-ml/azure/ai/ml/_telemetry/_customtraceback.py

@@ -143,9 +143,9 @@ def format_exc(limit: Optional[int] = None, chain: bool = True) -> str:
     """Like print_exc() but return a string.
 
     :param limit: None to include all frames or the number of frames to include.
-    :type limit: Optional[int], optional
+    :type limit: Optional[int]
     :param chain: Whether to format __cause__ and __context__. Defaults to True
-    :type chain: bool, optional
+    :type chain: bool
     :return: The formatted exception string
     :rtype: str
     """
@@ -170,9 +170,9 @@ def format_exception(  # pylint: disable=unused-argument
     :param tb: The exception traceback
     :type tb: types.TracebackType
     :param limit: None to include all frames or the number of frames to include.
-    :type limit: Optional[int], optional
+    :type limit: Optional[int]
     :param chain: Whether to format __cause__ and __context__. Defaults to True
-    :type chain: bool, optional
+    :type chain: bool
     :return: A list of strings, each ending in a newline and some containing internal newlines.
       When these lines are concatenated and printed, exactly the same text is printed as does print_exception().
     :rtype: List[str]