[formrecognizer] regenerates on v2.1 (#18551)

* add v2.1 generation

* some fixes for v2.1

* add note about 3.5 deprecation

* ingest new changes

* adjust code for new field value types and remove the old

* adjustments to tests for changes in models

* update changelog and samples for CountryRegion

* api version compatibility

* add recordings for v2.1

* Exclude recordings from spellcheck

* skip tests for regression in tables bounding box

* review feedback + skip AAD tests since not deployed

Co-authored-by: Daniel Jurek <djurek@microsoft.com>

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

@@ -1,13 +1,18 @@
 # Release History
 
-## 3.1.0b5 (Unreleased)
+## 3.1.0 (Unreleased)
+
+Note: this version will be the last to officially support Python 3.5, future versions will require Python 2.7 or Python 3.6+
 
 **Breaking Changes**
 
-- `begin_recognize_id_documents` renamed to `begin_recognize_identity_documents`
-- `begin_recognize_id_documents_from_url` renamed to `begin_recognize_identity_documents_from_url`
+- `begin_recognize_id_documents` renamed to `begin_recognize_identity_documents`.
+- `begin_recognize_id_documents_from_url` renamed to `begin_recognize_identity_documents_from_url`.
 - The model `TextAppearance` now includes the properties `style_name` and `style_confidence` that were part of the `TextStyle` object.
 - Removed the model `TextStyle`.
+- Removed field value types "gender" and "country" from the `FieldValueType` enum.
+- Added field value type "countryRegion" to the `FieldValueType` enum.
+- Renamed field name for identity documents from "Country" to "CountryRegion".
 
 **New features**
 

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

@@ -24,17 +24,16 @@ from form documents. It includes the following main functionalities:
 Install the Azure Form Recognizer client library for Python with [pip][pip]:
 
 ```bash
-pip install azure-ai-formrecognizer --pre
+pip install azure-ai-formrecognizer
 ```
 
-> Note: This version of the client library defaults to the v2.1-preview.3 version of the service
+> Note: This version of the client library defaults to the v2.1 version of the service
 
 This table shows the relationship between SDK versions and supported API versions of the service
 
 |SDK version|Supported API version of service
 |-|-
-|3.0.0 - Latest GA release (can be installed by removing the `--pre` flag)| 2.0
-|3.1.0b4 - Latest release (beta)| 2.0, 2.1-preview.3
+|3.1.0 - Latest GA release| 2.0, 2.1 (default)
 
 
 #### Create a Form Recognizer resource

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

@@ -10,7 +10,7 @@ class FormRecognizerApiVersion(str, Enum):
     """Form Recognizer API versions supported by this package"""
 
     #: This is the default version
-    V2_1_PREVIEW = "2.1-preview.3"
+    V2_1 = "2.1"
     V2_0 = "2.0"
 
 

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

@@ -21,8 +21,10 @@ def __init__(self, endpoint, credential, **kwargs):
         self._endpoint = endpoint
         self._credential = credential
         self._api_version = kwargs.pop(
-            "api_version", FormRecognizerApiVersion.V2_1_PREVIEW
+            "api_version", FormRecognizerApiVersion.V2_1
         )
+        if self._api_version.startswith("v"):  # v2.0 released with this option
+            self._api_version = self._api_version[1:]
         validate_api_version(self._api_version)
 
         authentication_policy = get_authentication_policy(credential)

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

@@ -100,7 +100,7 @@ def begin_recognize_receipts(self, receipt, **kwargs):
         :rtype: ~azure.core.polling.LROPoller[list[~azure.ai.formrecognizer.RecognizedForm]]
         :raises ~azure.core.exceptions.HttpResponseError:
 
-        .. versionadded:: v2.1-preview
+        .. versionadded:: v2.1
             The *locale* and *pages* keyword arguments and support for image/bmp content
 
         .. admonition:: Example:
@@ -127,20 +127,20 @@ def begin_recognize_receipts(self, receipt, **kwargs):
         # FIXME: part of this code will be removed once autorest can handle diff mixin
         # signatures across API versions
         if locale:
-            if self._api_version == FormRecognizerApiVersion.V2_1_PREVIEW:
+            if self._api_version == FormRecognizerApiVersion.V2_1:
                 kwargs.update({"locale": locale})
             else:
                 raise ValueError(
-                    "'locale' is only available for API version V2_1_PREVIEW and up"
+                    "'locale' is only available for API version V2_1 and up"
                 )
         # FIXME: part of this code will be removed once autorest can handle diff mixin
         # signatures across API versions
         if pages:
-            if self._api_version == FormRecognizerApiVersion.V2_1_PREVIEW:
+            if self._api_version == FormRecognizerApiVersion.V2_1:
                 kwargs.update({"pages": pages})
             else:
                 raise ValueError(
-                    "'pages' is only available for API version V2_1_PREVIEW and up"
+                    "'pages' is only available for API version V2_1 and up"
                 )
         return self._client.begin_analyze_receipt_async(  # type: ignore
             file_stream=receipt,
@@ -178,7 +178,7 @@ def begin_recognize_receipts_from_url(self, receipt_url, **kwargs):
         :rtype: ~azure.core.polling.LROPoller[list[~azure.ai.formrecognizer.RecognizedForm]]
         :raises ~azure.core.exceptions.HttpResponseError:
 
-        .. versionadded:: v2.1-preview
+        .. versionadded:: v2.1
             The *locale* and *pages* keyword arguments and support for image/bmp content
 
         .. admonition:: Example:
@@ -198,20 +198,20 @@ def begin_recognize_receipts_from_url(self, receipt_url, **kwargs):
         # FIXME: part of this code will be removed once autorest can handle diff mixin
         # signatures across API versions
         if locale:
-            if self._api_version == FormRecognizerApiVersion.V2_1_PREVIEW:
+            if self._api_version == FormRecognizerApiVersion.V2_1:
                 kwargs.update({"locale": locale})
             else:
                 raise ValueError(
-                    "'locale' is only available for API version V2_1_PREVIEW and up"
+                    "'locale' is only available for API version V2_1 and up"
                 )
         # FIXME: part of this code will be removed once autorest can handle diff mixin
         # signatures across API versions
         if pages:
-            if self._api_version == FormRecognizerApiVersion.V2_1_PREVIEW:
+            if self._api_version == FormRecognizerApiVersion.V2_1:
                 kwargs.update({"pages": pages})
             else:
                 raise ValueError(
-                    "'pages' is only available for API version V2_1_PREVIEW and up"
+                    "'pages' is only available for API version V2_1 and up"
                 )
         return self._client.begin_analyze_receipt_async(  # type: ignore
             file_stream={"source": receipt_url},
@@ -253,7 +253,7 @@ def begin_recognize_business_cards(self, business_card, **kwargs):
         :rtype: ~azure.core.polling.LROPoller[list[~azure.ai.formrecognizer.RecognizedForm]]
         :raises ~azure.core.exceptions.HttpResponseError:
 
-        .. versionadded:: v2.1-preview
+        .. versionadded:: v2.1
             The *begin_recognize_business_cards* client method
 
         .. admonition:: Example:
@@ -288,7 +288,7 @@ def begin_recognize_business_cards(self, business_card, **kwargs):
         except ValueError as e:
             if "begin_analyze_business_card_async" in str(e):
                 raise ValueError(
-                    "Method 'begin_recognize_business_cards' is only available for API version V2_1_PREVIEW and up"
+                    "Method 'begin_recognize_business_cards' is only available for API version V2_1 and up"
                 )
             raise e
 
@@ -319,7 +319,7 @@ def begin_recognize_business_cards_from_url(self, business_card_url, **kwargs):
         :rtype: ~azure.core.polling.LROPoller[list[~azure.ai.formrecognizer.RecognizedForm]]
         :raises ~azure.core.exceptions.HttpResponseError:
 
-        .. versionadded:: v2.1-preview
+        .. versionadded:: v2.1
             The *begin_recognize_business_cards_from_url* client method
 
         """
@@ -338,7 +338,7 @@ def begin_recognize_business_cards_from_url(self, business_card_url, **kwargs):
             if "begin_analyze_business_card_async" in str(e):
                 raise ValueError(
                     "Method 'begin_recognize_business_cards_from_url' is "
-                    "only available for API version V2_1_PREVIEW and up"
+                    "only available for API version V2_1 and up"
                 )
             raise e
 
@@ -372,7 +372,7 @@ def begin_recognize_identity_documents(self, identity_document, **kwargs):
         :rtype: ~azure.core.polling.LROPoller[list[~azure.ai.formrecognizer.RecognizedForm]]
         :raises ~azure.core.exceptions.HttpResponseError:
 
-        .. versionadded:: v2.1-preview
+        .. versionadded:: v2.1
             The *begin_recognize_identity_documents* client method
 
         .. admonition:: Example:
@@ -406,7 +406,7 @@ def begin_recognize_identity_documents(self, identity_document, **kwargs):
         except ValueError as e:
             if "begin_analyze_id_document_async" in str(e):
                 raise ValueError(
-                    "Method 'begin_recognize_identity_documents' is only available for API version V2_1_PREVIEW and up"
+                    "Method 'begin_recognize_identity_documents' is only available for API version V2_1 and up"
                 )
             raise e
 
@@ -435,7 +435,7 @@ def begin_recognize_identity_documents_from_url(self, identity_document_url, **k
         :rtype: ~azure.core.polling.LROPoller[list[~azure.ai.formrecognizer.RecognizedForm]]
         :raises ~azure.core.exceptions.HttpResponseError:
 
-        .. versionadded:: v2.1-preview
+        .. versionadded:: v2.1
             The *begin_recognize_identity_documents_from_url* client method
         """
 
@@ -453,7 +453,7 @@ def begin_recognize_identity_documents_from_url(self, identity_document_url, **k
             if "begin_analyze_id_document_async" in str(e):
                 raise ValueError(
                     "Method 'begin_recognize_identity_documents_from_url' is "
-                    "only available for API version V2_1_PREVIEW and up"
+                    "only available for API version V2_1 and up"
                 )
             raise e
 
@@ -488,7 +488,7 @@ def begin_recognize_invoices(self, invoice, **kwargs):
         :rtype: ~azure.core.polling.LROPoller[list[~azure.ai.formrecognizer.RecognizedForm]]
         :raises ~azure.core.exceptions.HttpResponseError:
 
-        .. versionadded:: v2.1-preview
+        .. versionadded:: v2.1
             The *begin_recognize_invoices* client method
 
         .. admonition:: Example:
@@ -523,7 +523,7 @@ def begin_recognize_invoices(self, invoice, **kwargs):
         except ValueError as e:
             if "begin_analyze_invoice_async" in str(e):
                 raise ValueError(
-                    "Method 'begin_recognize_invoices' is only available for API version V2_1_PREVIEW and up"
+                    "Method 'begin_recognize_invoices' is only available for API version V2_1 and up"
                 )
             raise e
 
@@ -553,7 +553,7 @@ def begin_recognize_invoices_from_url(self, invoice_url, **kwargs):
         :rtype: ~azure.core.polling.LROPoller[list[~azure.ai.formrecognizer.RecognizedForm]]
         :raises ~azure.core.exceptions.HttpResponseError:
 
-        .. versionadded:: v2.1-preview
+        .. versionadded:: v2.1
             The *begin_recognize_invoices_from_url* client method
         """
 
@@ -571,7 +571,7 @@ def begin_recognize_invoices_from_url(self, invoice_url, **kwargs):
             if "begin_analyze_invoice_async" in str(e):
                 raise ValueError(
                     "Method 'begin_recognize_invoices_from_url' is "
-                    "only available for API version V2_1_PREVIEW and up"
+                    "only available for API version V2_1 and up"
                 )
             raise e
 
@@ -617,7 +617,7 @@ def begin_recognize_content(self, form, **kwargs):
         :rtype: ~azure.core.polling.LROPoller[list[~azure.ai.formrecognizer.FormPage]]
         :raises ~azure.core.exceptions.HttpResponseError:
 
-        .. versionadded:: v2.1-preview
+        .. versionadded:: v2.1
             The *pages*, *language* and *reading_order* keyword arguments and support for image/bmp content
 
         .. admonition:: Example:
@@ -644,27 +644,27 @@ def begin_recognize_content(self, form, **kwargs):
         # FIXME: part of this code will be removed once autorest can handle diff mixin
         # signatures across API versions
         if pages:
-            if self._api_version == FormRecognizerApiVersion.V2_1_PREVIEW:
+            if self._api_version == FormRecognizerApiVersion.V2_1:
                 kwargs.update({"pages": pages})
             else:
                 raise ValueError(
-                    "'pages' is only available for API version V2_1_PREVIEW and up"
+                    "'pages' is only available for API version V2_1 and up"
                 )
 
         if reading_order:
-            if self._api_version == FormRecognizerApiVersion.V2_1_PREVIEW:
+            if self._api_version == FormRecognizerApiVersion.V2_1:
                 kwargs.update({"reading_order": reading_order})
             else:
                 raise ValueError(
-                    "'reading_order' is only available for API version V2_1_PREVIEW and up"
+                    "'reading_order' is only available for API version V2_1 and up"
                 )
 
         if language:
-            if self._api_version == FormRecognizerApiVersion.V2_1_PREVIEW:
+            if self._api_version == FormRecognizerApiVersion.V2_1:
                 kwargs.update({"language": language})
             else:
                 raise ValueError(
-                    "'language' is only available for API version V2_1_PREVIEW and up"
+                    "'language' is only available for API version V2_1 and up"
                 )
 
         return self._client.begin_analyze_layout_async(  # type: ignore
@@ -704,7 +704,7 @@ def begin_recognize_content_from_url(self, form_url, **kwargs):
         :rtype: ~azure.core.polling.LROPoller[list[~azure.ai.formrecognizer.FormPage]]
         :raises ~azure.core.exceptions.HttpResponseError:
 
-        .. versionadded:: v2.1-preview
+        .. versionadded:: v2.1
             The *pages*, *language* and *reading_order* keyword arguments and support for image/bmp content
         """
         pages = kwargs.pop("pages", None)
@@ -714,27 +714,27 @@ def begin_recognize_content_from_url(self, form_url, **kwargs):
         # FIXME: part of this code will be removed once autorest can handle diff mixin
         # signatures across API versions
         if pages:
-            if self._api_version == FormRecognizerApiVersion.V2_1_PREVIEW:
+            if self._api_version == FormRecognizerApiVersion.V2_1:
                 kwargs.update({"pages": pages})
             else:
                 raise ValueError(
-                    "'pages' is only available for API version V2_1_PREVIEW and up"
+                    "'pages' is only available for API version V2_1 and up"
                 )
 
         if reading_order:
-            if self._api_version == FormRecognizerApiVersion.V2_1_PREVIEW:
+            if self._api_version == FormRecognizerApiVersion.V2_1:
                 kwargs.update({"reading_order": reading_order})
             else:
                 raise ValueError(
-                    "'reading_order' is only available for API version V2_1_PREVIEW and up"
+                    "'reading_order' is only available for API version V2_1 and up"
                 )
 
         if language:
-            if self._api_version == FormRecognizerApiVersion.V2_1_PREVIEW:
+            if self._api_version == FormRecognizerApiVersion.V2_1:
                 kwargs.update({"language": language})
             else:
                 raise ValueError(
-                    "'language' is only available for API version V2_1_PREVIEW and up"
+                    "'language' is only available for API version V2_1 and up"
                 )
 
         return self._client.begin_analyze_layout_async(  # type: ignore
@@ -817,11 +817,11 @@ def analyze_callback(
         # FIXME: part of this code will be removed once autorest can handle diff mixin
         # signatures across API versions
         if pages:
-            if self._api_version == FormRecognizerApiVersion.V2_1_PREVIEW:
+            if self._api_version == FormRecognizerApiVersion.V2_1:
                 kwargs.update({"pages": pages})
             else:
                 raise ValueError(
-                    "'pages' is only available for API version V2_1_PREVIEW and up"
+                    "'pages' is only available for API version V2_1 and up"
                 )
 
         return self._client.begin_analyze_with_custom_model(  # type: ignore
@@ -886,11 +886,11 @@ def analyze_callback(
         # FIXME: part of this code will be removed once autorest can handle diff mixin
         # signatures across API versions
         if pages:
-            if self._api_version == FormRecognizerApiVersion.V2_1_PREVIEW:
+            if self._api_version == FormRecognizerApiVersion.V2_1:
                 kwargs.update({"pages": pages})
             else:
                 raise ValueError(
-                    "'pages' is only available for API version V2_1_PREVIEW and up"
+                    "'pages' is only available for API version V2_1 and up"
                 )
 
         return self._client.begin_analyze_with_custom_model(  # type: ignore

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

@@ -110,7 +110,7 @@ def begin_training(self, training_files_url, use_training_labels, **kwargs):
             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()`
 
-        .. versionadded:: v2.1-preview
+        .. versionadded:: v2.1
             The *model_name* keyword argument
 
         .. admonition:: Example:
@@ -135,7 +135,7 @@ def callback_v2_1(raw_response, _, headers):  # pylint: disable=unused-argument
         model_name = kwargs.pop("model_name", None)
         if model_name and self._api_version == "2.0":
             raise ValueError(
-                "'model_name' is only available for API version V2_1_PREVIEW and up"
+                "'model_name' is only available for API version V2_1 and up"
             )
         continuation_token = kwargs.pop("continuation_token", None)
         polling_interval = kwargs.pop(
@@ -454,7 +454,7 @@ def begin_create_composed_model(self, model_ids, **kwargs):
         :rtype: ~azure.core.polling.LROPoller[~azure.ai.formrecognizer.CustomFormModel]
         :raises ~azure.core.exceptions.HttpResponseError:
 
-        .. versionadded:: v2.1-preview
+        .. versionadded:: v2.1
             The *begin_create_composed_model* client method
 
         .. admonition:: Example:
@@ -492,7 +492,7 @@ def _compose_callback(
             )
         except ValueError:
             raise ValueError(
-                "Method 'begin_create_composed_model' is only available for API version V2_1_PREVIEW and up"
+                "Method 'begin_create_composed_model' is only available for API version V2_1 and up"
             )
 
     def get_form_recognizer_client(self, **kwargs):