[form recognizer] consistency renames for FormTrainingClient (#11390)

Author: iscai-msft

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

@@ -2,6 +2,12 @@
 
 ## 1.0.0b3 (Unreleased)
 
+**Breaking Changes**
+
+- `training_files` parameter of `begin_train_model` is renamed to `training_files_url`
+- `use_labels` parameter of `begin_train_model` is renamed to `use_training_labels`
+- `list_model_infos` method has been renamed to `list_custom_models`
+
 **New features**
 
 - Authentication using `azure-identity` credentials now supported
@@ -18,7 +24,7 @@
 
 ## 1.0.0b1 (2020-04-23)
 
-Version (1.0.0b1) is the first preview of our efforts to create a user-friendly and Pythonic client library for Azure Form Recognizer. 
+Version (1.0.0b1) is the first preview of our efforts to create a user-friendly and Pythonic client library for Azure Form Recognizer.
 This library replaces the package found here: https://pypi.org/project/azure-cognitiveservices-formrecognizer/
 
 For more information about this, and preview releases of other Azure SDK libraries, please visit
@@ -27,7 +33,7 @@ https://azure.github.io/azure-sdk/releases/latest/python.html.
 **Breaking changes: New API design**
 
 - New namespace/package name:
-  - The namespace/package name for the Form Recognizer client library has changed from 
+  - The namespace/package name for the Form Recognizer client library has changed from
     `azure.cognitiveservices.formrecognizer` to `azure.ai.formrecognizer`
 - Two client design:
     - FormRecognizerClient to analyze fields/values on custom forms, receipts, and form content/layout
@@ -38,7 +44,7 @@ https://azure.github.io/azure-sdk/releases/latest/python.html.
 - Asynchronous APIs added under `azure.ai.formrecognizer.aio` namespace
 - Authentication with API key supported using `AzureKeyCredential("<api_key>")` from `azure.core.credentials`
 - New underlying REST pipeline implementation based on the azure-core library
-- Client and pipeline configuration is now available via keyword arguments at both the client level, and per-operation. 
+- Client and pipeline configuration is now available via keyword arguments at both the client level, and per-operation.
     See README for a link to optional configuration arguments
 - New error hierarchy:
     - All service errors will now use the base type: `azure.core.exceptions.HttpResponseError`

sdk/formrecognizer/azure-ai-formrecognizer/README.md

@@ -302,7 +302,7 @@ print("Our account has {} custom models, and we can have at most {} custom model
 ))
 
 # Here we get a paged list of all of our custom models
-custom_models = form_training_client.list_model_infos()
+custom_models = form_training_client.list_custom_models()
 print("We have models with the following ids: {}".format(
     ", ".join([m.model_id for m in custom_models])
 ))

sdk/formrecognizer/azure-ai-formrecognizer/azure/ai/formrecognizer/_form_training_client.py

@@ -77,15 +77,15 @@ def __init__(self, endpoint, credential, **kwargs):
         )
 
     @distributed_trace
-    def begin_train_model(self, training_files, use_labels=False, **kwargs):
+    def begin_train_model(self, training_files_url, use_training_labels=False, **kwargs):
         # type: (str, Optional[bool], Any) -> LROPoller
-        """Create and train a custom model. The request must include a `training_files` parameter that is an
+        """Create and train a custom model. The request must include a `training_files_url` parameter that is an
         externally accessible Azure storage blob container Uri (preferably a Shared Access Signature Uri).
         Models are trained using documents that are of the following content type - 'application/pdf',
         'image/jpeg', 'image/png', 'image/tiff'. Other type of content in the container is ignored.
 
-        :param str training_files: An Azure Storage blob container's SAS URI.
-        :param bool use_labels: Whether to train with labels or not. Corresponding labeled files must
+        :param str training_files_url: An Azure Storage blob container's SAS URI.
+        :param bool use_training_labels: Whether to train with labels or not. Corresponding labeled files must
             exist in the blob container.
         :keyword str prefix: A case-sensitive prefix string to filter documents for training.
             Use `prefix` to filter documents themselves, or to restrict sub folders for training
@@ -114,8 +114,8 @@ def begin_train_model(self, training_files, use_labels=False, **kwargs):
         polling_interval = kwargs.pop("polling_interval", POLLING_INTERVAL)
         response = self._client.train_custom_model_async(  # type: ignore
             train_request=TrainRequest(
-                source=training_files,
-                use_label_file=use_labels,
+                source=training_files_url,
+                use_label_file=use_training_labels,
                 source_filter=TrainSourceFilter(
                     prefix=kwargs.pop("prefix", ""),
                     include_sub_folders=kwargs.pop("include_sub_folders", False),
@@ -166,7 +166,7 @@ def delete_model(self, model_id, **kwargs):
         )
 
     @distributed_trace
-    def list_model_infos(self, **kwargs):
+    def list_custom_models(self, **kwargs):
         # type: (Any) -> Iterable[CustomFormModelInfo]
         """List information for each model, including model id,
         model status, and when it was created and last modified.
@@ -178,8 +178,8 @@ def list_model_infos(self, **kwargs):
         .. admonition:: Example:
 
             .. literalinclude:: ../samples/sample_manage_custom_models.py
-                :start-after: [START list_model_infos]
-                :end-before: [END list_model_infos]
+                :start-after: [START list_custom_models]
+                :end-before: [END list_custom_models]
                 :language: python
                 :dedent: 8
                 :caption: List model information for each model on the account.

sdk/formrecognizer/azure-ai-formrecognizer/azure/ai/formrecognizer/aio/_form_training_client_async.py

@@ -83,17 +83,17 @@ def __init__(
     @distributed_trace_async
     async def train_model(
             self,
-            training_files: str,
-            use_labels: Optional[bool] = False,
+            training_files_url: str,
+            use_training_labels: Optional[bool] = False,
             **kwargs: Any
     ) -> CustomFormModel:
-        """Create and train a custom model. The request must include a `training_files` parameter that is an
+        """Create and train a custom model. The request must include a `training_files_url` parameter that is an
         externally accessible Azure storage blob container Uri (preferably a Shared Access Signature Uri).
         Models are trained using documents that are of the following content type - 'application/pdf',
         'image/jpeg', 'image/png', 'image/tiff'. Other type of content in the container is ignored.
 
-        :param str training_files: An Azure Storage blob container's SAS URI.
-        :param bool use_labels: Whether to train with labels or not. Corresponding labeled files must
+        :param str training_files_url: An Azure Storage blob container's SAS URI.
+        :param bool use_training_labels: Whether to train with labels or not. Corresponding labeled files must
             exist in the blob container.
         :keyword str prefix: A case-sensitive prefix string to filter documents for training.
             Use `prefix` to filter documents themselves, or to restrict sub folders for training
@@ -121,8 +121,8 @@ async def train_model(
         polling_interval = kwargs.pop("polling_interval", POLLING_INTERVAL)
         response = await self._client.train_custom_model_async(
             train_request=TrainRequest(
-                source=training_files,
-                use_label_file=use_labels,
+                source=training_files_url,
+                use_label_file=use_training_labels,
                 source_filter=TrainSourceFilter(
                     prefix=kwargs.pop("prefix", ""),
                     include_sub_folders=kwargs.pop("include_sub_folders", False)
@@ -171,7 +171,7 @@ async def delete_model(self, model_id: str, **kwargs: Any) -> None:
         )
 
     @distributed_trace
-    def list_model_infos(self, **kwargs: Any) -> AsyncIterable[CustomFormModelInfo]:
+    def list_custom_models(self, **kwargs: Any) -> AsyncIterable[CustomFormModelInfo]:
         """List information for each model, including model id,
         model status, and when it was created and last modified.
 
@@ -182,8 +182,8 @@ def list_model_infos(self, **kwargs: Any) -> AsyncIterable[CustomFormModelInfo]:
         .. admonition:: Example:
 
             .. literalinclude:: ../samples/async_samples/sample_manage_custom_models_async.py
-                :start-after: [START list_model_infos_async]
-                :end-before: [END list_model_infos_async]
+                :start-after: [START list_custom_models_async]
+                :end-before: [END list_custom_models_async]
                 :language: python
                 :dedent: 12
                 :caption: List model information for each model on the account.

sdk/formrecognizer/azure-ai-formrecognizer/samples/async_samples/sample_manage_custom_models_async.py

@@ -47,8 +47,8 @@ async def manage_custom_models(self):
             # [END get_account_properties_async]
 
             # Next, we get a paged list of all of our custom models
-            # [START list_model_infos_async]
-            custom_models = form_training_client.list_model_infos()
+            # [START list_custom_models_async]
+            custom_models = form_training_client.list_custom_models()
 
             print("We have models with the following ids:")
 
@@ -58,7 +58,7 @@ async def manage_custom_models(self):
                 print(model.model_id)
                 if not first_model:
                     first_model = model
-            # [END list_model_infos_async]
+            # [END list_custom_models_async]
 
             # Now we'll get the first custom model in the paged list
             # [START get_custom_model_async]

sdk/formrecognizer/azure-ai-formrecognizer/samples/async_samples/sample_train_model_with_labels_async.py

@@ -46,7 +46,7 @@ async def train_model_with_labels(self):
         # [END create_form_training_client_async]
         async with form_training_client:
 
-            model = await form_training_client.train_model(self.container_sas_url, use_labels=True)
+            model = await form_training_client.train_model(self.container_sas_url, use_training_labels=True)
             # Custom model information
             print("Model ID: {}".format(model.model_id))
             print("Status: {}".format(model.status))

sdk/formrecognizer/azure-ai-formrecognizer/samples/async_samples/sample_train_model_without_labels_async.py

@@ -42,7 +42,7 @@ async def train_model_without_labels(self):
             self.endpoint, AzureKeyCredential(self.key)
         ) as form_training_client:
 
-            # Default for train_model is `use_labels=False`
+            # Default for train_model is `use_training_labels=False`
             model = await form_training_client.train_model(self.container_sas_url)
 
             # Custom model information

sdk/formrecognizer/azure-ai-formrecognizer/samples/sample_manage_custom_models.py

@@ -44,8 +44,8 @@ def manage_custom_models(self):
         # [END get_account_properties]
 
         # Next, we get a paged list of all of our custom models
-        # [START list_model_infos]
-        custom_models = form_training_client.list_model_infos()
+        # [START list_custom_models]
+        custom_models = form_training_client.list_custom_models()
 
         print("We have models with the following ids:")
 
@@ -54,7 +54,7 @@ def manage_custom_models(self):
         print(first_model.model_id)
         for model in custom_models:
             print(model.model_id)
-        # [END list_model_infos]
+        # [END list_custom_models]
 
         # Now we'll get the first custom model in the paged list
         # [START get_custom_model]

sdk/formrecognizer/azure-ai-formrecognizer/samples/sample_train_model_with_labels.py

@@ -42,7 +42,7 @@ def train_model_with_labels(self):
         form_training_client = FormTrainingClient(self.endpoint, AzureKeyCredential(self.key))
         # [END create_form_training_client]
 
-        poller = form_training_client.begin_train_model(self.container_sas_url, use_labels=True)
+        poller = form_training_client.begin_train_model(self.container_sas_url, use_training_labels=True)
         model = poller.result()
 
         # Custom model information

sdk/formrecognizer/azure-ai-formrecognizer/samples/sample_train_model_without_labels.py

@@ -39,7 +39,7 @@ def train_model_without_labels(self):
 
         form_training_client = FormTrainingClient(self.endpoint, AzureKeyCredential(self.key))
 
-        # Default for begin_train_model is `use_labels=False`
+        # Default for begin_train_model is `use_training_labels=False`
         poller = form_training_client.begin_train_model(self.container_sas_url)
         model = poller.result()
 

sdk/formrecognizer/azure-ai-formrecognizer/tests/test_custom_forms.py

@@ -128,7 +128,7 @@ def test_custom_form_labeled(self, client, container_sas_url):
 
         poller = training_client.begin_train_model(
             container_sas_url,
-            use_labels=True
+            use_training_labels=True
         )
         model = poller.result()
 
@@ -154,7 +154,7 @@ def test_custom_form_multipage_labeled(self, client, container_sas_url):
 
         poller = training_client.begin_train_model(
             container_sas_url,
-            use_labels=True
+            use_training_labels=True
         )
         model = poller.result()
 
@@ -258,7 +258,7 @@ def callback(raw_response, _, headers):
     def test_custom_form_labeled_transform(self, client, container_sas_url):
         training_client = client.get_form_training_client()
 
-        poller = training_client.begin_train_model(container_sas_url, use_labels=True)
+        poller = training_client.begin_train_model(container_sas_url, use_training_labels=True)
         model = poller.result()
 
         responses = []
@@ -295,7 +295,7 @@ def callback(raw_response, _, headers):
     def test_custom_form_multipage_labeled_transform(self, client, container_sas_url):
         training_client = client.get_form_training_client()
 
-        poller = training_client.begin_train_model(container_sas_url, use_labels=True)
+        poller = training_client.begin_train_model(container_sas_url, use_training_labels=True)
         model = poller.result()
 
         responses = []

sdk/formrecognizer/azure-ai-formrecognizer/tests/test_custom_forms_async.py

@@ -121,7 +121,7 @@ async def test_custom_form_multipage_unlabeled(self, client, container_sas_url):
     async def test_custom_form_labeled(self, client, container_sas_url):
         training_client = client.get_form_training_client()
 
-        model = await training_client.train_model(container_sas_url, use_labels=True)
+        model = await training_client.train_model(container_sas_url, use_training_labels=True)
 
         with open(self.form_jpg, "rb") as fd:
             myfile = fd.read()
@@ -144,7 +144,7 @@ async def test_custom_form_multipage_labeled(self, client, container_sas_url):
 
         model = await training_client.train_model(
             container_sas_url,
-            use_labels=True
+            use_training_labels=True
         )
 
         with open(self.multipage_invoice_pdf, "rb") as fd:
@@ -246,7 +246,7 @@ def callback(raw_response, _, headers):
     async def test_form_labeled_transform(self, client, container_sas_url):
         training_client = client.get_form_training_client()
 
-        model = await training_client.train_model(container_sas_url, use_labels=True)
+        model = await training_client.train_model(container_sas_url, use_training_labels=True)
 
         responses = []
 
@@ -282,7 +282,7 @@ def callback(raw_response, _, headers):
     async def test_custom_forms_multipage_labeled_transform(self, client, container_sas_url):
         training_client = client.get_form_training_client()
 
-        model = await training_client.train_model(container_sas_url, use_labels=True)
+        model = await training_client.train_model(container_sas_url, use_training_labels=True)
 
         responses = []
 

sdk/formrecognizer/azure-ai-formrecognizer/tests/test_custom_forms_from_url.py

@@ -54,7 +54,7 @@ def test_pass_stream_into_url(self, resource_group, location, form_recognizer_ac
     def test_custom_form_bad_url(self, client, container_sas_url):
         training_client = client.get_form_training_client()
 
-        poller = training_client.begin_train_model(container_sas_url, use_labels=True)
+        poller = training_client.begin_train_model(container_sas_url, use_training_labels=True)
         model = poller.result()
 
         with self.assertRaises(HttpResponseError):
@@ -115,7 +115,7 @@ def test_form_multipage_unlabeled(self, client, container_sas_url, blob_sas_url)
     def test_custom_form_labeled(self, client, container_sas_url):
         training_client = client.get_form_training_client()
 
-        poller = training_client.begin_train_model(container_sas_url, use_labels=True)
+        poller = training_client.begin_train_model(container_sas_url, use_training_labels=True)
         model = poller.result()
 
         poller = client.begin_recognize_custom_forms_from_url(model.model_id, self.form_url_jpg)
@@ -137,7 +137,7 @@ def test_form_multipage_labeled(self, client, container_sas_url, blob_sas_url):
 
         poller = training_client.begin_train_model(
             container_sas_url,
-            use_labels=True
+            use_training_labels=True
         )
         model = poller.result()
 
@@ -233,7 +233,7 @@ def callback(raw_response, _, headers):
     def test_form_labeled_transform(self, client, container_sas_url):
         training_client = client.get_form_training_client()
 
-        poller = training_client.begin_train_model(container_sas_url, use_labels=True)
+        poller = training_client.begin_train_model(container_sas_url, use_training_labels=True)
         model = poller.result()
 
         responses = []
@@ -267,7 +267,7 @@ def callback(raw_response, _, headers):
     def test_custom_form_multipage_labeled_transform(self, client, container_sas_url, blob_sas_url):
         training_client = client.get_form_training_client()
 
-        poller = training_client.begin_train_model(container_sas_url, use_labels=True)
+        poller = training_client.begin_train_model(container_sas_url, use_training_labels=True)
         model = poller.result()
 
         responses = []

sdk/formrecognizer/azure-ai-formrecognizer/tests/test_custom_forms_from_url_async.py

@@ -54,7 +54,7 @@ async def test_pass_stream_into_url(self, resource_group, location, form_recogni
     async def test_form_bad_url(self, client, container_sas_url):
         training_client = client.get_form_training_client()
 
-        model = await training_client.train_model(container_sas_url, use_labels=True)
+        model = await training_client.train_model(container_sas_url, use_training_labels=True)
 
         with self.assertRaises(HttpResponseError):
             form = await client.recognize_custom_forms_from_url(
@@ -109,7 +109,7 @@ async def test_custom_form_multipage_unlabeled(self, client, container_sas_url,
     async def test_form_labeled(self, client, container_sas_url):
         training_client = client.get_form_training_client()
 
-        model = await training_client.train_model(container_sas_url, use_labels=True)
+        model = await training_client.train_model(container_sas_url, use_training_labels=True)
 
         form = await client.recognize_custom_forms_from_url(model.model_id, self.form_url_jpg)
 
@@ -129,7 +129,7 @@ async def test_form_multipage_labeled(self, client, container_sas_url, blob_sas_
 
         model = await training_client.train_model(
             container_sas_url,
-            use_labels=True
+            use_training_labels=True
         )
 
         forms = await client.recognize_custom_forms_from_url(
@@ -218,7 +218,7 @@ def callback(raw_response, _, headers):
     async def test_form_labeled_transform(self, client, container_sas_url):
         training_client = client.get_form_training_client()
 
-        model = await training_client.train_model(container_sas_url, use_labels=True)
+        model = await training_client.train_model(container_sas_url, use_training_labels=True)
 
         responses = []
 
@@ -251,7 +251,7 @@ def callback(raw_response, _, headers):
     async def test_multipage_labeled_transform(self, client, container_sas_url, blob_sas_url):
         training_client = client.get_form_training_client()
 
-        model = await training_client.train_model(container_sas_url, use_labels=True)
+        model = await training_client.train_model(container_sas_url, use_training_labels=True)
 
         responses = []