[formrecognizer] Renames and documentation updates (Azure#25941)

* OperationDetails rename

* add image/heif to supported content types

* rename OperationSummary

* pylint, cspell fixes

* docs correction

.vscode/cspell.json

@@ -457,7 +457,8 @@
         "allinone",
         "dmac",
         "ierr",
-        "mymodel"
+        "mymodel",
+        "heif"
       ]
     },
     {

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

@@ -3,13 +3,16 @@
 ## 3.2.0b7 (Unreleased)
 
 ### Features Added
+- Content type `image/heif` is supported for document analysis and building models.
 - Added `custom_document_models` property on `ResourceDetails`.
 - Added new `CustomDocumentModelsDetails` model to represent the details of the custom document models in a given Form Recognizer resource.
 
 ### Breaking Changes
 - This library will default to service API version `2022-08-31` going forward.
 - Removed `kind` property on `DocumentPage`.
 - Removed `document_model_count` and `document_model_limit` properties on `ResourceDetails`.
+- Renamed `DocumentModelOperationDetails` to `OperationDetails`.
+- Renamed `DocumentModelOperationSummary` to `OperationSummary`.
 
 ### Bugs Fixed
 

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

@@ -56,8 +56,8 @@
     DocumentTable,
     DocumentTableCell,
     DocumentWord,
-    DocumentModelOperationSummary,
-    DocumentModelOperationDetails,
+    OperationSummary,
+    OperationDetails,
     DocumentModelDetails,
     DocumentModelSummary,
     DocumentTypeDetails,
@@ -122,8 +122,8 @@
     "DocumentTableCell",
     "DocumentWord",
     "DocumentModelAdministrationLROPoller",
-    "DocumentModelOperationSummary",
-    "DocumentModelOperationDetails",
+    "OperationSummary",
+    "OperationDetails",
     "DocumentAnalysisApiVersion",
     "DocumentModelDetails",
     "DocumentModelSummary",

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

@@ -76,7 +76,7 @@ def begin_analyze_document(
         :param str model_id: A unique model identifier can be passed in as a string.
             Use this to specify the custom model ID or prebuilt model ID. Prebuilt model IDs supported
             can be found here: https://aka.ms/azsdk/formrecognizer/models
-        :param document: JPEG, PNG, PDF, TIFF, or BMP type file stream or bytes.
+        :param document: JPEG, PNG, PDF, TIFF, BMP, or HEIF type file stream or bytes.
         :type document: bytes or IO[bytes]
         :keyword str pages: Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers
             and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like
@@ -143,7 +143,7 @@ def begin_analyze_document_from_url(
             can be found here: https://aka.ms/azsdk/formrecognizer/models
         :param str document_url: The URL of the document to analyze. The input must be a valid, properly
             encoded  (i.e. encode special characters, such as empty spaces), and publicly accessible URL
-            of one of the supported formats: JPEG, PNG, PDF, TIFF, or BMP.
+            of one of the supported formats: JPEG, PNG, PDF, TIFF, BMP, or HEIF.
         :keyword str pages: Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers
             and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like
             `pages="1-3, 5-6"`. Separate each page number or range with a comma.

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

@@ -28,8 +28,8 @@
     ModelBuildMode,
     DocumentModelDetails,
     DocumentModelSummary,
-    DocumentModelOperationDetails,
-    DocumentModelOperationSummary,
+    OperationDetails,
+    OperationSummary,
     ResourceDetails,
     TargetAuthorization,
 )
@@ -97,7 +97,8 @@ def begin_build_model(
         configured, see more about configuring managed identities to work with Form Recognizer here:
         https://docs.microsoft.com/azure/applied-ai-services/form-recognizer/managed-identities.
         Models are built using documents that are of the following content type - 'application/pdf',
-        'image/jpeg', 'image/png', 'image/tiff', or 'image/bmp'. Other types of content in the container is ignored.
+        'image/jpeg', 'image/png', 'image/tiff', 'image/bmp', or 'image/heif'. Other types of content in the container
+        is ignored.
 
         :param build_mode: The custom model build mode. Possible values include: "template", "neural".
             For more information about build modes, see: https://aka.ms/azsdk/formrecognizer/buildmode.
@@ -427,15 +428,15 @@ def get_model(self, model_id: str, **kwargs: Any) -> DocumentModelDetails:
         return DocumentModelDetails._from_generated(response)
 
     @distributed_trace
-    def list_operations(self, **kwargs: Any) -> ItemPaged[DocumentModelOperationSummary]:
+    def list_operations(self, **kwargs: Any) -> ItemPaged[OperationSummary]:
         """List information for each document model operation.
 
         Lists all document model operations associated with the Form Recognizer resource.
         Note that operation information only persists for 24 hours. If the operation was successful,
         the document model can be accessed using the :func:`~get_model` or :func:`~list_models` APIs.
 
-        :return: A pageable of DocumentModelOperationSummary.
-        :rtype: ~azure.core.paging.ItemPaged[DocumentModelOperationSummary]
+        :return: A pageable of OperationSummary.
+        :rtype: ~azure.core.paging.ItemPaged[OperationSummary]
         :raises ~azure.core.exceptions.HttpResponseError:
 
         .. admonition:: Example:
@@ -451,22 +452,22 @@ def list_operations(self, **kwargs: Any) -> ItemPaged[DocumentModelOperationSumm
         return self._client.get_operations(  # type: ignore
             cls=kwargs.pop(
                 "cls",
-                lambda objs: [DocumentModelOperationSummary._from_generated(x) for x in objs],
+                lambda objs: [OperationSummary._from_generated(x) for x in objs],
             ),
             **kwargs
         )
 
     @distributed_trace
-    def get_operation(self, operation_id: str, **kwargs: Any) -> DocumentModelOperationDetails:
+    def get_operation(self, operation_id: str, **kwargs: Any) -> OperationDetails:
         """Get a document model operation by its ID.
 
         Get a document model operation associated with the Form Recognizer resource.
         Note that operation information only persists for 24 hours. If the operation was successful,
         the document model can be accessed using the :func:`~get_model` or :func:`~list_models` APIs.
 
         :param str operation_id: The operation ID.
-        :return: DocumentModelOperationDetails
-        :rtype: ~azure.ai.formrecognizer.DocumentModelOperationDetails
+        :return: OperationDetails
+        :rtype: ~azure.ai.formrecognizer.OperationDetails
         :raises ~azure.core.exceptions.HttpResponseError:
 
         .. admonition:: Example:
@@ -482,7 +483,7 @@ def get_operation(self, operation_id: str, **kwargs: Any) -> DocumentModelOperat
         if not operation_id:
             raise ValueError("'operation_id' cannot be None or empty.")
 
-        return DocumentModelOperationDetails._from_generated(
+        return OperationDetails._from_generated(
             self._client.get_operation(operation_id, **kwargs),
             api_version=self._api_version,
         )

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

@@ -3261,7 +3261,7 @@ def from_dict(cls, data: dict) -> "DocumentTableCell":
         )
 
 
-class DocumentModelOperationSummary:
+class OperationSummary:
     """Model operation information, including the kind and status of the operation, when it was
     created, and more.
 
@@ -3307,14 +3307,14 @@ def __init__(self, **kwargs):
 
     def __repr__(self):
         return (
-            f"DocumentModelOperationSummary(operation_id={self.operation_id}, status={self.status}, "
+            f"OperationSummary(operation_id={self.operation_id}, status={self.status}, "
             f"percent_completed={self.percent_completed}, created_on={self.created_on}, "
             f"last_updated_on={self.last_updated_on}, kind={self.kind}, "
             f"resource_location={self.resource_location}, api_version={self.api_version}, tags={self.tags})"
         )
 
     def to_dict(self) -> dict:
-        """Returns a dict representation of DocumentModelOperationSummary.
+        """Returns a dict representation of OperationSummary.
 
         :return: dict
         :rtype: dict
@@ -3332,12 +3332,12 @@ def to_dict(self) -> dict:
         }
 
     @classmethod
-    def from_dict(cls, data: dict) -> "DocumentModelOperationSummary":
-        """Converts a dict in the shape of a DocumentModelOperationSummary to the model itself.
+    def from_dict(cls, data: dict) -> "OperationSummary":
+        """Converts a dict in the shape of a OperationSummary to the model itself.
 
-        :param dict data: A dictionary in the shape of DocumentModelOperationSummary.
-        :return: DocumentModelOperationSummary
-        :rtype: DocumentModelOperationSummary
+        :param dict data: A dictionary in the shape of OperationSummary.
+        :return: OperationSummary
+        :rtype: OperationSummary
         """
         return cls(
             operation_id=data.get("operation_id", None),
@@ -3366,8 +3366,8 @@ def _from_generated(cls, op):
         )
 
 
-class DocumentModelOperationDetails(DocumentModelOperationSummary):
-    """DocumentModelOperationDetails consists of information about the model operation, including the result or
+class OperationDetails(OperationSummary):
+    """OperationDetails consists of information about the model operation, including the result or
     error of the operation if it has completed.
 
     Note that operation information only persists for 24 hours. If the operation was successful,
@@ -3412,15 +3412,15 @@ def __init__(self, **kwargs):
 
     def __repr__(self):
         return (
-            f"DocumentModelOperationDetails(operation_id={self.operation_id}, status={self.status}, "
+            f"OperationDetails(operation_id={self.operation_id}, status={self.status}, "
             f"percent_completed={self.percent_completed}, created_on={self.created_on}, "
             f"last_updated_on={self.last_updated_on}, kind={self.kind}, "
             f"resource_location={self.resource_location}, result={repr(self.result)}, "
             f"error={repr(self.error)}, api_version={self.api_version}, tags={self.tags})"
         )
 
     def to_dict(self) -> dict:
-        """Returns a dict representation of DocumentModelOperationDetails.
+        """Returns a dict representation of OperationDetails.
 
         :return: dict
         :rtype: dict
@@ -3440,12 +3440,12 @@ def to_dict(self) -> dict:
         }
 
     @classmethod
-    def from_dict(cls, data: dict) -> "DocumentModelOperationDetails":
-        """Converts a dict in the shape of a DocumentModelOperationDetails to the model itself.
+    def from_dict(cls, data: dict) -> "OperationDetails":
+        """Converts a dict in the shape of a OperationDetails to the model itself.
 
-        :param dict data: A dictionary in the shape of DocumentModelOperationDetails.
-        :return: DocumentModelOperationDetails
-        :rtype: DocumentModelOperationDetails
+        :param dict data: A dictionary in the shape of OperationDetails.
+        :return: OperationDetails
+        :rtype: OperationDetails
         """
         return cls(
             operation_id=data.get("operation_id", None),

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

@@ -79,7 +79,7 @@ async def begin_analyze_document(
         :param str model_id: A unique model identifier can be passed in as a string.
             Use this to specify the custom model ID or prebuilt model ID. Prebuilt model IDs supported
             can be found here: https://aka.ms/azsdk/formrecognizer/models
-        :param document: JPEG, PNG, PDF, TIFF, or BMP type file stream or bytes.
+        :param document: JPEG, PNG, PDF, TIFF, BMP, or HEIF type file stream or bytes.
         :type document: bytes or IO[bytes]
         :keyword str pages: Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers
             and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like
@@ -146,7 +146,7 @@ async def begin_analyze_document_from_url(
             can be found here: https://aka.ms/azsdk/formrecognizer/models
         :param str document_url: The URL of the document to analyze. The input must be a valid, properly
             encoded  (i.e. encode special characters, such as empty spaces), and publicly accessible URL
-            of one of the supported formats: JPEG, PNG, PDF, TIFF, or BMP.
+            of one of the supported formats: JPEG, PNG, PDF, TIFF, BMP, or HEIF.
         :keyword str pages: Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers
             and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like
             `pages="1-3, 5-6"`. Separate each page number or range with a comma.

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

@@ -28,8 +28,8 @@
     ModelBuildMode,
     DocumentModelDetails,
     DocumentModelSummary,
-    DocumentModelOperationDetails,
-    DocumentModelOperationSummary,
+    OperationDetails,
+    OperationSummary,
     ResourceDetails,
     TargetAuthorization,
 )
@@ -99,7 +99,8 @@ async def begin_build_model(
         configured, see more about configuring managed identities to work with Form Recognizer here:
         https://docs.microsoft.com/azure/applied-ai-services/form-recognizer/managed-identities.
         Models are built using documents that are of the following content type - 'application/pdf',
-        'image/jpeg', 'image/png', 'image/tiff', or 'image/bmp'. Other types of content in the container is ignored.
+        'image/jpeg', 'image/png', 'image/tiff', 'image/bmp', or 'image/heif'. Other types of content in the container
+        is ignored.
 
         :param build_mode: The custom model build mode. Possible values include: "template", "neural".
             For more information about build modes, see: https://aka.ms/azsdk/formrecognizer/buildmode.
@@ -429,15 +430,15 @@ async def get_model(self, model_id: str, **kwargs: Any) -> DocumentModelDetails:
         return DocumentModelDetails._from_generated(response)
 
     @distributed_trace
-    def list_operations(self, **kwargs: Any) -> AsyncItemPaged[DocumentModelOperationSummary]:
+    def list_operations(self, **kwargs: Any) -> AsyncItemPaged[OperationSummary]:
         """List information for each document model operation.
 
         Lists all document model operations associated with the Form Recognizer resource.
         Note that operation information only persists for 24 hours. If the operation was successful,
         the document model can be accessed using the :func:`~get_model` or :func:`~list_models` APIs.
 
-        :return: A pageable of DocumentModelOperationSummary.
-        :rtype: ~azure.core.async_paging.AsyncItemPaged[DocumentModelOperationSummary]
+        :return: A pageable of OperationSummary.
+        :rtype: ~azure.core.async_paging.AsyncItemPaged[OperationSummary]
         :raises ~azure.core.exceptions.HttpResponseError:
 
         .. admonition:: Example:
@@ -453,22 +454,22 @@ def list_operations(self, **kwargs: Any) -> AsyncItemPaged[DocumentModelOperatio
         return self._client.get_operations(  # type: ignore
             cls=kwargs.pop(
                 "cls",
-                lambda objs: [DocumentModelOperationSummary._from_generated(x) for x in objs],
+                lambda objs: [OperationSummary._from_generated(x) for x in objs],
             ),
             **kwargs
         )
 
     @distributed_trace_async
-    async def get_operation(self, operation_id: str, **kwargs: Any) -> DocumentModelOperationDetails:
+    async def get_operation(self, operation_id: str, **kwargs: Any) -> OperationDetails:
         """Get a document model operation by its ID.
 
         Get a document model operation associated with the Form Recognizer resource.
         Note that operation information only persists for 24 hours. If the operation was successful,
         the document model can be accessed using the :func:`~get_model` or :func:`~list_models` APIs.
 
         :param str operation_id: The operation ID.
-        :return: DocumentModelOperationDetails
-        :rtype: ~azure.ai.formrecognizer.DocumentModelOperationDetails
+        :return: OperationDetails
+        :rtype: ~azure.ai.formrecognizer.OperationDetails
         :raises ~azure.core.exceptions.HttpResponseError:
 
         .. admonition:: Example:
@@ -484,7 +485,7 @@ async def get_operation(self, operation_id: str, **kwargs: Any) -> DocumentModel
         if not operation_id:
             raise ValueError("'operation_id' cannot be None or empty.")
 
-        return DocumentModelOperationDetails._from_generated(
+        return OperationDetails._from_generated(
             await self._client.get_operation(operation_id, **kwargs),
             api_version=self._api_version,
         )

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

@@ -13,7 +13,7 @@
 from azure.ai.formrecognizer import (
     DocumentModelAdministrationClient,
     DocumentAnalysisApiVersion,
-    DocumentModelOperationDetails
+    OperationDetails
 )
 from testcase import FormRecognizerTest
 from preparers import GlobalClientPreparer as _GlobalClientPreparer
@@ -154,7 +154,7 @@ def test_get_list_operations(self, client, **kwargs):
             # assert op.tags is None
             # test to/from dict
             op_dict = op.to_dict()
-            op = DocumentModelOperationDetails.from_dict(op_dict)
+            op = OperationDetails.from_dict(op_dict)
             assert op.error is None
             model = op.result
             assert model.model_id
@@ -174,7 +174,7 @@ def test_get_list_operations(self, client, **kwargs):
             op = client.get_operation(failed_op.operation_id)
             # test to/from dict
             op_dict = op.to_dict()
-            op = DocumentModelOperationDetails.from_dict(op_dict)
+            op = OperationDetails.from_dict(op_dict)
 
             assert op.result is None
             error = op.error

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

@@ -14,7 +14,7 @@
 from azure.ai.formrecognizer import (
     DocumentModelAdministrationClient,
     DocumentAnalysisApiVersion,
-    DocumentModelOperationDetails
+    OperationDetails
 )
 from azure.ai.formrecognizer.aio import DocumentModelAdministrationClient
 from preparers import FormRecognizerPreparer
@@ -161,7 +161,7 @@ async def test_get_list_operations(self, client):
                 op = await client.get_operation(successful_op.operation_id)
                 # test to/from dict
                 op_dict = op.to_dict()
-                op = DocumentModelOperationDetails.from_dict(op_dict)
+                op = OperationDetails.from_dict(op_dict)
                 assert op.error is None
                 model = op.result
                 assert model.model_id
@@ -181,7 +181,7 @@ async def test_get_list_operations(self, client):
                 op = await client.get_operation(failed_op.operation_id)
                 # test to/from dict
                 op_dict = op.to_dict()
-                op = DocumentModelOperationDetails.from_dict(op_dict)
+                op = OperationDetails.from_dict(op_dict)
 
                 error = op.error
                 assert op.result is None