change: Disable type hints in doc signature and add PipelineVariable annotations in docstring (aws#3292)

Co-authored-by: Dewen Qi <[email protected]>

Author: qidewenwhen

doc/conf.py

@@ -96,6 +96,13 @@
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {"http://docs.python.org/": None}
 
+# -- Options for autodoc ----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration
+
+# Automatically extract typehints when specified and place them in
+# descriptions of the relevant function/method.
+autodoc_typehints = "description"
+
 # autosummary
 autosummary_generate = True
 

doc/workflows/pipelines/sagemaker.workflow.pipelines.rst

@@ -46,6 +46,8 @@ Entities
 
 .. autoclass:: sagemaker.workflow.entities.Expression
 
+.. autoclass:: sagemaker.workflow.entities.PipelineVariable
+
 Execution Variables
 -------------------
 

src/sagemaker/amazon/amazon_estimator.py

@@ -316,16 +316,16 @@ def __init__(
         """A collection of Amazon :class:~`Record` objects serialized and stored in S3.
 
         Args:
-            s3_data (str): The S3 location of the training data
+            s3_data (str or PipelineVariable): The S3 location of the training data
             num_records (int): The number of records in the set.
             feature_dim (int): The dimensionality of "values" arrays in the
                 Record features, and label (if each Record is labeled).
-            s3_data_type (str): Valid values: 'S3Prefix', 'ManifestFile'. If
-                'S3Prefix', ``s3_data`` defines a prefix of s3 objects to train
+            s3_data_type (str or PipelineVariable): Valid values: 'S3Prefix', 'ManifestFile'.
+                If 'S3Prefix', ``s3_data`` defines a prefix of s3 objects to train
                 on. All objects with s3 keys beginning with ``s3_data`` will be
                 used to train. If 'ManifestFile', then ``s3_data`` defines a
                 single s3 manifest file, listing each s3 object to train on.
-            channel (str): The SageMaker Training Job channel this RecordSet
+            channel (str or PipelineVariable): The SageMaker Training Job channel this RecordSet
                 should be bound to
         """
         self.s3_data = s3_data

src/sagemaker/amazon/factorization_machines.py

@@ -333,7 +333,7 @@ def __init__(
         """Initialization for FactorizationMachinesModel class.
 
         Args:
-            model_data (str): The S3 location of a SageMaker model data
+            model_data (str or PipelineVariable): The S3 location of a SageMaker model data
                 ``.tar.gz`` file.
             role (str): An AWS IAM role (either name or full ARN). The Amazon
                 SageMaker training jobs and APIs that create Amazon SageMaker

src/sagemaker/amazon/ipinsights.py

@@ -236,7 +236,7 @@ def __init__(
         """Creates object to get insights on S3 model data.
 
         Args:
-            model_data (str): The S3 location of a SageMaker model data
+            model_data (str or PipelineVariable): The S3 location of a SageMaker model data
                 ``.tar.gz`` file.
             role (str): An AWS IAM role (either name or full ARN). The Amazon
                 SageMaker training jobs and APIs that create Amazon SageMaker

src/sagemaker/amazon/kmeans.py

@@ -260,7 +260,7 @@ def __init__(
         """Initialization for KMeansModel class.
 
         Args:
-            model_data (str): The S3 location of a SageMaker model data
+            model_data (str or PipelineVariable): The S3 location of a SageMaker model data
                 ``.tar.gz`` file.
             role (str): An AWS IAM role (either name or full ARN). The Amazon
                 SageMaker training jobs and APIs that create Amazon SageMaker

src/sagemaker/amazon/knn.py

@@ -252,7 +252,7 @@ def __init__(
         """Function to initialize KNNModel.
 
         Args:
-            model_data (str): The S3 location of a SageMaker model data
+            model_data (str or PipelineVariable): The S3 location of a SageMaker model data
                 ``.tar.gz`` file.
             role (str): An AWS IAM role (either name or full ARN). The Amazon
                 SageMaker training jobs and APIs that create Amazon SageMaker

src/sagemaker/amazon/lda.py

@@ -234,7 +234,7 @@ def __init__(
         """Initialization for LDAModel class.
 
         Args:
-            model_data (str): The S3 location of a SageMaker model data
+            model_data (str or PipelineVariable): The S3 location of a SageMaker model data
                 ``.tar.gz`` file.
             role (str): An AWS IAM role (either name or full ARN). The Amazon
                 SageMaker training jobs and APIs that create Amazon SageMaker

src/sagemaker/amazon/linear_learner.py

@@ -495,7 +495,7 @@ def __init__(
         """Initialization for LinearLearnerModel.
 
         Args:
-            model_data (str): The S3 location of a SageMaker model data
+            model_data (str or PipelineVariable): The S3 location of a SageMaker model data
                 ``.tar.gz`` file.
             role (str): An AWS IAM role (either name or full ARN). The Amazon
                 SageMaker training jobs and APIs that create Amazon SageMaker

src/sagemaker/amazon/ntm.py

@@ -263,7 +263,7 @@ def __init__(
         """Initialization for NTMModel class.
 
         Args:
-            model_data (str): The S3 location of a SageMaker model data
+            model_data (str or PipelineVariable): The S3 location of a SageMaker model data
                 ``.tar.gz`` file.
             role (str): An AWS IAM role (either name or full ARN). The Amazon
                 SageMaker training jobs and APIs that create Amazon SageMaker

src/sagemaker/amazon/object2vec.py

@@ -358,7 +358,7 @@ def __init__(
         """Initialization for Object2VecModel class.
 
         Args:
-            model_data (str): The S3 location of a SageMaker model data
+            model_data (str or PipelineVariable): The S3 location of a SageMaker model data
                 ``.tar.gz`` file.
             role (str): An AWS IAM role (either name or full ARN). The Amazon
                 SageMaker training jobs and APIs that create Amazon SageMaker

src/sagemaker/amazon/pca.py

@@ -251,7 +251,7 @@ def __init__(
         """Initialization for PCAModel.
 
         Args:
-            model_data (str): The S3 location of a SageMaker model data
+            model_data (str or PipelineVariable): The S3 location of a SageMaker model data
                 ``.tar.gz`` file.
             role (str): An AWS IAM role (either name or full ARN). The Amazon
                 SageMaker training jobs and APIs that create Amazon SageMaker

src/sagemaker/amazon/randomcutforest.py

@@ -223,7 +223,7 @@ def __init__(
         """Initialization for RandomCutForestModel class.
 
         Args:
-            model_data (str): The S3 location of a SageMaker model data
+            model_data (str or PipelineVariable): The S3 location of a SageMaker model data
                 ``.tar.gz`` file.
             role (str): An AWS IAM role (either name or full ARN). The Amazon
                 SageMaker training jobs and APIs that create Amazon SageMaker

src/sagemaker/chainer/estimator.py

@@ -74,7 +74,7 @@ def __init__(
         home-page: https://github.com/aws/sagemaker-python-sdk
 
         Args:
-            entry_point (str): Path (absolute or relative) to the Python source
+            entry_point (str or PipelineVariable): Path (absolute or relative) to the Python source
                 file which should be executed as the entry point to training.
                 If ``source_dir`` is specified, then ``entry_point``
                 must point to a file located at the root of ``source_dir``.
@@ -92,7 +92,7 @@ def __init__(
                 command used to run the entry point. For example, '-X
                 NCCL_DEBUG=WARN' will pass that option string to the mpirun
                 command.
-            source_dir (str): Path (absolute or relative) to a directory with
+            source_dir (str or PipelineVariable): Path (absolute or relative) to a directory with
                 any other training source code dependencies aside from the entry
                 point file (default: None). Structure within this directory are
                 preserved when training on Amazon SageMaker.

src/sagemaker/chainer/model.py

@@ -94,7 +94,7 @@ def __init__(
         """Initialize an ChainerModel.
 
         Args:
-            model_data (str): The S3 location of a SageMaker model data
+            model_data (str or PipelineVariable): The S3 location of a SageMaker model data
                 ``.tar.gz`` file.
             role (str): An AWS IAM role (either name or full ARN). The Amazon
                 SageMaker training jobs and APIs that create Amazon SageMaker
@@ -105,8 +105,8 @@ def __init__(
                 file which should be executed as the entry point to model
                 hosting. If ``source_dir`` is specified, then ``entry_point``
                 must point to a file located at the root of ``source_dir``.
-            image_uri (str): A Docker image URI (default: None). If not specified,
-                a default image for Chainer will be used.
+            image_uri (str or PipelineVariable): A Docker image URI (default: None).
+                If not specified, a default image for Chainer will be used.
                 If ``framework_version`` or ``py_version``
                 are ``None``, then ``image_uri`` is required. If ``image_uri`` is also ``None``,
                 then a ``ValueError`` will be raised.
@@ -120,7 +120,7 @@ def __init__(
                 to call to create a predictor with an endpoint name and
                 SageMaker ``Session``. If specified, ``deploy()`` returns the
                 result of invoking this function on the created endpoint name.
-            model_server_workers (int): Optional. The number of worker processes
+            model_server_workers (int or PipelineVariable): Optional. The number of worker processes
                 used by the inference server. If None, server will use one
                 worker per vCPU.
             **kwargs: Keyword arguments passed to the
@@ -173,43 +173,49 @@ def register(
         """Creates a model package for creating SageMaker models or listing on Marketplace.
 
         Args:
-            content_types (list): The supported MIME types for the input data.
-            response_types (list): The supported MIME types for the output data.
-            inference_instances (list): A list of the instance types that are used to
-                generate inferences in real-time.
-            transform_instances (list): A list of the instance types on which a transformation
-                job can be run or on which an endpoint can be deployed.
-            model_package_name (str): Model Package name, exclusive to `model_package_group_name`,
-                using `model_package_name` makes the Model Package un-versioned (default: None).
-            model_package_group_name (str): Model Package Group name, exclusive to
-                `model_package_name`, using `model_package_group_name` makes the Model Package
-                versioned (default: None).
-            image_uri (str): Inference image uri for the container. Model class' self.image will
-                be used if it is None (default: None).
+            content_types (list[str] or list[PipelineVariable]): The supported MIME types
+                for the input data.
+            response_types (list[str] or list[PipelineVariable]): The supported MIME types
+                for the output data.
+            inference_instances (list[str] or list[PipelineVariable]): A list of the instance
+                types that are used to generate inferences in real-time.
+            transform_instances (list[str] or list[PipelineVariable]): A list of the instance
+                types on which a transformation job can be run or on which an endpoint
+                can be deployed.
+            model_package_name (str or PipelineVariable): Model Package name, exclusive to
+                `model_package_group_name`, using `model_package_name` makes the Model Package
+                un-versioned (default: None).
+            model_package_group_name (str or PipelineVariable): Model Package Group name,
+                exclusive to `model_package_name`, using `model_package_group_name` makes the
+                Model Package versioned (default: None).
+            image_uri (str or PipelineVariable): Inference image uri for the container. Model class'
+                self.image will be used if it is None (default: None).
             model_metrics (ModelMetrics): ModelMetrics object (default: None).
             metadata_properties (MetadataProperties): MetadataProperties (default: None).
             marketplace_cert (bool): A boolean value indicating if the Model Package is certified
                 for AWS Marketplace (default: False).
-            approval_status (str): Model Approval Status, values can be "Approved", "Rejected",
-                or "PendingManualApproval" (default: "PendingManualApproval").
+            approval_status (str or PipelineVariable): Model Approval Status, values can be
+                "Approved", "Rejected", or "PendingManualApproval"
+                (default: "PendingManualApproval").
             description (str): Model Package description (default: None).
             drift_check_baselines (DriftCheckBaselines): DriftCheckBaselines object (default: None).
-            customer_metadata_properties (dict[str, str]): A dictionary of key-value paired
-                metadata properties (default: None).
-            domain (str): Domain values can be "COMPUTER_VISION", "NATURAL_LANGUAGE_PROCESSING",
-                "MACHINE_LEARNING" (default: None).
-            sample_payload_url (str): The S3 path where the sample payload is stored
+            customer_metadata_properties (dict[str, str] or dict[str, PipelineVariable]):
+                A dictionary of key-value paired metadata properties (default: None).
+            domain (str or PipelineVariable): Domain values can be "COMPUTER_VISION",
+                "NATURAL_LANGUAGE_PROCESSING", "MACHINE_LEARNING" (default: None).
+            sample_payload_url (str or PipelineVariable): The S3 path where the sample payload
+                is stored (default: None).
+            task (str or PipelineVariable): Task values which are supported by Inference Recommender
+                are "FILL_MASK", "IMAGE_CLASSIFICATION", "OBJECT_DETECTION", "TEXT_GENERATION",
+                "IMAGE_SEGMENTATION", "CLASSIFICATION", "REGRESSION", "OTHER" (default: None).
+            framework (str or PipelineVariable): Machine learning framework of the model package
+                container image (default: None).
+            framework_version (str or PipelineVariable): Framework version of the Model Package
+                Container Image (default: None).
+            nearest_model_name (str or PipelineVariable): Name of a pre-trained machine learning
+                benchmarked by Amazon SageMaker Inference Recommender (default: None).
+            data_input_configuration (str or PipelineVariable): Input object for the model
                 (default: None).
-            task (str): Task values which are supported by Inference Recommender are "FILL_MASK",
-                "IMAGE_CLASSIFICATION", "OBJECT_DETECTION", "TEXT_GENERATION", "IMAGE_SEGMENTATION",
-                "CLASSIFICATION", "REGRESSION", "OTHER" (default: None).
-            framework (str): Machine learning framework of the model package container image
-                (default: None).
-            framework_version (str): Framework version of the Model Package Container Image
-                (default: None).
-            nearest_model_name (str): Name of a pre-trained machine learning benchmarked by
-                Amazon SageMaker Inference Recommender (default: None).
-            data_input_configuration (str): Input object for the model (default: None).
 
         Returns:
             str: A string of SageMaker Model Package ARN.