[formrecognizer] renames to support non-text elements (#12251)

* more renames

* corrections

* recordings

* add FieldData to init

* plural field_elements

* whoops

* one more fix

* fix

* FormContent -> FormElement

* review feedback

* update docstring

* wording

Author: kristapratico

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

@@ -8,6 +8,11 @@
 - `begin_recognize_receipts` and `begin_recognize_receipts_from_url` now return `RecognizedForm`.
 - `requested_on` renamed to `training_started_on` and `completed_on` renamed to `training_completed_on` on `CustomFormModel`
 and `CustomFormModelInfo`
+- `FieldText` has been renamed to `FieldData`
+- `FormContent` has been renamed to `FormElement`
+- Parameter `include_text_content` has been renamed to `include_field_elements` for 
+`begin_recognize_receipts`, `begin_recognize_receipts_from_url`, `begin_recognize_custom_forms`, and `begin_recognize_custom_forms_from_url`
+- `text_content` has been renamed to `field_elements` on `FieldData` and `FormTableCell`
 
 **Fixes and improvements**
 

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

@@ -9,7 +9,7 @@
 from ._form_training_client import FormTrainingClient
 
 from ._models import (
-    FormContent,
+    FormElement,
     LengthUnit,
     TrainingStatus,
     CustomFormModelStatus,
@@ -24,7 +24,7 @@
     FormPageRange,
     RecognizedForm,
     FormField,
-    FieldText,
+    FieldData,
     FormPage,
     FormLine,
     FormWord,
@@ -41,7 +41,7 @@
     'TrainingStatus',
     'CustomFormModelStatus',
     'FormContentType',
-    'FormContent',
+    'FormElement',
     'FormTable',
     'FormTableCell',
     'TrainingDocumentInfo',
@@ -52,7 +52,7 @@
     'FormPageRange',
     'RecognizedForm',
     'FormField',
-    'FieldText',
+    'FieldData',
     'FormPage',
     'FormLine',
     'FormWord',

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

@@ -93,8 +93,8 @@ def begin_recognize_receipts(self, receipt, **kwargs):
         :param receipt: JPEG, PNG, PDF and TIFF type file stream or bytes.
              Currently only supports US sales receipts.
         :type receipt: bytes or IO[bytes]
-        :keyword bool include_text_content:
-            Whether or not to include text elements such as lines and words in addition to form fields.
+        :keyword bool include_field_elements:
+            Whether or not to include field elements such as lines and words in addition to form fields.
         :keyword content_type: Media type of the body sent to the API. Content-type is
             auto-detected, but can be overridden by passing this keyword argument. For options,
             see :class:`~azure.ai.formrecognizer.FormContentType`.
@@ -123,15 +123,15 @@ def begin_recognize_receipts(self, receipt, **kwargs):
         if content_type == "application/json":
             raise TypeError("Call begin_recognize_receipts_from_url() to analyze a receipt from a url.")
 
-        include_text_content = kwargs.pop("include_text_content", False)
+        include_field_elements = kwargs.pop("include_field_elements", False)
 
         if content_type is None:
             content_type = get_content_type(receipt)
 
         return self._client.begin_analyze_receipt_async(
             file_stream=receipt,
             content_type=content_type,
-            include_text_details=include_text_content,
+            include_text_details=include_field_elements,
             cls=kwargs.pop("cls", self._receipt_callback),
             polling=LROBasePolling(timeout=polling_interval, **kwargs),
             error_map=error_map,
@@ -151,8 +151,8 @@ def begin_recognize_receipts_from_url(self, receipt_url, **kwargs):
         :param str receipt_url: The url of the receipt to analyze. The input must be a valid, encoded url
             of one of the supported formats: JPEG, PNG, PDF and TIFF. Currently only supports
             US sales receipts.
-        :keyword bool include_text_content:
-            Whether or not to include text elements such as lines and words in addition to form fields.
+        :keyword bool include_field_elements:
+            Whether or not to include field elements such as lines and words in addition to form fields.
         :keyword int polling_interval: Waiting time between two polls for LRO operations
             if no Retry-After header is present. Defaults to 5 seconds.
         :keyword str continuation_token: A continuation token to restart a poller from a saved state.
@@ -173,11 +173,11 @@ def begin_recognize_receipts_from_url(self, receipt_url, **kwargs):
 
         polling_interval = kwargs.pop("polling_interval", self._client._config.polling_interval)
         continuation_token = kwargs.pop("continuation_token", None)
-        include_text_content = kwargs.pop("include_text_content", False)
+        include_field_elements = kwargs.pop("include_field_elements", False)
 
         return self._client.begin_analyze_receipt_async(
             file_stream={"source": receipt_url},
-            include_text_details=include_text_content,
+            include_text_details=include_field_elements,
             cls=kwargs.pop("cls", self._receipt_callback),
             polling=LROBasePolling(timeout=polling_interval, **kwargs),
             error_map=error_map,
@@ -279,8 +279,8 @@ def begin_recognize_custom_forms(self, model_id, form, **kwargs):
         :param str model_id: Custom model identifier.
         :param form: JPEG, PNG, PDF and TIFF type file stream or bytes.
         :type form: bytes or IO[bytes]
-        :keyword bool include_text_content:
-            Whether or not to include text elements such as lines and words in addition to form fields.
+        :keyword bool include_field_elements:
+            Whether or not to include field elements such as lines and words in addition to form fields.
         :keyword content_type: Media type of the body sent to the API. Content-type is
             auto-detected, but can be overridden by passing this keyword argument. For options,
             see :class:`~azure.ai.formrecognizer.FormContentType`.
@@ -313,7 +313,7 @@ def begin_recognize_custom_forms(self, model_id, form, **kwargs):
         if content_type == "application/json":
             raise TypeError("Call begin_recognize_custom_forms_from_url() to analyze a document from a url.")
 
-        include_text_content = kwargs.pop("include_text_content", False)
+        include_field_elements = kwargs.pop("include_field_elements", False)
         if content_type is None:
             content_type = get_content_type(form)
 
@@ -325,7 +325,7 @@ def analyze_callback(raw_response, _, headers):  # pylint: disable=unused-argume
         return self._client.begin_analyze_with_custom_model(
             file_stream=form,
             model_id=model_id,
-            include_text_details=include_text_content,
+            include_text_details=include_field_elements,
             content_type=content_type,
             cls=deserialization_callback,
             polling=LROBasePolling(timeout=polling_interval, lro_algorithms=[AnalyzePolling()], **kwargs),
@@ -344,8 +344,8 @@ def begin_recognize_custom_forms_from_url(self, model_id, form_url, **kwargs):
         :param str model_id: Custom model identifier.
         :param str form_url: The url of the form to analyze. The input must be a valid, encoded url
             of one of the supported formats: JPEG, PNG, PDF and TIFF.
-        :keyword bool include_text_content:
-            Whether or not to include text elements such as lines and words in addition to form fields.
+        :keyword bool include_field_elements:
+            Whether or not to include field elements such as lines and words in addition to form fields.
         :keyword int polling_interval: Waiting time between two polls for LRO operations
             if no Retry-After header is present. Defaults to 5 seconds.
         :keyword str continuation_token: A continuation token to restart a poller from a saved state.
@@ -361,7 +361,7 @@ def begin_recognize_custom_forms_from_url(self, model_id, form_url, **kwargs):
         cls = kwargs.pop("cls", None)
         polling_interval = kwargs.pop("polling_interval", self._client._config.polling_interval)
         continuation_token = kwargs.pop("continuation_token", None)
-        include_text_content = kwargs.pop("include_text_content", False)
+        include_field_elements = kwargs.pop("include_field_elements", False)
 
         def analyze_callback(raw_response, _, headers):  # pylint: disable=unused-argument
             analyze_result = self._client._deserialize(AnalyzeOperationResult, raw_response)
@@ -371,7 +371,7 @@ def analyze_callback(raw_response, _, headers):  # pylint: disable=unused-argume
         return self._client.begin_analyze_with_custom_model(
             file_stream={"source": form_url},
             model_id=model_id,
-            include_text_details=include_text_content,
+            include_text_details=include_field_elements,
             cls=deserialization_callback,
             polling=LROBasePolling(timeout=polling_interval, lro_algorithms=[AnalyzePolling()], **kwargs),
             error_map=error_map,

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

@@ -138,8 +138,8 @@ def __new__(cls, first_page_number, last_page_number):
         return super(FormPageRange, cls).__new__(cls, first_page_number, last_page_number)
 
 
-class FormContent(object):
-    """Base type which includes properties for text.
+class FormElement(object):
+    """Base type which includes properties for a form element.
 
     :ivar str text: The text content of the line.
     :ivar list[~azure.ai.formrecognizer.Point] bounding_box:
@@ -188,10 +188,10 @@ def __repr__(self):
 class FormField(object):
     """Represents a field recognized in an input form.
 
-    :ivar ~azure.ai.formrecognizer.FieldText label_data:
-        Contains the text, bounding box, and text content of the field label.
-    :ivar ~azure.ai.formrecognizer.FieldText value_data:
-        Contains the text, bounding box, and text content of the field value.
+    :ivar ~azure.ai.formrecognizer.FieldData label_data:
+        Contains the text, bounding box, and field elements for the field label.
+    :ivar ~azure.ai.formrecognizer.FieldData value_data:
+        Contains the text, bounding box, and field elements for the field value.
     :ivar str name: The unique name of the field or label.
     :ivar value:
         The value for the recognized field. Possible types include: 'string',
@@ -212,8 +212,8 @@ def __init__(self, **kwargs):
     @classmethod
     def _from_generated(cls, field, value, read_result):
         return cls(
-            label_data=FieldText._from_generated(field, read_result),
-            value_data=FieldText._from_generated(value, read_result),
+            label_data=FieldData._from_generated(field, read_result),
+            value_data=FieldData._from_generated(value, read_result),
             value=get_field_value(field, value, read_result),
             name=field,
             confidence=adjust_confidence(value.confidence) if value else None,
@@ -222,8 +222,8 @@ def _from_generated(cls, field, value, read_result):
     @classmethod
     def _from_generated_unlabeled(cls, field, idx, page, read_result):
         return cls(
-            label_data=FieldText._from_generated_unlabeled(field.key, page, read_result),
-            value_data=FieldText._from_generated_unlabeled(field.value, page, read_result),
+            label_data=FieldData._from_generated_unlabeled(field.key, page, read_result),
+            value_data=FieldData._from_generated_unlabeled(field.value, page, read_result),
             value=field.value.text,
             name="field-" + str(idx),
             confidence=adjust_confidence(field.confidence),
@@ -235,7 +235,7 @@ def __repr__(self):
         )[:1024]
 
 
-class FieldText(FormContent):
+class FieldData(FormElement):
     """Represents the text that is part of a form field. This includes
     the location of the text in the form and a collection of the
     elements that make up the text.
@@ -248,16 +248,16 @@ class FieldText(FormContent):
         that outlines the text. The points are listed in clockwise
         order: top-left, top-right, bottom-right, bottom-left.
         Units are in pixels for images and inches for PDF.
-    :ivar text_content:
-        When `include_text_content` is set to true, a list of text
+    :ivar field_elements:
+        When `include_field_elements` is set to true, a list of
         elements constituting this field or value is returned. The list
-        constitutes of text elements such as lines and words.
-    :vartype text_content: list[~azure.ai.formrecognizer.FormWord, ~azure.ai.formrecognizer.FormLine]
+        constitutes of elements such as lines and words.
+    :vartype field_elements: list[~azure.ai.formrecognizer.FormWord, ~azure.ai.formrecognizer.FormLine]
     """
 
     def __init__(self, **kwargs):
-        super(FieldText, self).__init__(**kwargs)
-        self.text_content = kwargs.get("text_content", None)
+        super(FieldData, self).__init__(**kwargs)
+        self.field_elements = kwargs.get("field_elements", None)
 
     @classmethod
     def _from_generated(cls, field, read_result):
@@ -272,7 +272,7 @@ def _from_generated(cls, field, read_result):
                 Point(x=field.bounding_box[4], y=field.bounding_box[5]),
                 Point(x=field.bounding_box[6], y=field.bounding_box[7])
             ] if field.bounding_box else None,
-            text_content=get_elements(field, read_result) if field.elements else None
+            field_elements=get_elements(field, read_result) if field.elements else None
         )
 
     @classmethod
@@ -286,12 +286,12 @@ def _from_generated_unlabeled(cls, field, page, read_result):
                 Point(x=field.bounding_box[4], y=field.bounding_box[5]),
                 Point(x=field.bounding_box[6], y=field.bounding_box[7])
             ] if field.bounding_box else None,
-            text_content=get_elements(field, read_result) if field.elements else None
+            field_elements=get_elements(field, read_result) if field.elements else None
         )
 
     def __repr__(self):
-        return "FieldText(page_number={}, text={}, bounding_box={}, text_content={})".format(
-            self.page_number, self.text, self.bounding_box, repr(self.text_content)
+        return "FieldData(page_number={}, text={}, bounding_box={}, field_elements={})".format(
+            self.page_number, self.text, self.bounding_box, repr(self.field_elements)
         )[:1024]
 
 
@@ -315,7 +315,7 @@ class FormPage(object):
     :ivar list[~azure.ai.formrecognizer.FormTable] tables:
         A list of extracted tables contained in a page.
     :ivar list[~azure.ai.formrecognizer.FormLine] lines:
-        When `include_text_content` is set to true, a list of recognized text lines is returned.
+        When `include_field_elements` is set to true, a list of recognized text lines is returned.
         For calls to recognize content, this list is always populated. The maximum number of lines
         returned is 300 per page. The lines are sorted top to bottom, left to right, although in
         certain cases proximity is treated with higher priority. As the sorting order depends on
@@ -349,7 +349,7 @@ def __repr__(self):
         )[:1024]
 
 
-class FormLine(FormContent):
+class FormLine(FormElement):
     """An object representing an extracted line of text.
 
     :ivar str text: The text content of the line.
@@ -388,7 +388,7 @@ def __repr__(self):
         )[:1024]
 
 
-class FormWord(FormContent):
+class FormWord(FormElement):
     """Represents a word recognized from the input document.
 
     :ivar str text: The text content of the word.
@@ -452,7 +452,7 @@ def __repr__(self):
         )[:1024]
 
 
-class FormTableCell(FormContent):
+class FormTableCell(FormElement):
     """Represents a cell contained in a table recognized from the input document.
 
     :ivar str text: Text content of the cell.
@@ -471,12 +471,12 @@ class FormTableCell(FormContent):
     :ivar bool is_footer: Whether the current cell is a footer cell.
     :ivar int page_number:
         The 1-based number of the page in which this content is present.
-    :ivar text_content:
-        When `include_text_content` is set to true, a list of text
+    :ivar field_elements:
+        When `include_field_elements` is set to true, a list of
         elements constituting this cell is returned. The list
-        constitutes of text elements such as lines and words.
-        For calls to recognize content, this list is always populated.
-    :vartype text_content: list[~azure.ai.formrecognizer.FormWord, ~azure.ai.formrecognizer.FormLine]
+        constitutes of elements such as lines and words.
+        For calls to begin_recognize_content(), this list is always populated.
+    :vartype field_elements: list[~azure.ai.formrecognizer.FormWord, ~azure.ai.formrecognizer.FormLine]
     """
 
     def __init__(self, **kwargs):
@@ -488,7 +488,7 @@ def __init__(self, **kwargs):
         self.confidence = kwargs.get("confidence", None)
         self.is_header = kwargs.get("is_header", False)
         self.is_footer = kwargs.get("is_footer", False)
-        self.text_content = kwargs.get("text_content", None)
+        self.field_elements = kwargs.get("field_elements", None)
 
     @classmethod
     def _from_generated(cls, cell, page, read_result):
@@ -508,14 +508,14 @@ def _from_generated(cls, cell, page, read_result):
             is_header=cell.is_header or False,
             is_footer=cell.is_footer or False,
             page_number=page,
-            text_content=get_elements(cell, read_result) if cell.elements else None
+            field_elements=get_elements(cell, read_result) if cell.elements else None
         )
 
     def __repr__(self):
         return "FormTableCell(text={}, row_index={}, column_index={}, row_span={}, column_span={}, " \
-                "bounding_box={}, confidence={}, is_header={}, is_footer={}, page_number={}, text_content={})".format(
+                "bounding_box={}, confidence={}, is_header={}, is_footer={}, page_number={}, field_elements={})".format(
                     self.text, self.row_index, self.column_index, self.row_span, self.column_span, self.bounding_box,
-                    self.confidence, self.is_header, self.is_footer, self.page_number, repr(self.text_content)
+                    self.confidence, self.is_header, self.is_footer, self.page_number, repr(self.field_elements)
                 )[:1024]