[formrecognizer] Build model update

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

@@ -6,6 +6,8 @@
 - Added `TargetAuthorization` of type `dict[str, str]`.
 
 ### Breaking Changes
+- Renamed `source` argument to `blob_container_url` on `begin_build_model()`.
+- Changed argument order on `begin_build_model()`. `build_mode` is the first expected argument, followed by `blob_container_url`.
 - Renamed `begin_create_composed_model()` on `DocumentModelAdministrationClient` to `begin_compose_model()`.
 - Renamed `get_account_info()` on `DocumentModelAdministrationClient` to `get_resource_details()`.
 - Renamed `AccountInfo` model to `ResourceDetails`.

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

@@ -643,7 +643,7 @@ Train a custom model with `3.2.x`:
 ```python
 document_model_admin_client = DocumentModelAdministrationClient(endpoint, AzureKeyCredential(key))
 poller = document_model_admin_client.begin_build_model(
-    container_sas_url, "template", model_id="my-model-id", description="my model description"
+    "template", container_sas_url, model_id="my-model-id", description="my model description"
 )
 model = poller.result()
 

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

@@ -423,7 +423,7 @@ document_model_admin_client = DocumentModelAdministrationClient(endpoint, creden
 container_sas_url = "<container-sas-url>"  # training documents uploaded to blob storage
 poller = document_model_admin_client.begin_build_model(
     # For more information about build_mode, see: https://aka.ms/azsdk/formrecognizer/buildmode
-    source=container_sas_url, build_mode="template", model_id="my-first-model"
+    build_mode="template", blob_container_url=container_sas_url, model_id="my-first-model"
 )
 model = poller.result()
 

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

@@ -93,27 +93,27 @@ def __init__(self, endpoint: str, credential: Union[AzureKeyCredential, TokenCre
 
     @distributed_trace
     def begin_build_model(
-        self, source: str, build_mode: Union[str, DocumentBuildMode], **kwargs: Any
+        self, build_mode: Union[str, DocumentBuildMode], blob_container_url: str, **kwargs: Any
     ) -> DocumentModelAdministrationLROPoller[DocumentModelDetails]:
         """Build a custom model.
 
-        The request must include a `source` parameter that is an
+        The request must include a `blob_container_url` parameter that is an
         externally accessible Azure storage blob container URI (preferably a Shared Access Signature URI). Note that
         a container URI (without SAS) is accepted only when the container is public or has a managed identity
         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.
 
-        :param str source: An Azure Storage blob container's SAS URI. A container URI (without SAS)
-            can be used if the container is public or has a managed identity configured. For more information on
-            setting up a training data set, see: https://aka.ms/azsdk/formrecognizer/buildtrainingset.
         :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.
+        :param str blob_container_url: An Azure Storage blob container's SAS URI. A container URI (without SAS)
+            can be used if the container is public or has a managed identity configured. For more information on
+            setting up a training data set, see: https://aka.ms/azsdk/formrecognizer/buildtrainingset.
         :type build_mode: str or :class:`~azure.ai.formrecognizer.DocumentBuildMode`
         :keyword str model_id: A unique ID for your model. If not specified, a model ID will be created for you.
         :keyword str description: An optional description to add to the model.
-        :keyword str prefix: A case-sensitive prefix string to filter documents in the source path.
+        :keyword str prefix: A case-sensitive prefix string to filter documents in the blob container url path.
             For example, when using an Azure storage blob URI, use the prefix to restrict sub folders.
             `prefix` should end in '/' to avoid cases where filenames share the same prefix.
         :keyword tags: List of user defined key-value tag attributes associated with the model.
@@ -164,7 +164,7 @@ def callback(raw_response, _, headers):  # pylint: disable=unused-argument
                 description=description,
                 tags=tags,
                 azure_blob_source=self._generated_models.AzureBlobContentSource(
-                    container_url=source,
+                    container_url=blob_container_url,
                     prefix=kwargs.pop("prefix", None),
                 ),
             ),

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

@@ -98,27 +98,27 @@ def __init__(
 
     @distributed_trace_async
     async def begin_build_model(
-        self, source: str, build_mode: Union[str, DocumentBuildMode], **kwargs: Any
+        self, build_mode: Union[str, DocumentBuildMode], blob_container_url: str, **kwargs: Any
     ) -> AsyncDocumentModelAdministrationLROPoller[DocumentModelDetails]:
         """Build a custom model.
 
-        The request must include a `source` parameter that is an
+        The request must include a `blob_container_url` parameter that is an
         externally accessible Azure storage blob container URI (preferably a Shared Access Signature URI). Note that
         a container URI (without SAS) is accepted only when the container is public or has a managed identity
         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.
 
-        :param str source: An Azure Storage blob container's SAS URI. A container URI (without SAS)
-            can be used if the container is public or has a managed identity configured. For more information on
-            setting up a training data set, see: https://aka.ms/azsdk/formrecognizer/buildtrainingset.
         :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.
+        :param str blob_container_url: An Azure Storage blob container's SAS URI. A container URI (without SAS)
+            can be used if the container is public or has a managed identity configured. For more information on
+            setting up a training data set, see: https://aka.ms/azsdk/formrecognizer/buildtrainingset.
         :type build_mode: str or :class:`~azure.ai.formrecognizer.DocumentBuildMode`
         :keyword str model_id: A unique ID for your model. If not specified, a model ID will be created for you.
         :keyword str description: An optional description to add to the model.
-        :keyword str prefix: A case-sensitive prefix string to filter documents in the source path.
+        :keyword str prefix: A case-sensitive prefix string to filter documents in the blob container url path.
             For example, when using an Azure storage blob URI, use the prefix to restrict sub folders.
             `prefix` should end in '/' to avoid cases where filenames share the same prefix.
         :keyword tags: List of user defined key-value tag attributes associated with the model.
@@ -169,7 +169,7 @@ def callback(raw_response, _, headers):  # pylint: disable=unused-argument
                 description=description,
                 tags=tags,
                 azure_blob_source=self._generated_models.AzureBlobContentSource(
-                    container_url=source,
+                    container_url=blob_container_url,
                     prefix=kwargs.pop("prefix", None),
                 ),
             ),

sdk/formrecognizer/azure-ai-formrecognizer/samples/v3.2-beta/async_samples/sample_analyze_custom_documents_async.py

@@ -126,7 +126,7 @@ async def main():
         )
         async with document_model_admin_client:
             poller = await document_model_admin_client.begin_build_model(
-                os.getenv("CONTAINER_SAS_URL"), DocumentBuildMode.TEMPLATE
+                DocumentBuildMode.TEMPLATE, os.getenv("CONTAINER_SAS_URL")
             )
             model = await poller.result()
             model_id = model.model_id

sdk/formrecognizer/azure-ai-formrecognizer/samples/v3.2-beta/async_samples/sample_build_model_async.py

@@ -42,7 +42,7 @@ async def sample_build_model_async():
     document_model_admin_client = DocumentModelAdministrationClient(endpoint, AzureKeyCredential(key))
     async with document_model_admin_client:
         poller = await document_model_admin_client.begin_build_model(
-            container_sas_url, DocumentBuildMode.TEMPLATE, description="my model description"
+            DocumentBuildMode.TEMPLATE, container_sas_url, description="my model description"
         )
         model = await poller.result()
 

sdk/formrecognizer/azure-ai-formrecognizer/samples/v3.2-beta/async_samples/sample_compose_model_async.py

@@ -55,16 +55,16 @@ async def sample_compose_model_async():
     document_model_admin_client = DocumentModelAdministrationClient(endpoint=endpoint, credential=AzureKeyCredential(key))
     async with document_model_admin_client:
         supplies_poller = await document_model_admin_client.begin_build_model(
-            po_supplies, DocumentBuildMode.TEMPLATE, description="Purchase order-Office supplies"
+            DocumentBuildMode.TEMPLATE, po_supplies, description="Purchase order-Office supplies"
         )
         equipment_poller = await document_model_admin_client.begin_build_model(
-            po_equipment, DocumentBuildMode.TEMPLATE, description="Purchase order-Office Equipment"
+            DocumentBuildMode.TEMPLATE, po_equipment, description="Purchase order-Office Equipment"
         )
         furniture_poller = await document_model_admin_client.begin_build_model(
-            po_furniture, DocumentBuildMode.TEMPLATE, description="Purchase order-Furniture"
+            DocumentBuildMode.TEMPLATE, po_furniture, description="Purchase order-Furniture"
         )
         cleaning_supplies_poller = await document_model_admin_client.begin_build_model(
-            po_cleaning_supplies, DocumentBuildMode.TEMPLATE, description="Purchase order-Cleaning Supplies"
+            DocumentBuildMode.TEMPLATE, po_cleaning_supplies, description="Purchase order-Cleaning Supplies"
         )
         supplies_model = await supplies_poller.result()
         equipment_model = await equipment_poller.result()

sdk/formrecognizer/azure-ai-formrecognizer/samples/v3.2-beta/async_samples/sample_copy_model_to_async.py

@@ -90,7 +90,7 @@ async def main():
             endpoint=endpoint, credential=AzureKeyCredential(key)
         )
         async with document_model_admin_client:
-            model = await (await document_model_admin_client.begin_build_model(os.getenv("CONTAINER_SAS_URL"), DocumentBuildMode.TEMPLATE)).result()
+            model = await (await document_model_admin_client.begin_build_model(DocumentBuildMode.TEMPLATE, os.getenv("CONTAINER_SAS_URL"))).result()
             model_id = model.model_id
 
     await sample_copy_model_to_async(model_id)

sdk/formrecognizer/azure-ai-formrecognizer/samples/v3.2-beta/async_samples/sample_manage_models_async.py

@@ -56,7 +56,7 @@ async def sample_manage_models_async():
         # [END list_models_async]
 
         # let's build a model to use for this sample
-        poller = await document_model_admin_client.begin_build_model(container_sas_url, DocumentBuildMode.TEMPLATE, description="model for sample")
+        poller = await document_model_admin_client.begin_build_model(DocumentBuildMode.TEMPLATE, container_sas_url, description="model for sample")
         model = await poller.result()
 
         # [START get_model_async]

sdk/formrecognizer/azure-ai-formrecognizer/samples/v3.2-beta/sample_analyze_custom_documents.py

@@ -117,7 +117,7 @@ def analyze_custom_documents(custom_model_id):
             endpoint=endpoint, credential=AzureKeyCredential(key)
         )
         model = document_model_admin_client.begin_build_model(
-            os.getenv("CONTAINER_SAS_URL"), DocumentBuildMode.TEMPLATE
+            DocumentBuildMode.TEMPLATE, os.getenv("CONTAINER_SAS_URL")
         ).result()
         model_id = model.model_id
 

sdk/formrecognizer/azure-ai-formrecognizer/samples/v3.2-beta/sample_build_model.py

@@ -39,7 +39,7 @@ def sample_build_model():
 
     document_model_admin_client = DocumentModelAdministrationClient(endpoint, AzureKeyCredential(key))
     poller = document_model_admin_client.begin_build_model(
-        container_sas_url, DocumentBuildMode.TEMPLATE, description="my model description"
+        DocumentBuildMode.TEMPLATE, container_sas_url, description="my model description"
     )
     model = poller.result()
 

sdk/formrecognizer/azure-ai-formrecognizer/samples/v3.2-beta/sample_compose_model.py

@@ -52,16 +52,16 @@ def sample_compose_model():
 
     document_model_admin_client = DocumentModelAdministrationClient(endpoint=endpoint, credential=AzureKeyCredential(key))
     supplies_poller = document_model_admin_client.begin_build_model(
-        po_supplies, DocumentBuildMode.TEMPLATE, description="Purchase order-Office supplies"
+        DocumentBuildMode.TEMPLATE, po_supplies, description="Purchase order-Office supplies"
     )
     equipment_poller = document_model_admin_client.begin_build_model(
-        po_equipment, DocumentBuildMode.TEMPLATE, description="Purchase order-Office Equipment"
+        DocumentBuildMode.TEMPLATE, po_equipment, description="Purchase order-Office Equipment"
     )
     furniture_poller = document_model_admin_client.begin_build_model(
-        po_furniture, DocumentBuildMode.TEMPLATE, description="Purchase order-Furniture"
+        DocumentBuildMode.TEMPLATE, po_furniture, description="Purchase order-Furniture"
     )
     cleaning_supplies_poller = document_model_admin_client.begin_build_model(
-        po_cleaning_supplies, DocumentBuildMode.TEMPLATE, description="Purchase order-Cleaning Supplies"
+        DocumentBuildMode.TEMPLATE, po_cleaning_supplies, description="Purchase order-Cleaning Supplies"
     )
     supplies_model = supplies_poller.result()
     equipment_model = equipment_poller.result()

sdk/formrecognizer/azure-ai-formrecognizer/samples/v3.2-beta/sample_copy_model_to.py

@@ -85,7 +85,7 @@ def sample_copy_model_to(custom_model_id):
         document_model_admin_client = DocumentModelAdministrationClient(
             endpoint=endpoint, credential=AzureKeyCredential(key)
         )
-        model = document_model_admin_client.begin_build_model(os.getenv("CONTAINER_SAS_URL"), DocumentBuildMode.TEMPLATE).result()
+        model = document_model_admin_client.begin_build_model(DocumentBuildMode.TEMPLATE, os.getenv("CONTAINER_SAS_URL")).result()
         model_id = model.model_id
 
     sample_copy_model_to(model_id)

sdk/formrecognizer/azure-ai-formrecognizer/samples/v3.2-beta/sample_manage_models.py

@@ -53,7 +53,7 @@ def sample_manage_models():
     # [END list_models]
 
     # let's build a model to use for this sample
-    poller = document_model_admin_client.begin_build_model(container_sas_url, DocumentBuildMode.TEMPLATE, description="model for sample")
+    poller = document_model_admin_client.begin_build_model(DocumentBuildMode.TEMPLATE, container_sas_url, description="model for sample")
     model = poller.result()
 
     # [START get_model]

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

@@ -41,7 +41,7 @@ def test_custom_document_transform(self, client, formrecognizer_storage_containe
         set_bodiless_matcher()
         da_client = client.get_document_analysis_client()
 
-        poller = client.begin_build_model(formrecognizer_storage_container_sas_url, "template")
+        poller = client.begin_build_model("template", formrecognizer_storage_container_sas_url)
         model = poller.result()
 
         responses = []
@@ -86,7 +86,7 @@ def test_custom_document_multipage_transform(self, client, formrecognizer_multip
         set_bodiless_matcher()
         da_client = client.get_document_analysis_client()
 
-        poller = client.begin_build_model(formrecognizer_multipage_storage_container_sas_url, "template")
+        poller = client.begin_build_model("template", formrecognizer_multipage_storage_container_sas_url)
         model = poller.result()
 
         responses = []
@@ -131,7 +131,7 @@ def test_custom_document_selection_mark(self, client, formrecognizer_selection_m
         set_bodiless_matcher()
         da_client = client.get_document_analysis_client()
 
-        poller = client.begin_build_model(formrecognizer_selection_mark_storage_container_sas_url, "template")
+        poller = client.begin_build_model("template", formrecognizer_selection_mark_storage_container_sas_url)
         model = poller.result()
 
         with open(self.selection_form_pdf, "rb") as fd:
@@ -179,7 +179,7 @@ def test_pages_kwarg_specified(self, client, formrecognizer_storage_container_sa
         with open(self.form_jpg, "rb") as fd:
             my_file = fd.read()
 
-        build_poller = client.begin_build_model(formrecognizer_storage_container_sas_url, "template")
+        build_poller = client.begin_build_model("template", formrecognizer_storage_container_sas_url)
         model = build_poller.result()
 
         poller = da_client.begin_analyze_document(model.model_id, my_file, pages="1")
@@ -197,7 +197,7 @@ def test_custom_document_signature_field(self, client, formrecognizer_storage_co
         with open(self.form_jpg, "rb") as fd:
             my_file = fd.read()
 
-        build_polling = client.begin_build_model(formrecognizer_storage_container_sas_url, "template")
+        build_polling = client.begin_build_model("template", formrecognizer_storage_container_sas_url)
         model = build_polling.result()
 
         poller = da_client.begin_analyze_document(
@@ -221,7 +221,7 @@ def test_custom_document_blank_pdf(self, client, formrecognizer_storage_containe
         with open(self.blank_pdf, "rb") as fd:
             my_file = fd.read()
 
-        build_polling = client.begin_build_model(formrecognizer_storage_container_sas_url, "template")
+        build_polling = client.begin_build_model("template", formrecognizer_storage_container_sas_url)
         model = build_polling.result()
 
         poller = da_client.begin_analyze_document(