[formrecognizer] Rename "model" param to "model_id" (Azure#25311)

Part of Azure#24980

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

@@ -11,6 +11,7 @@
 - Renamed `AccountInfo` model to `ResourceInfo`.
 - Renamed `DocumentModelInfo` model to `DocumentModelSummary`.
 - Renamed `DocumentModel` to `DocumentModelInfo`.
+- Renamed `model` parameter to `model_id` on `begin_analyze_document()` and `begin_analyze_document_from_url()`.
 - Removed `continuation_token` keyword from `begin_analyze_document()` and `begin_analyze_document_from_url()` on `DocumentAnalysisClient` and from `begin_build_model()`, `begin_compose_model()` and `begin_copy_model_to()` on `DocumentModelAdministrationClient`.
 - Changed return type of `get_copy_authorization()` from `dict[str, str]` to `TargetAuthorization`.
 - Changed expected `target` parameter in `begin_copy_to()` from `dict[str, str]` to `TargetAuthorization`.

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

@@ -547,7 +547,7 @@ Analyze custom document with `3.2.x`:
 ```python
 with open(path_to_sample_documents, "rb") as f:
     poller = document_analysis_client.begin_analyze_document(
-        model=model_id, document=f
+        model_id=model_id, document=f
     )
 result = poller.result()
 

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

@@ -158,7 +158,7 @@ document_analysis_client = DocumentAnalysisClient(
 
 ### DocumentAnalysisClient
 `DocumentAnalysisClient` provides operations for analyzing input documents using prebuilt and custom models through the `begin_analyze_document` and `begin_analyze_document_from_url` APIs.
-Use the `model` parameter to select the type of model for analysis. See a full list of supported models [here][fr-models].
+Use the `model_id` parameter to select the type of model for analysis. See a full list of supported models [here][fr-models].
 
 Sample code snippets are provided to illustrate using a DocumentAnalysisClient [here](#examples "Examples").
 More information about analyzing documents, including supported features, locales, and document types can be found in the [service documentation][fr-models].
@@ -276,7 +276,7 @@ for table_idx, table in enumerate(result.tables):
 
 ### 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.
-Select the General Document Model by passing `model="prebuilt-document"` into the `begin_analyze_document` method:
+Select the General Document Model by passing `model_id="prebuilt-document"` into the `begin_analyze_document` method:
 
 ```python
 from azure.ai.formrecognizer import DocumentAnalysisClient
@@ -373,7 +373,7 @@ for page in result.pages:
 ### 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.
 
-For example, to analyze fields from a sales receipt, use the prebuilt receipt model provided by passing `model="prebuilt-receipt"` into the `begin_analyze_document` method:
+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:
 
 ```python
 from azure.ai.formrecognizer import DocumentAnalysisClient
@@ -455,7 +455,7 @@ model_id = "<your custom model id>"
 with open("<path to your document>", "rb") as fd:
     document = fd.read()
 
-poller = document_analysis_client.begin_analyze_document(model=model_id, document=document)
+poller = document_analysis_client.begin_analyze_document(model_id=model_id, document=document)
 result = poller.result()
 
 for analyzed_document in result.documents:
@@ -501,7 +501,7 @@ Alternatively, a document URL can also be used to analyze documents using the `b
 
 ```python
 document_url = "<url_of_the_document>"
-poller = document_analysis_client.begin_analyze_document_from_url(model=model_id, document_url=document_url)
+poller = document_analysis_client.begin_analyze_document_from_url(model_id=model_id, document_url=document_url)
 result = poller.result()
 ```
 

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

@@ -79,11 +79,11 @@ def _analyze_document_callback(
 
     @distributed_trace
     def begin_analyze_document(
-        self, model: str, document: Union[bytes, IO[bytes]], **kwargs: Any
+        self, model_id: str, document: Union[bytes, IO[bytes]], **kwargs: Any
     ) -> LROPoller[AnalyzeResult]:
         """Analyze field text and semantic values from a given document.
 
-        :param str model: A unique model identifier can be passed in as a string.
+        :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.
@@ -115,14 +115,14 @@ def begin_analyze_document(
                 :caption: Analyze a custom document. For more samples see the `samples` folder.
         """
 
-        if not model:
-            raise ValueError("model cannot be None or empty.")
+        if not model_id:
+            raise ValueError("model_id cannot be None or empty.")
 
         cls = kwargs.pop("cls", self._analyze_document_callback)
         continuation_token = kwargs.pop("continuation_token", None)
 
         return self._client.begin_analyze_document(  # type: ignore
-            model_id=model,
+            model_id=model_id,
             analyze_request=document,  # type: ignore
             content_type="application/octet-stream",
             string_index_type="unicodeCodePoint",
@@ -132,11 +132,13 @@ def begin_analyze_document(
         )
 
     @distributed_trace
-    def begin_analyze_document_from_url(self, model: str, document_url: str, **kwargs: Any) -> LROPoller[AnalyzeResult]:
+    def begin_analyze_document_from_url(
+        self, model_id: str, document_url: str, **kwargs: Any
+    ) -> LROPoller[AnalyzeResult]:
         """Analyze field text and semantic values from a given document.
         The input must be the location (URL) of the document to be analyzed.
 
-        :param str model: A unique model identifier can be passed in as a string.
+        :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 str document_url: The URL of the document to analyze. The input must be a valid, properly
@@ -162,14 +164,14 @@ def begin_analyze_document_from_url(self, model: str, document_url: str, **kwarg
                 :caption: Analyze a receipt. For more samples see the `samples` folder.
         """
 
-        if not model:
-            raise ValueError("model cannot be None or empty.")
+        if not model_id:
+            raise ValueError("model_id cannot be None or empty.")
 
         cls = kwargs.pop("cls", self._analyze_document_callback)
         continuation_token = kwargs.pop("continuation_token", None)
 
         return self._client.begin_analyze_document(  # type: ignore
-            model_id=model,
+            model_id=model_id,
             analyze_request={"urlSource": document_url},  # type: ignore
             string_index_type="unicodeCodePoint",
             continuation_token=continuation_token,

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

@@ -85,11 +85,11 @@ def _analyze_document_callback(
 
     @distributed_trace_async
     async def begin_analyze_document(
-        self, model: str, document: Union[bytes, IO[bytes]], **kwargs: Any
+        self, model_id: str, document: Union[bytes, IO[bytes]], **kwargs: Any
     ) -> AsyncLROPoller[AnalyzeResult]:
         """Analyze field text and semantic values from a given document.
 
-        :param str model: A unique model identifier can be passed in as a string.
+        :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.
@@ -121,14 +121,14 @@ async def begin_analyze_document(
                 :caption: Analyze a custom document. For more samples see the `samples` folder.
         """
 
-        if not model:
-            raise ValueError("model cannot be None or empty.")
+        if not model_id:
+            raise ValueError("model_id cannot be None or empty.")
 
         cls = kwargs.pop("cls", self._analyze_document_callback)
         continuation_token = kwargs.pop("continuation_token", None)
 
         return await self._client.begin_analyze_document(  # type: ignore
-            model_id=model,
+            model_id=model_id,
             analyze_request=document,  # type: ignore
             content_type="application/octet-stream",
             string_index_type="unicodeCodePoint",
@@ -139,12 +139,12 @@ async def begin_analyze_document(
 
     @distributed_trace_async
     async def begin_analyze_document_from_url(
-        self, model: str, document_url: str, **kwargs: Any
+        self, model_id: str, document_url: str, **kwargs: Any
     ) -> AsyncLROPoller[AnalyzeResult]:
         """Analyze field text and semantic values from a given document.
         The input must be the location (URL) of the document to be analyzed.
 
-        :param str model: A unique model identifier can be passed in as a string.
+        :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 str document_url: The URL of the document to analyze. The input must be a valid, properly
@@ -170,14 +170,14 @@ async def begin_analyze_document_from_url(
                 :caption: Analyze a receipt. For more samples see the `samples` folder.
         """
 
-        if not model:
-            raise ValueError("model cannot be None or empty.")
+        if not model_id:
+            raise ValueError("model_id cannot be None or empty.")
 
         cls = kwargs.pop("cls", self._analyze_document_callback)
         continuation_token = kwargs.pop("continuation_token", None)
 
         return await self._client.begin_analyze_document(  # type: ignore
-            model_id=model,
+            model_id=model_id,
             analyze_request={"urlSource": document_url},  # type: ignore
             string_index_type="unicodeCodePoint",
             continuation_token=continuation_token,

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

@@ -60,7 +60,7 @@ async def analyze_custom_documents_async(custom_model_id):
         # Make sure your document's type is included in the list of document types the custom model can analyze
         with open(path_to_sample_documents, "rb") as f:
             poller = await document_analysis_client.begin_analyze_document(
-                model=model_id, document=f
+                model_id=model_id, document=f
             )
         result = await poller.result()
 

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

@@ -13,7 +13,7 @@
     This sample demonstrates how to extract text, selection marks, and layout information from a document
     given through a file.
 
-    Note that selection marks returned from begin_analyze_document(model="prebuilt-layout") do not return the text
+    Note that selection marks returned from begin_analyze_document(model_id="prebuilt-layout") do not return the text
     associated with the checkbox. For the API to return this information, build a custom model to analyze the
     checkbox and its text. See sample_build_model.py for more information.
 

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

@@ -54,7 +54,7 @@ def analyze_custom_documents(custom_model_id):
     # Make sure your document's type is included in the list of document types the custom model can analyze
     with open(path_to_sample_documents, "rb") as f:
         poller = document_analysis_client.begin_analyze_document(
-            model=model_id, document=f
+            model_id=model_id, document=f
         )
     result = poller.result()
 

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

@@ -13,7 +13,7 @@
     This sample demonstrates how to extract text, selection marks, and layout information from a document
     given through a file.
 
-    Note that selection marks returned from begin_analyze_document(model="prebuilt-layout") do not return the text
+    Note that selection marks returned from begin_analyze_document(model_id="prebuilt-layout") do not return the text
     associated with the checkbox. For the API to return this information, build a custom model to analyze the
     checkbox and its text. See sample_build_model.py for more information.
 

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

@@ -24,15 +24,15 @@ def test_analyze_document_none_model_id(self, **kwargs):
         formrecognizer_test_api_key = kwargs.pop("formrecognizer_test_api_key")
         client = DocumentAnalysisClient(formrecognizer_test_endpoint, AzureKeyCredential(formrecognizer_test_api_key))
         with pytest.raises(ValueError):
-            client.begin_analyze_document(model=None, document=b"xx")
+            client.begin_analyze_document(model_id=None, document=b"xx")
 
     @FormRecognizerPreparer()
     def test_analyze_document_empty_model_id(self, **kwargs):
         formrecognizer_test_endpoint = kwargs.pop("formrecognizer_test_endpoint")
         formrecognizer_test_api_key = kwargs.pop("formrecognizer_test_api_key")
         client = DocumentAnalysisClient(formrecognizer_test_endpoint, AzureKeyCredential(formrecognizer_test_api_key))
         with pytest.raises(ValueError):
-            client.begin_analyze_document(model="", document=b"xx")
+            client.begin_analyze_document(model_id="", document=b"xx")
 
     @FormRecognizerPreparer()
     @DocumentModelAdministrationClientPreparer()

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

@@ -29,7 +29,7 @@ async def test_analyze_document_none_model_id(self, **kwargs):
         client = DocumentAnalysisClient(formrecognizer_test_endpoint, AzureKeyCredential(formrecognizer_test_api_key))
         with pytest.raises(ValueError):
             async with client:
-                await client.begin_analyze_document(model=None, document=b"xx")
+                await client.begin_analyze_document(model_id=None, document=b"xx")
 
     @FormRecognizerPreparer()
     async def test_analyze_document_empty_model_id(self, **kwargs):
@@ -38,7 +38,7 @@ async def test_analyze_document_empty_model_id(self, **kwargs):
         client = DocumentAnalysisClient(formrecognizer_test_endpoint, AzureKeyCredential(formrecognizer_test_api_key))
         with pytest.raises(ValueError):
             async with client:
-                await client.begin_analyze_document(model="", document=b"xx")
+                await client.begin_analyze_document(model_id="", document=b"xx")
 
     @FormRecognizerPreparer()
     @DocumentModelAdministrationClientPreparer()

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

@@ -24,15 +24,15 @@ def test_document_analysis_none_model(self, **kwargs):
         formrecognizer_test_api_key = kwargs.pop("formrecognizer_test_api_key")
         client = DocumentAnalysisClient(formrecognizer_test_endpoint, AzureKeyCredential(formrecognizer_test_api_key))
         with pytest.raises(ValueError):
-            client.begin_analyze_document_from_url(model=None, document_url="https://badurl.jpg")
+            client.begin_analyze_document_from_url(model_id=None, document_url="https://badurl.jpg")
 
     @FormRecognizerPreparer()
     def test_document_analysis_empty_model_id(self, **kwargs):
         formrecognizer_test_endpoint = kwargs.pop("formrecognizer_test_endpoint")
         formrecognizer_test_api_key = kwargs.pop("formrecognizer_test_api_key")
         client = DocumentAnalysisClient(formrecognizer_test_endpoint, AzureKeyCredential(formrecognizer_test_api_key))
         with pytest.raises(ValueError):
-            client.begin_analyze_document_from_url(model="", document_url="https://badurl.jpg")
+            client.begin_analyze_document_from_url(model_id="", document_url="https://badurl.jpg")
 
     @FormRecognizerPreparer()
     @DocumentModelAdministrationClientPreparer()
@@ -53,7 +53,7 @@ def callback(raw_response, _, headers):
             responses.append(document)
 
         poller = da_client.begin_analyze_document_from_url(
-            model=model.model_id,
+            model_id=model.model_id,
             document_url=self.selection_mark_url_pdf,
             cls=callback
         )

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

@@ -27,7 +27,7 @@ async def test_document_analysis_none_model(self, **kwargs):
         client = DocumentAnalysisClient(formrecognizer_test_endpoint, AzureKeyCredential(formrecognizer_test_api_key))
         with pytest.raises(ValueError):
             async with client:
-                await client.begin_analyze_document_from_url(model=None, document_url="https://badurl.jpg")
+                await client.begin_analyze_document_from_url(model_id=None, document_url="https://badurl.jpg")
 
     @FormRecognizerPreparer()
     async def test_document_analysis_empty_model_id(self, **kwargs):
@@ -36,7 +36,7 @@ async def test_document_analysis_empty_model_id(self, **kwargs):
         client = DocumentAnalysisClient(formrecognizer_test_endpoint, AzureKeyCredential(formrecognizer_test_api_key))
         with pytest.raises(ValueError):
             async with client:
-                await client.begin_analyze_document_from_url(model="", document_url="https://badurl.jpg")
+                await client.begin_analyze_document_from_url(model_id="", document_url="https://badurl.jpg")
 
     @FormRecognizerPreparer()
     @DocumentModelAdministrationClientPreparer()
@@ -60,7 +60,7 @@ def callback(raw_response, _, headers):
 
 
             poller = await da_client.begin_analyze_document_from_url(
-                model=model.model_id,
+                model_id=model.model_id,
                 document_url=self.selection_mark_url_pdf,
                 cls=callback
             )

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

@@ -190,7 +190,7 @@ def callback(raw_response, _, headers):
             my_file = fd.read()
 
         poller = client.begin_analyze_document(
-            model="prebuilt-invoice",
+            model_id="prebuilt-invoice",
             document=my_file,
             cls=callback
         )

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

@@ -454,7 +454,7 @@ def callback(raw_response, _, headers):
 
         async with client:
             poller = await client.begin_analyze_document(
-                model="prebuilt-invoice",
+                model_id="prebuilt-invoice",
                 document=my_file,
                 cls=callback
             )

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

@@ -127,7 +127,7 @@ def test_identity_document_jpg(self, client):
     @DocumentAnalysisClientPreparer()
     @recorded_by_proxy
     def test_invoice_tiff(self, client, **kwargs):
-        poller = client.begin_analyze_document_from_url(model="prebuilt-invoice", document_url=self.invoice_url_tiff)
+        poller = client.begin_analyze_document_from_url(model_id="prebuilt-invoice", document_url=self.invoice_url_tiff)
 
         result = poller.result()
         assert len(result.documents) == 1

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

@@ -132,7 +132,7 @@ async def test_identity_document_jpg(self, client):
     @recorded_by_proxy_async
     async def test_invoice_tiff(self, client, **kwargs):
         async with client:
-            poller = await client.begin_analyze_document_from_url(model="prebuilt-invoice", document_url=self.invoice_url_tiff)
+            poller = await client.begin_analyze_document_from_url(model_id="prebuilt-invoice", document_url=self.invoice_url_tiff)
 
             result = await poller.result()
         assert len(result.documents) == 1