azure.ai.formrecognizer package¶

class azure.ai.formrecognizer.AccountInfo(**kwargs)[source]¶

Info regarding models under the Form Recognizer resource.

Variables

model_count (int) – Number of custom models in the current resource.
model_limit (int) – Maximum number of custom models supported in the current resource.

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.AccountInfo[source]¶

Converts a dict in the shape of a AccountInfo to the model itself.

Parameters: data (dict) – A dictionary in the shape of AccountInfo.
Returns: AccountInfo
Return type: AccountInfo

to_dict() → dict [source]¶

Returns a dict representation of AccountInfo.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.AccountProperties(**kwargs)[source]¶

Summary of all the custom models on the account.

Variables

custom_model_count (int) – Current count of trained custom models.
custom_model_limit (int) – Max number of models that can be trained for this account.

New in version v2.1: Support for to_dict and from_dict methods

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.AccountProperties[source]¶

Converts a dict in the shape of a AccountProperties to the model itself.

Parameters: data (dict) – A dictionary in the shape of AccountProperties.
Returns: AccountProperties
Return type: AccountProperties

to_dict() → dict [source]¶

Returns a dict representation of AccountProperties.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.AnalyzeResult(**kwargs)[source]¶

Document analysis result.

Variables

api_version (str) – API version used to produce this result. Possible values include: “2021-09-30-preview”.
model_id (str) – Model ID used to produce this result.
content (str) – Concatenate string representation of all textual and visual elements in reading order.
pages (list[DocumentPage]) – Analyzed pages.
tables (list[DocumentTable]) – Extracted tables.
key_value_pairs (list[DocumentKeyValuePair]) – Extracted key-value pairs.
entities (list[DocumentEntity]) – Extracted entities.
styles (list[DocumentStyle]) – Extracted font styles.
documents (list[AnalyzedDocument]) – Extracted documents.

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.AnalyzeResult[source]¶

Converts a dict in the shape of a AnalyzeResult to the model itself.

Parameters: data (dict) – A dictionary in the shape of AnalyzeResult.
Returns: AnalyzeResult
Return type: AnalyzeResult

to_dict() → dict [source]¶

Returns a dict representation of AnalyzeResult.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.AnalyzedDocument(**kwargs)[source]¶

An object describing the location and semantic content of a document.

Variables

doc_type (str) – The type of document that was analyzed.
bounding_regions (list[BoundingRegion]) – Bounding regions covering the document.
spans (list[DocumentSpan]) – The location of the document in the reading order concatenated content.
fields (dict[str, DocumentField]) – A dictionary of named field values.
confidence (float) – Confidence of correctly extracting the document.

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.AnalyzedDocument[source]¶

Converts a dict in the shape of a AnalyzedDocument to the model itself.

Parameters: data (dict) – A dictionary in the shape of AnalyzedDocument.
Returns: AnalyzedDocument
Return type: AnalyzedDocument

to_dict() → dict [source]¶

Returns a dict representation of AnalyzedDocument.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.BoundingRegion(**kwargs)[source]¶

The bounding region corresponding to a page.

Variables

bounding_box (list[Point]) – A list of 4 points representing the quadrilateral bounding box that outlines the text. The points are listed in clockwise order relative to the text orientation: top-left, top-right, bottom-right, bottom-left. Units are in pixels for images and inches for PDF.
page_number (int) – The 1-based number of the page in which this content is present.

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.BoundingRegion[source]¶

Converts a dict in the shape of a BoundingRegion to the model itself.

Parameters: data (dict) – A dictionary in the shape of BoundingRegion.
Returns: BoundingRegion
Return type: BoundingRegion

to_dict() → dict [source]¶

Returns a dict representation of BoundingRegion.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.CustomFormModel(**kwargs)[source]¶

Represents a trained model.

Variables

model_id (str) – The unique identifier of this model.
status (str) – Status indicating the model’s readiness for use, CustomFormModelStatus. Possible values include: ‘creating’, ‘ready’, ‘invalid’.
training_started_on (datetime) – The date and time (UTC) when model training was started.
training_completed_on (datetime) – Date and time (UTC) when model training completed.
submodels (list[CustomFormSubmodel]) – A list of submodels that are part of this model, each of which can recognize and extract fields from a different type of form.
errors (list[FormRecognizerError]) – List of any training errors.
training_documents (list[TrainingDocumentInfo]) – Metadata about each of the documents used to train the model.
model_name (str) – Optional user defined model name.
properties (CustomFormModelProperties) – Optional model properties.

New in version v2.1: The model_name and properties properties, support for to_dict and from_dict methods

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.CustomFormModel[source]¶

Converts a dict in the shape of a CustomFormModel to the model itself.

Parameters: data (dict) – A dictionary in the shape of CustomFormModel.
Returns: CustomFormModel
Return type: CustomFormModel

to_dict() → dict [source]¶

Returns a dict representation of CustomFormModel.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.CustomFormModelField(**kwargs)[source]¶

A field that the model will extract from forms it analyzes.

Variables

label (str) – The form fields label on the form.
name (str) – Canonical name; uniquely identifies a field within the form.
accuracy (float) – The estimated recognition accuracy for this field.

New in version v2.1: Support for to_dict and from_dict methods

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.CustomFormModelField[source]¶

Converts a dict in the shape of a CustomFormModelField to the model itself.

Parameters: data (dict) – A dictionary in the shape of CustomFormModelField.
Returns: CustomFormModelField
Return type: CustomFormModelField

to_dict() → dict [source]¶

Returns a dict representation of CustomFormModelField.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.CustomFormModelInfo(**kwargs)[source]¶

Custom model information.

Variables

model_id (str) – The unique identifier of the model.
status (str) – The status of the model, CustomFormModelStatus. Possible values include: ‘creating’, ‘ready’, ‘invalid’.
training_started_on (datetime) – Date and time (UTC) when model training was started.
training_completed_on (datetime) – Date and time (UTC) when model training completed.
model_name (str) – Optional user defined model name.
properties (CustomFormModelProperties) – Optional model properties.

New in version v2.1: The model_name and properties properties, support for to_dict and from_dict methods

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.CustomFormModelInfo[source]¶

Converts a dict in the shape of a CustomFormModelInfo to the model itself.

Parameters: data (dict) – A dictionary in the shape of CustomFormModelInfo.
Returns: CustomFormModelInfo
Return type: CustomFormModelInfo

to_dict() → dict [source]¶

Returns a dict representation of CustomFormModelInfo.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.CustomFormModelProperties(**kwargs)[source]¶

Optional model properties.

Variables: is_composed_model (bool) – Is this model composed? (default: false).

New in version v2.1: Support for to_dict and from_dict methods

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.CustomFormModelProperties[source]¶

Converts a dict in the shape of a CustomFormModelProperties to the model itself.

Parameters: data (dict) – A dictionary in the shape of CustomFormModelProperties.
Returns: CustomFormModelProperties
Return type: CustomFormModelProperties

to_dict() → dict [source]¶

Returns a dict representation of CustomFormModelProperties.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.CustomFormModelStatus(value)[source]¶

Status indicating the model’s readiness for use.

CREATING = 'creating'¶

INVALID = 'invalid'¶

READY = 'ready'¶

class azure.ai.formrecognizer.CustomFormSubmodel(**kwargs)[source]¶

Represents a submodel that extracts fields from a specific type of form.

Variables

model_id (str) – Model identifier of the submodel.
accuracy (float) – The mean of the model’s field accuracies.
fields (dict[str, CustomFormModelField]) – A dictionary of the fields that this submodel will recognize from the input document. The fields dictionary keys are the name of the field. For models trained with labels, this is the training-time label of the field. For models trained without labels, a unique name is generated for each field.
form_type (str) – Type of form this submodel recognizes.

New in version v2.1: The model_id property, support for to_dict and from_dict methods

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.CustomFormSubmodel[source]¶

Converts a dict in the shape of a CustomFormSubmodel to the model itself.

Parameters: data (dict) – A dictionary in the shape of CustomFormSubmodel.
Returns: CustomFormSubmodel
Return type: CustomFormSubmodel

to_dict() → dict [source]¶

Returns a dict representation of CustomFormSubmodel.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.DocTypeInfo(**kwargs)[source]¶

DocTypeInfo represents a document type that a model can recognize, including its fields and types, and the confidence for those fields.

Variables

description (str) – A description for the model.
field_schema (dict[str, Any]) – Description of the document semantic schema.
field_confidence (dict[str, float]) – Estimated confidence for each field.

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.DocTypeInfo[source]¶

Converts a dict in the shape of a DocTypeInfo to the model itself.

Parameters: data (dict) – A dictionary in the shape of DocTypeInfo.
Returns: DocTypeInfo
Return type: DocTypeInfo

to_dict() → dict [source]¶

Returns a dict representation of DocTypeInfo.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.DocumentAnalysisApiVersion(value)[source]¶

Form Recognizer API versions supported by DocumentAnalysisClient and DocumentModelAdministrationClient.

V2021_09_30_PREVIEW = '2021-09-30-preview'¶: This is the default version

class azure.ai.formrecognizer.DocumentAnalysisClient(endpoint: str, credential: Union[AzureKeyCredential, TokenCredential], **kwargs: Any)[source]¶

DocumentAnalysisClient analyzes information from documents and images. It is the interface to use for analyzing with prebuilt models (receipts, business cards, invoices, identity documents), analyzing layout from documents, analyzing general document types, and analyzing custom documents with built models. It provides different methods based on inputs from a URL and inputs from a stream.

Note

DocumentAnalysisClient should be used with API versions 2021-09-30-preview and up. To use API versions <=v2.1, instantiate a FormRecognizerClient.

Parameters

endpoint (str) – Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus2.api.cognitive.microsoft.com).
credential (AzureKeyCredential or TokenCredential) – Credentials needed for the client to connect to Azure. This is an instance of AzureKeyCredential if using an API key or a token credential from azure.identity.

Keyword Arguments

api_version (str or DocumentAnalysisApiVersion) – The API version of the service to use for requests. It defaults to the latest service version. Setting to an older version may result in reduced feature compatibility. To use API versions <=v2.1, instantiate a FormRecognizerClient.

New in version 2021-09-30-preview: The DocumentAnalysisClient and its client methods.

Example:

Creating the DocumentAnalysisClient with an endpoint and API key.¶

from azure.core.credentials import AzureKeyCredential
from azure.ai.formrecognizer import DocumentAnalysisClient

endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]

document_analysis_client = DocumentAnalysisClient(endpoint, AzureKeyCredential(key))

Creating the DocumentAnalysisClient with a token credential.¶

"""DefaultAzureCredential will use the values from these environment
variables: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET
"""
from azure.ai.formrecognizer import DocumentAnalysisClient
from azure.identity import DefaultAzureCredential

endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
credential = DefaultAzureCredential()

document_analysis_client = DocumentAnalysisClient(endpoint, credential)

begin_analyze_document(model: str, document: Union[bytes, IO[bytes]], **kwargs: Any) → LROPoller[AnalyzeResult][source]¶

Analyze field text and semantic values from a given document.

Parameters

model (str) – 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
document (bytes or IO[bytes]) – JPEG, PNG, PDF, TIFF, or BMP type file stream or bytes.

Keyword Arguments

pages (str) – Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=”1-3, 5-6”. Separate each page number or range with a comma.
locale (str) – Locale hint of the input document. See supported locales here: https://aka.ms/azsdk/formrecognizer/supportedlocales.
continuation_token (str) – A continuation token to restart a poller from a saved state.

Returns

An instance of an LROPoller. Call result() on the poller object to return a AnalyzeResult.

Return type

LROPoller[AnalyzeResult]

Raises

HttpResponseError –

Example:

Analyze an invoice. For more samples see the samples folder.¶

from azure.core.credentials import AzureKeyCredential
from azure.ai.formrecognizer import DocumentAnalysisClient

endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]

document_analysis_client = DocumentAnalysisClient(
    endpoint=endpoint, credential=AzureKeyCredential(key)
)
with open(path_to_sample_documents, "rb") as f:
    poller = document_analysis_client.begin_analyze_document(
        "prebuilt-invoice", document=f, locale="en-US"
    )
invoices = poller.result()

for idx, invoice in enumerate(invoices.documents):
    print("--------Recognizing invoice #{}--------".format(idx + 1))
    vendor_name = invoice.fields.get("VendorName")
    if vendor_name:
        print(
            "Vendor Name: {} has confidence: {}".format(
                vendor_name.value, vendor_name.confidence
            )
        )
    vendor_address = invoice.fields.get("VendorAddress")
    if vendor_address:
        print(
            "Vendor Address: {} has confidence: {}".format(
                vendor_address.value, vendor_address.confidence
            )
        )
    vendor_address_recipient = invoice.fields.get("VendorAddressRecipient")
    if vendor_address_recipient:
        print(
            "Vendor Address Recipient: {} has confidence: {}".format(
                vendor_address_recipient.value, vendor_address_recipient.confidence
            )
        )
    customer_name = invoice.fields.get("CustomerName")
    if customer_name:
        print(
            "Customer Name: {} has confidence: {}".format(
                customer_name.value, customer_name.confidence
            )
        )
    customer_id = invoice.fields.get("CustomerId")
    if customer_id:
        print(
            "Customer Id: {} has confidence: {}".format(
                customer_id.value, customer_id.confidence
            )
        )
    customer_address = invoice.fields.get("CustomerAddress")
    if customer_address:
        print(
            "Customer Address: {} has confidence: {}".format(
                customer_address.value, customer_address.confidence
            )
        )
    customer_address_recipient = invoice.fields.get("CustomerAddressRecipient")
    if customer_address_recipient:
        print(
            "Customer Address Recipient: {} has confidence: {}".format(
                customer_address_recipient.value,
                customer_address_recipient.confidence,
            )
        )
    invoice_id = invoice.fields.get("InvoiceId")
    if invoice_id:
        print(
            "Invoice Id: {} has confidence: {}".format(
                invoice_id.value, invoice_id.confidence
            )
        )
    invoice_date = invoice.fields.get("InvoiceDate")
    if invoice_date:
        print(
            "Invoice Date: {} has confidence: {}".format(
                invoice_date.value, invoice_date.confidence
            )
        )
    invoice_total = invoice.fields.get("InvoiceTotal")
    if invoice_total:
        print(
            "Invoice Total: {} has confidence: {}".format(
                invoice_total.value, invoice_total.confidence
            )
        )
    due_date = invoice.fields.get("DueDate")
    if due_date:
        print(
            "Due Date: {} has confidence: {}".format(
                due_date.value, due_date.confidence
            )
        )
    purchase_order = invoice.fields.get("PurchaseOrder")
    if purchase_order:
        print(
            "Purchase Order: {} has confidence: {}".format(
                purchase_order.value, purchase_order.confidence
            )
        )
    billing_address = invoice.fields.get("BillingAddress")
    if billing_address:
        print(
            "Billing Address: {} has confidence: {}".format(
                billing_address.value, billing_address.confidence
            )
        )
    billing_address_recipient = invoice.fields.get("BillingAddressRecipient")
    if billing_address_recipient:
        print(
            "Billing Address Recipient: {} has confidence: {}".format(
                billing_address_recipient.value,
                billing_address_recipient.confidence,
            )
        )
    shipping_address = invoice.fields.get("ShippingAddress")
    if shipping_address:
        print(
            "Shipping Address: {} has confidence: {}".format(
                shipping_address.value, shipping_address.confidence
            )
        )
    shipping_address_recipient = invoice.fields.get("ShippingAddressRecipient")
    if shipping_address_recipient:
        print(
            "Shipping Address Recipient: {} has confidence: {}".format(
                shipping_address_recipient.value,
                shipping_address_recipient.confidence,
            )
        )
    print("Invoice items:")
    for idx, item in enumerate(invoice.fields.get("Items").value):
        print("...Item #{}".format(idx + 1))
        item_description = item.value.get("Description")
        if item_description:
            print(
                "......Description: {} has confidence: {}".format(
                    item_description.value, item_description.confidence
                )
            )
        item_quantity = item.value.get("Quantity")
        if item_quantity:
            print(
                "......Quantity: {} has confidence: {}".format(
                    item_quantity.value, item_quantity.confidence
                )
            )
        unit = item.value.get("Unit")
        if unit:
            print(
                "......Unit: {} has confidence: {}".format(
                    unit.value, unit.confidence
                )
            )
        unit_price = item.value.get("UnitPrice")
        if unit_price:
            print(
                "......Unit Price: {} has confidence: {}".format(
                    unit_price.value, unit_price.confidence
                )
            )
        product_code = item.value.get("ProductCode")
        if product_code:
            print(
                "......Product Code: {} has confidence: {}".format(
                    product_code.value, product_code.confidence
                )
            )
        item_date = item.value.get("Date")
        if item_date:
            print(
                "......Date: {} has confidence: {}".format(
                    item_date.value, item_date.confidence
                )
            )
        tax = item.value.get("Tax")
        if tax:
            print(
                "......Tax: {} has confidence: {}".format(tax.value, tax.confidence)
            )
        amount = item.value.get("Amount")
        if amount:
            print(
                "......Amount: {} has confidence: {}".format(
                    amount.value, amount.confidence
                )
            )
    subtotal = invoice.fields.get("SubTotal")
    if subtotal:
        print(
            "Subtotal: {} has confidence: {}".format(
                subtotal.value, subtotal.confidence
            )
        )
    total_tax = invoice.fields.get("TotalTax")
    if total_tax:
        print(
            "Total Tax: {} has confidence: {}".format(
                total_tax.value, total_tax.confidence
            )
        )
    previous_unpaid_balance = invoice.fields.get("PreviousUnpaidBalance")
    if previous_unpaid_balance:
        print(
            "Previous Unpaid Balance: {} has confidence: {}".format(
                previous_unpaid_balance.value, previous_unpaid_balance.confidence
            )
        )
    amount_due = invoice.fields.get("AmountDue")
    if amount_due:
        print(
            "Amount Due: {} has confidence: {}".format(
                amount_due.value, amount_due.confidence
            )
        )
    service_start_date = invoice.fields.get("ServiceStartDate")
    if service_start_date:
        print(
            "Service Start Date: {} has confidence: {}".format(
                service_start_date.value, service_start_date.confidence
            )
        )
    service_end_date = invoice.fields.get("ServiceEndDate")
    if service_end_date:
        print(
            "Service End Date: {} has confidence: {}".format(
                service_end_date.value, service_end_date.confidence
            )
        )
    service_address = invoice.fields.get("ServiceAddress")
    if service_address:
        print(
            "Service Address: {} has confidence: {}".format(
                service_address.value, service_address.confidence
            )
        )
    service_address_recipient = invoice.fields.get("ServiceAddressRecipient")
    if service_address_recipient:
        print(
            "Service Address Recipient: {} has confidence: {}".format(
                service_address_recipient.value,
                service_address_recipient.confidence,
            )
        )
    remittance_address = invoice.fields.get("RemittanceAddress")
    if remittance_address:
        print(
            "Remittance Address: {} has confidence: {}".format(
                remittance_address.value, remittance_address.confidence
            )
        )
    remittance_address_recipient = invoice.fields.get("RemittanceAddressRecipient")
    if remittance_address_recipient:
        print(
            "Remittance Address Recipient: {} has confidence: {}".format(
                remittance_address_recipient.value,
                remittance_address_recipient.confidence,
            )
        )

Analyze a custom document. For more samples see the samples folder.¶

from azure.core.credentials import AzureKeyCredential
from azure.ai.formrecognizer import DocumentAnalysisClient

endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]
model_id = os.getenv("CUSTOM_BUILT_MODEL_ID", custom_model_id)

document_analysis_client = DocumentAnalysisClient(
    endpoint=endpoint, credential=AzureKeyCredential(key)
)

# 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
    )
result = poller.result()

for idx, document in enumerate(result.documents):
    print("--------Analyzing document #{}--------".format(idx + 1))
    print("Document has type {}".format(document.doc_type))
    print("Document has confidence {}".format(document.confidence))
    print("Document was analyzed by model with ID {}".format(result.model_id))
    for name, field in document.fields.items():
        field_value = field.value if field.value else field.content
        print("......found field of type '{}' with value '{}' and with confidence {}".format(field.value_type, field_value, field.confidence))


# iterate over tables, lines, and selection marks on each page
for page in result.pages:
    print("\nLines found on page {}".format(page.page_number))
    for line in page.lines:
        print("...Line '{}'".format(line.content))
    for word in page.words:
        print(
            "...Word '{}' has a confidence of {}".format(
                word.content, word.confidence
            )
        )
    for selection_mark in page.selection_marks:
        print(
            "...Selection mark is '{}' and has a confidence of {}".format(
                selection_mark.state, selection_mark.confidence
            )
        )

for i, table in enumerate(result.tables):
    print("\nTable {} can be found on page:".format(i + 1))
    for region in table.bounding_regions:
        print("...{}".format(i + 1, region.page_number))
    for cell in table.cells:
        print(
            "...Cell[{}][{}] has content '{}'".format(
                cell.row_index, cell.column_index, cell.content
            )
        )
print("-----------------------------------")

begin_analyze_document_from_url(model: str, document_url: str, **kwargs: Any) → LROPoller[AnalyzeResult][source]¶

Analyze field text and semantic values from a given document. The input must be the location (URL) of the document to be analyzed.

Parameters

model (str) – 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
document_url (str) – The URL of the document to analyze. The input must be a valid, encoded, and publicly accessible URL of one of the supported formats: JPEG, PNG, PDF, TIFF, or BMP.

Keyword Arguments

pages (str) – Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=”1-3, 5-6”. Separate each page number or range with a comma.
locale (str) – Locale hint of the input document. See supported locales here: https://aka.ms/azsdk/formrecognizer/supportedlocales.
continuation_token (str) – A continuation token to restart a poller from a saved state.

Returns

An instance of an LROPoller. Call result() on the poller object to return a AnalyzeResult.

Return type

LROPoller[AnalyzeResult]

Raises

HttpResponseError –

Example:

Analyze a receipt. For more samples see the samples folder.¶

from azure.core.credentials import AzureKeyCredential
from azure.ai.formrecognizer import DocumentAnalysisClient

endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]

document_analysis_client = DocumentAnalysisClient(
    endpoint=endpoint, credential=AzureKeyCredential(key)
)
url = "https://raw.githubusercontent.com/Azure/azure-sdk-for-python/main/sdk/formrecognizer/azure-ai-formrecognizer/tests/sample_forms/receipt/contoso-receipt.png"
poller = document_analysis_client.begin_analyze_document_from_url(
    "prebuilt-receipt", document_url=url
)
receipts = poller.result()

for idx, receipt in enumerate(receipts.documents):
    print("--------Recognizing receipt #{}--------".format(idx + 1))
    receipt_type = receipt.fields.get("ReceiptType")
    if receipt_type:
        print(
            "Receipt Type: {} has confidence: {}".format(
                receipt_type.value, receipt_type.confidence
            )
        )
    merchant_name = receipt.fields.get("MerchantName")
    if merchant_name:
        print(
            "Merchant Name: {} has confidence: {}".format(
                merchant_name.value, merchant_name.confidence
            )
        )
    transaction_date = receipt.fields.get("TransactionDate")
    if transaction_date:
        print(
            "Transaction Date: {} has confidence: {}".format(
                transaction_date.value, transaction_date.confidence
            )
        )
    if receipt.fields.get("Items"):
        print("Receipt items:")
        for idx, item in enumerate(receipt.fields.get("Items").value):
            print("...Item #{}".format(idx + 1))
            item_name = item.value.get("Name")
            if item_name:
                print(
                    "......Item Name: {} has confidence: {}".format(
                        item_name.value, item_name.confidence
                    )
                )
            item_quantity = item.value.get("Quantity")
            if item_quantity:
                print(
                    "......Item Quantity: {} has confidence: {}".format(
                        item_quantity.value, item_quantity.confidence
                    )
                )
            item_price = item.value.get("Price")
            if item_price:
                print(
                    "......Individual Item Price: {} has confidence: {}".format(
                        item_price.value, item_price.confidence
                    )
                )
            item_total_price = item.value.get("TotalPrice")
            if item_total_price:
                print(
                    "......Total Item Price: {} has confidence: {}".format(
                        item_total_price.value, item_total_price.confidence
                    )
                )
    subtotal = receipt.fields.get("Subtotal")
    if subtotal:
        print(
            "Subtotal: {} has confidence: {}".format(
                subtotal.value, subtotal.confidence
            )
        )
    tax = receipt.fields.get("Tax")
    if tax:
        print("Tax: {} has confidence: {}".format(tax.value, tax.confidence))
    tip = receipt.fields.get("Tip")
    if tip:
        print("Tip: {} has confidence: {}".format(tip.value, tip.confidence))
    total = receipt.fields.get("Total")
    if total:
        print("Total: {} has confidence: {}".format(total.value, total.confidence))
    print("--------------------------------------")

close() → None [source]¶: Close the DocumentAnalysisClient session.

class azure.ai.formrecognizer.DocumentAnalysisError(**kwargs)[source]¶

DocumentAnalysisError contains the details of the error returned by the service.

Variables

code (str) – Error code.
message (str) – Error message.
target (str) – Target of the error.
details (list[DocumentAnalysisError]) – List of detailed errors.
innererror (DocumentAnalysisInnerError) – Detailed error.

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.DocumentAnalysisError[source]¶

Converts a dict in the shape of a DocumentAnalysisError to the model itself.

Parameters: data (dict) – A dictionary in the shape of DocumentAnalysisError.
Returns: DocumentAnalysisError
Return type: DocumentAnalysisError

to_dict() → dict [source]¶

Returns a dict representation of DocumentAnalysisError.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.DocumentAnalysisInnerError(**kwargs)[source]¶

Inner error details for the DocumentAnalysisError.

Variables

code (str) – Error code.
message – Error message.
innererror (DocumentAnalysisInnerError) – Detailed error.

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.DocumentAnalysisInnerError[source]¶

Converts a dict in the shape of a DocumentAnalysisInnerError to the model itself.

Parameters: data (dict) – A dictionary in the shape of DocumentAnalysisInnerError.
Returns: DocumentAnalysisInnerError
Return type: DocumentAnalysisInnerError

to_dict() → dict [source]¶

Returns a dict representation of DocumentAnalysisInnerError.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.DocumentElement(**kwargs)[source]¶

A DocumentElement.

Variables

content (str) – Text content of the word.
bounding_box (list[Point]) – Bounding box of the word.
kind (str) – The kind of document element. Possible kinds are “word” or “selectionMark” which correspond to a DocumentWord or DocumentSelectionMark, respectively.

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.DocumentElement[source]¶

Converts a dict in the shape of a DocumentElement to the model itself.

Parameters: data (dict) – A dictionary in the shape of DocumentElement.
Returns: DocumentElement
Return type: DocumentElement

to_dict() → dict [source]¶

Returns a dict representation of DocumentElement.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.DocumentEntity(**kwargs)[source]¶

An object representing various categories of entities.

Variables

category (str) – Entity type.
sub_category (str) – Entity sub type.
content (str) – Entity content.
bounding_regions (list[BoundingRegion]) – Bounding regions covering the entity.
spans (list[DocumentSpan]) – Location of the entity in the reading order concatenated content.
confidence (float) – Confidence of correctly extracting the entity.

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.DocumentEntity[source]¶

Converts a dict in the shape of a DocumentEntity to the model itself.

Parameters: data (dict) – A dictionary in the shape of DocumentEntity.
Returns: DocumentEntity
Return type: DocumentEntity

to_dict() → dict [source]¶

Returns a dict representation of DocumentEntity.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.DocumentField(**kwargs)[source]¶

An object representing the content and location of a document field value.

Variables

value_type (str) – The type of value found on DocumentField. Possible types include: “string”, “date”, “time”, “phoneNumber”, “float”, “integer”, “selectionMark”, “countryRegion”, “signature”, “list”, “dictionary”.
value (str, int, float, date, time, dict[str, DocumentField], or list[DocumentField]) – The value for the recognized field. Its semantic data type is described by value_type. If the value is extracted from the document, but cannot be normalized to its type, then access the content property for a textual representation of the value.
content (str) – The field’s content.
bounding_regions (list[BoundingRegion]) – Bounding regions covering the field.
spans (list[DocumentSpan]) – Location of the field in the reading order concatenated content.
confidence (float) – The confidence of correctly extracting the field.

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.DocumentField[source]¶

Converts a dict in the shape of a DocumentField to the model itself.

Parameters: data (dict) – A dictionary in the shape of DocumentField.
Returns: DocumentField
Return type: DocumentField

to_dict() → dict [source]¶

Returns a dict representation of DocumentField.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.DocumentKeyValueElement(**kwargs)[source]¶

An object representing the field key or value in a key-value pair.

Variables

content (str) – Concatenated content of the key-value element in reading order.
bounding_regions (list[BoundingRegion]) – Bounding regions covering the key-value element.
spans (list[DocumentSpan]) – Location of the key-value element in the reading order of the concatenated content.

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.DocumentKeyValueElement[source]¶

Converts a dict in the shape of a DocumentKeyValueElement to the model itself.

Parameters: data (dict) – A dictionary in the shape of DocumentKeyValueElement.
Returns: DocumentKeyValueElement
Return type: DocumentKeyValueElement

to_dict() → dict [source]¶

Returns a dict representation of DocumentKeyValueElement.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.DocumentKeyValuePair(**kwargs)[source]¶

An object representing a document field with distinct field label (key) and field value (may be empty).

Variables

key (DocumentKeyValueElement) – Field label of the key-value pair.
value (DocumentKeyValueElement) – Field value of the key-value pair.
confidence (float) – Confidence of correctly extracting the key-value pair.

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.DocumentKeyValuePair[source]¶

Converts a dict in the shape of a DocumentKeyValuePair to the model itself.

Parameters: data (dict) – A dictionary in the shape of DocumentKeyValuePair.
Returns: DocumentKeyValuePair
Return type: DocumentKeyValuePair

to_dict() → dict [source]¶

Returns a dict representation of DocumentKeyValuePair.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.DocumentLine(**kwargs)[source]¶

A content line object representing the content found on a single line of the document.

Variables

content (str) – Concatenated content of the contained elements in reading order.
bounding_box (list[Point]) – Bounding box of the line.
spans (list[DocumentSpan]) – Location of the line in the reading order concatenated content.

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.DocumentLine[source]¶

Converts a dict in the shape of a DocumentLine to the model itself.

Parameters: data (dict) – A dictionary in the shape of DocumentLine.
Returns: DocumentLine
Return type: DocumentLine

to_dict() → dict [source]¶

Returns a dict representation of DocumentLine.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.DocumentModel(**kwargs)[source]¶

Document model information. Includes the doc types that the model can analyze.

Variables

model_id (str) – Unique model id.
description (str) – A description for the model.
created_on (datetime) – Date and time (UTC) when the model was created.
doc_types (dict[str, DocTypeInfo]) – Supported document types, including the fields for each document and their types.

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.DocumentModel[source]¶

Converts a dict in the shape of a DocumentModel to the model itself.

Parameters: data (dict) – A dictionary in the shape of DocumentModel.
Returns: DocumentModel
Return type: DocumentModel

to_dict() → dict [source]¶

Returns a dict representation of DocumentModel.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.DocumentModelAdministrationClient(endpoint: str, credential: Union[AzureKeyCredential, TokenCredential], **kwargs: Any)[source]¶

DocumentModelAdministrationClient is the Form Recognizer interface to use for building and managing models.

It provides methods for building models, as well as methods for viewing and deleting models, viewing document model operations, accessing account information, copying models to another Form Recognizer resource, and composing a new model from a collection of existing models.

Note

DocumentModelAdministrationClient should be used with API versions 2021-09-30-preview and up. To use API versions <=v2.1, instantiate a FormTrainingClient.

Parameters

endpoint (str) – Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus2.api.cognitive.microsoft.com).
credential (AzureKeyCredential or TokenCredential) – Credentials needed for the client to connect to Azure. This is an instance of AzureKeyCredential if using an API key or a token credential from azure.identity.

Keyword Arguments

api_version (str or DocumentAnalysisApiVersion) – The API version of the service to use for requests. It defaults to the latest service version. Setting to an older version may result in reduced feature compatibility. To use API versions <=v2.1, instantiate a FormTrainingClient.

New in version 2021-09-30-preview: The DocumentModelAdministrationClient and its client methods.

Example:

Creating the DocumentModelAdministrationClient with an endpoint and API key.¶

from azure.core.credentials import AzureKeyCredential
from azure.ai.formrecognizer import DocumentModelAdministrationClient

endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]

document_model_admin_client = DocumentModelAdministrationClient(endpoint, AzureKeyCredential(key))

Creating the DocumentModelAdministrationClient with a token credential.¶

"""DefaultAzureCredential will use the values from these environment
variables: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET
"""
from azure.ai.formrecognizer import DocumentModelAdministrationClient
from azure.identity import DefaultAzureCredential

endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
credential = DefaultAzureCredential()

document_model_admin_client = DocumentModelAdministrationClient(endpoint, credential)

begin_build_model(source: str, **kwargs: Any) → DocumentModelAdministrationLROPoller[DocumentModel][source]¶

Build a custom model.

The request must include a source parameter that is an externally accessible Azure storage blob container URI (preferably a Shared Access Signature URI). 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.

Parameters

source (str) – An Azure Storage blob container’s SAS URI. A container URI (without SAS) can be used if the container is public. For more information on setting up a training data set, see: https://aka.ms/azsdk/formrecognizer/buildtrainingset

Keyword Arguments

model_id (str) – A unique ID for your model. If not specified, a model ID will be created for you.
description (str) – An optional description to add to the model.
prefix (str) – A case-sensitive prefix string to filter documents in the source 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.
continuation_token (str) – A continuation token to restart a poller from a saved state.

Returns

An instance of an DocumentModelAdministrationLROPoller. Call result() on the poller object to return a DocumentModel.

Return type

DocumentModelAdministrationLROPoller[DocumentModel]

Raises

HttpResponseError –

Example:

Building a model from training files.¶

from azure.ai.formrecognizer import DocumentModelAdministrationClient
from azure.core.credentials import AzureKeyCredential

endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]
container_sas_url = os.environ["CONTAINER_SAS_URL"]

document_model_admin_client = DocumentModelAdministrationClient(endpoint, AzureKeyCredential(key))
poller = document_model_admin_client.begin_build_model(
    container_sas_url, description="my model description"
)
model = poller.result()

print("Model ID: {}".format(model.model_id))
print("Description: {}".format(model.description))
print("Model created on: {}\n".format(model.created_on))
print("Doc types the model can recognize:")
for name, doc_type in model.doc_types.items():
    print("\nDoc Type: '{}' which has the following fields:".format(name))
    for field_name, field in doc_type.field_schema.items():
        print("Field: '{}' has type '{}' and confidence score {}".format(
            field_name, field["type"], doc_type.field_confidence[field_name]
        ))

begin_copy_model(model_id: str, target: Dict, **kwargs: Any) → DocumentModelAdministrationLROPoller[DocumentModel][source]¶

Copy a 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 (with the model that is intended to be copied). The target parameter should be supplied from the target resource’s output from calling the get_copy_authorization() method.

Parameters

model_id (str) – Model identifier of the model to copy to target resource.
target (dict) – The copy authorization generated from the target resource’s call to get_copy_authorization().

Keyword Arguments

continuation_token (str) – A continuation token to restart a poller from a saved state.

Returns

An instance of a DocumentModelAdministrationLROPoller. Call result() on the poller object to return a DocumentModel.

Return type

DocumentModelAdministrationLROPoller[DocumentModel]

Raises

HttpResponseError –

Example:

Copy a model from the source resource to the target resource¶

from azure.core.credentials import AzureKeyCredential
from azure.ai.formrecognizer import DocumentModelAdministrationClient

source_endpoint = os.environ["AZURE_FORM_RECOGNIZER_SOURCE_ENDPOINT"]
source_key = os.environ["AZURE_FORM_RECOGNIZER_SOURCE_KEY"]
target_endpoint = os.environ["AZURE_FORM_RECOGNIZER_TARGET_ENDPOINT"]
target_key = os.environ["AZURE_FORM_RECOGNIZER_TARGET_KEY"]
source_model_id = os.getenv("AZURE_SOURCE_MODEL_ID", custom_model_id)

target_client = DocumentModelAdministrationClient(endpoint=target_endpoint, credential=AzureKeyCredential(target_key))

target = target_client.get_copy_authorization(
    description="model copied from other resource"
)

source_client = DocumentModelAdministrationClient(endpoint=source_endpoint, credential=AzureKeyCredential(source_key))
poller = source_client.begin_copy_model(
    model_id=source_model_id,
    target=target  # output from target client's call to get_copy_authorization()
)
copied_over_model = poller.result()

print("Model ID: {}".format(model.model_id))
print("Description: {}".format(model.description))
print("Model created on: {}\n".format(model.created_on))
print("Doc types the model can recognize:")
for name, doc_type in model.doc_types.items():
    print("\nDoc Type: '{}' which has the following fields:".format(name))
    for field_name, field in doc_type.field_schema.items():
        print("Field: '{}' has type '{}' and confidence score {}".format(
            field_name, field["type"], doc_type.field_confidence[field_name]
        ))

begin_create_composed_model(model_ids: List[str], **kwargs: Any) → DocumentModelAdministrationLROPoller[DocumentModel][source]¶

Creates a composed 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 route it to the correct custom model.

Parameters

model_ids (list[str]) – List of model IDs to use in the composed model.

Keyword Arguments

model_id (str) – A unique ID for your composed model. If not specified, a model ID will be created for you.
description (str) – An optional description to add to the model.
continuation_token (str) – A continuation token to restart a poller from a saved state.

Returns

An instance of an DocumentModelAdministrationLROPoller. Call result() on the poller object to return a DocumentModel.

Return type

DocumentModelAdministrationLROPoller[DocumentModel]

Raises

HttpResponseError –

Example:

Creating a composed model with existing models.¶

from azure.core.credentials import AzureKeyCredential
from azure.ai.formrecognizer import DocumentModelAdministrationClient

endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]
po_supplies = os.environ['PURCHASE_ORDER_OFFICE_SUPPLIES_SAS_URL']
po_equipment = os.environ['PURCHASE_ORDER_OFFICE_EQUIPMENT_SAS_URL']
po_furniture = os.environ['PURCHASE_ORDER_OFFICE_FURNITURE_SAS_URL']
po_cleaning_supplies = os.environ['PURCHASE_ORDER_OFFICE_CLEANING_SUPPLIES_SAS_URL']

document_model_admin_client = DocumentModelAdministrationClient(endpoint=endpoint, credential=AzureKeyCredential(key))
supplies_poller = document_model_admin_client.begin_build_model(
    po_supplies, description="Purchase order-Office supplies"
)
equipment_poller = document_model_admin_client.begin_build_model(
    po_equipment, description="Purchase order-Office Equipment"
)
furniture_poller = document_model_admin_client.begin_build_model(
    po_furniture, description="Purchase order-Furniture"
)
cleaning_supplies_poller = document_model_admin_client.begin_build_model(
    po_cleaning_supplies, description="Purchase order-Cleaning Supplies"
)
supplies_model = supplies_poller.result()
equipment_model = equipment_poller.result()
furniture_model = furniture_poller.result()
cleaning_supplies_model = cleaning_supplies_poller.result()

purchase_order_models = [
    supplies_model.model_id,
    equipment_model.model_id,
    furniture_model.model_id,
    cleaning_supplies_model.model_id
]

poller = document_model_admin_client.begin_create_composed_model(
    purchase_order_models, description="Office Supplies Composed Model"
)
model = poller.result()

print("Office Supplies Composed Model Info:")
print("Model ID: {}".format(model.model_id))
print("Description: {}".format(model.description))
print("Model created on: {}\n".format(model.created_on))
print("Doc types the model can recognize:")
for name, doc_type in model.doc_types.items():
    print("\nDoc Type: '{}' which has the following fields:".format(name))
    for field_name, field in doc_type.field_schema.items():
        print("Field: '{}' has type '{}' and confidence score {}".format(
            field_name, field["type"], doc_type.field_confidence[field_name]
        ))

close() → None [source]¶: Close the DocumentModelAdministrationClient session.

delete_model(model_id: str, **kwargs: Any) → None [source]¶

Delete a custom model.

Parameters: model_id (str) – Model identifier.
Return type: None
Raises: HttpResponseError or ResourceNotFoundError –

Example:

Delete a model.¶

document_model_admin_client.delete_model(model_id=my_model.model_id)

try:
    document_model_admin_client.get_model(model_id=my_model.model_id)
except ResourceNotFoundError:
    print("Successfully deleted model with ID {}".format(my_model.model_id))

get_account_info(**kwargs: Any) → AccountInfo [source]¶

Get information about the models under the Form Recognizer resource.

Returns: Summary of models under the resource - model count and limit.
Return type: AccountInfo
Raises: HttpResponseError –

Example:

Get model counts and limits under the Form Recognizer resource.¶

document_model_admin_client = DocumentModelAdministrationClient(endpoint=endpoint, credential=AzureKeyCredential(key))

account_info = document_model_admin_client.get_account_info()
print("Our account has {} custom models, and we can have at most {} custom models\n".format(
    account_info.model_count, account_info.model_limit
))

get_copy_authorization(**kwargs: Any) → Dict[str, str][source]¶

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 begin_copy_model().

Keyword Arguments

model_id (str) – A unique ID for your copied model. If not specified, a model ID will be created for you.
description (str) – An optional description to add to the model.

Returns

A dictionary with values necessary for the copy authorization.

Return type

Dict[str, str]

Raises

HttpResponseError –

get_document_analysis_client(**kwargs: Any) → azure.ai.formrecognizer._document_analysis_client.DocumentAnalysisClient[source]¶

Get an instance of a DocumentAnalysisClient from DocumentModelAdministrationClient.

Return type: DocumentAnalysisClient
Returns: A DocumentAnalysisClient

get_model(model_id: str, **kwargs: Any) → DocumentModel [source]¶

Get a model by its ID.

Parameters: model_id (str) – Model identifier.
Returns: DocumentModel
Return type: DocumentModel
Raises: HttpResponseError or ResourceNotFoundError –

Example:

Get a model by its ID.¶

my_model = document_model_admin_client.get_model(model_id=model.model_id)
print("\nModel ID: {}".format(my_model.model_id))
print("Description: {}".format(my_model.description))
print("Model created on: {}".format(my_model.created_on))

get_operation(operation_id: str, **kwargs: Any) → ModelOperation [source]¶

Get a document model 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 get_model() or list_models() APIs.

Parameters: operation_id (str) – The operation ID.
Returns: ModelOperation
Return type: ModelOperation
Raises: HttpResponseError –

Example:

Get a document model operation by its ID.¶

# Get an operation by ID
print("\nGetting operation info by ID: {}".format(operations[0].operation_id))
operation_info = document_model_admin_client.get_operation(operations[0].operation_id)
if operation_info.status == "succeeded":
    print("My {} operation is completed.".format(operation_info.kind))
    result = operation_info.result
    print("Model ID: {}".format(result.model_id))
elif operation_info.status == "failed":
    print("My {} operation failed.".format(operation_info.kind))
    error = operation_info.error
    print("{}: {}".format(error.code, error.message))
else:
    print("My operation status is {}".format(operation_info.status))

list_models(**kwargs: Any) → ItemPaged[DocumentModelInfo][source]¶

List information for each model, including its model ID, description, and when it was created.

Returns: Pageable of DocumentModelInfo.
Return type: ItemPaged[DocumentModelInfo]
Raises: HttpResponseError –

Example:

List all models that were built successfully under the Form Recognizer resource.¶

models = document_model_admin_client.list_models()

print("We have the following 'ready' models with IDs and descriptions:")
for model in models:
    print("{} | {}".format(model.model_id, model.description))

list_operations(**kwargs: Any) → ItemPaged[ModelOperationInfo][source]¶

List information for each document model 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 get_model() or list_models() APIs.

Returns: A pageable of ModelOperationInfo.
Return type: ItemPaged[ModelOperationInfo]
Raises: HttpResponseError –

Example:

List all document model operations in the past 24 hours.¶

from azure.core.credentials import AzureKeyCredential
from azure.ai.formrecognizer import DocumentModelAdministrationClient

endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]

document_model_admin_client = DocumentModelAdministrationClient(endpoint=endpoint, credential=AzureKeyCredential(key))

operations = list(document_model_admin_client.list_operations())

print("The following document model operations exist under my resource:")
for operation in operations:
    print("\nOperation ID: {}".format(operation.operation_id))
    print("Operation kind: {}".format(operation.kind))
    print("Operation status: {}".format(operation.status))
    print("Operation percent completed: {}".format(operation.percent_completed))
    print("Operation created on: {}".format(operation.created_on))
    print("Operation last updated on: {}".format(operation.last_updated_on))
    print("Resource location of successful operation: {}".format(operation.resource_location))

class azure.ai.formrecognizer.DocumentModelAdministrationLROPoller(client: Any, initial_response: Any, deserialization_callback: Callable, polling_method: PollingMethod[PollingReturnType])[source]¶

Custom poller for model build operations. Call result() on the poller to return a DocumentModel.

New in version 2021-09-30-preview: The DocumentModelAdministrationLROPoller poller object

add_done_callback(func: Callable) → None ¶

Add callback function to be run once the long running operation has completed - regardless of the status of the operation.

Parameters: func (callable) – Callback function that takes at least one argument, a completed LongRunningOperation.

continuation_token() → str ¶

Return a continuation token that allows to restart the poller later.

Returns: An opaque continuation token
Return type: str

done() → bool ¶

Check status of the long running operation.

Returns: ‘True’ if the process has completed, else ‘False’.
Return type: bool

classmethod from_continuation_token(polling_method: azure.core.polling._poller.PollingMethod[PollingReturnType], continuation_token: str, **kwargs: Any) → azure.ai.formrecognizer._polling.DocumentModelAdministrationLROPoller[source]¶

polling_method() → azure.core.polling._poller.PollingMethod[PollingReturnType]¶: Return the polling method associated to this poller.

remove_done_callback(func: Callable) → None ¶

Remove a callback from the long running operation.

Parameters: func (callable) – The function to be removed from the callbacks.
Raises: ValueError – if the long running operation has already completed.

result(timeout: Optional[int] = None) → PollingReturnType¶

Return the result of the long running operation, or the result available after the specified timeout.

Returns: The deserialized resource of the long running operation, if one is available.
Raises: HttpResponseError – Server problem with the query.

status() → str ¶

Returns the current status string.

Returns: The current status string
Return type: str

wait(timeout: Optional[int] = None) → None ¶

Wait on the long running operation for a specified length of time. You can check if this call as ended with timeout with the “done()” method.

Parameters: timeout (int) – Period of time to wait for the long running operation to complete (in seconds).
Raises: HttpResponseError – Server problem with the query.

property created_on¶

Date and time (UTC) when the operation was created.

Return type: datetime

property last_updated_on¶

Date and time (UTC) when the operation was last updated.

Return type: datetime

property operation_id¶

The operation ID of the model operation.

Return type: str

property operation_kind¶

The model operation kind. For example, ‘documentModelBuild’, ‘documentModelCompose’, ‘documentModelCopyTo’.

Return type: str

property percent_completed¶

Operation progress (0-100).

Return type: int

property resource_location_url¶

URL of the resource targeted by this operation.

Return type: str

class azure.ai.formrecognizer.DocumentModelInfo(**kwargs)[source]¶

Document model information including the model ID, its description, and when the model was created.

Variables

model_id (str) – Unique model id.
description (str) – A description for the model.
created_on (datetime) – Date and time (UTC) when the model was created.

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.DocumentModelInfo[source]¶

Converts a dict in the shape of a DocumentModelInfo to the model itself.

Parameters: data (dict) – A dictionary in the shape of DocumentModelInfo.
Returns: DocumentModelInfo
Return type: DocumentModelInfo

to_dict() → dict [source]¶

Returns a dict representation of DocumentModelInfo.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.DocumentPage(**kwargs)[source]¶

Content and layout elements extracted from a page of the input.

Variables

page_number (int) – 1-based page number in the input document.
angle (float) – The general orientation of the content in clockwise direction, measured in degrees between (-180, 180].
width (float) – The width of the image/PDF in pixels/inches, respectively.
height (float) – The height of the image/PDF in pixels/inches, respectively.
unit (str) – The unit used by the width, height, and boundingBox properties. For images, the unit is “pixel”. For PDF, the unit is “inch”. Possible values include: “pixel”, “inch”.
spans (list[DocumentSpan]) – Location of the page in the reading order concatenated content.
words (list[DocumentWord]) – Extracted words from the page.
selection_marks (list[DocumentSelectionMark]) – Extracted selection marks from the page.
lines (list[DocumentLine]) – Extracted lines from the page, potentially containing both textual and visual elements.

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.DocumentPage[source]¶

Converts a dict in the shape of a DocumentPage to the model itself.

Parameters: data (dict) – A dictionary in the shape of DocumentPage.
Returns: DocumentPage
Return type: DocumentPage

to_dict() → dict [source]¶

Returns a dict representation of DocumentPage.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.DocumentSelectionMark(**kwargs)[source]¶

A selection mark object representing check boxes, radio buttons, and other elements indicating a selection.

Variables

state (str) – State of the selection mark. Possible values include: “selected”, “unselected”.
content (str) – The text content - not returned for DocumentSelectionMark.
bounding_box (list[Point]) – Bounding box of the selection mark.
span (DocumentSpan) – Location of the selection mark in the reading order concatenated content.
confidence (float) – Confidence of correctly extracting the selection mark.
kind (str) – For DocumentSelectionMark, this is “selectionMark”.

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.DocumentSelectionMark[source]¶

Converts a dict in the shape of a DocumentSelectionMark to the model itself.

Parameters: data (dict) – A dictionary in the shape of DocumentSelectionMark.
Returns: DocumentSelectionMark
Return type: DocumentSelectionMark

to_dict() → dict [source]¶

Returns a dict representation of DocumentSelectionMark.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.DocumentSpan(**kwargs)[source]¶

Contiguous region of the content of the property, specified as an offset and length.

Variables

offset (int) – Zero-based index of the content represented by the span.
length (int) – Number of characters in the content represented by the span.

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.DocumentSpan[source]¶

Converts a dict in the shape of a DocumentSpan to the model itself.

Parameters: data (dict) – A dictionary in the shape of DocumentSpan.
Returns: DocumentSpan
Return type: DocumentSpan

to_dict() → dict [source]¶

Returns a dict representation of DocumentSpan.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.DocumentStyle(**kwargs)[source]¶

An object representing observed text styles.

Variables

is_handwritten (bool) – Is content handwritten?.
spans (list[DocumentSpan]) – Location of the text elements in the concatenated content the style applies to.
confidence (float) – Confidence of correctly identifying the style.

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.DocumentStyle[source]¶

Converts a dict in the shape of a DocumentStyle to the model itself.

Parameters: data (dict) – A dictionary in the shape of DocumentStyle.
Returns: DocumentStyle
Return type: DocumentStyle

to_dict() → dict [source]¶

Returns a dict representation of DocumentStyle.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.DocumentTable(**kwargs)[source]¶

A table object consisting table cells arranged in a rectangular layout.

Variables

row_count (int) – Number of rows in the table.
column_count (int) – Number of columns in the table.
cells (list[DocumentTableCell]) – Cells contained within the table.
bounding_regions (list[BoundingRegion]) – Bounding regions covering the table.
spans (list[DocumentSpan]) – Location of the table in the reading order concatenated content.

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.DocumentTable[source]¶

Converts a dict in the shape of a DocumentTable to the model itself.

Parameters: data (dict) – A dictionary in the shape of DocumentTable.
Returns: DocumentTable
Return type: DocumentTable

to_dict() → dict [source]¶

Returns a dict representation of DocumentTable.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.DocumentTableCell(**kwargs)[source]¶

An object representing the location and content of a table cell.

Variables

kind (str) – Table cell kind. Possible values include: “content”, “rowHeader”, “columnHeader”, “stubHead”, “description”. Default value: “content”.
row_index (int) – Row index of the cell.
column_index (int) – Column index of the cell.
row_span (int) – Number of rows spanned by this cell.
column_span (int) – Number of columns spanned by this cell.
content (str) – Concatenated content of the table cell in reading order.
bounding_regions (list[BoundingRegion]) – Bounding regions covering the table cell.
spans (list[DocumentSpan]) – Location of the table cell in the reading order concatenated content.

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.DocumentTableCell[source]¶

Converts a dict in the shape of a DocumentTableCell to the model itself.

Parameters: data (dict) – A dictionary in the shape of DocumentTableCell.
Returns: DocumentTableCell
Return type: DocumentTableCell

to_dict() → dict [source]¶

Returns a dict representation of DocumentTableCell.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.DocumentWord(**kwargs)[source]¶

A word object consisting of a contiguous sequence of characters. For non-space delimited languages, such as Chinese, Japanese, and Korean, each character is represented as its own word.

Variables

content (str) – Text content of the word.
bounding_box (list[Point]) – Bounding box of the word.
span (DocumentSpan) – Location of the word in the reading order concatenated content.
confidence (float) – Confidence of correctly extracting the word.
kind (str) – For DocumentWord, this is “word”.

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.DocumentWord[source]¶

Converts a dict in the shape of a DocumentWord to the model itself.

Parameters: data (dict) – A dictionary in the shape of DocumentWord.
Returns: DocumentWord
Return type: DocumentWord

to_dict() → dict [source]¶

Returns a dict representation of DocumentWord.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.FieldData(**kwargs)[source]¶

Contains the data for the form field. This includes the text, location of the text on the form, and a collection of the elements that make up the text.

Variables

page_number (int) – The 1-based number of the page in which this content is present.
text (str) – The string representation of the field or value.
bounding_box (list[Point]) – A list of 4 points representing the quadrilateral bounding box 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.
field_elements (list[Union[FormElement, FormWord, FormLine, FormSelectionMark]]) – When include_field_elements is set to true, a list of elements constituting this field or value is returned. The list constitutes of elements such as lines, words, and selection marks.

New in version v2.1: FormSelectionMark is added to the types returned in the list of field_elements, support for to_dict and from_dict methods

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.FieldData[source]¶

Converts a dict in the shape of a FieldData to the model itself.

Parameters: data (dict) – A dictionary in the shape of FieldData.
Returns: FieldData
Return type: FieldData

to_dict() → dict [source]¶

Returns a dict representation of FieldData.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.FieldValueType(value)[source]¶

Semantic data type of the field value.

New in version v2.1: The selectionMark and countryRegion values

COUNTRY_REGION = 'countryRegion'¶

DATE = 'date'¶

DICTIONARY = 'dictionary'¶

FLOAT = 'float'¶

INTEGER = 'integer'¶

LIST = 'list'¶

PHONE_NUMBER = 'phoneNumber'¶

SELECTION_MARK = 'selectionMark'¶

STRING = 'string'¶

TIME = 'time'¶

class azure.ai.formrecognizer.FormContentType(value)[source]¶

Content type for upload.

New in version v2.1: Support for image/bmp

APPLICATION_PDF = 'application/pdf'¶

IMAGE_BMP = 'image/bmp'¶

IMAGE_JPEG = 'image/jpeg'¶

IMAGE_PNG = 'image/png'¶

IMAGE_TIFF = 'image/tiff'¶

class azure.ai.formrecognizer.FormElement(**kwargs)[source]¶

Base type which includes properties for a form element.

Variables

text (str) – The text content of the element.
bounding_box (list[Point]) – A list of 4 points representing the quadrilateral bounding box 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.
page_number (int) – The 1-based number of the page in which this content is present.
kind (str) – The kind of form element. Possible kinds are “word”, “line”, or “selectionMark” which correspond to a FormWord FormLine, or FormSelectionMark, respectively.

New in version v2.1: Support for to_dict and from_dict methods

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.FormElement[source]¶

Converts a dict in the shape of a FormElement to the model itself.

Parameters: data (dict) – A dictionary in the shape of FormElement.
Returns: FormElement
Return type: FormElement

to_dict() → dict [source]¶

Returns a dict representation of FormElement.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.FormField(**kwargs)[source]¶

Represents a field recognized in an input form.

Variables

value_type (str) – The type of value found on FormField. Described in FieldValueType, possible types include: ‘string’, ‘date’, ‘time’, ‘phoneNumber’, ‘float’, ‘integer’, ‘dictionary’, ‘list’, ‘selectionMark’, or ‘countryRegion’.
label_data (FieldData) – Contains the text, bounding box, and field elements for the field label. Note that this is not returned for forms analyzed by models trained with labels.
value_data (FieldData) – Contains the text, bounding box, and field elements for the field value.
name (str) – The unique name of the field or the training-time label if analyzed from a custom model that was trained with labels.
value (str, int, float, date, time, dict[str, FormField], or list[FormField]) – The value for the recognized field. Its semantic data type is described by value_type. If the value is extracted from the form, but cannot be normalized to its type, then access the value_data.text property for a textual representation of the value.
confidence (float) – Measures the degree of certainty of the recognition result. Value is between [0.0, 1.0].

New in version v2.1: Support for to_dict and from_dict methods

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.FormField[source]¶

Converts a dict in the shape of a FormField to the model itself.

Parameters: data (dict) – A dictionary in the shape of FormField.
Returns: FormField
Return type: FormField

to_dict() → dict [source]¶

Returns a dict representation of FormField.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.FormLine(**kwargs)[source]¶

An object representing an extracted line of text.

Variables

text (str) – The text content of the line.
bounding_box (list[Point]) – A list of 4 points representing the quadrilateral bounding box 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.
words (list[FormWord]) – A list of the words that make up the line.
page_number (int) – The 1-based number of the page in which this content is present.
kind (str) – For FormLine, this is “line”.
appearance (Appearance) – An object representing the appearance of the line.

New in version v2.1: appearance property, support for to_dict and from_dict methods

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.FormLine[source]¶

Converts a dict in the shape of a FormLine to the model itself.

Parameters: data (dict) – A dictionary in the shape of FormLine.
Returns: FormLine
Return type: FormLine

to_dict() → dict [source]¶

Returns a dict representation of FormLine.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.FormPage(**kwargs)[source]¶

Represents a page recognized from the input document. Contains lines, words, selection marks, tables and page metadata.

Variables

page_number (int) – The 1-based number of the page in which this content is present.
text_angle (float) – The general orientation of the text in clockwise direction, measured in degrees between (-180, 180].
width (float) – The width of the image/PDF in pixels/inches, respectively.
height (float) – The height of the image/PDF in pixels/inches, respectively.
unit (str) – The LengthUnit used by the width, height, and bounding box properties. For images, the unit is “pixel”. For PDF, the unit is “inch”.
tables (list[FormTable]) – A list of extracted tables contained in a page.
lines (list[FormLine]) – 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 the detected text, it may change across images and OCR version updates. Thus, business logic should be built upon the actual line location instead of order. The reading order of lines can be specified by the reading_order keyword argument (Note: reading_order only supported in begin_recognize_content and begin_recognize_content_from_url).
selection_marks (list[FormSelectionMark]) – List of selection marks extracted from the page.

New in version v2.1: selection_marks property, support for to_dict and from_dict methods

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.FormPage[source]¶

Converts a dict in the shape of a FormPage to the model itself.

Parameters: data (dict) – A dictionary in the shape of FormPage.
Returns: FormPage
Return type: FormPage

to_dict() → dict [source]¶

Returns a dict representation of FormPage.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.FormPageRange(first_page_number, last_page_number)[source]¶

The 1-based page range of the form.

Variables

first_page_number (int) – The first page number of the form.
last_page_number (int) – The last page number of the form.

New in version v2.1: Support for to_dict and from_dict methods

Create new instance of FormPageRange(first_page_number, last_page_number)

count(value) → integer – return number of occurrences of value¶

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.FormPageRange[source]¶

Converts a dict in the shape of a FormPageRange to the model itself.

Parameters: data (dict) – A dictionary in the shape of FormPageRange.
Returns: FormPageRange
Return type: FormPageRange

index(value[, start[, stop]]) → integer – return first index of value.¶: Raises ValueError if the value is not present.

to_dict() → dict [source]¶

Returns a dict representation of FormPageRange.

Returns: dict
Return type: dict

property first_page_number¶: Alias for field number 0

property last_page_number¶: Alias for field number 1

class azure.ai.formrecognizer.FormRecognizerApiVersion(value)[source]¶

Form Recognizer API versions supported by FormRecognizerClient and FormTrainingClient.

V2_0 = '2.0'¶

V2_1 = '2.1'¶: This is the default version

class azure.ai.formrecognizer.FormRecognizerClient(endpoint: str, credential: Union[AzureKeyCredential, TokenCredential], **kwargs: Any)[source]¶

FormRecognizerClient extracts information from forms and images into structured data. It is the interface to use for analyzing with prebuilt models (receipts, business cards, invoices, identity documents), recognizing content/layout from forms, and analyzing custom forms from trained models. It provides different methods based on inputs from a URL and inputs from a stream.

Note

FormRecognizerClient should be used with API versions <=v2.1. To use API versions 2021-09-30-preview and up, instantiate a DocumentAnalysisClient.

Parameters

endpoint (str) – Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus2.api.cognitive.microsoft.com).
credential (AzureKeyCredential or TokenCredential) – Credentials needed for the client to connect to Azure. This is an instance of AzureKeyCredential if using an API key or a token credential from azure.identity.

Keyword Arguments

api_version (str or FormRecognizerApiVersion) – The API version of the service to use for requests. It defaults to API version v2.1. Setting to an older version may result in reduced feature compatibility. To use the latest supported API version and features, instantiate a DocumentAnalysisClient instead.

Example:

Creating the FormRecognizerClient with an endpoint and API key.¶

from azure.core.credentials import AzureKeyCredential
from azure.ai.formrecognizer import FormRecognizerClient
endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]

form_recognizer_client = FormRecognizerClient(endpoint, AzureKeyCredential(key))

Creating the FormRecognizerClient with a token credential.¶

"""DefaultAzureCredential will use the values from these environment
variables: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET
"""
from azure.ai.formrecognizer import FormRecognizerClient
from azure.identity import DefaultAzureCredential

endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
credential = DefaultAzureCredential()

form_recognizer_client = FormRecognizerClient(endpoint, credential)

begin_recognize_business_cards(business_card: Union[bytes, IO[bytes]], **kwargs: Any) → LROPoller[List[RecognizedForm]][source]¶

Extract field text and semantic values from a given business card. 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 a business card here: https://aka.ms/formrecognizer/businesscardfields

Parameters

business_card (bytes or IO[bytes]) – JPEG, PNG, PDF, TIFF, or BMP type file stream or bytes.

Keyword Arguments

locale (str) – Locale of the business card. Supported locales include: en-US, en-AU, en-CA, en-GB, and en-IN.
include_field_elements (bool) – Whether or not to include all lines per page and field elements such as lines, words, and selection marks for each form field.
pages (list[str]) – Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=[“1-3”, “5-6”]. Separate each page number or range with a comma.
content_type (str or FormContentType) – Content-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 FormContentType.
continuation_token (str) – A continuation token to restart a poller from a saved state.

Returns

An instance of an LROPoller. Call result() on the poller object to return a list[RecognizedForm].

Return type

LROPoller[list[RecognizedForm]]

Raises

HttpResponseError –

New in version v2.1: The begin_recognize_business_cards client method

Example:

Recognize business cards from a file.¶

from azure.core.credentials import AzureKeyCredential
from azure.ai.formrecognizer import FormRecognizerClient

endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]

form_recognizer_client = FormRecognizerClient(
    endpoint=endpoint, credential=AzureKeyCredential(key)
)
with open(path_to_sample_forms, "rb") as f:
    poller = form_recognizer_client.begin_recognize_business_cards(business_card=f, locale="en-US")
business_cards = poller.result()

for idx, business_card in enumerate(business_cards):
    print("--------Recognizing business card #{}--------".format(idx+1))
    contact_names = business_card.fields.get("ContactNames")
    if contact_names:
        for contact_name in contact_names.value:
            print("Contact First Name: {} has confidence: {}".format(
                contact_name.value["FirstName"].value, contact_name.value["FirstName"].confidence
            ))
            print("Contact Last Name: {} has confidence: {}".format(
                contact_name.value["LastName"].value, contact_name.value["LastName"].confidence
            ))
    company_names = business_card.fields.get("CompanyNames")
    if company_names:
        for company_name in company_names.value:
            print("Company Name: {} has confidence: {}".format(company_name.value, company_name.confidence))
    departments = business_card.fields.get("Departments")
    if departments:
        for department in departments.value:
            print("Department: {} has confidence: {}".format(department.value, department.confidence))
    job_titles = business_card.fields.get("JobTitles")
    if job_titles:
        for job_title in job_titles.value:
            print("Job Title: {} has confidence: {}".format(job_title.value, job_title.confidence))
    emails = business_card.fields.get("Emails")
    if emails:
        for email in emails.value:
            print("Email: {} has confidence: {}".format(email.value, email.confidence))
    websites = business_card.fields.get("Websites")
    if websites:
        for website in websites.value:
            print("Website: {} has confidence: {}".format(website.value, website.confidence))
    addresses = business_card.fields.get("Addresses")
    if addresses:
        for address in addresses.value:
            print("Address: {} has confidence: {}".format(address.value, address.confidence))
    mobile_phones = business_card.fields.get("MobilePhones")
    if mobile_phones:
        for phone in mobile_phones.value:
            print("Mobile phone number: {} has confidence: {}".format(phone.value, phone.confidence))
    faxes = business_card.fields.get("Faxes")
    if faxes:
        for fax in faxes.value:
            print("Fax number: {} has confidence: {}".format(fax.value, fax.confidence))
    work_phones = business_card.fields.get("WorkPhones")
    if work_phones:
        for work_phone in work_phones.value:
            print("Work phone number: {} has confidence: {}".format(work_phone.value, work_phone.confidence))
    other_phones = business_card.fields.get("OtherPhones")
    if other_phones:
        for other_phone in other_phones.value:
            print("Other phone number: {} has confidence: {}".format(other_phone.value, other_phone.confidence))

begin_recognize_business_cards_from_url(business_card_url: str, **kwargs: Any) → LROPoller[List[RecognizedForm]][source]¶

Extract field text and semantic values from a given business card. The input document must be the location (URL) of the card to be analyzed.

See fields found on a business card here: https://aka.ms/formrecognizer/businesscardfields

Parameters

business_card_url (str) – The URL of the business card to analyze. The input must be a valid, encoded URL of one of the supported formats: JPEG, PNG, PDF, TIFF, or BMP.

Keyword Arguments

locale (str) – Locale of the business card. Supported locales include: en-US, en-AU, en-CA, en-GB, and en-IN.
include_field_elements (bool) – Whether or not to include all lines per page and field elements such as lines, words, and selection marks for each form field.
pages (list[str]) – Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=[“1-3”, “5-6”]. Separate each page number or range with a comma.
continuation_token (str) – A continuation token to restart a poller from a saved state.

Returns

An instance of an LROPoller. Call result() on the poller object to return a list[RecognizedForm].

Return type

LROPoller[list[RecognizedForm]]

Raises

HttpResponseError –

New in version v2.1: The begin_recognize_business_cards_from_url client method

begin_recognize_content(form: Union[bytes, IO[bytes]], **kwargs: Any) → LROPoller[List[FormPage]][source]¶

Extract text and content/layout information from a given document. The input document must be of one of the supported content types - ‘application/pdf’, ‘image/jpeg’, ‘image/png’, ‘image/tiff’ or ‘image/bmp’.

Parameters

form (bytes or IO[bytes]) – JPEG, PNG, PDF, TIFF, or BMP type file stream or bytes.

Keyword Arguments

pages (list[str]) – Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=[“1-3”, “5-6”]. Separate each page number or range with a comma.
language (str) – The BCP-47 language code of the text in the document. See supported language codes here: https://docs.microsoft.com/azure/cognitive-services/form-recognizer/language-support. Content supports auto language identification and multilanguage documents, so only provide a language code if you would like to force the documented to be processed as that specific language.
reading_order (str) – Reading order algorithm to sort the text lines returned. Supported reading orders include: basic (default), natural. Set ‘basic’ to sort lines left to right and top to bottom, although in some cases proximity is treated with higher priority. Set ‘natural’ to sort lines by using positional information to keep nearby lines together.
content_type (str or FormContentType) – Content-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 FormContentType.
continuation_token (str) – A continuation token to restart a poller from a saved state.

Returns

An instance of an LROPoller. Call result() on the poller object to return a list[FormPage].

Return type

LROPoller[list[FormPage]]

Raises

HttpResponseError –

New in version v2.1: The pages, language and reading_order keyword arguments and support for image/bmp content

Example:

Recognize text and content/layout information from a form.¶

from azure.core.credentials import AzureKeyCredential
from azure.ai.formrecognizer import FormRecognizerClient

endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]

form_recognizer_client = FormRecognizerClient(endpoint=endpoint, credential=AzureKeyCredential(key))
with open(path_to_sample_forms, "rb") as f:
    poller = form_recognizer_client.begin_recognize_content(form=f)
form_pages = poller.result()

for idx, content in enumerate(form_pages):
    print("----Recognizing content from page #{}----".format(idx+1))
    print("Page has width: {} and height: {}, measured with unit: {}".format(
        content.width,
        content.height,
        content.unit
    ))
    for table_idx, table in enumerate(content.tables):
        print("Table # {} has {} rows and {} columns".format(table_idx, table.row_count, table.column_count))
        print("Table # {} location on page: {}".format(table_idx, format_bounding_box(table.bounding_box)))
        for cell in table.cells:
            print("...Cell[{}][{}] has text '{}' within bounding box '{}'".format(
                cell.row_index,
                cell.column_index,
                cell.text,
                format_bounding_box(cell.bounding_box)
            ))

    for line_idx, line in enumerate(content.lines):
        print("Line # {} has word count '{}' and text '{}' within bounding box '{}'".format(
            line_idx,
            len(line.words),
            line.text,
            format_bounding_box(line.bounding_box)
        ))
        if line.appearance:
            if line.appearance.style_name == "handwriting" and line.appearance.style_confidence > 0.8:
                print("Text line '{}' is handwritten and might be a signature.".format(line.text))
        for word in line.words:
            print("...Word '{}' has a confidence of {}".format(word.text, word.confidence))

    for selection_mark in content.selection_marks:
        print("Selection mark is '{}' within bounding box '{}' and has a confidence of {}".format(
            selection_mark.state,
            format_bounding_box(selection_mark.bounding_box),
            selection_mark.confidence
        ))
    print("----------------------------------------")

begin_recognize_content_from_url(form_url: str, **kwargs: Any) → LROPoller[List[FormPage]][source]¶

Extract text and layout information from a given document. The input document must be the location (URL) of the document to be analyzed.

Parameters

form_url (str) – The URL of the form to analyze. The input must be a valid, encoded URL of one of the supported formats: JPEG, PNG, PDF, TIFF, or BMP.

Keyword Arguments

pages (list[str]) – Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=[“1-3”, “5-6”]. Separate each page number or range with a comma.
language (str) – The BCP-47 language code of the text in the document. See supported language codes here: https://docs.microsoft.com/azure/cognitive-services/form-recognizer/language-support. Content supports auto language identification and multilanguage documents, so only provide a language code if you would like to force the documented to be processed as that specific language.
reading_order (str) – Reading order algorithm to sort the text lines returned. Supported reading orders include: basic (default), natural. Set ‘basic’ to sort lines left to right and top to bottom, although in some cases proximity is treated with higher priority. Set ‘natural’ to sort lines by using positional information to keep nearby lines together.
continuation_token (str) – A continuation token to restart a poller from a saved state.

Returns

An instance of an LROPoller. Call result() on the poller object to return a list[FormPage].

Return type

LROPoller[list[FormPage]]

Raises

HttpResponseError –

New in version v2.1: The pages, language and reading_order keyword arguments and support for image/bmp content

begin_recognize_custom_forms(model_id: str, form: Union[bytes, IO[bytes]], **kwargs: Any) → LROPoller[List[RecognizedForm]][source]¶

Analyze a custom form with a model trained with or without labels. The form to analyze should be of the same type as the forms that were used to train the model. The input document must be of one of the supported content types - ‘application/pdf’, ‘image/jpeg’, ‘image/png’, ‘image/tiff’, or ‘image/bmp’.

Parameters

model_id (str) – Custom model identifier.
form (bytes or IO[bytes]) – JPEG, PNG, PDF, TIFF, or BMP type file stream or bytes.

Keyword Arguments

include_field_elements (bool) – Whether or not to include all lines per page and field elements such as lines, words, and selection marks for each form field.
content_type (str or FormContentType) – Content-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 FormContentType.
pages (list[str]) – Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=[“1-3”, “5-6”]. Separate each page number or range with a comma.
continuation_token (str) – A continuation token to restart a poller from a saved state.

Returns

An instance of an LROPoller. Call result() on the poller object to return a list[RecognizedForm].

Return type

LROPoller[list[RecognizedForm]

Raises

HttpResponseError –

Example:

Recognize fields and values from a custom form.¶

from azure.core.credentials import AzureKeyCredential
from azure.ai.formrecognizer import FormRecognizerClient

endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]
model_id = os.getenv("CUSTOM_TRAINED_MODEL_ID", custom_model_id)

form_recognizer_client = FormRecognizerClient(
    endpoint=endpoint, credential=AzureKeyCredential(key)
)

# Make sure your form's type is included in the list of form types the custom model can recognize
with open(path_to_sample_forms, "rb") as f:
    poller = form_recognizer_client.begin_recognize_custom_forms(
        model_id=model_id, form=f, include_field_elements=True
    )
forms = poller.result()

for idx, form in enumerate(forms):
    print("--------Recognizing Form #{}--------".format(idx+1))
    print("Form has type {}".format(form.form_type))
    print("Form has form type confidence {}".format(form.form_type_confidence))
    print("Form was analyzed with model with ID {}".format(form.model_id))
    for name, field in form.fields.items():
        # each field is of type FormField
        # label_data is populated if you are using a model trained without labels,
        # since the service needs to make predictions for labels if not explicitly given to it.
        if field.label_data:
            print("...Field '{}' has label '{}' with a confidence score of {}".format(
                name,
                field.label_data.text,
                field.confidence
            ))

        print("...Label '{}' has value '{}' with a confidence score of {}".format(
            field.label_data.text if field.label_data else name, field.value, field.confidence
        ))

    # iterate over tables, lines, and selection marks on each page
    for page in form.pages:
        for i, table in enumerate(page.tables):
            print("\nTable {} on page {}".format(i+1, table.page_number))
            for cell in table.cells:
                print("...Cell[{}][{}] has text '{}' with confidence {}".format(
                    cell.row_index, cell.column_index, cell.text, cell.confidence
                ))
        print("\nLines found on page {}".format(page.page_number))
        for line in page.lines:
            print("...Line '{}' is made up of the following words: ".format(line.text))
            for word in line.words:
                print("......Word '{}' has a confidence of {}".format(
                    word.text,
                    word.confidence
                ))
        if page.selection_marks:
            print("\nSelection marks found on page {}".format(page.page_number))
            for selection_mark in page.selection_marks:
                print("......Selection mark is '{}' and has a confidence of {}".format(
                    selection_mark.state,
                    selection_mark.confidence
                ))

    print("-----------------------------------")

begin_recognize_custom_forms_from_url(model_id: str, form_url: str, **kwargs: Any) → LROPoller[List[RecognizedForm]][source]¶

Analyze a custom form with a model trained with or without labels. The form to analyze should be of the same type as the forms that were used to train the model. The input document must be the location (URL) of the document to be analyzed.

Parameters

model_id (str) – Custom model identifier.
form_url (str) – The URL of the form to analyze. The input must be a valid, encoded URL of one of the supported formats: JPEG, PNG, PDF, TIFF, or BMP.

Keyword Arguments

include_field_elements (bool) – Whether or not to include all lines per page and field elements such as lines, words, and selection marks for each form field.
pages (list[str]) – Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=[“1-3”, “5-6”]. Separate each page number or range with a comma.
continuation_token (str) – A continuation token to restart a poller from a saved state.

Returns

An instance of an LROPoller. Call result() on the poller object to return a list[RecognizedForm].

Return type

LROPoller[list[RecognizedForm]

Raises

HttpResponseError –

begin_recognize_identity_documents(identity_document: Union[bytes, IO[bytes]], **kwargs: Any) → LROPoller[List[RecognizedForm]][source]¶

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 identity document here: https://aka.ms/formrecognizer/iddocumentfields

Parameters

identity_document (bytes or IO[bytes]) – JPEG, PNG, PDF, TIFF, or BMP type file stream or bytes.

Keyword Arguments

include_field_elements (bool) – Whether or not to include all lines per page and field elements such as lines, words, and selection marks for each form field.
content_type (str or FormContentType) – Content-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 FormContentType.
continuation_token (str) – A continuation token to restart a poller from a saved state.
pages (list[str]) – Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=[“1-3”, “5-6”]. Separate each page number or range with a comma.

Returns

An instance of an LROPoller. Call result() on the poller object to return a list[RecognizedForm].

Return type

LROPoller[list[RecognizedForm]]

Raises

HttpResponseError –

New in version v2.1: The begin_recognize_identity_documents client method

Example:

Recognize identity document fields.¶

from azure.core.credentials import AzureKeyCredential
from azure.ai.formrecognizer import FormRecognizerClient

endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]

form_recognizer_client = FormRecognizerClient(
    endpoint=endpoint, credential=AzureKeyCredential(key)
)
with open(path_to_sample_forms, "rb") as f:
    poller = form_recognizer_client.begin_recognize_identity_documents(identity_document=f)
id_documents = poller.result()

for idx, id_document in enumerate(id_documents):
    print("--------Recognizing ID document #{}--------".format(idx+1))
    first_name = id_document.fields.get("FirstName")
    if first_name:
        print("First Name: {} has confidence: {}".format(first_name.value, first_name.confidence))
    last_name = id_document.fields.get("LastName")
    if last_name:
        print("Last Name: {} has confidence: {}".format(last_name.value, last_name.confidence))
    document_number = id_document.fields.get("DocumentNumber")
    if document_number:
        print("Document Number: {} has confidence: {}".format(document_number.value, document_number.confidence))
    dob = id_document.fields.get("DateOfBirth")
    if dob:
        print("Date of Birth: {} has confidence: {}".format(dob.value, dob.confidence))
    doe = id_document.fields.get("DateOfExpiration")
    if doe:
        print("Date of Expiration: {} has confidence: {}".format(doe.value, doe.confidence))
    sex = id_document.fields.get("Sex")
    if sex:
        print("Sex: {} has confidence: {}".format(sex.value, sex.confidence))
    address = id_document.fields.get("Address")
    if address:
        print("Address: {} has confidence: {}".format(address.value, address.confidence))
    country_region = id_document.fields.get("CountryRegion")
    if country_region:
        print("Country/Region: {} has confidence: {}".format(country_region.value, country_region.confidence))
    region = id_document.fields.get("Region")
    if region:
        print("Region: {} has confidence: {}".format(region.value, region.confidence))

begin_recognize_identity_documents_from_url(identity_document_url: str, **kwargs: Any) → LROPoller[List[RecognizedForm]][source]¶

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 identity document here: https://aka.ms/formrecognizer/iddocumentfields

Parameters

identity_document_url (str) – 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 Arguments

include_field_elements (bool) – Whether or not to include all lines per page and field elements such as lines, words, and selection marks for each form field.
continuation_token (str) – A continuation token to restart a poller from a saved state.
pages (list[str]) – Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=[“1-3”, “5-6”]. Separate each page number or range with a comma.

Returns

An instance of an LROPoller. Call result() on the poller object to return a list[RecognizedForm].

Return type

LROPoller[list[RecognizedForm]]

Raises

HttpResponseError –

New in version v2.1: The begin_recognize_identity_documents_from_url client method

begin_recognize_invoices(invoice: Union[bytes, IO[bytes]], **kwargs: Any) → LROPoller[List[RecognizedForm]][source]¶

Extract field text and semantic values from a given invoice. 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 a invoice here: https://aka.ms/formrecognizer/invoicefields

Parameters

invoice (bytes or IO[bytes]) – JPEG, PNG, PDF, TIFF, or BMP type file stream or bytes.

Keyword Arguments

locale (str) – Locale of the invoice. Supported locales include: en-US
include_field_elements (bool) – Whether or not to include all lines per page and field elements such as lines, words, and selection marks for each form field.
pages (list[str]) – Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=[“1-3”, “5-6”]. Separate each page number or range with a comma.
content_type (str or FormContentType) – Content-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 FormContentType.
continuation_token (str) – A continuation token to restart a poller from a saved state.

Returns

An instance of an LROPoller. Call result() on the poller object to return a list[RecognizedForm].

Return type

LROPoller[list[RecognizedForm]]

Raises

HttpResponseError –

New in version v2.1: The begin_recognize_invoices client method

Example:

Recognize invoices from a file.¶

from azure.core.credentials import AzureKeyCredential
from azure.ai.formrecognizer import FormRecognizerClient

endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]

form_recognizer_client = FormRecognizerClient(
    endpoint=endpoint, credential=AzureKeyCredential(key)
)
with open(path_to_sample_forms, "rb") as f:
    poller = form_recognizer_client.begin_recognize_invoices(invoice=f, locale="en-US")
invoices = poller.result()

for idx, invoice in enumerate(invoices):
    print("--------Recognizing invoice #{}--------".format(idx+1))
    vendor_name = invoice.fields.get("VendorName")
    if vendor_name:
        print("Vendor Name: {} has confidence: {}".format(vendor_name.value, vendor_name.confidence))
    vendor_address = invoice.fields.get("VendorAddress")
    if vendor_address:
        print("Vendor Address: {} has confidence: {}".format(vendor_address.value, vendor_address.confidence))
    vendor_address_recipient = invoice.fields.get("VendorAddressRecipient")
    if vendor_address_recipient:
        print("Vendor Address Recipient: {} has confidence: {}".format(vendor_address_recipient.value, vendor_address_recipient.confidence))
    customer_name = invoice.fields.get("CustomerName")
    if customer_name:
        print("Customer Name: {} has confidence: {}".format(customer_name.value, customer_name.confidence))
    customer_id = invoice.fields.get("CustomerId")
    if customer_id:
        print("Customer Id: {} has confidence: {}".format(customer_id.value, customer_id.confidence))
    customer_address = invoice.fields.get("CustomerAddress")
    if customer_address:
        print("Customer Address: {} has confidence: {}".format(customer_address.value, customer_address.confidence))
    customer_address_recipient = invoice.fields.get("CustomerAddressRecipient")
    if customer_address_recipient:
        print("Customer Address Recipient: {} has confidence: {}".format(customer_address_recipient.value, customer_address_recipient.confidence))
    invoice_id = invoice.fields.get("InvoiceId")
    if invoice_id:
        print("Invoice Id: {} has confidence: {}".format(invoice_id.value, invoice_id.confidence))
    invoice_date = invoice.fields.get("InvoiceDate")
    if invoice_date:
        print("Invoice Date: {} has confidence: {}".format(invoice_date.value, invoice_date.confidence))
    invoice_total = invoice.fields.get("InvoiceTotal")
    if invoice_total:
        print("Invoice Total: {} has confidence: {}".format(invoice_total.value, invoice_total.confidence))
    due_date = invoice.fields.get("DueDate")
    if due_date:
        print("Due Date: {} has confidence: {}".format(due_date.value, due_date.confidence))
    purchase_order = invoice.fields.get("PurchaseOrder")
    if purchase_order:
        print("Purchase Order: {} has confidence: {}".format(purchase_order.value, purchase_order.confidence))
    billing_address = invoice.fields.get("BillingAddress")
    if billing_address:
        print("Billing Address: {} has confidence: {}".format(billing_address.value, billing_address.confidence))
    billing_address_recipient = invoice.fields.get("BillingAddressRecipient")
    if billing_address_recipient:
        print("Billing Address Recipient: {} has confidence: {}".format(billing_address_recipient.value, billing_address_recipient.confidence))
    shipping_address = invoice.fields.get("ShippingAddress")
    if shipping_address:
        print("Shipping Address: {} has confidence: {}".format(shipping_address.value, shipping_address.confidence))
    shipping_address_recipient = invoice.fields.get("ShippingAddressRecipient")
    if shipping_address_recipient:
        print("Shipping Address Recipient: {} has confidence: {}".format(shipping_address_recipient.value, shipping_address_recipient.confidence))
    print("Invoice items:")
    for idx, item in enumerate(invoice.fields.get("Items").value):
        print("...Item #{}".format(idx+1))
        item_description = item.value.get("Description")
        if item_description:
            print("......Description: {} has confidence: {}".format(item_description.value, item_description.confidence))
        item_quantity = item.value.get("Quantity")
        if item_quantity:
            print("......Quantity: {} has confidence: {}".format(item_quantity.value, item_quantity.confidence))
        unit = item.value.get("Unit")
        if unit:
            print("......Unit: {} has confidence: {}".format(unit.value, unit.confidence))
        unit_price = item.value.get("UnitPrice")
        if unit_price:
            print("......Unit Price: {} has confidence: {}".format(unit_price.value, unit_price.confidence))
        product_code = item.value.get("ProductCode")
        if product_code:
            print("......Product Code: {} has confidence: {}".format(product_code.value, product_code.confidence))
        item_date = item.value.get("Date")
        if item_date:
            print("......Date: {} has confidence: {}".format(item_date.value, item_date.confidence))
        tax = item.value.get("Tax")
        if tax:
            print("......Tax: {} has confidence: {}".format(tax.value, tax.confidence))
        amount = item.value.get("Amount")
        if amount:
            print("......Amount: {} has confidence: {}".format(amount.value, amount.confidence))
    subtotal = invoice.fields.get("SubTotal")
    if subtotal:
        print("Subtotal: {} has confidence: {}".format(subtotal.value, subtotal.confidence))
    total_tax = invoice.fields.get("TotalTax")
    if total_tax:
        print("Total Tax: {} has confidence: {}".format(total_tax.value, total_tax.confidence))
    previous_unpaid_balance = invoice.fields.get("PreviousUnpaidBalance")
    if previous_unpaid_balance:
        print("Previous Unpaid Balance: {} has confidence: {}".format(previous_unpaid_balance.value, previous_unpaid_balance.confidence))
    amount_due = invoice.fields.get("AmountDue")
    if amount_due:
        print("Amount Due: {} has confidence: {}".format(amount_due.value, amount_due.confidence))
    service_start_date = invoice.fields.get("ServiceStartDate")
    if service_start_date:
        print("Service Start Date: {} has confidence: {}".format(service_start_date.value, service_start_date.confidence))
    service_end_date = invoice.fields.get("ServiceEndDate")
    if service_end_date:
        print("Service End Date: {} has confidence: {}".format(service_end_date.value, service_end_date.confidence))
    service_address = invoice.fields.get("ServiceAddress")
    if service_address:
        print("Service Address: {} has confidence: {}".format(service_address.value, service_address.confidence))
    service_address_recipient = invoice.fields.get("ServiceAddressRecipient")
    if service_address_recipient:
        print("Service Address Recipient: {} has confidence: {}".format(service_address_recipient.value, service_address_recipient.confidence))
    remittance_address = invoice.fields.get("RemittanceAddress")
    if remittance_address:
        print("Remittance Address: {} has confidence: {}".format(remittance_address.value, remittance_address.confidence))
    remittance_address_recipient = invoice.fields.get("RemittanceAddressRecipient")
    if remittance_address_recipient:
        print("Remittance Address Recipient: {} has confidence: {}".format(remittance_address_recipient.value, remittance_address_recipient.confidence))

begin_recognize_invoices_from_url(invoice_url: str, **kwargs: Any) → LROPoller[List[RecognizedForm]][source]¶

Extract field text and semantic values from a given invoice. The input document must be the location (URL) of the invoice to be analyzed.

See fields found on a invoice card here: https://aka.ms/formrecognizer/invoicefields

Parameters

invoice_url (str) – The URL of the invoice to analyze. The input must be a valid, encoded URL of one of the supported formats: JPEG, PNG, PDF, TIFF, or BMP.

Keyword Arguments

locale (str) – Locale of the invoice. Supported locales include: en-US
include_field_elements (bool) – Whether or not to include all lines per page and field elements such as lines, words, and selection marks for each form field.
pages (list[str]) – Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=[“1-3”, “5-6”]. Separate each page number or range with a comma.
continuation_token (str) – A continuation token to restart a poller from a saved state.

Returns

An instance of an LROPoller. Call result() on the poller object to return a list[RecognizedForm].

Return type

LROPoller[list[RecognizedForm]]

Raises

HttpResponseError –

New in version v2.1: The begin_recognize_invoices_from_url client method

begin_recognize_receipts(receipt: Union[bytes, IO[bytes]], **kwargs: Any) → LROPoller[List[RecognizedForm]][source]¶

Extract field text and semantic values from a given sales receipt. 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 a receipt here: https://aka.ms/formrecognizer/receiptfields

Parameters

receipt (bytes or IO[bytes]) – JPEG, PNG, PDF, TIFF, or BMP type file stream or bytes.

Keyword Arguments

include_field_elements (bool) – Whether or not to include all lines per page and field elements such as lines, words, and selection marks for each form field.
content_type (str or FormContentType) – Content-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 FormContentType.
continuation_token (str) – A continuation token to restart a poller from a saved state.
locale (str) – Locale of the receipt. Supported locales include: en-US, en-AU, en-CA, en-GB, and en-IN.
pages (list[str]) – Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=[“1-3”, “5-6”]. Separate each page number or range with a comma.

Returns

An instance of an LROPoller. Call result() on the poller object to return a list[RecognizedForm].

Return type

LROPoller[list[RecognizedForm]]

Raises

HttpResponseError –

New in version v2.1: The locale and pages keyword arguments and support for image/bmp content

Example:

Recognize sales receipt fields.¶

from azure.core.credentials import AzureKeyCredential
from azure.ai.formrecognizer import FormRecognizerClient

endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]

form_recognizer_client = FormRecognizerClient(
    endpoint=endpoint, credential=AzureKeyCredential(key)
)
with open(path_to_sample_forms, "rb") as f:
    poller = form_recognizer_client.begin_recognize_receipts(receipt=f, locale="en-US")
receipts = poller.result()

for idx, receipt in enumerate(receipts):
    print("--------Recognizing receipt #{}--------".format(idx+1))
    receipt_type = receipt.fields.get("ReceiptType")
    if receipt_type:
        print("Receipt Type: {} has confidence: {}".format(receipt_type.value, receipt_type.confidence))
    merchant_name = receipt.fields.get("MerchantName")
    if merchant_name:
        print("Merchant Name: {} has confidence: {}".format(merchant_name.value, merchant_name.confidence))
    transaction_date = receipt.fields.get("TransactionDate")
    if transaction_date:
        print("Transaction Date: {} has confidence: {}".format(transaction_date.value, transaction_date.confidence))
    if receipt.fields.get("Items"):
        print("Receipt items:")
        for idx, item in enumerate(receipt.fields.get("Items").value):
            print("...Item #{}".format(idx+1))
            item_name = item.value.get("Name")
            if item_name:
                print("......Item Name: {} has confidence: {}".format(item_name.value, item_name.confidence))
            item_quantity = item.value.get("Quantity")
            if item_quantity:
                print("......Item Quantity: {} has confidence: {}".format(item_quantity.value, item_quantity.confidence))
            item_price = item.value.get("Price")
            if item_price:
                print("......Individual Item Price: {} has confidence: {}".format(item_price.value, item_price.confidence))
            item_total_price = item.value.get("TotalPrice")
            if item_total_price:
                print("......Total Item Price: {} has confidence: {}".format(item_total_price.value, item_total_price.confidence))
    subtotal = receipt.fields.get("Subtotal")
    if subtotal:
        print("Subtotal: {} has confidence: {}".format(subtotal.value, subtotal.confidence))
    tax = receipt.fields.get("Tax")
    if tax:
        print("Tax: {} has confidence: {}".format(tax.value, tax.confidence))
    tip = receipt.fields.get("Tip")
    if tip:
        print("Tip: {} has confidence: {}".format(tip.value, tip.confidence))
    total = receipt.fields.get("Total")
    if total:
        print("Total: {} has confidence: {}".format(total.value, total.confidence))
    print("--------------------------------------")

begin_recognize_receipts_from_url(receipt_url: str, **kwargs: Any) → LROPoller[List[RecognizedForm]][source]¶

Extract field text and semantic values from a given sales receipt. The input document must be the location (URL) of the receipt to be analyzed.

See fields found on a receipt here: https://aka.ms/formrecognizer/receiptfields

Parameters

receipt_url (str) – The URL of the receipt to analyze. The input must be a valid, encoded URL of one of the supported formats: JPEG, PNG, PDF, TIFF, or BMP.

Keyword Arguments

include_field_elements (bool) – Whether or not to include all lines per page and field elements such as lines, words, and selection marks for each form field.
continuation_token (str) – A continuation token to restart a poller from a saved state.
locale (str) – Locale of the receipt. Supported locales include: en-US, en-AU, en-CA, en-GB, and en-IN.
pages (list[str]) – Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=[“1-3”, “5-6”]. Separate each page number or range with a comma.

Returns

An instance of an LROPoller. Call result() on the poller object to return a list[RecognizedForm].

Return type

LROPoller[list[RecognizedForm]]

Raises

HttpResponseError –

New in version v2.1: The locale and pages keyword arguments and support for image/bmp content

Example:

Recognize sales receipt fields from a URL.¶

from azure.core.credentials import AzureKeyCredential
from azure.ai.formrecognizer import FormRecognizerClient

endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]

form_recognizer_client = FormRecognizerClient(
    endpoint=endpoint, credential=AzureKeyCredential(key)
)
url = "https://raw.githubusercontent.com/Azure/azure-sdk-for-python/main/sdk/formrecognizer/azure-ai-formrecognizer/tests/sample_forms/receipt/contoso-receipt.png"
poller = form_recognizer_client.begin_recognize_receipts_from_url(receipt_url=url)
receipts = poller.result()

for idx, receipt in enumerate(receipts):
    print("--------Recognizing receipt #{}--------".format(idx+1))
    receipt_type = receipt.fields.get("ReceiptType")
    if receipt_type:
        print("Receipt Type: {} has confidence: {}".format(receipt_type.value, receipt_type.confidence))
    merchant_name = receipt.fields.get("MerchantName")
    if merchant_name:
        print("Merchant Name: {} has confidence: {}".format(merchant_name.value, merchant_name.confidence))
    transaction_date = receipt.fields.get("TransactionDate")
    if transaction_date:
        print("Transaction Date: {} has confidence: {}".format(transaction_date.value, transaction_date.confidence))
    if receipt.fields.get("Items"):
        print("Receipt items:")
        for idx, item in enumerate(receipt.fields.get("Items").value):
            print("...Item #{}".format(idx+1))
            item_name = item.value.get("Name")
            if item_name:
                print("......Item Name: {} has confidence: {}".format(item_name.value, item_name.confidence))
            item_quantity = item.value.get("Quantity")
            if item_quantity:
                print("......Item Quantity: {} has confidence: {}".format(item_quantity.value, item_quantity.confidence))
            item_price = item.value.get("Price")
            if item_price:
                print("......Individual Item Price: {} has confidence: {}".format(item_price.value, item_price.confidence))
            item_total_price = item.value.get("TotalPrice")
            if item_total_price:
                print("......Total Item Price: {} has confidence: {}".format(item_total_price.value, item_total_price.confidence))
    subtotal = receipt.fields.get("Subtotal")
    if subtotal:
        print("Subtotal: {} has confidence: {}".format(subtotal.value, subtotal.confidence))
    tax = receipt.fields.get("Tax")
    if tax:
        print("Tax: {} has confidence: {}".format(tax.value, tax.confidence))
    tip = receipt.fields.get("Tip")
    if tip:
        print("Tip: {} has confidence: {}".format(tip.value, tip.confidence))
    total = receipt.fields.get("Total")
    if total:
        print("Total: {} has confidence: {}".format(total.value, total.confidence))
    print("--------------------------------------")

close() → None [source]¶: Close the FormRecognizerClient session.

class azure.ai.formrecognizer.FormRecognizerError(**kwargs)[source]¶

Represents an error that occurred while training.

Variables

code (str) – Error code.
message (str) – Error message.

New in version v2.1: Support for to_dict and from_dict methods

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.FormRecognizerError[source]¶

Converts a dict in the shape of a FormRecognizerError to the model itself.

Parameters: data (dict) – A dictionary in the shape of FormRecognizerError.
Returns: FormRecognizerError
Return type: FormRecognizerError

to_dict() → dict [source]¶

Returns a dict representation of FormRecognizerError.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.FormSelectionMark(**kwargs)[source]¶

Information about the extracted selection mark.

Variables

text (str) – The text content - not returned for FormSelectionMark.
bounding_box (list[Point]) – A list of 4 points representing the quadrilateral bounding box 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.
confidence (float) – Measures the degree of certainty of the recognition result. Value is between [0.0, 1.0].
state (str) – State of the selection mark. Possible values include: “selected”, “unselected”.
page_number (int) – The 1-based number of the page in which this content is present.
kind (str) – For FormSelectionMark, this is “selectionMark”.

New in version v2.1: Support for to_dict and from_dict methods

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.FormSelectionMark[source]¶

Converts a dict in the shape of a FormSelectionMark to the model itself.

Parameters: data (dict) – A dictionary in the shape of FormSelectionMark.
Returns: FormSelectionMark
Return type: FormSelectionMark

to_dict() → dict [source]¶

Returns a dict representation of FormSelectionMark.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.FormTable(**kwargs)[source]¶

Information about the extracted table contained on a page.

Variables

page_number (int) – The 1-based number of the page in which this table is present.
cells (list[FormTableCell]) – List of cells contained in the table.
row_count (int) – Number of rows in table.
column_count (int) – Number of columns in table.
bounding_box (list[Point]) – A list of 4 points representing the quadrilateral bounding box that outlines the table. 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.

New in version v2.1: The bounding_box property, support for to_dict and from_dict methods

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.FormTable[source]¶

Converts a dict in the shape of a FormTable to the model itself.

Parameters: data (dict) – A dictionary in the shape of FormTable.
Returns: FormTable
Return type: FormTable

to_dict() → dict [source]¶

Returns a dict representation of FormTable.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.FormTableCell(**kwargs)[source]¶

Represents a cell contained in a table recognized from the input document.

Variables

text (str) – Text content of the cell.
row_index (int) – Row index of the cell.
column_index (int) – Column index of the cell.
row_span (int) – Number of rows spanned by this cell.
column_span (int) – Number of columns spanned by this cell.
bounding_box (list[Point]) – A list of 4 points representing the quadrilateral bounding box 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.
confidence (float) – Measures the degree of certainty of the recognition result. Value is between [0.0, 1.0].
is_header (bool) – Whether the current cell is a header cell.
is_footer (bool) – Whether the current cell is a footer cell.
page_number (int) – The 1-based number of the page in which this content is present.
field_elements (list[Union[FormElement, FormWord, FormLine, FormSelectionMark]]) – When include_field_elements is set to true, a list of elements constituting this cell is returned. The list constitutes of elements such as lines, words, and selection marks. For calls to begin_recognize_content(), this list is always populated.

New in version v2.1: FormSelectionMark is added to the types returned in the list of field_elements, support for to_dict and from_dict methods

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.FormTableCell[source]¶

Converts a dict in the shape of a FormTableCell to the model itself.

Parameters: data (dict) – A dictionary in the shape of FormTableCell.
Returns: FormTableCell
Return type: FormTableCell

to_dict() → dict [source]¶

Returns a dict representation of FormTableCell.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.FormTrainingClient(endpoint: str, credential: Union[AzureKeyCredential, TokenCredential], **kwargs: Any)[source]¶

FormTrainingClient is the Form Recognizer interface to use for creating and managing custom models. It provides methods for training models on the forms you provide, as well as methods for viewing and deleting models, accessing account properties, copying models to another Form Recognizer resource, and composing models from a collection of existing models trained with labels.

Note

FormTrainingClient should be used with API versions <=v2.1. To use API versions 2021-09-30-preview and up, instantiate a DocumentModelAdministrationClient.

Parameters

endpoint (str) – Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus2.api.cognitive.microsoft.com).
credential (AzureKeyCredential or TokenCredential) – Credentials needed for the client to connect to Azure. This is an instance of AzureKeyCredential if using an API key or a token credential from azure.identity.

Keyword Arguments

api_version (str or FormRecognizerApiVersion) – The API version of the service to use for requests. It defaults to API version v2.1. Setting to an older version may result in reduced feature compatibility. To use the latest supported API version and features, instantiate a DocumentModelAdministrationClient instead.

Example:

Creating the FormTrainingClient with an endpoint and API key.¶

from azure.core.credentials import AzureKeyCredential
from azure.ai.formrecognizer import FormTrainingClient
endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]

form_training_client = FormTrainingClient(endpoint, AzureKeyCredential(key))

Creating the FormTrainingClient with a token credential.¶

"""DefaultAzureCredential will use the values from these environment
variables: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET
"""
from azure.ai.formrecognizer import FormTrainingClient
from azure.identity import DefaultAzureCredential

endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
credential = DefaultAzureCredential()

form_training_client = FormTrainingClient(endpoint, credential)

begin_copy_model(model_id: str, target: Dict, **kwargs: Any) → LROPoller[CustomFormModelInfo][source]¶

Copy a custom 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 (with the model that is intended to be copied). The target parameter should be supplied from the target resource’s output from calling the get_copy_authorization() method.

Parameters

model_id (str) – Model identifier of the model to copy to target resource.
target (dict) – The copy authorization generated from the target resource’s call to get_copy_authorization().

Keyword Arguments

continuation_token (str) – A continuation token to restart a poller from a saved state.

Returns

An instance of an LROPoller. Call result() on the poller object to return a CustomFormModelInfo.

Return type

LROPoller[CustomFormModelInfo]

Raises

HttpResponseError –

Example:

Copy a model from the source resource to the target resource¶

source_client = FormTrainingClient(endpoint=source_endpoint, credential=AzureKeyCredential(source_key))

poller = source_client.begin_copy_model(
    model_id=source_model_id,
    target=target  # output from target client's call to get_copy_authorization()
)
copied_over_model = poller.result()

print("Model ID: {}".format(copied_over_model.model_id))
print("Status: {}".format(copied_over_model.status))

begin_create_composed_model(model_ids: List[str], **kwargs: Any) → LROPoller[CustomFormModel][source]¶

Creates a composed model from a collection of existing models that were trained with labels.

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 route it to the correct custom model.

Parameters

model_ids (list[str]) – List of model IDs to use in the composed model.

Keyword Arguments

model_name (str) – An optional, user-defined name to associate with your model.
continuation_token (str) – A continuation token to restart a poller from a saved state.

Returns

An instance of an LROPoller. Call result() on the poller object to return a CustomFormModel.

Return type

LROPoller[CustomFormModel]

Raises

HttpResponseError –

New in version v2.1: The begin_create_composed_model client method

Example:

Create a composed model¶

from azure.core.credentials import AzureKeyCredential
from azure.ai.formrecognizer import FormTrainingClient

endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]
po_supplies = os.environ['PURCHASE_ORDER_OFFICE_SUPPLIES_SAS_URL_V2']
po_equipment = os.environ['PURCHASE_ORDER_OFFICE_EQUIPMENT_SAS_URL_V2']
po_furniture = os.environ['PURCHASE_ORDER_OFFICE_FURNITURE_SAS_URL_V2']
po_cleaning_supplies = os.environ['PURCHASE_ORDER_OFFICE_CLEANING_SUPPLIES_SAS_URL_V2']

form_training_client = FormTrainingClient(endpoint=endpoint, credential=AzureKeyCredential(key))
supplies_poller = form_training_client.begin_training(
    po_supplies, use_training_labels=True, model_name="Purchase order - Office supplies"
)
equipment_poller = form_training_client.begin_training(
    po_equipment, use_training_labels=True, model_name="Purchase order - Office Equipment"
)
furniture_poller = form_training_client.begin_training(
    po_furniture, use_training_labels=True, model_name="Purchase order - Furniture"
)
cleaning_supplies_poller = form_training_client.begin_training(
    po_cleaning_supplies, use_training_labels=True, model_name="Purchase order - Cleaning Supplies"
)
supplies_model = supplies_poller.result()
equipment_model = equipment_poller.result()
furniture_model = furniture_poller.result()
cleaning_supplies_model = cleaning_supplies_poller.result()

models_trained_with_labels = [
    supplies_model.model_id,
    equipment_model.model_id,
    furniture_model.model_id,
    cleaning_supplies_model.model_id
]

poller = form_training_client.begin_create_composed_model(
    models_trained_with_labels, model_name="Office Supplies Composed Model"
)
model = poller.result()

print("Office Supplies Composed Model Info:")
print("Model ID: {}".format(model.model_id))
print("Model name: {}".format(model.model_name))
print("Is this a composed model?: {}".format(model.properties.is_composed_model))
print("Status: {}".format(model.status))
print("Composed model creation started on: {}".format(model.training_started_on))
print("Creation completed on: {}".format(model.training_completed_on))

begin_training(training_files_url: str, use_training_labels: bool, **kwargs: Any) → LROPoller[CustomFormModel][source]¶

Create and train a custom model. The request must include a training_files_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. Models are trained 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.

Parameters

training_files_url (str) – An Azure Storage blob container’s SAS URI. A container URI (without SAS) can be used if the container is public. For more information on setting up a training data set, see: https://docs.microsoft.com/azure/cognitive-services/form-recognizer/build-training-data-set
use_training_labels (bool) – Whether to train with labels or not. Corresponding labeled files must exist in the blob container if set to True.

Keyword Arguments

prefix (str) – A case-sensitive prefix string to filter documents in the source path for training. For example, when using an Azure storage blob URI, use the prefix to restrict sub folders for training.
include_subfolders (bool) – A flag to indicate if subfolders within the set of prefix folders will also need to be included when searching for content to be preprocessed. Not supported if training with labels.
model_name (str) – An optional, user-defined name to associate with your model.
continuation_token (str) – A continuation token to restart a poller from a saved state.

Returns

An instance of an LROPoller. Call result() on the poller object to return a CustomFormModel.

Return type

LROPoller[CustomFormModel]

Raises

HttpResponseError – Note that if the training fails, the exception is raised, but a model with an “invalid” status is still created. You can delete this model by calling delete_model()

New in version v2.1: The model_name keyword argument

Example:

Training a model (without labels) with your custom forms.¶

from azure.ai.formrecognizer import FormTrainingClient
from azure.core.credentials import AzureKeyCredential

endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]
container_sas_url = os.environ["CONTAINER_SAS_URL_V2"]

form_training_client = FormTrainingClient(endpoint, AzureKeyCredential(key))
poller = form_training_client.begin_training(container_sas_url, use_training_labels=False)
model = poller.result()

# Custom model information
print("Model ID: {}".format(model.model_id))
print("Status: {}".format(model.status))
print("Model name: {}".format(model.model_name))
print("Training started on: {}".format(model.training_started_on))
print("Training completed on: {}".format(model.training_completed_on))

print("Recognized fields:")
# Looping through the submodels, which contains the fields they were trained on
for submodel in model.submodels:
    print("...The submodel has form type '{}'".format(submodel.form_type))
    for name, field in submodel.fields.items():
        print("...The model found field '{}' to have label '{}'".format(
            name, field.label
        ))

close() → None [source]¶: Close the FormTrainingClient session.

delete_model(model_id: str, **kwargs: Any) → None [source]¶

Mark model for deletion. Model artifacts will be permanently removed within a predetermined period.

Parameters: model_id (str) – Model identifier.
Return type: None
Raises: HttpResponseError or ResourceNotFoundError –

Example:

Delete a custom model.¶

form_training_client.delete_model(model_id=custom_model.model_id)

try:
    form_training_client.get_custom_model(model_id=custom_model.model_id)
except ResourceNotFoundError:
    print("Successfully deleted model with id {}".format(custom_model.model_id))

get_account_properties(**kwargs: Any) → AccountProperties [source]¶

Get information about the models on the form recognizer account.

Returns: Summary of models on account - custom model count, custom model limit.
Return type: AccountProperties
Raises: HttpResponseError –

Example:

Get properties for the form recognizer account.¶

form_training_client = FormTrainingClient(endpoint=endpoint, credential=AzureKeyCredential(key))
# First, we see how many custom models we have, and what our limit is
account_properties = form_training_client.get_account_properties()
print("Our account has {} custom models, and we can have at most {} custom models\n".format(
    account_properties.custom_model_count, account_properties.custom_model_limit
))

get_copy_authorization(resource_id: str, resource_region: str, **kwargs: Any) → Dict[str, Union[str, int]][source]¶

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 begin_copy_model().

Parameters

resource_id (str) – Azure Resource Id of the target Form Recognizer resource where the model will be copied to.
resource_region (str) – Location of the target Form Recognizer resource. A valid Azure region name supported by Cognitive Services. For example, ‘westus’, ‘eastus’ etc. See https://azure.microsoft.com/global-infrastructure/services/?products=cognitive-services for the regional availability of Cognitive Services.

Returns

A dictionary with values for the copy authorization - “modelId”, “accessToken”, “resourceId”, “resourceRegion”, and “expirationDateTimeTicks”.

Return type

Dict[str, Union[str, int]]

Raises

HttpResponseError –

Example:

Authorize the target resource to receive the copied model¶

target_client = FormTrainingClient(endpoint=target_endpoint, credential=AzureKeyCredential(target_key))

target = target_client.get_copy_authorization(
    resource_region=target_region,
    resource_id=target_resource_id
)
# model ID that target client will use to access the model once copy is complete
print("Model ID: {}".format(target["modelId"]))

get_custom_model(model_id: str, **kwargs: Any) → CustomFormModel [source]¶

Get a description of a custom model, including the types of forms it can recognize, and the fields it will extract for each form type.

Parameters: model_id (str) – Model identifier.
Returns: CustomFormModel
Return type: CustomFormModel
Raises: HttpResponseError or ResourceNotFoundError –

Example:

Get a custom model with a model ID.¶

custom_model = form_training_client.get_custom_model(model_id=model.model_id)
print("\nModel ID: {}".format(custom_model.model_id))
print("Status: {}".format(custom_model.status))
print("Model name: {}".format(custom_model.model_name))
print("Is this a composed model?: {}".format(custom_model.properties.is_composed_model))
print("Training started on: {}".format(custom_model.training_started_on))
print("Training completed on: {}".format(custom_model.training_completed_on))

get_form_recognizer_client(**kwargs: Any) → azure.ai.formrecognizer._form_recognizer_client.FormRecognizerClient[source]¶

Get an instance of a FormRecognizerClient from FormTrainingClient.

Return type: FormRecognizerClient
Returns: A FormRecognizerClient

list_custom_models(**kwargs: Any) → ItemPaged[CustomFormModelInfo][source]¶

List information for each model, including model id, model status, and when it was created and last modified.

Returns: ItemPaged[CustomFormModelInfo]
Return type: ItemPaged
Raises: HttpResponseError –

Example:

List model information for each model on the account.¶

custom_models = form_training_client.list_custom_models()

print("We have models with the following IDs:")
for model in custom_models:
    print(model.model_id)

class azure.ai.formrecognizer.FormWord(**kwargs)[source]¶

Represents a word recognized from the input document.

Variables

text (str) – The text content of the word.
bounding_box (list[Point]) – A list of 4 points representing the quadrilateral bounding box 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.
confidence (float) – Measures the degree of certainty of the recognition result. Value is between [0.0, 1.0].
page_number (int) – The 1-based number of the page in which this content is present.
kind (str) – For FormWord, this is “word”.

New in version v2.1: Support for to_dict and from_dict methods

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.FormWord[source]¶

Converts a dict in the shape of a FormWord to the model itself.

Parameters: data (dict) – A dictionary in the shape of FormWord.
Returns: FormWord
Return type: FormWord

to_dict() → dict [source]¶

Returns a dict representation of FormWord.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.LengthUnit(value)[source]¶

The unit used by the width, height and bounding box properties. For images, the unit is “pixel”. For PDF, the unit is “inch”.

INCH = 'inch'¶

PIXEL = 'pixel'¶

class azure.ai.formrecognizer.ModelOperation(**kwargs)[source]¶

ModelOperation consists of information about the model operation, including the result or 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 get_model() or list_models() APIs.

Variables

operation_id (str) – Operation ID.
status (str) – Operation status. Possible values include: “notStarted”, “running”, “failed”, “succeeded”, “canceled”.
percent_completed (int) – Operation progress (0-100).
created_on (datetime) – Date and time (UTC) when the operation was created.
last_updated_on (datetime) – Date and time (UTC) when the operation was last updated.
kind (str) – Type of operation. Possible values include: “documentModelBuild”, “documentModelCompose”, “documentModelCopyTo”.
resource_location (str) – URL of the resource targeted by this operation.
error (DocumentAnalysisError) – Encountered error, includes the error code, message, and details for why the operation failed.
result (DocumentModel) – Operation result upon success. Returns a DocumentModel which contains all information about the model including the doc types and fields it can analyze from documents.

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.ModelOperation[source]¶

Converts a dict in the shape of a ModelOperation to the model itself.

Parameters: data (dict) – A dictionary in the shape of ModelOperation.
Returns: ModelOperation
Return type: ModelOperation

to_dict() → dict [source]¶

Returns a dict representation of ModelOperation.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.ModelOperationInfo(**kwargs)[source]¶

Model operation information, including the kind and status of the operation, when it was created, and more.

Note that operation information only persists for 24 hours. If the operation was successful, the model can be accessed using the get_model() or list_models() APIs. To find out why an operation failed, use get_operation() and provide the operation_id.

Variables

operation_id (str) – Operation ID.
status (str) – Operation status. Possible values include: “notStarted”, “running”, “failed”, “succeeded”, “canceled”.
percent_completed (int) – Operation progress (0-100).
created_on (datetime) – Date and time (UTC) when the operation was created.
last_updated_on (datetime) – Date and time (UTC) when the operation was last updated.
kind (str) – Type of operation. Possible values include: “documentModelBuild”, “documentModelCompose”, “documentModelCopyTo”.
resource_location (str) – URL of the resource targeted by this operation.

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.ModelOperationInfo[source]¶

Converts a dict in the shape of a ModelOperationInfo to the model itself.

Parameters: data (dict) – A dictionary in the shape of ModelOperationInfo.
Returns: ModelOperationInfo
Return type: ModelOperationInfo

to_dict() → dict [source]¶

Returns a dict representation of ModelOperationInfo.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.Point(x, y)[source]¶

The x, y coordinate of a point on a bounding box.

Variables

x (float) – x-coordinate
y (float) – y-coordinate

New in version v2.1: Support for to_dict and from_dict methods

Create new instance of Point(x, y)

count(value) → integer – return number of occurrences of value¶

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.Point[source]¶

Converts a dict in the shape of a Point to the model itself.

Parameters: data (dict) – A dictionary in the shape of Point.
Returns: Point
Return type: Point

index(value[, start[, stop]]) → integer – return first index of value.¶: Raises ValueError if the value is not present.

to_dict() → dict [source]¶

Returns a dict representation of Point.

Returns: dict
Return type: dict

property x¶: Alias for field number 0

property y¶: Alias for field number 1

class azure.ai.formrecognizer.RecognizedForm(**kwargs)[source]¶

Represents a form that has been recognized by a trained or prebuilt model. The fields property contains the form fields that were extracted from the form. Tables, text lines/words, and selection marks are extracted per page and found in the pages property.

Variables

form_type (str) – The type of form the model identified the submitted form to be.
form_type_confidence (str) – Confidence of the type of form the model identified the submitted form to be.
model_id (str) – Model identifier of model used to analyze form if not using a prebuilt model.
fields (dict[str, FormField]) – A dictionary of the fields found on the form. The fields dictionary keys are the name of the field. For models trained with labels, this is the training-time label of the field. For models trained without labels, a unique name is generated for each field.
page_range (FormPageRange) – The first and last page number of the input form.
pages (list[FormPage]) – A list of pages recognized from the input document. Contains lines, words, selection marks, tables and page metadata.

New in version v2.1: The form_type_confidence and model_id properties, support for to_dict and from_dict methods

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.RecognizedForm[source]¶

Converts a dict in the shape of a RecognizedForm to the model itself.

Parameters: data (dict) – A dictionary in the shape of RecognizedForm.
Returns: RecognizedForm
Return type: RecognizedForm

to_dict() → dict [source]¶

Returns a dict representation of RecognizedForm.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.TextAppearance(**kwargs)[source]¶

An object representing the appearance of the text line.

Variables

style_name (str) – The text line style name. Possible values include: “other”, “handwriting”.
style_confidence (float) – The confidence of text line style.

New in version v2.1: Support for to_dict and from_dict methods

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.TextAppearance[source]¶

Converts a dict in the shape of a TextAppearance to the model itself.

Parameters: data (dict) – A dictionary in the shape of TextAppearance.
Returns: TextAppearance
Return type: TextAppearance

to_dict() → dict [source]¶

Returns a dict representation of TextAppearance.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.TrainingDocumentInfo(**kwargs)[source]¶

Report for an individual document used for training a custom model.

Variables

name (str) – The name of the document.
status (str) – The TrainingStatus of the training operation. Possible values include: ‘succeeded’, ‘partiallySucceeded’, ‘failed’.
page_count (int) – Total number of pages trained.
errors (list[FormRecognizerError]) – List of any errors for document.
model_id (str) – The model ID that used the document to train.

New in version v2.1: The model_id property, support for to_dict and from_dict methods

classmethod from_dict(data: dict) → azure.ai.formrecognizer._models.TrainingDocumentInfo[source]¶

Converts a dict in the shape of a TrainingDocumentInfo to the model itself.

Parameters: data (dict) – A dictionary in the shape of TrainingDocumentInfo.
Returns: TrainingDocumentInfo
Return type: TrainingDocumentInfo

to_dict() → dict [source]¶

Returns a dict representation of TrainingDocumentInfo.

Returns: dict
Return type: dict

class azure.ai.formrecognizer.TrainingStatus(value)[source]¶

Status of the training operation.

FAILED = 'failed'¶

PARTIALLY_SUCCEEDED = 'partiallySucceeded'¶

SUCCEEDED = 'succeeded'¶

Subpackages¶

azure.ai.formrecognizer.aio package