azure.ai.formrecognizer package

class azure.ai.formrecognizer.FormRecognizerApiVersion[source]

Form Recognizer API versions supported by this package

V2_0 = '2.0'
V2_1_PREVIEW = '2.1-preview.2'

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 receipts, business cards, invoices, 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.

Parameters
Keyword Arguments

api_version (str or FormRecognizerApiVersion) – 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.

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_AAD_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.

  • 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.

  • polling_interval (int) – Waiting time between two polls for LRO operations if no Retry-After header is present. Defaults to 5 seconds.

  • 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-preview: 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.

  • polling_interval (int) – Waiting time between two polls for LRO operations if no Retry-After header is present. Defaults to 5 seconds.

  • 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-preview: 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 number of the pages you want to get OCR result. For a range of pages, use a hyphen. Separate each page 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.

  • 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.

  • polling_interval (int) – Waiting time between two polls for LRO operations if no Retry-After header is present. Defaults to 5 seconds.

  • 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-preview: The pages and language 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)
        ))
        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 number of the pages you want to get OCR result. For a range of pages, use a hyphen. Separate each page 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.

  • polling_interval (int) – Waiting time between two polls for LRO operations if no Retry-After header is present. Defaults to 5 seconds.

  • 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-preview: The pages and language 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’, or ‘image/tiff’.

Parameters

  • model_id (str) – Custom model identifier.

  • form (bytes or IO[bytes]) – JPEG, PNG, PDF, or TIFF 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.

  • polling_interval (int) – Waiting time between two polls for LRO operations if no Retry-After header is present. Defaults to 5 seconds.

  • 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.environ["CUSTOM_TRAINED_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
    )
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
        ))

    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, or TIFF.

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.

  • polling_interval (int) – Waiting time between two polls for LRO operations if no Retry-After header is present. Defaults to 5 seconds.

  • 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_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.

  • 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.

  • polling_interval (int) – Waiting time between two polls for LRO operations if no Retry-After header is present. Defaults to 5 seconds.

  • 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-preview: 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))
    customer_name = invoice.fields.get("CustomerName")
    if customer_name:
        print("Customer Name: {} has confidence: {}".format(customer_name.value, customer_name.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))
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.

  • polling_interval (int) – Waiting time between two polls for LRO operations if no Retry-After header is present. Defaults to 5 seconds.

  • 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-preview: 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.

  • polling_interval (int) – Waiting time between two polls for LRO operations if no Retry-After header is present. Defaults to 5 seconds.

  • 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.

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-preview: The locale keyword argument 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))
    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.

  • polling_interval (int) – Waiting time between two polls for LRO operations if no Retry-After header is present. Defaults to 5 seconds.

  • 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.

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-preview: The locale keyword argument 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/master/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))
    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.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.

Parameters
Keyword Arguments

api_version (str or FormRecognizerApiVersion) – 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.

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_AAD_ENDPOINT"]
credential = DefaultAzureCredential()

form_training_client = FormTrainingClient(endpoint, credential)
begin_copy_model(model_id: str, target: Dict, **kwargs: Any) → azure.core.polling._poller.LROPoller[azure.ai.formrecognizer._models.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

  • polling_interval (int) – Default waiting time between two polls for LRO operations if no Retry-After header is present.

  • 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) → azure.core.polling._poller.LROPoller[azure.ai.formrecognizer._models.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.

  • polling_interval (int) – Default waiting time between two polls for LRO operations if no Retry-After header is present.

  • 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-preview: 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']
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']

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) → azure.core.polling._poller.LROPoller[azure.ai.formrecognizer._models.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’. Other types of content in the container is ignored.

Parameters
Keyword Arguments

  • prefix (str) – A case-sensitive prefix string to filter documents in the source path for training. For example, when using a 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.

  • polling_interval (int) – Waiting time between two polls for LRO operations if no Retry-After header is present. Defaults to 5 seconds.

  • 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-preview: 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"]

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) → azure.ai.formrecognizer._models.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.
from azure.core.credentials import AzureKeyCredential
from azure.core.exceptions import ResourceNotFoundError
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=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
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) → azure.ai.formrecognizer._models.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=first_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:")

# Let's pull out the first model
first_model = next(custom_models)
print(first_model.model_id)
for model in custom_models:
    print(model.model_id)
class azure.ai.formrecognizer.LengthUnit[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.TrainingStatus[source]

Status of the training operation.

FAILED = 'failed'
PARTIALLY_SUCCEEDED = 'partiallySucceeded'
SUCCEEDED = 'succeeded'
class azure.ai.formrecognizer.CustomFormModelStatus[source]

Status indicating the model’s readiness for use.

CREATING = 'creating'
INVALID = 'invalid'
READY = 'ready'
class azure.ai.formrecognizer.FormContentType[source]

Content type for upload.

New in version v2.1-preview: 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.

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-preview: The bounding_box property.

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-preview: FormSelectionMark is added to the types returned in the list of field_elements

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-preview: The model_id property

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

Represents an error that occurred while training.

Variables

  • code (str) – Error code.

  • message (str) – Error message.

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-preview: The model_name and properties properties

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.

class azure.ai.formrecognizer.Point[source]

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

Variables

Create new instance of Point(x, y)

count(value) → integer – return number of occurrences of value
index(value[, start[, stop]]) → integer – return first index of value.

Raises ValueError if the value is not present.

property x

Alias for field number 0

property y

Alias for field number 1

class azure.ai.formrecognizer.FormPageRange[source]

The 1-based page range of the form.

Variables

Create new instance of FormPageRange(first_page_number, last_page_number)

count(value) → integer – return number of occurrences of value
index(value[, start[, stop]]) → integer – return first index of value.

Raises ValueError if the value is not present.

property first_page_number

Alias for field number 0

property last_page_number

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.

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-preview: The form_type_confidence and model_id properties

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’, or ‘selectionMark’.

  • 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.

  • confidence (float) – Measures the degree of certainty of the recognition result. Value is between [0.0, 1.0].

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-preview: FormSelectionMark is added to the types returned in the list of field_elements

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.

  • selection_marks (list[FormSelectionMark]) – List of selection marks extracted from the page.

New in version v2.1-preview: selection_marks property

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) – Text appearance properties.

New in version v2.1-preview: appearance property

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”.

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

Represents a model trained from custom forms.

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-preview: The model_name and properties properties.

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-preview: The model_id property

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.

class azure.ai.formrecognizer.FieldValueType[source]

Semantic data type of the field value.

DATE = 'date'
DICTIONARY = 'dictionary'
FLOAT = 'float'
INTEGER = 'integer'
LIST = 'list'
PHONE_NUMBER = 'phoneNumber'
SELECTION_MARK = 'selectionMark'
STRING = 'string'
TIME = 'time'
class azure.ai.formrecognizer.CustomFormModelProperties(**kwargs)[source]

Optional model properties.

Variables

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

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”.

class azure.ai.formrecognizer.Appearance(*, style: azure.ai.formrecognizer._generated.v2_1_preview_2.models._models_py3.Style, **kwargs)[source]

An object representing the appearance of the text line.

All required parameters must be populated in order to send to Azure.

Parameters

style (Style) – Required. An object representing the style of the text line.

as_dict(keep_readonly=True, key_transformer=<function attribute_transformer>, **kwargs)

Return a dict that can be JSONify using json.dump.

Advanced usage might optionaly use a callback as parameter:

Key is the attribute name used in Python. Attr_desc is a dict of metadata. Currently contains ‘type’ with the msrest type and ‘key’ with the RestAPI encoded key. Value is the current value in this object.

The string returned will be used to serialize the key. If the return type is a list, this is considered hierarchical result dict.

See the three examples in this file:

  • attribute_transformer

  • full_restapi_key_transformer

  • last_restapi_key_transformer

If you want XML serialization, you can pass the kwargs is_xml=True.

Parameters

key_transformer (function) – A key transformer function.

Returns

A dict JSON compatible object

Return type

dict

classmethod deserialize(data, content_type=None)

Parse a str using the RestAPI syntax and return a model.

Parameters

  • data (str) – A str using RestAPI structure. JSON by default.

  • content_type (str) – JSON by default, set application/xml if XML.

Returns

An instance of this model

Raises

DeserializationError if something went wrong

classmethod enable_additional_properties_sending()
classmethod from_dict(data, key_extractors=None, content_type=None)

Parse a dict using given key extractor return a model.

By default consider key extractors (rest_key_case_insensitive_extractor, attribute_key_case_insensitive_extractor and last_rest_key_case_insensitive_extractor)

Parameters

  • data (dict) – A dict using RestAPI structure

  • content_type (str) – JSON by default, set application/xml if XML.

Returns

An instance of this model

Raises

DeserializationError if something went wrong

classmethod is_xml_model()
serialize(keep_readonly=False, **kwargs)

Return the JSON that would be sent to azure from this model.

This is an alias to as_dict(full_restapi_key_transformer, keep_readonly=False).

If you want XML serialization, you can pass the kwargs is_xml=True.

Parameters

keep_readonly (bool) – If you want to serialize the readonly attributes

Returns

A dict JSON compatible object

Return type

dict

validate()

Validate this model recursively and return a list of ValidationError.

Returns

A list of validation error

Return type

list

class azure.ai.formrecognizer.Style(*, name: Union[str, TextStyle], confidence: float, **kwargs)[source]

An object representing the style of the text line.

All required parameters must be populated in order to send to Azure.

Parameters

  • name (str or TextStyle) – Required. The text line style name, including handwriting and other. Possible values include: “other”, “handwriting”.

  • confidence (float) – Required. The confidence of text line style.

as_dict(keep_readonly=True, key_transformer=<function attribute_transformer>, **kwargs)

Return a dict that can be JSONify using json.dump.

Advanced usage might optionaly use a callback as parameter:

Key is the attribute name used in Python. Attr_desc is a dict of metadata. Currently contains ‘type’ with the msrest type and ‘key’ with the RestAPI encoded key. Value is the current value in this object.

The string returned will be used to serialize the key. If the return type is a list, this is considered hierarchical result dict.

See the three examples in this file:

  • attribute_transformer

  • full_restapi_key_transformer

  • last_restapi_key_transformer

If you want XML serialization, you can pass the kwargs is_xml=True.

Parameters

key_transformer (function) – A key transformer function.

Returns

A dict JSON compatible object

Return type

dict

classmethod deserialize(data, content_type=None)

Parse a str using the RestAPI syntax and return a model.

Parameters

  • data (str) – A str using RestAPI structure. JSON by default.

  • content_type (str) – JSON by default, set application/xml if XML.

Returns

An instance of this model

Raises

DeserializationError if something went wrong

classmethod enable_additional_properties_sending()
classmethod from_dict(data, key_extractors=None, content_type=None)

Parse a dict using given key extractor return a model.

By default consider key extractors (rest_key_case_insensitive_extractor, attribute_key_case_insensitive_extractor and last_rest_key_case_insensitive_extractor)

Parameters

  • data (dict) – A dict using RestAPI structure

  • content_type (str) – JSON by default, set application/xml if XML.

Returns

An instance of this model

Raises

DeserializationError if something went wrong

classmethod is_xml_model()
serialize(keep_readonly=False, **kwargs)

Return the JSON that would be sent to azure from this model.

This is an alias to as_dict(full_restapi_key_transformer, keep_readonly=False).

If you want XML serialization, you can pass the kwargs is_xml=True.

Parameters

keep_readonly (bool) – If you want to serialize the readonly attributes

Returns

A dict JSON compatible object

Return type

dict

validate()

Validate this model recursively and return a list of ValidationError.

Returns

A list of validation error

Return type

list