From c404138e005703a217c8593d0bfe792cea9a320e Mon Sep 17 00:00:00 2001 From: Diondra <16376603+diondrapeck@users.noreply.github.com> Date: Fri, 18 Aug 2023 13:42:57 -0500 Subject: [PATCH] [ml] Address apiview docstring comments for 1.10.0 release (#31709) * Remove extra/incorrect load_component methods and fix example * Fix 'integer' typo to 'int' * Fix 'integer' typo to 'int', change keyword args from param * Remove parent class args from docstring * Fix load_component example --- .../ai/ml/entities/_inputs_outputs/input.py | 106 +++++++++--------- .../ai/ml/entities/_inputs_outputs/output.py | 48 ++++---- .../azure/ai/ml/entities/_job/command_job.py | 26 ----- .../azure/ai/ml/entities/_job/spark_job.py | 31 ----- .../azure/ai/ml/entities/_load_functions.py | 14 +-- .../ml_samples_component_configurations.py | 16 +-- 6 files changed, 85 insertions(+), 156 deletions(-) diff --git a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_inputs_outputs/input.py b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_inputs_outputs/input.py index 9f77a7f05fa4..f4a473a7097d 100644 --- a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_inputs_outputs/input.py +++ b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_inputs_outputs/input.py @@ -47,7 +47,7 @@ class Input(_InputOutputBase): # pylint: disable=too-many-instance-attributes :paramtype min: Union[int, float] :keyword max: The maximum value for the input. If a value larger than the maximum is passed to a job, the job execution will fail. - :paramtype max: Union[integer, float] + :paramtype max: Union[int, float] :keyword optional: Specifies if the input is optional. :paramtype optional: Optional[bool] :keyword description: Description of the input @@ -85,20 +85,20 @@ def __init__( ) -> None: """Initialize a uri_folder input. - :param type: The type of the data input. Can only be set to "uri_folder". - :type type: str - :param path: The path to the input data. Paths can be local paths, remote data uris, or a registered AzureML + :keyword type: The type of the data input. Can only be set to "uri_folder". + :paramtype type: str + :keyword path: The path to the input data. Paths can be local paths, remote data uris, or a registered AzureML asset id. - :type path: str - :param mode: The mode of the data input. Accepted values are: + :paramtype path: str + :keyword mode: The mode of the data input. Accepted values are: * 'ro_mount': Mount the data to the compute target as read-only, * 'download': Download the data to the compute target, * 'direct': Pass in the URI as a string to be accessed at runtime - :type mode: str - :param optional: Specifies if the input is optional. - :type optional: bool - :param description: Description of the input - :type description: str + :paramtype mode: str + :keyword optional: Specifies if the input is optional. + :paramtype optional: bool + :keyword description: Description of the input + :paramtype description: str :raises ~azure.ai.ml.exceptions.ValidationException: Raised if Input cannot be successfully validated. Details will be provided in the error message. """ @@ -117,20 +117,20 @@ def __init__( ) -> None: """Initialize a number input. - :param type: The type of the data input. Can only be set to "number". - :type type: str - :param default: The default value of the input. If a default is set, the input data will be optional. - :type default: Union[str, int, float, bool] - :param min: The minimum value for the input. If a value smaller than the minimum is passed to the job, the job + :keyword type: The type of the data input. Can only be set to "number". + :paramtype type: str + :keyword default: The default value of the input. If a default is set, the input data will be optional. + :paramtype default: Union[str, int, float, bool] + :keyword min: The minimum value for the input. If a value smaller than the minimum is passed to the job, the job execution will fail. - :type min: Union[int, float] - :param max: The maximum value for the input. If a value larger than the maximum is passed to a job, the job + :paramtype min: Union[int, float] + :keyword max: The maximum value for the input. If a value larger than the maximum is passed to a job, the job execution will fail. - :type max: Union[integer, float] - :param optional: Specifies if the input is optional. - :type optional: bool - :param description: Description of the input - :type description: str + :paramtype max: Union[int, float] + :keyword optional: Specifies if the input is optional. + :paramtype optional: bool + :keyword description: Description of the input + :paramtype description: str :raises ~azure.ai.ml.exceptions.ValidationException: Raised if Input cannot be successfully validated. Details will be provided in the error message. """ @@ -149,20 +149,20 @@ def __init__( ) -> None: """Initialize an integer input. - :param type: The type of the data input. Can only be set to "integer". - :type type: str - :param default: The default value of the input. If a default is set, the input data will be optional. - :type default: Union[str, int, float, bool] - :param min: The minimum value for the input. If a value smaller than the minimum is passed to the job, the job + :keyword type: The type of the data input. Can only be set to "integer". + :paramtype type: str + :keyword default: The default value of the input. If a default is set, the input data will be optional. + :paramtype default: Union[str, int, float, bool] + :keyword min: The minimum value for the input. If a value smaller than the minimum is passed to the job, the job execution will fail. - :type min: Union[int, float] - :param max: The maximum value for the input. If a value larger than the maximum is passed to a job, the job + :paramtype min: Union[int, float] + :keyword max: The maximum value for the input. If a value larger than the maximum is passed to a job, the job execution will fail. - :type max: Union[integer, float] - :param optional: Specifies if the input is optional. - :type optional: bool - :param description: Description of the input - :type description: str + :paramtype max: Union[int, float] + :keyword optional: Specifies if the input is optional. + :paramtype optional: bool + :keyword description: Description of the input + :paramtype description: str """ @overload @@ -177,14 +177,14 @@ def __init__( ) -> None: """Initialize a string input. - :param type: The type of the data input. Can only be set to "string". - :type type: str - :param default: The default value of this input. When a `default` is set, the input will be optional. - :type default: str - :param optional: Determine if this input is optional. - :type optional: bool - :param description: Description of the input. - :type description: str + :keyword type: The type of the data input. Can only be set to "string". + :paramtype type: str + :keyword default: The default value of this input. When a `default` is set, the input will be optional. + :paramtype default: str + :keyword optional: Determine if this input is optional. + :paramtype optional: bool + :keyword description: Description of the input. + :paramtype description: str :raises ~azure.ai.ml.exceptions.ValidationException: Raised if Input cannot be successfully validated. Details will be provided in the error message. """ @@ -201,17 +201,17 @@ def __init__( ) -> None: """Initialize a bool input. - :param type: The type of the data input. Can only be set to "boolean". - :type type: str - :param path: The path to the input data. Paths can be local paths, remote data uris, or a registered AzureML + :keyword type: The type of the data input. Can only be set to "boolean". + :paramtype type: str + :keyword path: The path to the input data. Paths can be local paths, remote data uris, or a registered AzureML asset id. - :type path: str - :param default: The default value of the input. If a default is set, the input data will be optional. - :type default: Union[str, int, float, bool] - :param optional: Specifies if the input is optional. - :type optional: bool - :param description: Description of the input - :type description: str + :paramtype path: str + :keyword default: The default value of the input. If a default is set, the input data will be optional. + :paramtype default: Union[str, int, float, bool] + :keyword optional: Specifies if the input is optional. + :paramtype optional: bool + :keyword description: Description of the input + :paramtype description: str :raises ~azure.ai.ml.exceptions.ValidationException: Raised if Input cannot be successfully validated. Details will be provided in the error message. """ diff --git a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_inputs_outputs/output.py b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_inputs_outputs/output.py index 944caed1ea8a..74a29407d4de 100644 --- a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_inputs_outputs/output.py +++ b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_inputs_outputs/output.py @@ -64,46 +64,46 @@ class Output(_InputOutputBase): def __init__(self, type: Literal["uri_folder"] = "uri_folder", path=None, mode=None, description=None) -> None: """Define a URI folder output. - :param type: The type of the data output. Can only be set to "uri_folder". - :type type: str - :param path: The remote path where the output should be stored. - :type path: str - :param mode: The access mode of the data output. Accepted values are + :keyword type: The type of the data output. Can only be set to "uri_folder". + :paramtype type: str + :keyword path: The remote path where the output should be stored. + :paramtype path: str + :keyword mode: The access mode of the data output. Accepted values are * 'rw_mount': Read-write mount the data * 'upload': Upload the data from the compute target * 'direct': Pass in the URI as a string - :type mode: str - :param description: The description of the output. - :type description: str - :param name: The name to be used to register the output as a Data or Model asset. A name can be set without + :paramtype mode: str + :keyword description: The description of the output. + :paramtype description: str + :keyword name: The name to be used to register the output as a Data or Model asset. A name can be set without setting a version. - :type name: str - :param version: The version used to register the output as a Data or Model asset. A version can be set only + :paramtype name: str + :keyword version: The version used to register the output as a Data or Model asset. A version can be set only when name is set. - :type version: str + :paramtype version: str """ @overload def __init__(self, type: Literal["uri_file"] = "uri_file", path=None, mode=None, description=None): """Define a URI file outputs. - :param type: The type of the data output. Can only be set to 'uri_file'. - :type type: str - :param path: The remote path where the output should be stored. - :type path: str - :param mode: The access mode of the data output. Accepted values are + :keyword type: The type of the data output. Can only be set to 'uri_file'. + :paramtype type: str + :keyword path: The remote path where the output should be stored. + :paramtype path: str + :keyword mode: The access mode of the data output. Accepted values are * 'rw_mount': Read-write mount the data, * 'upload': Upload the data from the compute target, * 'direct': Pass in the URI as a string - :type mode: str - :param description: The description of the output. - :type description: str - :param name: The name to be used to register the output as a Data or Model asset. A name can be set without + :paramtype mode: str + :keyword description: The description of the output. + :paramtype description: str + :keyword name: The name to be used to register the output as a Data or Model asset. A name can be set without setting a version. - :type name: str - :param version: The version used to register the output as a Data or Model asset. A version can be set only + :paramtype name: str + :keyword version: The version used to register the output as a Data or Model asset. A version can be set only when name is set. - :type version: str + :paramtype version: str """ def __init__(self, *, type=AssetTypes.URI_FOLDER, path=None, mode=None, description=None, **kwargs) -> None: diff --git a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_job/command_job.py b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_job/command_job.py index 52de55a8024d..2d9775037106 100644 --- a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_job/command_job.py +++ b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_job/command_job.py @@ -55,38 +55,12 @@ class CommandJob(Job, ParameterizedCommand, JobIOMixin): """Command job. - :keyword name: The name of the job. - :paramtype name: str - :keyword description: The job description. - :paramtype description: str - :keyword tags: Tag dictionary. Tags can be added, removed, and updated. - :paramtype tags: dict[str, str] - :keyword display_name: The job display name. - :paramtype display_name: str - :keyword properties: A dictionary of properties for the job. - :paramtype properties: dict[str, str] - :keyword experiment_name: The name of the experiment that the job will be created under. Defaults to current - directory name. - :paramtype experiment_name: str :keyword services: Read-only information on services associated with the job. :paramtype services: Optional[dict[str, ~azure.ai.ml.entities.JobService]] :keyword inputs: Mapping of output data bindings used in the command. :paramtype inputs: Optional[dict[str, Union[~azure.ai.ml.Input, str, bool, int, float]]] :keyword outputs: Mapping of output data bindings used in the job. :paramtype outputs: Optional[dict[str, ~azure.ai.ml.Output]] - :keyword command: The command to be executed. - :paramtype command: str - :keyword compute: The compute target the job runs on. - :paramtype compute: str - :keyword resources: The compute resource configuration for the job. - :paramtype resources: ~azure.ai.ml.entities.ResourceConfiguration - :keyword code: A local path or "http:", "https:", or "azureml:" url pointing to a remote location. - :type code: str - :keyword distribution: The distribution configuration for distributed jobs. - :paramtype distribution: Union[~azure.ai.ml.PyTorchDistribution, ~azure.ai.ml.MpiDistribution, - ~azure.ai.ml.TensorFlowDistribution, ~azure.ai.ml.RayDistribution] - :keyword environment: The environment that the job will run in. - :paramtype environment: Union[~azure.ai.ml.entities.Environment, str] :keyword identity: The identity that the job will use while running on compute. :paramtype identity: Optional[Union[~azure.ai.ml.ManagedIdentityConfiguration, ~azure.ai.ml.AmlTokenConfiguration, ~azure.ai.ml.UserIdentityConfiguration]] diff --git a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_job/spark_job.py b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_job/spark_job.py index cc618f5d87e4..39bec4379031 100644 --- a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_job/spark_job.py +++ b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_job/spark_job.py @@ -78,37 +78,6 @@ class SparkJob(Job, ParameterizedSpark, JobIOMixin, SparkJobEntryMixin): :keyword identity: The identity that the Spark job will use while running on compute. :paramtype identity: Optional[Union[dict[str, str], ~azure.ai.ml.ManagedIdentityConfiguration, ~azure.ai.ml.AmlTokenConfiguration, ~azure.ai.ml.UserIdentityConfiguration]] - :keyword resources: The compute resource configuration for the job. - :paramtype resources: Optional[Union[dict, ~azure.ai.ml.entities.SparkResourceConfiguration]] - :keyword experiment_name: The name of the experiment the job will be created under. - :paramtype experiment_name: str - :keyword name: The name of the job. - :paramtype name: str - :keyword display_name: The job display name. - :paramtype display_name: str - :keyword description: The job description. - :paramtype description: str - :keyword tags: The tag dictionary. Tags can be added, removed, and updated. - :paramtype tags: dict[str, str] - :keyword code: The source code to run the job. Can be a local path or "http:", "https:", or "azureml:" url pointing - to a remote location. - :type code: Union[str, os.PathLike] - :keyword entry: The file or class entry point. - :paramtype entry: dict[str, str] - :keyword py_files: The list of .zip, .egg or .py files to place on the PYTHONPATH for Python apps. - :paramtype py_files: list[str] - :keyword jars: The list of .JAR files to include on the driver and executor classpaths. - :paramtype jars: list[str] - :keyword files: The list of files to be placed in the working directory of each executor. - :paramtype files: list[str] - :keyword archives: The list of archives to be extracted into the working directory of each executor. - :paramtype archives: list[str] - :keyword conf: A dictionary with pre-defined Spark configurations key and values. - :paramtype conf: dict[str, str] - :keyword environment: The Azure ML environment to run the job in. - :paramtype environment: Union[str, ~azure.ai.ml.entities.Environment] - :keyword args: The arguments for the job. - :paramtype args: str .. admonition:: Example: diff --git a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_load_functions.py b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_load_functions.py index d1757d0c40e8..57a934af95f5 100644 --- a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_load_functions.py +++ b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_load_functions.py @@ -357,16 +357,7 @@ def load_component( :keyword params_override: Fields to overwrite on top of the yaml file. Format is [{"field1": "value1"}, {"field2": "value2"}] :paramtype params_override: List[Dict] - :keyword client: An MLClient instance. - :paramtype client: MLClient - :keyword name: Name of the component. - :paramtype name: str - :keyword version: Version of the component. - :paramtype version: str - :keyword kwargs: A dictionary of additional configuration parameters. - :paramtype kwargs: dict - - :return: A function that can be called with parameters to get a `azure.ai.ml.entities.Component` + :return: A Component object :rtype: Union[CommandComponent, ParallelComponent, PipelineComponent] .. admonition:: Example: @@ -376,7 +367,8 @@ def load_component( :end-before: [END configure_load_component] :language: python :dedent: 8 - :caption: Loading a Component object from a YAML file. + :caption: Loading a Component object from a YAML file, overriding its version to "1.0.2", and + registering it remotely. """ client = kwargs.pop("client", None) diff --git a/sdk/ml/azure-ai-ml/samples/ml_samples_component_configurations.py b/sdk/ml/azure-ai-ml/samples/ml_samples_component_configurations.py index d5b6650c8648..9068ac10e3a3 100644 --- a/sdk/ml/azure-ai-ml/samples/ml_samples_component_configurations.py +++ b/sdk/ml/azure-ai-ml/samples/ml_samples_component_configurations.py @@ -20,10 +20,9 @@ class ComponentConfigurationOptions(object): def ml_component_config(self): - from azure.identity import DefaultAzureCredential - from azure.ai.ml import MLClient from azure.ai.ml.entities import Environment + from azure.identity import DefaultAzureCredential subscription_id = os.environ["AZURE_SUBSCRIPTION_ID"] resource_group = os.environ["RESOURCE_GROUP_NAME"] @@ -40,15 +39,10 @@ def ml_component_config(self): # [START configure_load_component] from azure.ai.ml import load_component - # Load a local component to a component function. - component_func = load_component(source=r"../tests/test_configs/components/helloworld_component.yml") - - # Consuming the component func - component = component_func(component_in_number=10.99) - - # Load a remote component to a component function. - component = ml_client.components.create_or_update(component_func, version="1") - component_func = load_component(client=ml_client, name=component.name, version="1") + component = load_component( + source="../tests/test_configs/components/helloworld_component.yml", params_override=[{"version": "1.0.2"}] + ) + registered_component = ml_client.components.create_or_update(component) # [END configure_load_component]