[formrecognizer] GA docs updates (#31464)

* readme updates

* fix dict typing in docstrings

* fix client docs

* fix DocumentPage typing

* fix typing according to swagger check

* fix dac docs

* fix type for doc_types

* revert typing updates on barcodes and formulas

* fix README wording

* update changelog

* revert typing changes

* update changelog

* typing corrections

* changelog update

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

@@ -1,11 +1,9 @@
 # Release History
 
-## 3.3.0 (Unreleased)
+## 3.3.0 (2023-08-08)
 
 This version of the client library defaults to the service API version `2023-07-31`.
 
-### Features Added
-
 ### Breaking Changes
  > Note: The following changes are only breaking from the previous beta. They are not breaking against previous stable versions.
  
@@ -21,11 +19,11 @@ This version of the client library defaults to the service API version `2023-07-
 - Renamed `custom_neural_document_model_builds` property to `neural_document_model_quota` on `ResourceDetails` model.
 - Renamed `AzureBlobSource` model to `BlobSource`.
 - Renamed `AzureBlobFileListSource` model to `BlobFileListSource`.
-
-### Bugs Fixed
+- Marked `neural_document_model_quota` as optional on `ResourceDetails`.
 
 ### Other Changes
-
+- Corrected typing for the `polygon` property on `DocumentWord`, `DocumentSelectionMark`, `DocumentLine`.
+- Corrected typing for `words`, `lines`, and `selection_marks` properties on `DocumentPage`.
 
 ## 3.3.0b1 (2023-04-13)
 

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

@@ -1,10 +1,10 @@
 # Azure Form Recognizer client library for Python
 
-Azure Form Recognizer is a cloud service that uses machine learning to analyze text and structured data from your documents. It includes the following main features:
+Azure Document Intelligence (previously Form Recognizer) is a cloud service that uses machine learning to analyze text and structured data from your documents. It includes the following main features:
 
 - Layout - Extract content and structure (ex. words, selection marks, tables) from documents.
 - Document - Analyze key-value pairs in addition to general layout from documents.
-- Read - Read page information and detected languages from documents.
+- Read - Read page information from documents.
 - Prebuilt - Extract common field values from select document types (ex. receipts, invoices, business cards, ID documents, U.S. W-2 tax documents, among others) using prebuilt models.
 - Custom - Build custom models from your own data to extract tailored field values in addition to general layout from documents.
 - Classifiers - Build custom classification models that combine layout and language features to accurately detect and identify documents you process within your application.
@@ -45,7 +45,7 @@ This table shows the relationship between SDK versions and supported API version
 |3.0.0| 2.0
 
 > Note: Starting with version `3.2.X`, a new set of clients were introduced to leverage the newest features
-> of the Form Recognizer service. Please see the [Migration Guide][migration-guide] for detailed instructions on how to update application
+> of the Document Intelligence service. Please see the [Migration Guide][migration-guide] for detailed instructions on how to update application
 > code from client library version `3.1.X` or lower to the latest version. Additionally, see the [Changelog][changelog] for more detailed information.
 > The below table describes the relationship of each client and its supported API version(s):
 
@@ -58,7 +58,7 @@ This table shows the relationship between SDK versions and supported API version
 
 #### Create a Cognitive Services or Form Recognizer resource
 
-Form Recognizer supports both [multi-service and single-service access][cognitive_resource_portal]. Create a Cognitive Services resource if you plan to access multiple cognitive services under a single endpoint/key. For Form Recognizer access only, create a Form Recognizer resource. Please note that you will need a single-service resource if you intend to use [Azure Active Directory authentication](#create-the-client-with-an-azure-active-directory-credential).
+Document Intelligence supports both [multi-service and single-service access][cognitive_resource_portal]. Create a Cognitive Services resource if you plan to access multiple cognitive services under a single endpoint/key. For Document Intelligence access only, create a Form Recognizer resource. Please note that you will need a single-service resource if you intend to use [Azure Active Directory authentication](#create-the-client-with-an-azure-active-directory-credential).
 
 You can create either resource using: 
 
@@ -68,7 +68,7 @@ You can create either resource using:
 Below is an example of how you can create a Form Recognizer resource using the CLI:
 
 ```PowerShell
-# Create a new resource group to hold the form recognizer resource
+# Create a new resource group to hold the Form Recognizer resource
 # if using an existing resource group, skip this step
 az group create --name <your-resource-name> --location <location>
 ```
@@ -88,7 +88,7 @@ For more information about creating the resource or how to get the location and
 
 ### Authenticate the client
 
-In order to interact with the Form Recognizer service, you will need to create an instance of a client.
+In order to interact with the Document Intelligence service, you will need to create an instance of a client.
 An **endpoint** and **credential** are necessary to instantiate the client object.
 
 #### Get the endpoint
@@ -98,7 +98,7 @@ You can find the endpoint for your Form Recognizer resource using the
 or [Azure CLI][azure_cli_endpoint_lookup]:
 
 ```bash
-# Get the endpoint for the form recognizer resource
+# Get the endpoint for the Form Recognizer resource
 az cognitiveservices account show --name "resource-name" --resource-group "resource-group-name" --query "properties.endpoint"
 ```
 
@@ -147,7 +147,7 @@ with the Azure SDK, please install the `azure-identity` package:
 
 ```pip install azure-identity```
 
-You will also need to [register a new AAD application and grant access][register_aad_app] to Form Recognizer by assigning the `"Cognitive Services User"` role to your service principal.
+You will also need to [register a new AAD application and grant access][register_aad_app] to Document Intelligence by assigning the `"Cognitive Services User"` role to your service principal.
 
 Once completed, set the values of the client ID, tenant ID, and client secret of the AAD application as environment variables:
 `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET`.
@@ -192,7 +192,7 @@ More information about analyzing documents, including supported features, locale
 - Copying a custom model from one Form Recognizer resource to another.
 - Build and manage a custom classification model to classify the documents you process within your application.
 
-Please note that models can also be built using a graphical user interface such as [Form Recognizer Studio][fr-studio].
+Please note that models can also be built using a graphical user interface such as [Document Intelligence Studio][fr-studio].
 
 Sample code snippets are provided to illustrate using a DocumentModelAdministrationClient [here](#examples "Examples").
 
@@ -209,7 +209,7 @@ Sample code snippets are provided to illustrate using long-running operations [b
 
 ## Examples
 
-The following section provides several code snippets covering some of the most common Form Recognizer tasks, including:
+The following section provides several code snippets covering some of the most common Document Intelligence tasks, including:
 
 * [Extract Layout](#extract-layout "Extract Layout")
 * [Using the General Document Model](#using-the-general-document-model "Using the General Document Model")
@@ -316,7 +316,7 @@ print("----------------------------------------")
 
 ### Using the General Document Model
 
-Analyze key-value pairs, tables, styles, and selection marks from documents using the general document model provided by the Form Recognizer service.
+Analyze key-value pairs, tables, styles, and selection marks from documents using the general document model provided by the Document Intelligence service.
 Select the General Document Model by passing `model_id="prebuilt-document"` into the `begin_analyze_document` method:
 
 ```python
@@ -428,7 +428,7 @@ print("----------------------------------------")
 
 ### Using Prebuilt Models
 
-Extract fields from select document types such as receipts, invoices, business cards, identity documents, and U.S. W-2 tax documents using prebuilt models provided by the Form Recognizer service.
+Extract fields from select document types such as receipts, invoices, business cards, identity documents, and U.S. W-2 tax documents using prebuilt models provided by the Document Intelligence service.
 
 For example, to analyze fields from a sales receipt, use the prebuilt receipt model provided by passing `model_id="prebuilt-receipt"` into the `begin_analyze_document` method:
 
@@ -679,7 +679,7 @@ except ResourceNotFoundError:
 ### General
 
 Form Recognizer client library will raise exceptions defined in [Azure Core][azure_core_exceptions].
-Error codes and messages raised by the Form Recognizer service can be found in the [service documentation][fr-errors].
+Error codes and messages raised by the Document Intelligence service can be found in the [service documentation][fr-errors].
 
 ### Logging
 
@@ -707,7 +707,7 @@ See the [Sample README][sample_readme] for several code snippets illustrating co
 
 ### Additional documentation
 
-For more extensive documentation on Azure Cognitive Services Form Recognizer, see the [Form Recognizer documentation][python-fr-product-docs] on docs.microsoft.com.
+For more extensive documentation on Azure AI Document Intelligence, see the [Document Intelligence documentation][python-fr-product-docs] on docs.microsoft.com.
 
 ## Contributing
 

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

@@ -15,7 +15,7 @@
 
 
 class DocumentAnalysisClient(FormRecognizerClientBase):
-    """DocumentAnalysisClient analyzes information from documents and images.
+    """DocumentAnalysisClient analyzes information from documents and images, and classifies documents.
     It is the interface to use for analyzing with prebuilt models (receipts, business cards,
     invoices, identity documents, among others), analyzing layout from documents, analyzing general
     document types, and analyzing custom documents with built models (to see a full list of models

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

@@ -44,9 +44,10 @@ class DocumentModelAdministrationClient(FormRecognizerClientBase):
     """DocumentModelAdministrationClient is the Form Recognizer interface to use for building
     and managing models.
 
-    It provides methods for building models, as well as methods for viewing and deleting models,
-    viewing model operations, accessing account information, copying models to another
-    Form Recognizer resource, and composing a new model from a collection of existing models.
+    It provides methods for building models and classifiers, as well as methods for viewing and
+    deleting models and classifiers, viewing model and classifier operations, accessing account
+    information, copying models to another Form Recognizer resource, and composing a new model
+    from a collection of existing models.
 
     .. note:: DocumentModelAdministrationClient should be used with API versions
         2022-08-31 and up. To use API versions <=v2.1, instantiate a FormTrainingClient.
@@ -648,8 +649,8 @@ def begin_build_document_classifier(
         """Build a document classifier. For more information on how to build and train
         a custom classifier model, see https://aka.ms/azsdk/formrecognizer/buildclassifiermodel.
 
-        :param doc_types: Required. Mapping of document types to classify against.
-        :paramtype doc_types: Mapping[str, ~azure.ai.formrecognizer.ClassifierDocumentTypeDetails]
+        :param doc_types: Mapping of document types to classify against.
+        :type doc_types: Mapping[str, ~azure.ai.formrecognizer.ClassifierDocumentTypeDetails]
         :keyword str classifier_id: Unique document classifier name.
             If not specified, a classifier ID will be created for you.
         :keyword str description: Document classifier description.

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

@@ -2712,7 +2712,7 @@ class DocumentWord:
     """
     content: str
     """Text content of the word."""
-    polygon: Optional[Sequence[Point]]
+    polygon: Sequence[Point]
     """Bounding polygon of the word."""
     span: DocumentSpan
     """Location of the word in the reading order concatenated content."""
@@ -2781,7 +2781,7 @@ class DocumentSelectionMark:
     state: str
     """State of the selection mark. Possible values include: "selected",
      "unselected"."""
-    polygon: Optional[Sequence[Point]]
+    polygon: Sequence[Point]
     """Bounding polygon of the selection mark."""
     span: DocumentSpan
     """Location of the selection mark in the reading order concatenated
@@ -2850,7 +2850,7 @@ class DocumentLine:
 
     content: str
     """Concatenated content of the contained elements in reading order."""
-    polygon: Optional[Sequence[Point]]
+    polygon: Sequence[Point]
     """Bounding polygon of the line."""
     spans: List[DocumentSpan]
     """Location of the line in the reading order concatenated content."""
@@ -3180,11 +3180,11 @@ class DocumentPage:  # pylint: disable=too-many-instance-attributes
      "inch"."""
     spans: List[DocumentSpan]
     """Location of the page in the reading order concatenated content."""
-    words: Optional[List[DocumentWord]]
+    words: List[DocumentWord]
     """Extracted words from the page."""
-    selection_marks: Optional[List[DocumentSelectionMark]]
+    selection_marks: List[DocumentSelectionMark]
     """Extracted selection marks from the page."""
-    lines: Optional[List[DocumentLine]]
+    lines: List[DocumentLine]
     """Extracted lines from the page, potentially containing both textual and
      visual elements."""
     barcodes: List[DocumentBarcode]
@@ -3811,7 +3811,7 @@ def to_dict(self) -> Dict[str, Any]:
     def from_dict(cls, data: Dict[str, Any]) -> "BlobFileListSource":
         """Converts a dict in the shape of a BlobFileListSource to the model itself.
 
-        :param Dict[str, Any] data: A dictionary in the shape of BlobFileListSource.
+        :param dict data: A dictionary in the shape of BlobFileListSource.
         :return: BlobFileListSource
         :rtype: BlobFileListSource
         """
@@ -3869,7 +3869,7 @@ def to_dict(self) -> Dict[str, Any]:
     def from_dict(cls, data: Dict[str, Any]) -> "BlobSource":
         """Converts a dict in the shape of a BlobSource to the model itself.
 
-        :param Dict[str, Any] data: A dictionary in the shape of BlobSource.
+        :param dict data: A dictionary in the shape of BlobSource.
         :return: BlobSource
         :rtype: BlobSource
         """
@@ -3932,7 +3932,7 @@ def to_dict(self) -> Dict[str, Any]:
     def from_dict(cls, data: Dict[str, Any]) -> "ClassifierDocumentTypeDetails":
         """Converts a dict in the shape of a ClassifierDocumentTypeDetails to the model itself.
 
-        :param Dict[str, Any] data: A dictionary in the shape of ClassifierDocumentTypeDetails.
+        :param dict data: A dictionary in the shape of ClassifierDocumentTypeDetails.
         :return: ClassifierDocumentTypeDetails
         :rtype: ClassifierDocumentTypeDetails
         """
@@ -4748,7 +4748,7 @@ class ResourceDetails:
 
     custom_document_models: CustomDocumentModelsDetails
     """Details regarding the custom models under the Form Recognizer resource."""
-    neural_document_model_quota: QuotaDetails
+    neural_document_model_quota: Optional[QuotaDetails]
     """Quota details regarding the custom neural document model builds under the Form Recognizer resource."""
 
     def __init__(

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

@@ -16,7 +16,7 @@
 
 
 class DocumentAnalysisClient(FormRecognizerClientBaseAsync):
-    """DocumentAnalysisClient analyzes information from documents and images.
+    """DocumentAnalysisClient analyzes information from documents and images, and classifies documents.
     It is the interface to use for analyzing with prebuilt models (receipts, business cards,
     invoices, identity documents, among others), analyzing layout from documents, analyzing general
     document types, and analyzing custom documents with built models (to see a full list of models

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

@@ -44,9 +44,10 @@ class DocumentModelAdministrationClient(FormRecognizerClientBaseAsync):
     """DocumentModelAdministrationClient is the Form Recognizer interface to use for building
     and managing models.
 
-    It provides methods for building models, as well as methods for viewing and deleting models,
-    viewing model operations, accessing account information, copying models to another
-    Form Recognizer resource, and composing a new model from a collection of existing models.
+    It provides methods for building models and classifiers, as well as methods for viewing and
+    deleting models and classifiers, viewing model and classifier operations, accessing account
+    information, copying models to another Form Recognizer resource, and composing a new model
+    from a collection of existing models.
 
     .. note:: DocumentModelAdministrationClient should be used with API versions
         2022-08-31 and up. To use API versions <=v2.1, instantiate a FormTrainingClient.
@@ -651,7 +652,7 @@ async def begin_build_document_classifier(
         a custom classifier model, see https://aka.ms/azsdk/formrecognizer/buildclassifiermodel.
 
         :param doc_types: Mapping of document types to classify against.
-        :paramtype doc_types: Mapping[str, ~azure.ai.formrecognizer.ClassifierDocumentTypeDetails]
+        :type doc_types: Mapping[str, ~azure.ai.formrecognizer.ClassifierDocumentTypeDetails]
         :keyword str classifier_id: Unique document classifier name.
             If not specified, a classifier ID will be created for you.
         :keyword str description: Document classifier description.