[formrecognizer] rename id documents -> identity documents (#18474)

* rename on clients

* rename for samples

* renames for samples, tests, readme, changelog

* rename param in tests

* rename param in samples

* cat's review feedback

Author: kristapratico

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

@@ -2,6 +2,10 @@
 
 ## 3.1.0b5 (Unreleased)
 
+**Breaking Changes**
+
+- `begin_recognize_id_documents` renamed to `begin_recognize_identity_documents`
+- `begin_recognize_id_documents_from_url` renamed to `begin_recognize_identity_documents_from_url`
 
 ## 3.1.0b4 (2021-04-06)
 

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

@@ -9,7 +9,7 @@ from form documents. It includes the following main functionalities:
     * Receipt model - Recognize data from sales receipts using a prebuilt model.
     * Business card model - Recognize data from business cards using a prebuilt model.
     * Invoice model - Recognize data from invoices using a prebuilt model.
-    * ID document model - Recognize data from ID documents using a prebuilt model.
+    * Identity document model - Recognize data from identity documents using a prebuilt model.
 
 [Source code][python-fr-src] | [Package (PyPI)][python-fr-pypi] | [API reference documentation][python-fr-ref-docs]| [Product documentation][python-fr-product-docs] | [Samples][python-fr-samples]
 
@@ -139,7 +139,7 @@ form_recognizer_client = FormRecognizerClient(
     - Sales receipts. See fields found on a receipt [here][service_recognize_receipt].
     - Business cards. See fields found on a business card [here][service_recognize_business_cards].
     - Invoices. See fields found on an invoice [here][service_recognize_invoice].
-    - ID documents. See fields found on an ID document [here][service_recognize_id_documents].
+    - Identity documents. See fields found on identity documents [here][service_recognize_identity_documents].
  - Recognizing form content, including tables, lines, words, and selection marks, without the need to train a model. Form content is returned in a collection of `FormPage` objects.
 
 Sample code snippets are provided to illustrate using a FormRecognizerClient [here](#recognize-forms-using-a-custom-model "Recognize Forms Using a Custom Model").
@@ -293,7 +293,7 @@ You are not limited to receipts! There are a few prebuilt models to choose from,
 - Analyze receipts through the `begin_recognize_receipts` method (fields recognized by the service can be found [here][service_recognize_receipt])
 - Analyze business cards through the `begin_recognize_business_cards` method (fields recognized by the service can be found [here][service_recognize_business_cards]).
 - Analyze invoices through the `begin_recognize_invoices` method (fields recognized by the service can be found [here][service_recognize_invoice]).
-- Analyze identity documents through the `begin_recognize_id_documents` method (fields recognized by the service can be found [here][service_recognize_id_documents]).
+- Analyze identity documents through the `begin_recognize_identity_documents` method (fields recognized by the service can be found [here][service_recognize_identity_documents]).
 
 
 ### Train a model
@@ -427,7 +427,7 @@ These code samples show common scenario operations with the Azure Form Recognize
 * Recognize receipts from a URL: [sample_recognize_receipts_from_url.py][sample_recognize_receipts_from_url]
 * Recognize business cards: [sample_recognize_business_cards.py][sample_recognize_business_cards]
 * Recognize invoices: [sample_recognize_invoices.py][sample_recognize_invoices]
-* Recognize ID documents: [sample_recognize_id_documents.py][sample_recognize_id_documents]
+* Recognize identity documents: [sample_recognize_identity_documents.py][sample_recognize_identity_documents]
 * Recognize content: [sample_recognize_content.py][sample_recognize_content]
 * Recognize custom forms: [sample_recognize_custom_forms.py][sample_recognize_custom_forms]
 * Train a model without labels: [sample_train_model_without_labels.py][sample_train_model_without_labels]
@@ -446,7 +446,7 @@ are found under the `azure.ai.formrecognizer.aio` namespace.
 * Recognize receipts from a URL: [sample_recognize_receipts_from_url_async.py][sample_recognize_receipts_from_url_async]
 * Recognize business cards: [sample_recognize_business_cards_async.py][sample_recognize_business_cards_async]
 * Recognize invoices: [sample_recognize_invoices_async.py][sample_recognize_invoices_async]
-* Recognize ID documents: [sample_recognize_id_documents_async.py][sample_recognize_id_documents_async]
+* Recognize identity documents: [sample_recognize_identity_documents_async.py][sample_recognize_identity_documents_async]
 * Recognize content: [sample_recognize_content_async.py][sample_recognize_content_async]
 * Recognize custom forms: [sample_recognize_custom_forms_async.py][sample_recognize_custom_forms_async]
 * Train a model without labels: [sample_train_model_without_labels_async.py][sample_train_model_without_labels_async]
@@ -502,7 +502,7 @@ This project has adopted the [Microsoft Open Source Code of Conduct][code_of_con
 [service_recognize_receipt]: https://aka.ms/formrecognizer/receiptfields
 [service_recognize_business_cards]: https://aka.ms/formrecognizer/businesscardfields
 [service_recognize_invoice]: https://aka.ms/formrecognizer/invoicefields
-[service_recognize_id_documents]: https://aka.ms/formrecognizer/iddocumentfields
+[service_recognize_identity_documents]: https://aka.ms/formrecognizer/iddocumentfields
 [sdk_logging_docs]: https://docs.microsoft.com/azure/developer/python/azure-sdk-logging
 
 [cla]: https://cla.microsoft.com
@@ -526,8 +526,8 @@ This project has adopted the [Microsoft Open Source Code of Conduct][code_of_con
 [sample_recognize_business_cards_async]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/formrecognizer/azure-ai-formrecognizer/samples/async_samples/sample_recognize_business_cards_async.py
 [sample_recognize_invoices]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/formrecognizer/azure-ai-formrecognizer/samples/sample_recognize_invoices.py
 [sample_recognize_invoices_async]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/formrecognizer/azure-ai-formrecognizer/samples/async_samples/sample_recognize_invoices_async.py
-[sample_recognize_id_documents]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/formrecognizer/azure-ai-formrecognizer/samples/sample_recognize_id_documents.py
-[sample_recognize_id_documents_async]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/formrecognizer/azure-ai-formrecognizer/samples/async_samples/sample_recognize_id_documents_async.py
+[sample_recognize_identity_documents]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/formrecognizer/azure-ai-formrecognizer/samples/sample_recognize_identity_documents.py
+[sample_recognize_identity_documents_async]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/formrecognizer/azure-ai-formrecognizer/samples/async_samples/sample_recognize_identity_documents_async.py
 [sample_train_model_with_labels]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/formrecognizer/azure-ai-formrecognizer/samples/sample_train_model_with_labels.py
 [sample_train_model_with_labels_async]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/formrecognizer/azure-ai-formrecognizer/samples/async_samples/sample_train_model_with_labels_async.py
 [sample_train_model_without_labels]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/formrecognizer/azure-ai-formrecognizer/samples/sample_train_model_without_labels.py

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

@@ -343,17 +343,17 @@ def begin_recognize_business_cards_from_url(self, business_card_url, **kwargs):
             raise e
 
     @distributed_trace
-    def begin_recognize_id_documents(self, id_document, **kwargs):
+    def begin_recognize_identity_documents(self, identity_document, **kwargs):
         # type: (Union[bytes, IO[bytes]], Any) -> LROPoller[List[RecognizedForm]]
-        """Extract field text and semantic values from a given ID document.
+        """Extract field text and semantic values from a given identity document.
         The input document must be of one of the supported content types - 'application/pdf',
         'image/jpeg', 'image/png', 'image/tiff' or 'image/bmp'.
 
-        See fields found on an ID document here:
+        See fields found on an identity document here:
         https://aka.ms/formrecognizer/iddocumentfields
 
-        :param id_document: JPEG, PNG, PDF, TIFF, or BMP type file stream or bytes.
-        :type id_document: bytes or IO[bytes]
+        :param identity_document: JPEG, PNG, PDF, TIFF, or BMP type file stream or bytes.
+        :type identity_document: bytes or IO[bytes]
         :keyword bool include_field_elements:
             Whether or not to include all lines per page and field elements such as lines, words,
             and selection marks for each form field.
@@ -373,30 +373,30 @@ def begin_recognize_id_documents(self, id_document, **kwargs):
         :raises ~azure.core.exceptions.HttpResponseError:
 
         .. versionadded:: v2.1-preview
-            The *begin_recognize_id_documents* client method
+            The *begin_recognize_identity_documents* client method
 
         .. admonition:: Example:
 
-            .. literalinclude:: ../samples/sample_recognize_id_documents.py
-                :start-after: [START recognize_id_documents]
-                :end-before: [END recognize_id_documents]
+            .. literalinclude:: ../samples/sample_recognize_identity_documents.py
+                :start-after: [START recognize_identity_documents]
+                :end-before: [END recognize_identity_documents]
                 :language: python
                 :dedent: 8
-                :caption: Recognize ID document fields.
+                :caption: Recognize identity document fields.
         """
         content_type = kwargs.pop("content_type", None)
         if content_type == "application/json":
             raise TypeError(
-                "Call begin_recognize_id_documents_from_url() to analyze an ID document from a URL."
+                "Call begin_recognize_identity_documents_from_url() to analyze an identity document from a URL."
             )
         if content_type is None and kwargs.get("continuation_token", None) is None:
-            content_type = get_content_type(id_document)
+            content_type = get_content_type(identity_document)
 
         include_field_elements = kwargs.pop("include_field_elements", False)
 
         try:
             return self._client.begin_analyze_id_document_async(  # type: ignore
-                file_stream=id_document,
+                file_stream=identity_document,
                 content_type=content_type,
                 include_text_details=include_field_elements,
                 cls=kwargs.pop("cls", self._prebuilt_callback),
@@ -406,21 +406,21 @@ def begin_recognize_id_documents(self, id_document, **kwargs):
         except ValueError as e:
             if "begin_analyze_id_document_async" in str(e):
                 raise ValueError(
-                    "Method 'begin_recognize_id_documents' is only available for API version V2_1_PREVIEW and up"
+                    "Method 'begin_recognize_identity_documents' is only available for API version V2_1_PREVIEW and up"
                 )
             raise e
 
     @distributed_trace
-    def begin_recognize_id_documents_from_url(self, id_document_url, **kwargs):
+    def begin_recognize_identity_documents_from_url(self, identity_document_url, **kwargs):
         # type: (str, Any) -> LROPoller[List[RecognizedForm]]
-        """Extract field text and semantic values from a given ID document.
-        The input document must be the location (URL) of the ID document to be analyzed.
+        """Extract field text and semantic values from a given identity document.
+        The input document must be the location (URL) of the identity document to be analyzed.
 
-        See fields found on an ID document here:
+        See fields found on an identity document here:
         https://aka.ms/formrecognizer/iddocumentfields
 
-        :param str id_document_url: The URL of the ID document to analyze. The input must be a valid, encoded URL
-            of one of the supported formats: JPEG, PNG, PDF, TIFF, or BMP.
+        :param str identity_document_url: The URL of the identity document to analyze.
+            The input must be a valid, encoded URL of one of the supported formats: JPEG, PNG, PDF, TIFF, or BMP.
         :keyword bool include_field_elements:
             Whether or not to include all lines per page and field elements such as lines, words,
             and selection marks for each form field.
@@ -436,14 +436,14 @@ def begin_recognize_id_documents_from_url(self, id_document_url, **kwargs):
         :raises ~azure.core.exceptions.HttpResponseError:
 
         .. versionadded:: v2.1-preview
-            The *begin_recognize_id_documents_from_url* client method
+            The *begin_recognize_identity_documents_from_url* client method
         """
 
         include_field_elements = kwargs.pop("include_field_elements", False)
 
         try:
             return self._client.begin_analyze_id_document_async(  # type: ignore
-                file_stream={"source": id_document_url},
+                file_stream={"source": identity_document_url},
                 include_text_details=include_field_elements,
                 cls=kwargs.pop("cls", self._prebuilt_callback),
                 polling=True,
@@ -452,7 +452,7 @@ def begin_recognize_id_documents_from_url(self, id_document_url, **kwargs):
         except ValueError as e:
             if "begin_analyze_id_document_async" in str(e):
                 raise ValueError(
-                    "Method 'begin_recognize_id_documents_from_url' is "
+                    "Method 'begin_recognize_identity_documents_from_url' is "
                     "only available for API version V2_1_PREVIEW and up"
                 )
             raise e

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

@@ -349,18 +349,18 @@ async def begin_recognize_business_cards_from_url(
             raise e
 
     @distributed_trace_async
-    async def begin_recognize_id_documents(
-        self, id_document: Union[bytes, IO[bytes]], **kwargs: Any
+    async def begin_recognize_identity_documents(
+        self, identity_document: Union[bytes, IO[bytes]], **kwargs: Any
     ) -> AsyncLROPoller[List[RecognizedForm]]:
-        """Extract field text and semantic values from a given ID document.
+        """Extract field text and semantic values from a given identity document.
         The input document must be of one of the supported content types - 'application/pdf',
         'image/jpeg', 'image/png', 'image/tiff' or 'image/bmp'.
 
-        See fields found on an ID document here:
+        See fields found on an identity document here:
         https://aka.ms/formrecognizer/iddocumentfields
 
-        :param id_document: JPEG, PNG, PDF, TIFF, or BMP type file stream or bytes.
-        :type id_document: bytes or IO[bytes]
+        :param identity_document: JPEG, PNG, PDF, TIFF, or BMP type file stream or bytes.
+        :type identity_document: bytes or IO[bytes]
         :keyword bool include_field_elements:
             Whether or not to include all lines per page and field elements such as lines, words,
             and selection marks for each form field.
@@ -380,31 +380,31 @@ async def begin_recognize_id_documents(
         :raises ~azure.core.exceptions.HttpResponseError:
 
         .. versionadded:: v2.1-preview
-            The *begin_recognize_id_documents* client method
+            The *begin_recognize_identity_documents* client method
 
         .. admonition:: Example:
 
-            .. literalinclude:: ../samples/async_samples/sample_recognize_id_documents_async.py
-                :start-after: [START recognize_id_documents_async]
-                :end-before: [END recognize_id_documents_async]
+            .. literalinclude:: ../samples/async_samples/sample_recognize_identity_documents_async.py
+                :start-after: [START recognize_identity_documents_async]
+                :end-before: [END recognize_identity_documents_async]
                 :language: python
                 :dedent: 8
-                :caption: Recognize ID documents from a file.
+                :caption: Recognize identity documents from a file.
         """
         content_type = kwargs.pop("content_type", None)
         if content_type == "application/json":
             raise TypeError(
-                "Call begin_recognize_id_documents_from_url() to analyze an ID document from a URL."
+                "Call begin_recognize_identity_documents_from_url() to analyze an identity document from a URL."
             )
 
         include_field_elements = kwargs.pop("include_field_elements", False)
 
         if content_type is None and kwargs.get("continuation_token", None) is None:
-            content_type = get_content_type(id_document)
+            content_type = get_content_type(identity_document)
 
         try:
             return await self._client.begin_analyze_id_document_async(  # type: ignore
-                file_stream=id_document,
+                file_stream=identity_document,
                 content_type=content_type,
                 include_text_details=include_field_elements,
                 cls=kwargs.pop("cls", self._prebuilt_callback),
@@ -414,22 +414,22 @@ async def begin_recognize_id_documents(
         except ValueError as e:
             if "begin_analyze_id_document_async" in str(e):
                 raise ValueError(
-                    "Method 'begin_recognize_id_documents' is only available for API version V2_1_PREVIEW and up"
+                    "Method 'begin_recognize_identity_documents' is only available for API version V2_1_PREVIEW and up"
                 )
             raise e
 
     @distributed_trace_async
-    async def begin_recognize_id_documents_from_url(
-        self, id_document_url: str, **kwargs: Any
+    async def begin_recognize_identity_documents_from_url(
+        self, identity_document_url: str, **kwargs: Any
     ) -> AsyncLROPoller[List[RecognizedForm]]:
-        """Extract field text and semantic values from a given ID document.
-        The input document must be the location (URL) of the ID document to be analyzed.
+        """Extract field text and semantic values from a given identity document.
+        The input document must be the location (URL) of the identity document to be analyzed.
 
-        See fields found on an ID document here:
+        See fields found on an identity document here:
         https://aka.ms/formrecognizer/iddocumentfields
 
-        :param str id_document_url: The URL of the ID document to analyze. The input must be a valid, encoded URL
-            of one of the supported formats: JPEG, PNG, PDF, TIFF, or BMP.
+        :param str identity_document_url: The URL of the identity document to analyze. The input must be a valid,
+            encoded URL of one of the supported formats: JPEG, PNG, PDF, TIFF, or BMP.
         :keyword bool include_field_elements:
             Whether or not to include all lines per page and field elements such as lines, words,
             and selection marks for each form field.
@@ -445,14 +445,14 @@ async def begin_recognize_id_documents_from_url(
         :raises ~azure.core.exceptions.HttpResponseError:
 
         .. versionadded:: v2.1-preview
-            The *begin_recognize_id_documents_from_url* client method
+            The *begin_recognize_identity_documents_from_url* client method
         """
 
         include_field_elements = kwargs.pop("include_field_elements", False)
 
         try:
             return await self._client.begin_analyze_id_document_async(  # type: ignore
-                file_stream={"source": id_document_url},
+                file_stream={"source": identity_document_url},
                 include_text_details=include_field_elements,
                 cls=kwargs.pop("cls", self._prebuilt_callback),
                 polling=True,
@@ -461,7 +461,7 @@ async def begin_recognize_id_documents_from_url(
         except ValueError as e:
             if "begin_analyze_id_document_async" in str(e):
                 raise ValueError(
-                    "Method 'begin_recognize_id_documents_from_url' is "
+                    "Method 'begin_recognize_identity_documents_from_url' is "
                     "only available for API version V2_1_PREVIEW and up"
                 )
             raise e