[formrecognizer] Update operation names to include document model (Azure#25843)

* update operation names to include document model

* complete document model renames

* changelog

* docs

* migration guide and docs

* samples

* update tests

* fix CurrencyValue docs

* update operations description

* update async sample tags

Author: catalinaperalta

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

@@ -10,6 +10,12 @@
 ### Breaking Changes
 - This library will default to service API version `2022-08-31` going forward.
 - Removed `kind` property on `DocumentPage`.
+- Renamed `begin_build_model()` to `begin_build_document_model()` on the `DocumentModelAdministrationClient`.
+- Renamed `begin_compose_model()` to `begin_compose_document_model()` on the `DocumentModelAdministrationClient`.
+- Renamed `begin_copy_model_to()` to `begin_copy_document_model_to()` on the `DocumentModelAdministrationClient`.
+- Renamed `list_models()` to `list_document_models()` on the `DocumentModelAdministrationClient`.
+- Renamed `get_model()` to `get_document_model()` on the `DocumentModelAdministrationClient`.
+- Renamed `delete_model()` to `delete_document_model()` on the `DocumentModelAdministrationClient`.
 - Removed `document_model_count` and `document_model_limit` properties on `ResourceDetails`.
 - Renamed `DocumentModelOperationDetails` to `OperationDetails`.
 - Renamed `DocumentModelOperationSummary` to `OperationSummary`.

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

@@ -31,9 +31,9 @@ New features provided by the `DocumentAnalysisClient` include:
 
 New features provided by the `DocumentModelAdministrationClient` include:
 - Users can now assign their own model IDs and specify a description when building, composing, or copying models.
-- Users can specify the algorithm used to build the custom model through the required `build_mode` parameter on `begin_build_model()`. See more about `build_mode` [here][https://aka.ms/azsdk/formrecognizer/buildmode].
+- Users can specify the algorithm used to build the custom model through the required `build_mode` parameter on `begin_build_document_model()`. See more about `build_mode` [here][https://aka.ms/azsdk/formrecognizer/buildmode].
 - Listing models now includes both prebuilt and custom models.
-- When using `get_model()`, users can get the field schema (field names and types that the model can extract) for the model they specified, including for prebuilt models. 
+- When using `get_document_model()`, users can get the field schema (field names and types that the model can extract) for the model they specified, including for prebuilt models. 
 - Ability to get information from model operations that occurred in the last 24 hours.
 
 The table below describes the relationship of each client and its supported API version(s):
@@ -632,11 +632,11 @@ for doc in model.training_documents:
 ```
 
 Train a custom model with `3.2.x`:
-Use `begin_build_model()` to build a custom model. Please note that this method has a required `build_mode` parameter. See https://aka.ms/azsdk/formrecognizer/buildmode for more information about build modes. Additionally, `blob_container_url` is a required keyword-only parameter.
+Use `begin_build_document_model()` to build a custom document model. Please note that this method has a required `build_mode` parameter. See https://aka.ms/azsdk/formrecognizer/buildmode for more information about build modes. Additionally, `blob_container_url` is a required keyword-only parameter.
 
 ```python
 document_model_admin_client = DocumentModelAdministrationClient(endpoint, AzureKeyCredential(key))
-poller = document_model_admin_client.begin_build_model(
+poller = document_model_admin_client.begin_build_document_model(
     "template", blob_container_url=container_sas_url, model_id="my-model-id", description="my model description"
 )
 model = poller.result()

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

@@ -421,7 +421,7 @@ credential = AzureKeyCredential("<api_key>")
 document_model_admin_client = DocumentModelAdministrationClient(endpoint, credential)
 
 container_sas_url = "<container-sas-url>"  # training documents uploaded to blob storage
-poller = document_model_admin_client.begin_build_model(
+poller = document_model_admin_client.begin_build_document_model(
     # For more information about build_mode, see: https://aka.ms/azsdk/formrecognizer/buildmode
     build_mode="template", blob_container_url=container_sas_url, model_id="my-first-model"
 )
@@ -524,24 +524,24 @@ print("Our account has {} custom models, and we can have at most {} custom model
 ))
 
 # Here we get a paged list of all of our models
-models = document_model_admin_client.list_models()
+models = document_model_admin_client.list_document_models()
 print("We have models with the following ids: {}".format(
     ", ".join([m.model_id for m in models])
 ))
 
 # Replace with the custom model ID from the "Build a model" sample
 model_id = "<model_id from the Build a Model sample>"
 
-custom_model = document_model_admin_client.get_model(model_id=model_id)
+custom_model = document_model_admin_client.get_document_model(model_id=model_id)
 print("Model ID: {}".format(custom_model.model_id))
 print("Description: {}".format(custom_model.description))
 print("Model created on: {}\n".format(custom_model.created_on))
 
 # Finally, we will delete this model by ID
-document_model_admin_client.delete_model(model_id=custom_model.model_id)
+document_model_admin_client.delete_document_model(model_id=custom_model.model_id)
 
 try:
-    document_model_admin_client.get_model(model_id=custom_model.model_id)
+    document_model_admin_client.get_document_model(model_id=custom_model.model_id)
 except ResourceNotFoundError:
     print("Successfully deleted model with id {}".format(custom_model.model_id))
 ```

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

@@ -86,10 +86,10 @@ def __init__(self, endpoint: str, credential: Union[AzureKeyCredential, TokenCre
         )
 
     @distributed_trace
-    def begin_build_model(
+    def begin_build_document_model(
         self, build_mode: Union[str, ModelBuildMode], *, blob_container_url: str, **kwargs: Any
     ) -> DocumentModelAdministrationLROPoller[DocumentModelDetails]:
-        """Build a custom model.
+        """Build a custom document model.
 
         The request must include a `blob_container_url` keyword parameter that is an
         externally accessible Azure storage blob container URI (preferably a Shared Access Signature URI). Note that
@@ -166,10 +166,10 @@ def callback(raw_response, _, headers):  # pylint: disable=unused-argument
         )
 
     @distributed_trace
-    def begin_compose_model(
+    def begin_compose_document_model(
         self, component_model_ids: List[str], **kwargs: Any
     ) -> DocumentModelAdministrationLROPoller[DocumentModelDetails]:
-        """Creates a composed model from a collection of existing models.
+        """Creates a composed document model from a collection of existing models.
 
         A composed model allows multiple models to be called with a single model ID. When a document is
         submitted to be analyzed with a composed model ID, a classification step is first performed to
@@ -238,7 +238,7 @@ def get_copy_authorization(self, **kwargs: Any) -> TargetAuthorization:
         """Generate authorization for copying a custom model into the target Form Recognizer resource.
 
         This should be called by the target resource (where the model will be copied to)
-        and the output can be passed as the `target` parameter into :func:`~begin_copy_model_to()`.
+        and the output can be passed as the `target` parameter into :func:`~begin_copy_document_model_to()`.
 
         :keyword str model_id: A unique ID for your copied model.
             If not specified, a model ID will be created for you.
@@ -270,10 +270,10 @@ def get_copy_authorization(self, **kwargs: Any) -> TargetAuthorization:
         return target
 
     @distributed_trace
-    def begin_copy_model_to(
+    def begin_copy_document_model_to(
         self, model_id: str, target: TargetAuthorization, **kwargs: Any
     ) -> DocumentModelAdministrationLROPoller[DocumentModelDetails]:
-        """Copy a model stored in this resource (the source) to the user specified
+        """Copy a document model stored in this resource (the source) to the user specified
         target Form Recognizer resource.
 
         This should be called with the source Form Recognizer resource
@@ -292,8 +292,8 @@ def begin_copy_model_to(
         .. admonition:: Example:
 
             .. literalinclude:: ../samples/v3.2-beta/sample_copy_model.py
-                :start-after: [START begin_copy_model_to]
-                :end-before: [END begin_copy_model_to]
+                :start-after: [START begin_copy_document_model_to]
+                :end-before: [END begin_copy_document_model_to]
                 :language: python
                 :dedent: 4
                 :caption: Copy a model from the source resource to the target resource
@@ -331,8 +331,8 @@ def _copy_callback(raw_response, _, headers):  # pylint: disable=unused-argument
         )
 
     @distributed_trace
-    def delete_model(self, model_id: str, **kwargs: Any) -> None:
-        """Delete a custom model.
+    def delete_document_model(self, model_id: str, **kwargs: Any) -> None:
+        """Delete a custom document model.
 
         :param model_id: Model identifier.
         :type model_id: str
@@ -342,8 +342,8 @@ def delete_model(self, model_id: str, **kwargs: Any) -> None:
         .. admonition:: Example:
 
             .. literalinclude:: ../samples/v3.2-beta/sample_manage_models.py
-                :start-after: [START delete_model]
-                :end-before: [END delete_model]
+                :start-after: [START delete_document_model]
+                :end-before: [END delete_document_model]
                 :language: python
                 :dedent: 4
                 :caption: Delete a model.
@@ -355,7 +355,7 @@ def delete_model(self, model_id: str, **kwargs: Any) -> None:
         return self._client.delete_document_model(model_id=model_id, **kwargs)
 
     @distributed_trace
-    def list_models(self, **kwargs: Any) -> ItemPaged[DocumentModelSummary]:
+    def list_document_models(self, **kwargs: Any) -> ItemPaged[DocumentModelSummary]:
         """List information for each model, including its model ID,
         description, and when it was created.
 
@@ -366,8 +366,8 @@ def list_models(self, **kwargs: Any) -> ItemPaged[DocumentModelSummary]:
         .. admonition:: Example:
 
             .. literalinclude:: ../samples/v3.2-beta/sample_manage_models.py
-                :start-after: [START list_models]
-                :end-before: [END list_models]
+                :start-after: [START list_document_models]
+                :end-before: [END list_document_models]
                 :language: python
                 :dedent: 4
                 :caption: List all models that were built successfully under the Form Recognizer resource.
@@ -403,8 +403,8 @@ def get_resource_details(self, **kwargs: Any) -> ResourceDetails:
         return ResourceDetails._from_generated(response.custom_document_models)
 
     @distributed_trace
-    def get_model(self, model_id: str, **kwargs: Any) -> DocumentModelDetails:
-        """Get a model by its ID.
+    def get_document_model(self, model_id: str, **kwargs: Any) -> DocumentModelDetails:
+        """Get a document model by its ID.
 
         :param str model_id: Model identifier.
         :return: DocumentModelDetails
@@ -414,8 +414,8 @@ def get_model(self, model_id: str, **kwargs: Any) -> DocumentModelDetails:
         .. admonition:: Example:
 
             .. literalinclude:: ../samples/v3.2-beta/sample_manage_models.py
-                :start-after: [START get_model]
-                :end-before: [END get_model]
+                :start-after: [START get_document_model]
+                :end-before: [END get_document_model]
                 :language: python
                 :dedent: 4
                 :caption: Get a model by its ID.
@@ -429,11 +429,11 @@ def get_model(self, model_id: str, **kwargs: Any) -> DocumentModelDetails:
 
     @distributed_trace
     def list_operations(self, **kwargs: Any) -> ItemPaged[OperationSummary]:
-        """List information for each document model operation.
+        """List information for each 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.
+        Lists all operations associated with the Form Recognizer resource.
+        Note that operation information only persists for 24 hours. If a document model operation was successful,
+        the document model can be accessed using the :func:`~get_document_model` or :func:`~list_document_models` APIs.
 
         :return: A pageable of OperationSummary.
         :rtype: ~azure.core.paging.ItemPaged[OperationSummary]
@@ -459,11 +459,11 @@ def list_operations(self, **kwargs: Any) -> ItemPaged[OperationSummary]:
 
     @distributed_trace
     def get_operation(self, operation_id: str, **kwargs: Any) -> OperationDetails:
-        """Get a document model operation by its ID.
+        """Get an 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.
+        Get an operation associated with the Form Recognizer resource.
+        Note that operation information only persists for 24 hours. If the document model operation was successful,
+        the model can be accessed using the :func:`~get_document_model` or :func:`~list_document_models` APIs.
 
         :param str operation_id: The operation ID.
         :return: OperationDetails

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

@@ -2120,9 +2120,9 @@ class CurrencyValue:
     """A currency value element.
 
     :ivar amount: The currency amount.
-    :vartype: float
+    :vartype amount: float
     :ivar symbol: The currency symbol, if found.
-    :vartype: Optional[str]
+    :vartype symbol: Optional[str]
     """
 
     def __init__(self, **kwargs):
@@ -3266,7 +3266,7 @@ class OperationSummary:
     created, and more.
 
     Note that operation information only persists for 24 hours. If the operation was successful,
-    the model can be accessed using the :func:`~get_model` or :func:`~list_models` APIs.
+    the model can be accessed using the :func:`~get_document_model` or :func:`~list_document_models` APIs.
     To find out why an operation failed, use :func:`~get_operation` and provide the `operation_id`.
 
     :ivar operation_id: Operation ID.
@@ -3371,7 +3371,7 @@ class OperationDetails(OperationSummary):
     error of the operation if it has completed.
 
     Note that operation information only persists for 24 hours. If the operation was successful,
-    the model can also be accessed using the :func:`~get_model` or :func:`~list_models` APIs.
+    the model can also be accessed using the :func:`~get_document_model` or :func:`~list_document_models` APIs.
 
     :ivar operation_id: Operation ID.
     :vartype operation_id: str