[ml] Enable strict sphinx check (#34688)

* Remove Optional type annotation from get() methods

* Remove duplicate overloads

* Fix sphinx errors

* Fix indentation

* Turn on strict sphinx check

* Implicitly expose search_space and _credentials classes to avoid duplicate object exposures

* Add deprecation warning message for imports and update CHANGELOG

* Update formatting

* Ignore mypy error

Author: diondrapeck

sdk/ml/azure-ai-ml/CHANGELOG.md

@@ -10,6 +10,22 @@
 
 ### Other Changes
 
+- The following classes will still be able to be imported from `azure.ai.ml`, but the import is deprecated and emits a warning. Instead, please import them from `azure.ai.ml.entities`.
+  - `AmlTokenConfiguration`
+  - `ManagedIdentityConfiguration`
+  - `UserIdentityConfiguration`
+- The following classes will still be able to be imported from `azure.ai.ml.entities`, but the import is deprecated and emits a warning. Instead, please import them from `azure.ai.ml.sweep`.
+  - `Choice`
+  - `Uniform`
+  - `LogUniform`
+  - `QLogUniform`
+  - `QUniform`
+  - `QLogNormal`
+  - `QNormal`
+  - `LogNormal`
+  - `Normal`
+  - `Randint`
+
 ## 1.14.0 (2024-03-11)
 
 ### Features Added

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

@@ -5,6 +5,7 @@
 __path__ = __import__("pkgutil").extend_path(__path__, __name__)
 
 import logging
+from typing import Any, Optional
 
 # from .entities._builders.parallel_func import parallel
 from azure.ai.ml.entities._inputs_outputs import Input, Output
@@ -14,7 +15,6 @@
 from ._version import VERSION
 from .entities._builders.command_func import command
 from .entities._builders.spark_func import spark
-from .entities._credentials import AmlTokenConfiguration, ManagedIdentityConfiguration, UserIdentityConfiguration
 from .entities._job.distribution import MpiDistribution, PyTorchDistribution, RayDistribution, TensorFlowDistribution
 from .entities._load_functions import (
     load_batch_deployment,
@@ -52,9 +52,6 @@
     "PyTorchDistribution",
     "TensorFlowDistribution",
     "RayDistribution",
-    "ManagedIdentityConfiguration",
-    "AmlTokenConfiguration",
-    "UserIdentityConfiguration",
     "load_batch_deployment",
     "load_batch_endpoint",
     "load_component",
@@ -77,3 +74,35 @@
 ]
 
 __version__ = VERSION
+
+
+# Allow importing these types for backwards compatibility
+
+
+def __getattr__(name: str):
+    requested: Optional[Any] = None
+
+    if name == "AmlTokenConfiguration":
+        from .entities._credentials import AmlTokenConfiguration
+
+        requested = AmlTokenConfiguration
+    if name == "ManagedIdentityConfiguration":
+        from .entities._credentials import ManagedIdentityConfiguration
+
+        requested = ManagedIdentityConfiguration
+    if name == "UserIdentityConfiguration":
+        from .entities._credentials import UserIdentityConfiguration
+
+        requested = UserIdentityConfiguration
+
+    if requested:
+        if not getattr(__getattr__, "warning_issued", False):
+            logging.warning(
+                " %s will be removed from the azure.ai.ml namespace in a future release."
+                " Please use the azure.ai.ml.entities namespace instead.",
+                name,
+            )
+            __getattr__.warning_issued = True  # type: ignore[attr-defined]
+        return requested
+
+    raise AttributeError(f"module 'azure.ai.ml' has no attribute {name}")

sdk/ml/azure-ai-ml/azure/ai/ml/entities/__init__.py

@@ -9,6 +9,9 @@
 # pylint: disable=naming-mismatch
 __path__ = __import__("pkgutil").extend_path(__path__, __name__)
 
+import logging
+from typing import Any, Optional
+
 from azure.ai.ml._restclient.v2022_10_01.models import CreatedByType
 from azure.ai.ml._restclient.v2022_10_01_preview.models import UsageUnit
 
@@ -138,18 +141,6 @@
 from ._job.spark_job import SparkJob
 from ._job.spark_job_entry import SparkJobEntry, SparkJobEntryType
 from ._job.spark_resource_configuration import SparkResourceConfiguration
-from ._job.sweep.search_space import (
-    Choice,
-    LogNormal,
-    LogUniform,
-    Normal,
-    QLogNormal,
-    QLogUniform,
-    QNormal,
-    QUniform,
-    Randint,
-    Uniform,
-)
 from ._monitoring.alert_notification import AlertNotification
 from ._monitoring.compute import ServerlessSparkCompute
 from ._monitoring.definition import MonitorDefinition
@@ -325,16 +316,6 @@
     "ParallelComponent",
     "CommandComponent",
     "SparkComponent",
-    "Choice",
-    "Normal",
-    "LogNormal",
-    "QNormal",
-    "QLogNormal",
-    "Randint",
-    "Uniform",
-    "QUniform",
-    "LogUniform",
-    "QLogUniform",
     "ResourceRequirementsSettings",
     "ResourceSettings",
     "AssignedUserConfiguration",
@@ -472,3 +453,62 @@
     "RequestLogging",
     "NoneCredentialConfiguration",
 ]
+
+# Allow importing these types for backwards compatibility
+
+
+def __getattr__(name: str):
+    requested: Optional[Any] = None
+
+    if name == "Choice":
+        from ..sweep import Choice
+
+        requested = Choice
+    if name == "LogNormal":
+        from ..sweep import LogNormal
+
+        requested = LogNormal
+    if name == "LogUniform":
+        from ..sweep import LogUniform
+
+        requested = LogUniform
+    if name == "Normal":
+        from ..sweep import Normal
+
+        requested = Normal
+    if name == "QLogNormal":
+        from ..sweep import QLogNormal
+
+        requested = QLogNormal
+    if name == "QLogUniform":
+        from ..sweep import QLogUniform
+
+        requested = QLogUniform
+    if name == "QNormal":
+        from ..sweep import QNormal
+
+        requested = QNormal
+    if name == "QUniform":
+        from ..sweep import QUniform
+
+        requested = QUniform
+    if name == "Randint":
+        from ..sweep import Randint
+
+        requested = Randint
+    if name == "Uniform":
+        from ..sweep import Uniform
+
+        requested = Uniform
+
+    if requested:
+        if not getattr(__getattr__, "warning_issued", False):
+            logging.warning(
+                " %s will be removed from the azure.ai.ml.entities namespace in a future release."
+                " Please import from the azure.ai.ml.sweep namespace instead.",
+                name,
+            )
+            __getattr__.warning_issued = True  # type: ignore[attr-defined]
+        return requested
+
+    raise AttributeError(f"module 'azure.ai.ml.entities' has no attribute {name}")

sdk/ml/azure-ai-ml/azure/ai/ml/entities/_job/pipeline/_attr_dict.py

@@ -12,7 +12,7 @@
 V = TypeVar("V")
 
 
-class _AttrDict(Generic[K, V], dict, ABC):
+class _AttrDict(Generic[K, V], Dict, ABC):
     """This class is used for accessing values with instance.some_key. It supports the following scenarios:
 
     1. Setting arbitrary attribute, eg: obj.resource_layout.node_count = 2
@@ -34,6 +34,7 @@ def __init__(self, allowed_keys: Optional[Dict] = None, **kwargs: Any):
 
         :param allowed_keys: A dictionary of keys that allowed to set as arbitrary attributes. None means all keys can
             be set as arbitrary attributes.
+
         :type dict
         :param kwargs: A dictionary of additional configuration parameters.
         :type kwargs: dict

sdk/ml/azure-ai-ml/azure/ai/ml/entities/_job/sweep/parameterized_sweep.py

@@ -66,10 +66,19 @@ def __init__(
         :param early_termination: Early termination policy for sweep job.
         :type early_termination: ~azure.ai.ml.entities._job.sweep.early_termination_policy.EarlyTerminationPolicy
         :param search_space: Search space for sweep job.
-        :type search_space: Dict[str, Union[~azure.ai.ml.sweep.Choice, ~azure.ai.ml.sweep.LogNormal,
-        ~azure.ai.ml.sweep.LogUniform, ~azure.ai.ml.sweep.Normal, ~azure.ai.ml.sweep.QLogNormal,
-        ~azure.ai.ml.sweep.QLogUniform, ~azure.ai.ml.sweep.QNormal, ~azure.ai.ml.sweep.QUniform,
-        ~azure.ai.ml.sweep.Randint, ~azure.ai.ml.sweep.Uniform]]
+        :type search_space: Dict[str, Union[
+            ~azure.ai.ml.sweep.Choice,
+            ~azure.ai.ml.sweep.LogNormal,
+            ~azure.ai.ml.sweep.LogUniform,
+            ~azure.ai.ml.sweep.Normal,
+            ~azure.ai.ml.sweep.QLogNormal,
+            ~azure.ai.ml.sweep.QLogUniform,
+            ~azure.ai.ml.sweep.QNormal,
+            ~azure.ai.ml.sweep.QUniform,
+            ~azure.ai.ml.sweep.Randint,
+            ~azure.ai.ml.sweep.Uniform
+
+            ]]
         :param queue_settings: Queue settings for sweep job.
         :type queue_settings: ~azure.ai.ml.entities.QueueSettings
         :param resources: Compute Resource configuration for the job.

sdk/ml/azure-ai-ml/azure/ai/ml/entities/_job/sweep/search_space.py

@@ -267,7 +267,6 @@ def _from_rest_object(cls, obj: List) -> "Randint":
 
 class Uniform(SweepDistribution):
     """
-    :noindex:
 
     Uniform distribution configuration.
 

sdk/ml/azure-ai-ml/azure/ai/ml/entities/_job/sweep/sweep_job.py

@@ -88,16 +88,21 @@ class SweepJob(Job, ParameterizedSweep, JobIOMixin):
     :paramtype identity: Union[
         ~azure.ai.ml.ManagedIdentityConfiguration,
         ~azure.ai.ml.AmlTokenConfiguration,
-        ~azure.ai.ml.UserIdentityConfiguration]
+        ~azure.ai.ml.UserIdentityConfiguration
+
+    ]
+
     :keyword inputs: Inputs to the command.
     :paramtype inputs: dict
     :keyword outputs: Mapping of output data bindings used in the job.
     :paramtype outputs: dict[str, ~azure.ai.ml.Output]
     :keyword sampling_algorithm: The hyperparameter sampling algorithm to use over the `search_space`. Defaults to
         "random".
+
     :paramtype sampling_algorithm: str
     :keyword search_space: Dictionary of the hyperparameter search space. The key is the name of the hyperparameter
         and the value is the parameter expression.
+
     :paramtype search_space: Dict
     :keyword objective: Metric to optimize for.
     :paramtype objective: Objective
@@ -111,12 +116,17 @@ class SweepJob(Job, ParameterizedSweep, JobIOMixin):
         ~azure.ai.ml.entities.CommandComponent
 
     ]
+
     :keyword early_termination: The early termination policy to use. A trial job is canceled
         when the criteria of the specified policy are met. If omitted, no early termination policy will be applied.
+
     :paramtype early_termination:  Union[
         ~azure.mgmt.machinelearningservices.models.BanditPolicy,
         ~azure.mgmt.machinelearningservices.models.MedianStoppingPolicy,
-        ~azure.mgmt.machinelearningservices.models.TruncationSelectionPolicy]
+        ~azure.mgmt.machinelearningservices.models.TruncationSelectionPolicy
+
+    ]
+
     :keyword limits: Limits for the sweep job.
     :paramtype limits: ~azure.ai.ml.entities.SweepJobLimits
     :keyword queue_settings: Queue settings for the job.

sdk/ml/azure-ai-ml/azure/ai/ml/entities/_workspace/connections/workspace_connection.py

@@ -4,35 +4,31 @@
 
 # pylint: disable=protected-access
 
+import warnings
 from os import PathLike
 from pathlib import Path
-import warnings
 from typing import IO, Any, AnyStr, Dict, List, Optional, Type, Union, cast
 
+from azure.ai.ml._restclient.v2023_08_01_preview.models import (
+    WorkspaceConnectionPropertiesV2BasicResource as RestWorkspaceConnection,
+)
 from azure.ai.ml._restclient.v2024_01_01_preview.models import (
     ConnectionCategory,
     NoneAuthTypeWorkspaceConnectionProperties,
 )
-from azure.ai.ml._restclient.v2023_08_01_preview.models import (
-    WorkspaceConnectionPropertiesV2BasicResource as RestWorkspaceConnection,
-)
 from azure.ai.ml._schema.workspace.connections.workspace_connection import WorkspaceConnectionSchema
 from azure.ai.ml._utils._experimental import experimental
 from azure.ai.ml._utils.utils import _snake_to_camel, camel_to_snake, dump_yaml_to_file
-from azure.ai.ml.constants._common import (
-    BASE_PATH_CONTEXT_KEY,
-    PARAMS_OVERRIDE_KEY,
-    WorkspaceConnectionTypes,
-)
+from azure.ai.ml.constants._common import BASE_PATH_CONTEXT_KEY, PARAMS_OVERRIDE_KEY, WorkspaceConnectionTypes
 from azure.ai.ml.entities._credentials import (
     AccessKeyConfiguration,
     ApiKeyConfiguration,
     ManagedIdentityConfiguration,
+    NoneCredentialConfiguration,
     PatTokenConfiguration,
     SasTokenConfiguration,
     ServicePrincipalConfiguration,
     UsernamePasswordConfiguration,
-    NoneCredentialConfiguration,
     _BaseIdentityConfiguration,
 )
 from azure.ai.ml.entities._resource import Resource
@@ -174,6 +170,7 @@ def credentials(
             ~azure.ai.ml.entities.ServicePrincipalConfiguration,
             ~azure.ai.ml.entities.AccessKeyConfiguration,
             ~azure.ai.ml.entities.ApiKeyConfiguration
+
         ]
         """
         return self._credentials
@@ -373,8 +370,8 @@ def _get_entity_class_from_type(cls, conn_type: Optional[str]) -> Type:
         from .workspace_connection_subtypes import (
             AzureAISearchWorkspaceConnection,
             AzureAIServiceWorkspaceConnection,
-            AzureOpenAIWorkspaceConnection,
             AzureBlobStoreWorkspaceConnection,
+            AzureOpenAIWorkspaceConnection,
         )
 
         # Connection categories don't perfectly follow perfect camel casing, so lower

sdk/ml/azure-ai-ml/azure/ai/ml/operations/_model_operations.py

@@ -415,7 +415,7 @@ def archive(
                 :end-before: [END model_operations_archive]
                 :language: python
                 :dedent: 8
-                :caption: Archive a model example.
+                :caption: Archive a model.
         """
         _archive_or_restore(
             asset_operations=self,
@@ -451,7 +451,7 @@ def restore(
                 :end-before: [END model_operations_restore]
                 :language: python
                 :dedent: 8
-                :caption: Restore a model example.
+                :caption: Restore an archived model.
         """
         _archive_or_restore(
             asset_operations=self,

sdk/ml/azure-ai-ml/pyproject.toml

@@ -4,7 +4,7 @@ pyright = false
 type_check_samples = false
 verifytypes = false
 pylint = true
-strict_sphinx = false
+strict_sphinx = true
 
 
 [tool.isort]