[formrecognizer] GA work (Azure#25809)

* [formrecognizer] Preview cleanup (Azure#25711)

* remove preview refs in samples

* remove preview refs in migration guide and readme

* [formrecognizer] Regenerate with new swagger (Azure#25710)

* regenerate with new swagger

* update versions and refs to GA version

* fix import

* fix dmac tests

* update api version refs

* update swagger readme

* update dmac operations, tests, & recordings

* add copy recordings

* remove kind from DocumentPage

* update generated models and operations refs

* update DAC prebuilt tests

* update dac custom model recordings

* update general document recordings

* update layout recordings

* update prebuilt read recordings

* update prebuilts recordings

* update dmac mgmt recordings

* update dmac operation refs

* update get children recordings

* regenerate with latest swagger

* update dmac training recordings

* dac from url method, check url is str

* enable bad endpoint tests

* pylint and changelog updates

* shorten dmac lines

* api version changelog entry

* regenerate with python 3 only

* update swagger readme

* added autorest.python version used to regenerate in example command

Author: catalinaperalta

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

@@ -5,6 +5,8 @@
 ### Features Added
 
 ### Breaking Changes
+- This library will default to service API version `2022-08-31` going forward.
+- Removed `kind` property on `DocumentPage`.
 
 ### Bugs Fixed
 

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

@@ -1,8 +1,8 @@
 # Guide for migrating azure-ai-formrecognizer to version 3.2.x from versions 3.1.x and below
 
-This guide is intended to assist in the migration to `azure-ai-formrecognizer (3.2.x)` from versions `3.1.x` and below. It will focus on side-by-side comparisons for similar operations between versions. Please note that version `3.2.0b6` will be used for comparison with `3.1.2`. 
+This guide is intended to assist in the migration to `azure-ai-formrecognizer (3.2.x)` from versions `3.1.x` and below. It will focus on side-by-side comparisons for similar operations between versions. Please note that version `3.2.0` will be used for comparison with `3.1.2`. 
 
-> NOTE: Please read the [CHANGELOG][changelog] to see important changes that have occurred since version `3.2.0b6` of the SDK.
+> NOTE: Please read the [CHANGELOG][changelog] to see important changes that have occurred since version `3.2.0` of the SDK.
 
 Familiarity with `azure-ai-formrecognizer (3.1.x and below)` package is assumed. For those new to the Azure Form Recognizer client library for Python please refer to the [README][readme] rather than this guide.
 
@@ -21,7 +21,7 @@ Familiarity with `azure-ai-formrecognizer (3.1.x and below)` package is assumed.
 
 A natural question to ask when considering whether to adopt a new version of the library is what the benefits of doing so would be. As Azure Form Recognizer has matured and been embraced by a more diverse group of developers, we have been focused on learning the patterns and practices to best support developer productivity and add value to our customers.
 
-There are many benefits to using the new design of the `azure-ai-formrecognizer (3.2.x)` library. This new version of the library introduces two new clients `DocumentAnalysisClient` and the `DocumentModelAdministrationClient` with unified methods for analyzing documents and provides support for the new features added by the service in API version `2022-06-30-preview` and later.
+There are many benefits to using the new design of the `azure-ai-formrecognizer (3.2.x)` library. This new version of the library introduces two new clients `DocumentAnalysisClient` and the `DocumentModelAdministrationClient` with unified methods for analyzing documents and provides support for the new features added by the service in API version `2022-08-31` and later.
 
 New features provided by the `DocumentAnalysisClient` include:
 - One consolidated method for analyzing document layout, a prebuilt general document model type, a prebuilt read model to get text detection and detected languages, along with more new prebuilt models that can be seen [here][fr-models].
@@ -40,7 +40,7 @@ The table below describes the relationship of each client and its supported API
 
 |API version|Supported clients
 |-|-
-|2022-06-30-preview | DocumentAnalysisClient and DocumentModelAdministrationClient
+|2022-08-31 | DocumentAnalysisClient and DocumentModelAdministrationClient
 |2.1 | FormRecognizerClient and FormTrainingClient
 |2.0 | FormRecognizerClient and FormTrainingClient
 
@@ -61,7 +61,7 @@ Some terminology has changed to reflect the enhanced capabilities of the newest
 
 We continue to support API key and AAD authentication methods when creating the clients. Below are the differences between the two versions:
 
-- In `3.2.x`, we have added `DocumentAnalysisClient` and `DocumentModelAdministrationClient` which support API version `2022-06-30-preview` and later.
+- In `3.2.x`, we have added `DocumentAnalysisClient` and `DocumentModelAdministrationClient` which support API version `2022-08-31` and later.
 - `FormRecognizerClient` and `FormTrainingClient` will continue to work targeting API versions `2.1` and `2.0`.
 - In `DocumentAnalysisClient` all prebuilt model methods along with custom model, layout, and a prebuilt general document analysis model are unified into two methods called
 `begin_analyze_document` and `begin_analyze_document_from_url`.
@@ -109,7 +109,7 @@ Differences between the versions:
 - In the new version of the library, the functionality of `begin_recognize_content` has been added as a prebuilt model and can be called in library version `azure-ai-formrecognizer (3.2.x)` with `begin_analyze_document` by passing in the `prebuilt-layout` model ID. Similarly, to get general document information, such as key-value pairs and text layout, the `prebuilt-document` model ID can be used with `begin_analyze_document`. Additionally, passing in the `prebuilt-read` model was added to read information about pages and detected languages.
 - When calling `begin_analyze_document` and `begin_analyze_document_from_url` the returned type is an `AnalyzeResult` object, while the various methods used with `FormRecognizerClient` return a list of `RecognizedForm`.
 - The `pages` keyword argument is a string with library version `azure-ai-formrecognizer (3.2.x)`. In `azure-ai-formrecognizer (3.1.x)`, `pages` was a list of strings.
-- The `include_field_elements` keyword argument is not supported with the `DocumentAnalysisClient`, text details are automatically included with API version `2022-06-30-preview` and later.
+- The `include_field_elements` keyword argument is not supported with the `DocumentAnalysisClient`, text details are automatically included with API version `2022-08-31` and later.
 - The `reading_order` keyword argument does not exist on `begin_analyze_document` and `begin_analyze_document_from_url`. The service uses `natural` reading order to return data.
 
 Analyzing prebuilt models like business cards, identity documents, invoices, and receipts with `3.1.x`:
@@ -480,7 +480,7 @@ print("----------------------------------------")
 Differences between the versions:
 - Analyzing a custom model with `DocumentAnalysisClient` uses the general `begin_analyze_document` and `begin_analyze_document_from_url` methods.
 - In order to analyze a custom model with `FormRecognizerClient` the `begin_recognize_custom_models` and its corresponding URL methods are used.
-- The `include_field_elements` keyword argument is not supported with the `DocumentAnalysisClient`, text details are automatically included with API version `2022-06-30-preview` and later.
+- The `include_field_elements` keyword argument is not supported with the `DocumentAnalysisClient`, text details are automatically included with API version `2022-08-31` and later.
 
 Analyze custom document with `3.1.x`:
 ```python
@@ -654,7 +654,7 @@ for name, doc_type in model.doc_types.items():
 ### Managing models
 
 Differences between the versions:
-- When using API version `2022-06-30-preview` and later models no longer include submodels, instead a model can analyze different document types.
+- When using API version `2022-08-31` and later models no longer include submodels, instead a model can analyze different document types.
 - When building, composing, or copying models users can now assign their own model IDs and specify a description.
 - In version `3.2.x` of the library, only models that build successfully can be retrieved from the get and list model calls. Unsuccessful model operations can be viewed with the get and list operation methods (note that document model operation data persists for only 24 hours). In version `3.1.x` of the library, models that had not succeeded were still created, had to be deleted by the user, and were returned in the list models response.
 

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

@@ -28,14 +28,14 @@ Install the Azure Form Recognizer client library for Python with [pip][pip]:
 pip install azure-ai-formrecognizer --pre
 ```
 
-> Note: This version of the client library defaults to the `2022-06-30-preview` version of the service.
+> Note: This version of the client library defaults to the `2022-08-31` 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.2.0b6 - Latest beta release | 2.0, 2.1, 2022-06-30-preview
-|3.1.X - Latest GA release| 2.0, 2.1 (default)
+|3.2.0 - Latest GA release | 2.0, 2.1, 2022-08-31
+|3.1.X| 2.0, 2.1 (default)
 |3.0.0| 2.0
 
 > Note: Starting with version `3.2.X`, a new set of clients were introduced to leverage the newest features
@@ -45,7 +45,7 @@ This table shows the relationship between SDK versions and supported API version
 
 |API version|Supported clients
 |-|-
-|2022-06-30-preview | DocumentAnalysisClient and DocumentModelAdministrationClient
+|2022-08-31 | DocumentAnalysisClient and DocumentModelAdministrationClient
 |2.1 | FormRecognizerClient and FormTrainingClient
 |2.0 | FormRecognizerClient and FormTrainingClient
 

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

@@ -11,7 +11,7 @@ class DocumentAnalysisApiVersion(str, Enum, metaclass=CaseInsensitiveEnumMeta):
     """Form Recognizer API versions supported by DocumentAnalysisClient and DocumentModelAdministrationClient."""
 
     #: This is the default version
-    V2022_06_30_PREVIEW = "2022-06-30-preview"
+    V2022_08_31 = "2022-08-31"
 
 
 class FormRecognizerApiVersion(str, Enum, metaclass=CaseInsensitiveEnumMeta):

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

@@ -58,7 +58,7 @@ class DocumentAnalysisClient(FormRecognizerClientBase):
     """
 
     def __init__(self, endpoint: str, credential: Union[AzureKeyCredential, TokenCredential], **kwargs: Any) -> None:
-        api_version = kwargs.pop("api_version", DocumentAnalysisApiVersion.V2022_06_30_PREVIEW)
+        api_version = kwargs.pop("api_version", DocumentAnalysisApiVersion.V2022_08_31)
         super().__init__(
             endpoint=endpoint, credential=credential, api_version=api_version, client_kind="document", **kwargs
         )
@@ -157,6 +157,11 @@ def begin_analyze_document_from_url(
         if not model_id:
             raise ValueError("model_id cannot be None or empty.")
 
+        if not isinstance(document_url, str):
+            raise ValueError(
+                "'document_url' needs to be of type 'str'."
+                "Please see `begin_analyze_document()` to pass a byte stream.")
+
         cls = kwargs.pop("cls", self._analyze_document_callback)
         continuation_token = kwargs.pop("continuation_token", None)
 

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

@@ -80,7 +80,7 @@ class DocumentModelAdministrationClient(FormRecognizerClientBase):
     """
 
     def __init__(self, endpoint: str, credential: Union[AzureKeyCredential, TokenCredential], **kwargs: Any) -> None:
-        api_version = kwargs.pop("api_version", DocumentAnalysisApiVersion.V2022_06_30_PREVIEW)
+        api_version = kwargs.pop("api_version", DocumentAnalysisApiVersion.V2022_08_31)
         super().__init__(
             endpoint=endpoint, credential=credential, api_version=api_version, client_kind="document", **kwargs
         )
@@ -131,8 +131,8 @@ def begin_build_model(
         """
 
         def callback(raw_response, _, headers):  # pylint: disable=unused-argument
-            op_response = self._deserialize(self._generated_models.GetOperationResponse, raw_response)
-            model_info = self._deserialize(self._generated_models.ModelInfo, op_response.result)
+            op_response = self._deserialize(self._generated_models.DocumentModelBuildOperationDetails, raw_response)
+            model_info = self._deserialize(self._generated_models.DocumentModelDetails, op_response.result)
             return DocumentModelDetails._from_generated(model_info)
 
         description = kwargs.pop("description", None)
@@ -199,8 +199,8 @@ def begin_compose_model(
         """
 
         def _compose_callback(raw_response, _, headers):  # pylint: disable=unused-argument
-            op_response = self._deserialize(self._generated_models.GetOperationResponse, raw_response)
-            model_info = self._deserialize(self._generated_models.ModelInfo, op_response.result)
+            op_response = self._deserialize(self._generated_models.DocumentModelComposeOperationDetails, raw_response)
+            model_info = self._deserialize(self._generated_models.DocumentModelDetails, op_response.result)
             return DocumentModelDetails._from_generated(model_info)
 
         model_id = kwargs.pop("model_id", None)
@@ -218,7 +218,8 @@ def _compose_callback(raw_response, _, headers):  # pylint: disable=unused-argum
                 description=description,
                 tags=tags,
                 component_models=[
-                    self._generated_models.ComponentModelInfo(model_id=model_id) for model_id in component_model_ids
+                    self._generated_models.ComponentDocumentModelDetails(model_id=model_id)
+                    for model_id in component_model_ids
                 ]
                 if component_model_ids
                 else [],
@@ -298,8 +299,8 @@ def begin_copy_model_to(
         """
 
         def _copy_callback(raw_response, _, headers):  # pylint: disable=unused-argument
-            op_response = self._deserialize(self._generated_models.GetOperationResponse, raw_response)
-            model_info = self._deserialize(self._generated_models.ModelInfo, op_response.result)
+            op_response = self._deserialize(self._generated_models.DocumentModelCopyToOperationDetails, raw_response)
+            model_info = self._deserialize(self._generated_models.DocumentModelDetails, op_response.result)
             return DocumentModelDetails._from_generated(model_info)
 
         if not model_id:
@@ -350,7 +351,7 @@ def delete_model(self, model_id: str, **kwargs: Any) -> None:
         if not model_id:
             raise ValueError("model_id cannot be None or empty.")
 
-        return self._client.delete_model(model_id=model_id, **kwargs)
+        return self._client.delete_document_model(model_id=model_id, **kwargs)
 
     @distributed_trace
     def list_models(self, **kwargs: Any) -> ItemPaged[DocumentModelSummary]:
@@ -371,7 +372,7 @@ def list_models(self, **kwargs: Any) -> ItemPaged[DocumentModelSummary]:
                 :caption: List all models that were built successfully under the Form Recognizer resource.
         """
 
-        return self._client.get_models(  # type: ignore
+        return self._client.get_document_models(  # type: ignore
             cls=kwargs.pop(
                 "cls",
                 lambda objs: [DocumentModelSummary._from_generated(x) for x in objs],
@@ -397,7 +398,7 @@ def get_resource_details(self, **kwargs: Any) -> ResourceDetails:
                 :caption: Get model counts and limits under the Form Recognizer resource.
         """
 
-        response = self._client.get_info(**kwargs)
+        response = self._client.get_resource_details(**kwargs)
         return ResourceDetails._from_generated(response.custom_document_models)
 
     @distributed_trace
@@ -422,7 +423,7 @@ def get_model(self, model_id: str, **kwargs: Any) -> DocumentModelDetails:
         if not model_id:
             raise ValueError("model_id cannot be None or empty.")
 
-        response = self._client.get_model(model_id=model_id, **kwargs)
+        response = self._client.get_document_model(model_id=model_id, **kwargs)
         return DocumentModelDetails._from_generated(response)
 
     @distributed_trace

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

@@ -60,18 +60,18 @@ class FormRecognizerClient(FormRecognizerClientOperationsMixin, MultiApiClientMi
     LATEST_PROFILE = ProfileDefinition({
         _PROFILE_TAG: {
             None: DEFAULT_API_VERSION,
-            'authorize_copy_document_model': '2022-06-30-preview',
-            'begin_analyze_document': '2022-06-30-preview',
-            'begin_build_document_model': '2022-06-30-preview',
-            'begin_compose_document_model': '2022-06-30-preview',
-            'begin_copy_document_model_to': '2022-06-30-preview',
-            'delete_model': '2022-06-30-preview',
-            'get_analyze_document_result': '2022-06-30-preview',
-            'get_info': '2022-06-30-preview',
-            'get_model': '2022-06-30-preview',
-            'get_models': '2022-06-30-preview',
-            'get_operation': '2022-06-30-preview',
-            'get_operations': '2022-06-30-preview',
+            'authorize_copy_document_model': '2022-08-31',
+            'begin_analyze_document': '2022-08-31',
+            'begin_build_document_model': '2022-08-31',
+            'begin_compose_document_model': '2022-08-31',
+            'begin_copy_document_model_to': '2022-08-31',
+            'delete_document_model': '2022-08-31',
+            'get_analyze_document_result': '2022-08-31',
+            'get_document_model': '2022-08-31',
+            'get_document_models': '2022-08-31',
+            'get_operation': '2022-08-31',
+            'get_operations': '2022-08-31',
+            'get_resource_details': '2022-08-31',
             'train_custom_model_async': '2.0',
         }},
         _PROFILE_TAG + " latest"
@@ -85,7 +85,7 @@ def __init__(
         profile=KnownProfiles.default, # type: KnownProfiles
         **kwargs  # type: Any
     ):
-        if api_version == '2022-06-30-preview':
+        if api_version == '2022-08-31':
             base_url = '{endpoint}/formrecognizer'
         elif api_version == '2.0':
             base_url = '{endpoint}/formrecognizer/v2.0'
@@ -108,12 +108,12 @@ def _models_dict(cls, api_version):
     def models(cls, api_version=DEFAULT_API_VERSION):
         """Module depends on the API version:
 
-           * 2022-06-30-preview: :mod:`v2022_06_30_preview.models<azure.ai.formrecognizer.v2022_06_30_preview.models>`
+           * 2022-08-31: :mod:`v2022_08_31.models<azure.ai.formrecognizer.v2022_08_31.models>`
            * 2.0: :mod:`v2_0.models<azure.ai.formrecognizer.v2_0.models>`
            * 2.1: :mod:`v2_1.models<azure.ai.formrecognizer.v2_1.models>`
         """
-        if api_version == '2022-06-30-preview':
-            from .v2022_06_30_preview import models
+        if api_version == '2022-08-31':
+            from .v2022_08_31 import models
             return models
         elif api_version == '2.0':
             from .v2_0 import models