[formrecognizer] consistency on handling LRO's with failed status (#11445)

* samples handle invalid models from training

* update to throw exception on training methods that return invalid model

* update tests now that we treat invalid status differently

* pass response to error

Author: kristapratico

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

@@ -9,6 +9,7 @@
 - `list_model_infos` method has been renamed to `list_custom_models`
 - Removed `get_form_training_client` from `FormRecognizerClient`
 - Added `get_form_recognizer_client` to `FormTrainingClient`
+- A `HttpResponseError` is now raised if a model with `status=="invalid"` is returned from the `begin_train_model()` or `train_model()` methods
 
 **New features**
 

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

@@ -101,6 +101,8 @@ def begin_train_model(self, training_files_url, use_training_labels=False, **kwa
             object to return a :class:`~azure.ai.formrecognizer.CustomFormModel`.
         :rtype: ~azure.core.polling.LROPoller[~azure.ai.formrecognizer.CustomFormModel]
         :raises ~azure.core.exceptions.HttpResponseError:
+            Note that if the training fails, the exception is raised, but a model with an
+            "invalid" status is still created. You can delete this model by calling :func:`~delete_model()`
 
         .. admonition:: Example:
 

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

@@ -17,6 +17,12 @@
     from azure.core.pipeline import PipelineResponse
 
 
+def raise_error(response, errors, message):
+    for err in errors:
+        message += "({}) {}\n".format(err["code"], err["message"])
+    raise HttpResponseError(message=message, response=response)
+
+
 class TrainingPolling(LocationPolling):
     """Polling method overrides for training endpoints.
     """
@@ -40,6 +46,14 @@ def get_status(self, pipeline_response):  # pylint: disable=no-self-use
             status = body['modelInfo']['status']
             if not status:
                 raise BadResponse("No status found in body")
+            if status.lower() == "invalid":
+                train_result = body.get('trainResult')
+                if train_result:
+                    errors = train_result.get("errors")
+                    if errors:
+                        message = "Invalid model created with ID={}\n".format(body["modelInfo"]["modelId"])
+                        raise_error(response, errors, message)
+                return "Failed"
             if status.lower() != "creating":
                 return "Succeeded"
 
@@ -50,8 +64,6 @@ def get_status(self, pipeline_response):  # pylint: disable=no-self-use
 
 class AnalyzePolling(OperationResourcePolling):
     """Polling method overrides for custom analyze endpoints.
-
-    :param str operation_location_header: Name of the header to return operation format (default 'operation-location')
     """
 
     def get_status(self, pipeline_response):  # pylint: disable=no-self-use
@@ -78,8 +90,5 @@ def get_status(self, pipeline_response):  # pylint: disable=no-self-use
             if analyze_result:
                 errors = analyze_result.get("errors")
                 if errors:
-                    message = ""
-                    for err in errors:
-                        message += "({}) {}\n".format(err.get("code"), err.get("message"))
-                    raise HttpResponseError(message)
+                    raise_error(response, errors, message="")
         return status

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

@@ -109,6 +109,8 @@ async def train_model(
         :return: CustomFormModel
         :rtype: ~azure.ai.formrecognizer.CustomFormModel
         :raises ~azure.core.exceptions.HttpResponseError:
+            Note that if the training fails, the exception is raised, but a model with an
+            "invalid" status is still created. You can delete this model by calling :func:`~delete_model()`
 
         .. admonition:: Example:
 

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

@@ -41,16 +41,14 @@ async def get_bounding_boxes(self):
         # the sample forms are located in this file's parent's parent's files.
         path_to_sample_forms = Path(__file__).parent.parent.absolute() / Path("sample_forms/forms/Form_1.jpg")
         from azure.ai.formrecognizer import FormWord, FormLine
-        # [START create_form_recognizer_client_async]
         from azure.core.credentials import AzureKeyCredential
         from azure.ai.formrecognizer.aio import FormRecognizerClient
 
         form_recognizer_client = FormRecognizerClient(
             endpoint=self.endpoint, credential=AzureKeyCredential(self.key)
         )
-        # [END create_form_recognizer_client_async]
-        async with form_recognizer_client:
 
+        async with form_recognizer_client:
             # Make sure your form's type is included in the list of form types the custom model can recognize
             with open(path_to_sample_forms, "rb") as f:
                 forms = await form_recognizer_client.recognize_custom_forms(

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

@@ -36,17 +36,16 @@ class TrainModelWithLabelsSampleAsync(object):
     container_sas_url = os.environ["CONTAINER_SAS_URL"]
 
     async def train_model_with_labels(self):
-        # [START create_form_training_client_async]
         from azure.ai.formrecognizer.aio import FormTrainingClient
         from azure.core.credentials import AzureKeyCredential
 
         form_training_client = FormTrainingClient(
             endpoint=self.endpoint, credential=AzureKeyCredential(self.key)
         )
-        # [END create_form_training_client_async]
-        async with form_training_client:
 
+        async with form_training_client:
             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/sample_get_bounding_boxes.py

@@ -37,13 +37,11 @@ class GetBoundingBoxesSample(object):
 
     def get_bounding_boxes(self):
         from azure.ai.formrecognizer import FormWord, FormLine
-        # [START create_form_recognizer_client]
         from azure.core.credentials import AzureKeyCredential
         from azure.ai.formrecognizer import FormRecognizerClient
         form_recognizer_client = FormRecognizerClient(
             endpoint=self.endpoint, credential=AzureKeyCredential(self.key)
         )
-        # [END create_form_recognizer_client]
 
         # Make sure your form's type is included in the list of form types the custom model can recognize
         with open("sample_forms/forms/Form_1.jpg", "rb") as f:

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

@@ -35,12 +35,10 @@ class TrainModelWithLabelsSample(object):
     container_sas_url = os.environ["CONTAINER_SAS_URL"]
 
     def train_model_with_labels(self):
-        # [START create_form_training_client]
         from azure.ai.formrecognizer import FormTrainingClient
         from azure.core.credentials import AzureKeyCredential
 
         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_training_labels=True)
         model = poller.result()

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

@@ -6,7 +6,7 @@
 
 import functools
 from azure.core.credentials import AzureKeyCredential
-from azure.core.exceptions import ClientAuthenticationError
+from azure.core.exceptions import ClientAuthenticationError, HttpResponseError
 from azure.ai.formrecognizer._generated.models import Model
 from azure.ai.formrecognizer._models import CustomFormModel
 from azure.ai.formrecognizer import FormTrainingClient
@@ -209,6 +209,6 @@ def test_training_with_files_filter(self, client, container_sas_url):
         self.assertEqual(len(model.training_documents), 1)
         self.assertEqual(model.training_documents[0].document_name, "subfolder/Form_6.jpg")  # we filtered for only subfolders
 
-        poller = client.begin_train_model(training_files_url=container_sas_url, prefix="xxx")
-        model = poller.result()
-        self.assertEqual(model.status, "invalid")  # prefix doesn't include any files so training fails
+        with self.assertRaises(HttpResponseError):
+            poller = client.begin_train_model(training_files_url=container_sas_url, prefix="xxx")
+            model = poller.result()

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

@@ -6,7 +6,7 @@
 
 import functools
 from azure.core.credentials import AzureKeyCredential
-from azure.core.exceptions import ClientAuthenticationError
+from azure.core.exceptions import ClientAuthenticationError, HttpResponseError
 from azure.ai.formrecognizer._generated.models import Model
 from azure.ai.formrecognizer._models import CustomFormModel
 from azure.ai.formrecognizer.aio import FormTrainingClient
@@ -197,5 +197,5 @@ async def test_training_with_files_filter(self, client, container_sas_url):
         self.assertEqual(len(model.training_documents), 1)
         self.assertEqual(model.training_documents[0].document_name, "subfolder/Form_6.jpg")  # we filtered for only subfolders
 
-        model = await client.train_model(training_files_url=container_sas_url, prefix="xxx")
-        self.assertEqual(model.status, "invalid")  # prefix doesn't include any files so training fails
+        with self.assertRaises(HttpResponseError):
+            model = await client.train_model(training_files_url=container_sas_url, prefix="xxx")