Package: azure-ai-formrecognizer
Azure Form Recognizer client library for PythonAzure Document Intelligence (previously known as Form Recognizer) is a cloud service that uses machine learning to analyze text and structured data from your documents. It includes the following main features:Layout - Extract content and structure (ex. words, selection marks, tables) from documents.Document - Analyze key-value pairs in addition to general layout from documents.Read - Read page information from documents.Prebuilt - Extract common field values from select document types (ex. receipts, invoices, business cards, ID documents, U.S. W-2 tax documents, among others) using prebuilt models.Custom - Build custom models from your own data to extract tailored field values in addition to general layout from documents.Classifiers - Build custom classification models that combine layout and language features to accurately detect and identify documents you process within your application.Add-on capabilities - Extract barcodes/QR codes, formulas, font/style, etc. or enable high resolution mode for large documents with optional parameters.Source code|Package (PyPI)|Package (Conda)|API reference documentation|Product documentation|SamplesGetting startedPrerequisitesPython 3.7 or later is required to use this package.You must have anAzure subscriptionand aCognitive Services or Form Recognizer resourceto use this package.Install the packageInstall the Azure Form Recognizer client library for Python withpip:pipinstallazure-ai-formrecognizerNote: This version of the client library defaults to the2023-07-31version of the service.This table shows the relationship between SDK versions and supported API versions of the service:SDK versionSupported API version of service3.3.X - Latest GA release2.0, 2.1, 2022-08-31, 2023-07-31 (default)3.2.X2.0, 2.1, 2022-08-31 (default)3.1.X2.0, 2.1 (default)3.0.02.0Note: Starting with version3.2.X, a new set of clients were introduced to leverage the newest features
of the Document Intelligence service. Please see theMigration Guidefor detailed instructions on how to update application
code from client library version3.1.Xor lower to the latest version. Additionally, see theChangelogfor more detailed information.
The below table describes the relationship of each client and its supported API version(s):API versionSupported clients2023-07-31DocumentAnalysisClient and DocumentModelAdministrationClient2022-08-31DocumentAnalysisClient and DocumentModelAdministrationClient2.1FormRecognizerClient and FormTrainingClient2.0FormRecognizerClient and FormTrainingClientCreate a Cognitive Services or Form Recognizer resourceDocument Intelligence supports bothmulti-service and single-service access. Create a Cognitive Services resource if you plan to access multiple cognitive services under a single endpoint/key. For Document Intelligence access only, create a Form Recognizer resource. Please note that you will need a single-service resource if you intend to useAzure Active Directory authentication.You can create either resource using:Option 1:Azure Portal.Option 2:Azure CLI.Below is an example of how you can create a Form Recognizer resource using the CLI:# Create a new resource group to hold the Form Recognizer resource# if using an existing resource group, skip this stepazgroupcreate--name<your-resource-name>--location<location># Create form recognizerazcognitiveservicesaccountcreate\--name<your-resource-name>\--resource-group<your-resource-group-name>\--kindFormRecognizer\--sku<sku>\--location<location>\--yesFor more information about creating the resource or how to get the location and sku information seehere.Authenticate the clientIn order to interact with the Document Intelligence service, you will need to create an instance of a client.
Anendpointandcredentialare necessary to instantiate the client object.Get the endpointYou can find the endpoint for your Form Recognizer resource using theAzure PortalorAzure CLI:# Get the endpoint for the Form Recognizer resourceazcognitiveservicesaccountshow--name"resource-name"--resource-group"resource-group-name"--query"properties.endpoint"Either a regional endpoint or a custom subdomain can be used for authentication. They are formatted as follows:Regional endpoint: https://<region>.api.cognitive.microsoft.com/
Custom subdomain: https://<resource-name>.cognitiveservices.azure.com/A regional endpoint is the same for every resource in a region. A complete list of supported regional endpoints can be consultedhere. Please note that regional endpoints do not support AAD authentication.A custom subdomain, on the other hand, is a name that is unique to the Form Recognizer resource. They can only be used bysingle-service resources.Get the API keyThe API key can be found in theAzure Portalor by running the following Azure CLI command:azcognitiveservicesaccountkeyslist--name"<resource-name>"--resource-group"<resource-group-name>"Create the client with AzureKeyCredentialTo use anAPI keyas thecredentialparameter,
pass the key as a string into an instance ofAzureKeyCredential.fromazure.core.credentialsimportAzureKeyCredentialfromazure.ai.formrecognizerimportDocumentAnalysisClientendpoint="https://<my-custom-subdomain>.cognitiveservices.azure.com/"credential=AzureKeyCredential("<api_key>")document_analysis_client=DocumentAnalysisClient(endpoint,credential)Create the client with an Azure Active Directory credentialAzureKeyCredentialauthentication is used in the examples in this getting started guide, but you can also
authenticate with Azure Active Directory using theazure-identitylibrary.
Note that regional endpoints do not support AAD authentication. Create acustom subdomainname for your resource in order to use this type of authentication.To use theDefaultAzureCredentialtype shown below, or other credential types provided
with the Azure SDK, please install theazure-identitypackage:pip install azure-identityYou will also need toregister a new AAD application and grant accessto Document Intelligence by assigning the"Cognitive Services User"role to your service principal.Once completed, set the values of the client ID, tenant ID, and client secret of the AAD application as environment variables:AZURE_CLIENT_ID,AZURE_TENANT_ID,AZURE_CLIENT_SECRET."""DefaultAzureCredential will use the values from these environmentvariables: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET"""fromazure.ai.formrecognizerimportDocumentAnalysisClientfromazure.identityimportDefaultAzureCredentialendpoint=os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]credential=DefaultAzureCredential()document_analysis_client=DocumentAnalysisClient(endpoint,credential)Key conceptsDocumentAnalysisClientDocumentAnalysisClientprovides operations for analyzing input documents using prebuilt and custom models through thebegin_analyze_documentandbegin_analyze_document_from_urlAPIs.
Use themodel_idparameter to select the type of model for analysis. See a full list of supported modelshere.
TheDocumentAnalysisClientalso provides operations for classifying documents through thebegin_classify_documentandbegin_classify_document_from_urlAPIs.
Custom classification models can classify each page in an input file to identify the document(s) within and can also identify multiple documents or multiple instances of a single document within an input file.Sample code snippets are provided to illustrate using a DocumentAnalysisClienthere.
More information about analyzing documents, including supported features, locales, and document types can be found in theservice documentation.DocumentModelAdministrationClientDocumentModelAdministrationClientprovides operations for:Building custom models to analyze specific fields you specify by labeling your custom documents. ADocumentModelDetailsis returned indicating the document type(s) the model can analyze, as well as the estimated confidence for each field. See theservice documentationfor a more detailed explanation.Creating a composed model from a collection of existing models.Managing models created in your account.Listing operations or getting a specific model operation created within the last 24 hours.Copying a custom model from one Form Recognizer resource to another.Build and manage a custom classification model to classify the documents you process within your application.Please note that models can also be built using a graphical user interface such asDocument Intelligence Studio.Sample code snippets are provided to illustrate using a DocumentModelAdministrationClienthere.Long-running operationsLong-running operations are operations which consist of an initial request sent to the service to start an operation,
followed by polling the service at intervals to determine whether the operation has completed or failed, and if it has
succeeded, to get the result.Methods that analyze documents, build models, or copy/compose models are modeled as long-running operations.
The client exposes abegin_<method-name>method that returns anLROPollerorAsyncLROPoller. Callers should wait
for the operation to complete by callingresult()on the poller object returned from thebegin_<method-name>method.
Sample code snippets are provided to illustrate using long-running operationsbelow.ExamplesThe following section provides several code snippets covering some of the most common Document Intelligence tasks, including:Extract LayoutUsing the General Document ModelUsing Prebuilt ModelsBuild a Custom ModelAnalyze Documents Using a Custom ModelManage Your ModelsClassify DocumentsAdd-on capabilitiesExtract LayoutExtract text, selection marks, text styles, and table structures, along with their bounding region coordinates, from documents.fromazure.core.credentialsimportAzureKeyCredentialfromazure.ai.formrecognizerimportDocumentAnalysisClientendpoint=os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]key=os.environ["AZURE_FORM_RECOGNIZER_KEY"]document_analysis_client=DocumentAnalysisClient(endpoint=endpoint,credential=AzureKeyCredential(key))withopen(path_to_sample_documents,"rb")asf:poller=document_analysis_client.begin_analyze_document("prebuilt-layout",document=f)result=poller.result()foridx,styleinenumerate(result.styles):print("Document contains{}content".format("handwritten"ifstyle.is_handwrittenelse"no handwritten"))forpageinresult.pages:print("----Analyzing layout from page #{}----".format(page.page_number))print("Page has width:{}and height:{}, measured with unit:{}".format(page.width,page.height,page.unit))forline_idx,lineinenumerate(page.lines):words=line.get_words()print("...Line #{}has word count{}and text '{}' within bounding polygon '{}'".format(line_idx,len(words),line.content,line.polygon,))forwordinwords:print("......Word '{}' has a confidence of{}".format(word.content,word.confidence))forselection_markinpage.selection_marks:print("...Selection mark is '{}' within bounding polygon '{}' and has a confidence of{}".format(selection_mark.state,selection_mark.polygon,selection_mark.confidence,))fortable_idx,tableinenumerate(result.tables):print("Table #{}has{}rows and{}columns".format(table_idx,table.row_count,table.column_count))forregionintable.bounding_regions:print("Table #{}location on page:{}is{}".format(table_idx,region.page_number,region.polygon,))forcellintable.cells:print("...Cell[{}][{}] has content '{}'".format(cell.row_index,cell.column_index,cell.content,))forregionincell.bounding_regions:print("...content on page{}is within bounding polygon '{}'".format(region.page_number,region.polygon,))print("----------------------------------------")Using the General Document ModelAnalyze key-value pairs, tables, styles, and selection marks from documents using the general document model provided by the Document Intelligence service.
Select the General Document Model by passingmodel_id="prebuilt-document"into thebegin_analyze_documentmethod:fromazure.core.credentialsimportAzureKeyCredentialfromazure.ai.formrecognizerimportDocumentAnalysisClientendpoint=os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]key=os.environ["AZURE_FORM_RECOGNIZER_KEY"]document_analysis_client=DocumentAnalysisClient(endpoint=endpoint,credential=AzureKeyCredential(key))withopen(path_to_sample_documents,"rb")asf:poller=document_analysis_client.begin_analyze_document("prebuilt-document",document=f)result=poller.result()forstyleinresult.styles:ifstyle.is_handwritten:print("Document contains handwritten content: ")print(",".join([result.content[span.offset:span.offset+span.length]forspaninstyle.spans]))print("----Key-value pairs found in document----")forkv_pairinresult.key_value_pairs:ifkv_pair.key:print("Key '{}' found within '{}' bounding regions".format(kv_pair.key.content,kv_pair.key.bounding_regions,))ifkv_pair.value:print("Value '{}' found within '{}' bounding regions\n".format(kv_pair.value.content,kv_pair.value.bounding_regions,))forpageinresult.pages:print("----Analyzing document from page #{}----".format(page.page_number))print("Page has width:{}and height:{}, measured with unit:{}".format(page.width,page.height,page.unit))forline_idx,lineinenumerate(page.lines):words=line.get_words()print("...Line #{}has{}words and text '{}' within bounding polygon '{}'".format(line_idx,len(words),line.content,line.polygon,))forwordinwords:print("......Word '{}' has a confidence of{}".format(word.content,word.confidence))forselection_markinpage.selection_marks:print("...Selection mark is '{}' within bounding polygon '{}' and has a confidence of{}".format(selection_mark.state,selection_mark.polygon,selection_mark.confidence,))fortable_idx,tableinenumerate(result.tables):print("Table #{}has{}rows and{}columns".format(table_idx,table.row_count,table.column_count))forregionintable.bounding_regions:print("Table #{}location on page:{}is{}".format(table_idx,region.page_number,region.polygon,))forcellintable.cells:print("...Cell[{}][{}] has content '{}'".format(cell.row_index,cell.column_index,cell.content,))forregionincell.bounding_regions:print("...content on page{}is within bounding polygon '{}'\n".format(region.page_number,region.polygon,))print("----------------------------------------")Read more about the features provided by theprebuilt-documentmodelhere.Using Prebuilt ModelsExtract fields from select document types such as receipts, invoices, business cards, identity documents, and U.S. W-2 tax documents using prebuilt models provided by the Document Intelligence service.For example, to analyze fields from a sales receipt, use the prebuilt receipt model provided by passingmodel_id="prebuilt-receipt"into thebegin_analyze_documentmethod:fromazure.core.credentialsimportAzureKeyCredentialfromazure.ai.formrecognizerimportDocumentAnalysisClientendpoint=os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]key=os.environ["AZURE_FORM_RECOGNIZER_KEY"]document_analysis_client=DocumentAnalysisClient(endpoint=endpoint,credential=AzureKeyCredential(key))withopen(path_to_sample_documents,"rb")asf:poller=document_analysis_client.begin_analyze_document("prebuilt-receipt",document=f,locale="en-US")receipts=poller.result()foridx,receiptinenumerate(receipts.documents):print(f"--------Analysis of receipt #{idx+1}--------")print(f"Receipt type:{receipt.doc_typeifreceipt.doc_typeelse'N/A'}")merchant_name=receipt.fields.get("MerchantName")ifmerchant_name:print(f"Merchant Name:{merchant_name.value}has confidence: "f"{merchant_name.confidence}")transaction_date=receipt.fields.get("TransactionDate")iftransaction_date:print(f"Transaction Date:{transaction_date.value}has confidence: "f"{transaction_date.confidence}")ifreceipt.fields.get("Items"):print("Receipt items:")foridx,iteminenumerate(receipt.fields.get("Items").value):print(f"...Item #{idx+1}")item_description=item.value.get("Description")ifitem_description:print(f"......Item Description:{item_description.value}has confidence: "f"{item_description.confidence}")item_quantity=item.value.get("Quantity")ifitem_quantity:print(f"......Item Quantity:{item_quantity.value}has confidence: "f"{item_quantity.confidence}")item_price=item.value.get("Price")ifitem_price:print(f"......Individual Item Price:{item_price.value}has confidence: "f"{item_price.confidence}")item_total_price=item.value.get("TotalPrice")ifitem_total_price:print(f"......Total Item Price:{item_total_price.value}has confidence: "f"{item_total_price.confidence}")subtotal=receipt.fields.get("Subtotal")ifsubtotal:print(f"Subtotal:{subtotal.value}has confidence:{subtotal.confidence}")tax=receipt.fields.get("TotalTax")iftax:print(f"Total tax:{tax.value}has confidence:{tax.confidence}")tip=receipt.fields.get("Tip")iftip:print(f"Tip:{tip.value}has confidence:{tip.confidence}")total=receipt.fields.get("Total")iftotal:print(f"Total:{total.value}has confidence:{total.confidence}")print("--------------------------------------")You are not limited to receipts! There are a few prebuilt models to choose from, each of which has its own set of supported fields. See other supported prebuilt modelshere.Build a Custom ModelBuild a custom model on your own document type. The resulting model can be used to analyze values from the types of documents it was trained on.
Provide a container SAS URL to your Azure Storage Blob container where you're storing the training documents.More details on setting up a container and required file structure can be found in theservice documentation.fromazure.ai.formrecognizerimport(DocumentModelAdministrationClient,ModelBuildMode,)fromazure.core.credentialsimportAzureKeyCredentialendpoint=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_document_model(ModelBuildMode.TEMPLATE,blob_container_url=container_sas_url,description="my model description",)model=poller.result()print(f"Model ID:{model.model_id}")print(f"Description:{model.description}")print(f"Model created on:{model.created_on}")print(f"Model expires on:{model.expires_on}")print("Doc types the model can recognize:")forname,doc_typeinmodel.doc_types.items():print(f"Doc Type: '{name}' built with '{doc_type.build_mode}' mode which has the following fields:")forfield_name,fieldindoc_type.field_schema.items():print(f"Field: '{field_name}' has type '{field['type']}' and confidence score "f"{doc_type.field_confidence[field_name]}")Analyze Documents Using a Custom ModelAnalyze document fields, tables, selection marks, and more. These models are trained with your own data, so they're tailored to your documents.
For best results, you should only analyze documents of the same document type that the custom model was built with.fromazure.core.credentialsimportAzureKeyCredentialfromazure.ai.formrecognizerimportDocumentAnalysisClientendpoint=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 analyzewithopen(path_to_sample_documents,"rb")asf:poller=document_analysis_client.begin_analyze_document(model_id=model_id,document=f)result=poller.result()foridx,documentinenumerate(result.documents):print(f"--------Analyzing document #{idx+1}--------")print(f"Document has type{document.doc_type}")print(f"Document has document type confidence{document.confidence}")print(f"Document was analyzed with model with ID{result.model_id}")forname,fieldindocument.fields.items():field_value=field.valueiffield.valueelsefield.contentprint(f"......found field of type '{field.value_type}' with value '{field_value}' and with confidence{field.confidence}")# iterate over tables, lines, and selection marks on each pageforpageinresult.pages:print(f"\nLines found on page{page.page_number}")forlineinpage.lines:print(f"...Line '{line.content}'")forwordinpage.words:print(f"...Word '{word.content}' has a confidence of{word.confidence}")ifpage.selection_marks:print(f"\nSelection marks found on page{page.page_number}")forselection_markinpage.selection_marks:print(f"...Selection mark is '{selection_mark.state}' and has a confidence of{selection_mark.confidence}")fori,tableinenumerate(result.tables):print(f"\nTable{i+1}can be found on page:")forregionintable.bounding_regions:print(f"...{region.page_number}")forcellintable.cells:print(f"...Cell[{cell.row_index}][{cell.column_index}] has text '{cell.content}'")print("-----------------------------------")Alternatively, a document URL can also be used to analyze documents using thebegin_analyze_document_from_urlmethod.document_url="<url_of_the_document>"poller=document_analysis_client.begin_analyze_document_from_url(model_id=model_id,document_url=document_url)result=poller.result()Manage Your ModelsManage the custom models attached to your account.fromazure.ai.formrecognizerimportDocumentModelAdministrationClientfromazure.core.credentialsimportAzureKeyCredentialfromazure.core.exceptionsimportResourceNotFoundErrorendpoint="https://<my-custom-subdomain>.cognitiveservices.azure.com/"credential=AzureKeyCredential("<api_key>")document_model_admin_client=DocumentModelAdministrationClient(endpoint,credential)account_details=document_model_admin_client.get_resource_details()print("Our account has{}custom models, and we can have at most{}custom models".format(account_details.custom_document_models.count,account_details.custom_document_models.limit))# Here we get a paged list of all of our modelsmodels=document_model_admin_client.list_document_models()print("We have models with the following ids:{}".format(", ".join([m.model_idforminmodels])))# Replace with the custom model ID from the "Build a model" samplemodel_id="<model_id from the Build a Model sample>"custom_model=document_model_admin_client.get_document_model(model_id=model_id)print("Model ID:{}".format(custom_model.model_id))print("Description:{}".format(custom_model.description))print("Model created on:{}\n".format(custom_model.created_on))# Finally, we will delete this model by IDdocument_model_admin_client.delete_document_model(model_id=custom_model.model_id)try:document_model_admin_client.get_document_model(model_id=custom_model.model_id)exceptResourceNotFoundError:print("Successfully deleted model with id{}".format(custom_model.model_id))Add-on CapabilitiesDocument Intelligence supports more sophisticated analysis capabilities. These optional features can be enabled and disabled depending on the scenario of the document extraction.The following add-on capabilities are available for 2023-07-31 (GA) and later releases:barcode/QR codeformulafont/stylehigh resolution modelanguageNote that some add-on capabilities will incur additional charges. See pricing:https://azure.microsoft.com/pricing/details/ai-document-intelligence/.TroubleshootingGeneralForm Recognizer client library will raise exceptions defined inAzure Core.
Error codes and messages raised by the Document Intelligence service can be found in theservice documentation.LoggingThis library uses the standardlogginglibrary for logging.Basic information about HTTP sessions (URLs, headers, etc.) is logged atINFOlevel.DetailedDEBUGlevel logging, including request/response bodies andunredactedheaders, can be enabled on the client or per-operation with thelogging_enablekeyword argument.See full SDK logging documentation with exampleshere.Optional ConfigurationOptional keyword arguments can be passed in at the client and per-operation level.
The azure-corereference documentationdescribes available configurations for retries, logging, transport protocols, and more.Next stepsMore sample codeSee theSample READMEfor several code snippets illustrating common patterns used in the Form Recognizer Python API.Additional documentationFor more extensive documentation on Azure AI Document Intelligence, see theDocument Intelligence documentationon docs.microsoft.com.ContributingThis project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visitcla.microsoft.com.When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.This project has adopted theMicrosoft Open Source Code of Conduct. For more information see theCode of Conduct FAQor contactopencode@microsoft.comwith any additional questions or comments.Release History3.3.2 (2023-11-07)Bugs FixedFixed incorrect data type for returned formula objects.3.3.1 (2023-10-10)Features AddedExposedsend_request()method in each client to send custom requests using the client's existing pipeline. (#32151)3.3.0 (2023-08-08)This version of the client library defaults to the service API version2023-07-31.Breaking ChangesNote: The following changes are only breaking from the previous beta. They are not breaking against previous stable versions.Going forward this library will default to service API version2023-07-31.Removedquery_fieldskeyword argument frombegin_analyze_document()andbegin_analyze_document_from_url().Removedkindproperty fromDocumentPage.Removedimagesproperty fromDocumentPage.RemovedDocumentImagemodel.Removedannotationsproperty fromDocumentPage.RemovedDocumentAnnotationmodel.Removedcommon_nameproperty fromDocumentKeyValuePair.ChangedAnalysisFeatureenum member names and values. Supported enum members are:OCR_HIGH_RESOLUTION,LANGUAGES,BARCODES,FORMULAS,KEY_VALUE_PAIRS,STYLE_FONT.Renamedcustom_neural_document_model_buildsproperty toneural_document_model_quotaonResourceDetailsmodel.RenamedAzureBlobSourcemodel toBlobSource.RenamedAzureBlobFileListSourcemodel toBlobFileListSource.Markedneural_document_model_quotaas optional onResourceDetails.Other ChangesCorrected typing for thepolygonproperty onDocumentWord,DocumentSelectionMark,DocumentLine.Corrected typing forwords,lines, andselection_marksproperties onDocumentPage.Renamed the samples directory tov3.2_and_later/for samples that support 3.2 and later.3.3.0b1 (2023-04-13)This version of the client library defaults to the service API version2023-02-28-preview.Features AddedAddedfeatureskeyword argument onbegin_analyze_document()andbegin_analyze_document_from_url().Addedquery_fieldskeyword argument onbegin_analyze_document()andbegin_analyze_document_from_url().AddedAnalysisFeatureenum with optional document analysis feature to enable.Addedfile_listkeyword argument onbegin_build_document_model().Added the following optional properties onDocumentStyleclass:similar_font_family,font_style,font_weight,color,background_color.Added support for custom document classification onDocumentModelAdministrationClient:begin_build_document_classifier,list_document_classifiers,get_document_classifier, anddelete_document_classifier.Added support for classifying documents onDocumentAnalysisClient:begin_classify_documentandbegin_classify_document_from_url.AddedClassifierDocumentTypeDetailsto use withbegin_build_document_classifier().Added modelQuotaDetailsand propertycustom_neural_document_model_buildsonResourceDetails.Added kinddocumentClassifierBuildtoOperationSummaryandOperationDetails.Added propertyexpires_ontoDocumentModelDetailsandDocumentModelSummary.Added kindformulaBlocktoDocumentParagraph.Added propertycommon_nametoDocumentKeyValuePair.Added propertycodetoCurrencyValue.Added propertiesunit,city_district,state_district,suburb,house, andleveltoAddressValue.Added "boolean"value_typeandboolvaluetoDocumentField.Added propertiesannotations,images,formulas, andbarcodestoDocumentPage.Added modelsDocumentAnnotation,DocumentImage,DocumentFormula, andDocumentBarcode.3.2.1 (2023-03-07)Bugs FixedCorrected typing forinvoiceargument inbegin_recognize_invoices()on asyncFormRecognizerClient.Fixed issue when callingto_dict()onDocumentFieldwherevalueis not returned for address and currency fields.Corrected typing forform_type_confidenceproperty onRecognizedForm.Corrected typing forappearanceproperty onFormLine.Other ChangesImproved static typing.3.2.0 (2022-09-08)Features AddedContent typeimage/heifis supported for document analysis and building models.Addedcustom_document_modelsproperty onResourceDetails.Added newCustomDocumentModelsDetailsmodel to represent the details of the custom document models in a given Form Recognizer resource.Breaking ChangesThis library will default to service API version2022-08-31going forward.Removedkindproperty onDocumentPage.Renamedbegin_build_model()tobegin_build_document_model()on theDocumentModelAdministrationClient.Renamedbegin_compose_model()tobegin_compose_document_model()on theDocumentModelAdministrationClient.Renamedbegin_copy_model_to()tobegin_copy_document_model_to()on theDocumentModelAdministrationClient.Renamedlist_models()tolist_document_models()on theDocumentModelAdministrationClient.Renamedget_model()toget_document_model()on theDocumentModelAdministrationClient.Renameddelete_model()todelete_document_model()on theDocumentModelAdministrationClient.Removeddocument_model_countanddocument_model_limitproperties onResourceDetails.RenamedDocumentModelOperationDetailstoOperationDetails.RenamedDocumentModelOperationSummarytoOperationSummary.RemovedDocumentContentElement.Removedkindandcontentproperties fromDocumentSelectionMark.RemovedkindfromDocumentWord.Bugs FixedAddedDocumentParagraphto__all__.3.2.0b6 (2022-08-09)Features AddedAddedTargetAuthorizationof typedict[str, str].Breaking ChangesRenamedsourceargument toblob_container_urlonbegin_build_model()and made it a required keyword-only argument.Changed argument order onbegin_build_model().build_modeis the first expected argument, followed byblob_container_url.Renamedbegin_create_composed_model()onDocumentModelAdministrationClienttobegin_compose_model().Renamedget_account_info()onDocumentModelAdministrationClienttoget_resource_details().RenamedDocumentBuildModetoModelBuildMode.RenamedAccountInfomodel toResourceDetails.RenamedDocTypeInfomodel toDocumentTypeDetails.RenamedDocumentModelInfomodel toDocumentModelSummary.RenamedDocumentModeltoDocumentModelDetails.RenamedModelOperationtoDocumentModelOperationDetails.RenamedModelOperationInfotoDocumentModelOperationSummary.Renamedmodelparameter tomodel_idonbegin_analyze_document()andbegin_analyze_document_from_url().Removedcontinuation_tokenkeyword frombegin_analyze_document()andbegin_analyze_document_from_url()onDocumentAnalysisClientand frombegin_build_model(),begin_compose_model()andbegin_copy_model_to()onDocumentModelAdministrationClient.Changed return type ofget_copy_authorization()fromdict[str, str]toTargetAuthorization.Changed expectedtargetparameter inbegin_copy_to()fromdict[str, str]toTargetAuthorization.Long-running operation metadata is now accessible through thedetailsproperty on the returnedDocumentModelAdministrationLROPollerandAsyncDocumentModelAdministrationLROPollerinstances.Other ChangesPython 3.6 is no longer supported in this release. Please use Python 3.7 or later.3.2.0b5 (2022-06-07)Features AddedAddedparagraphsproperty onAnalyzeResult.Added newDocumentParagraphmodel to represent document paragraphs.Added newAddressValuemodel to represent address fields found in documents.Addedkindproperty onDocumentPage.Breaking ChangesRenamedbounding_boxtopolygononBoundingRegion,DocumentContentElement,DocumentLine,DocumentSelectionMark,DocumentWord.Renamedlanguage_codetolocaleonDocumentLanguage.Some models that previously returned string for address related fields may now returnAddressValue. TIP: Useget_model()onDocumentModelAdministrationClientto see updated prebuilt model schemas.Removedentitiesproperty onAnalyzeResult.RemovedDocumentEntitymodel.3.2.0b4 (2022-04-05)Breaking ChangesRenamedbegin_copy_model()tobegin_copy_model_to().Inbegin_create_composed_model(), renamed required parametermodel_idstocomponent_model_ids.Renamedmodel_countandmodel_limitonAccountInfotodocument_model_countanddocument_model_limit.Bugs FixedFixedto_dict()andfrom_dict()methods onDocumentFieldto support converting lists, dictionaries, and CurrenyValue field types to and from a dictionary.Other ChangesRenamedsample_copy_model.pyandsample_copy_model_async.pytosample_copy_model_to.pyandsample_copy_model_to_async.pyunder the3.2-betasamples folder. Updated the samples to use renamed copy model method.3.2.0b3 (2022-02-10)Features AddedAdded newCurrencyValuemodel to represent the amount and currency symbol values found in documents.AddedDocumentBuildModeenum with valuestemplateandneural. These enum values can be passed in for thebuild_modeparameter inbegin_build_model().Addedapi_versionandtagsproperties onModelOperation,ModelOperationInfo,DocumentModel,DocumentModelInfo.Addedbuild_modeproperty onDocTypeInfo.Added atagskeyword argument tobegin_build_model(),begin_create_composed_model(), andget_copy_authorization().Addedlanguagesproperty onAnalyzeResult.Added modelDocumentLanguagethat includes information about the detected languages found in a document.Addedsample_analyze_read.pyandsample_analyze_read_async.pyunder thev3.2-betasamples directory. These samples use the newprebuilt-readmodel added by the service.Addedsample_analyze_tax_us_w2.pyandsample_analyze_tax_us_w2_async.pyunder thev3.2-betasamples directory. These samples use the newprebuilt-tax.us.w2model added by the service.Breaking ChangesAdded new required parameterbuild_modetobegin_build_model().Some models that previously returned float for currency related fields may now return aCurrencyValue. TIP: Useget_model()onDocumentModelAdministrationClientto see updated prebuilt model schemas.Bugs FixedDefault thepercent_completedproperty to 0 when not returned with model operation information.Other ChangesPython 2.7 is no longer supported in this release. Please use Python 3.6 or later.Bumpedazure-coreminimum dependency version from1.13.0to1.20.1.Updated samples that callbegin_build_model()to send thebuild_modeparameter.3.2.0b2 (2021-11-09)Features AddedAddedget_words()onDocumentLine.Added samples showing how to useget_words()on aDocumentLineunder/samples/v3.2-beta:sample_get_words_on_document_line.pyandsample_get_words_on_document_line_async.py.Breaking ChangesRenamedDocumentElementtoDocumentContentElement.3.2.0b1 (2021-10-07)This version of the SDK defaults to the latest supported API version, which is currently 2021-09-30-preview.Note: Starting with version 2021-09-30-preview, a new set of clients were introduced to leverage the newest features of the Form Recognizer service. Please see theMigration Guidefor detailed instructions on how to update application code from client library version 3.1.X or lower to the latest version. Also, please refer to theREADMEfor more information about the library.Features AddedAdded newDocumentAnalysisClientwithbegin_analyze_documentandbegin_analyze_document_from_urlmethods. Use these methods with the latest Form Recognizer
API version to analyze documents, with prebuilt and custom models.Added new models to use with the newDocumentAnalysisClient:AnalyzeResult,AnalyzedDocument,BoundingRegion,DocumentElement,DocumentEntity,DocumentField,DocumentKeyValuePair,DocumentKeyValueElement,DocumentLine,DocumentPage,DocumentSelectionMark,DocumentSpan,DocumentStyle,DocumentTable,DocumentTableCell,DocumentWord.Added newDocumentModelAdministrationClientwith methods:begin_build_model,begin_create_composed_model,begin_copy_model,get_copy_authorization,get_model,delete_model,list_models,get_operation,list_operations,get_account_info,get_document_analysis_client.Added new models to use with the newDocumentModelAdministrationClient:DocumentModel,DocumentModelInfo,DocTypeInfo,ModelOperation,ModelOperationInfo,AccountInfo,DocumentAnalysisError,DocumentAnalysisInnerError.Added samples using theDocumentAnalysisClientandDocumentModelAdministrationClientunder/samples/v3.2-beta.AddedDocumentAnalysisApiVersionto be used withDocumentAnalysisClientandDocumentModelAdministrationClient.Other ChangesPython 3.5 is no longer supported in this release.3.1.2 (2021-08-10)Bugs FixedAHttpResponseErrorwill be immediately raised when the call quota volume is exceeded in aF0tier Form Recognizer
resource.Other ChangesBumpedazure-coreminimum dependency version from1.8.2to1.13.03.1.1 (2021-06-08)Bug FixesHandles invoices that do not have sub-line item fields detected.3.1.0 (2021-05-26)This version of the SDK defaults to the latest supported API version, which currently is v2.1Note: this version will be the last to officially support Python 3.5, future versions will require Python 2.7 or Python 3.6+Breaking Changesbegin_recognize_id_documentsrenamed tobegin_recognize_identity_documents.begin_recognize_id_documents_from_urlrenamed tobegin_recognize_identity_documents_from_url.The modelTextAppearancenow includes the propertiesstyle_nameandstyle_confidencethat were part of theTextStyleobject.Removed the modelTextStyle.Removed field value types "gender" and "country" from theFieldValueTypeenum.Added field value type "countryRegion" to theFieldValueTypeenum.Renamed field name for identity documents from "Country" to "CountryRegion".New featuresAddedto_dictandfrom_dictmethods to all of the models3.1.0b4 (2021-04-06)New featuresNew methodsbegin_recognize_id_documentsandbegin_recognize_id_documents_from_urlintroduced to the SDK. Use these methods to recognize data from identity documents.New field value types "gender" and "country" described in theFieldValueTypeenum.Content-typeimage/bmpnow supported by custom forms and training methods.Added keyword argumentpagesfor business cards, receipts, custom forms, and invoices
to specify which page to process of the document.Added keyword argumentreading_ordertobegin_recognize_contentandbegin_recognize_content_from_url.Dependency UpdatesBumpedmsrestrequirement from0.6.12to0.6.21.3.1.0b3 (2021-02-09)Breaking ChangesAppearanceis renamed toTextAppearanceStyleis renamed toTextStyleClient propertyapi_versionis no longer exposed. Pass keyword argumentapi_versioninto the client to select the
API versionDependency UpdatesBumpedsixrequirement from1.6to1.11.0.3.1.0b2 (2021-01-12)Bug FixesPackage requiresazure-coreversion 1.8.2 or greater3.1.0b1 (2020-11-23)This version of the SDK defaults to the latest supported API version, which currently is v2.1-preview.New featuresNew methodsbegin_recognize_business_cardsandbegin_recognize_business_cards_from_urlintroduced to the SDK. Use these
methods to recognize data from business cardsNew methodsbegin_recognize_invoicesandbegin_recognize_invoices_from_urlintroduced to the SDK. Use these
methods to recognize data from invoicesRecognize receipt methods now take keyword argumentlocaleto optionally indicate the locale of the receipt for
improved resultsAdded ability to create a composed model from theFormTrainingClientby calling methodbegin_create_composed_model()Added support to train and recognize custom forms with selection marks such as check boxes and radio buttons.
This functionality is only available for models trained with labelsAdded propertyselection_markstoFormPagewhich contains a list ofFormSelectionMarkWhen passinginclude_field_elements=True, the propertyfield_elementsonFieldDataandFormTableCellwill
also be populated with any selection marks found on the pageAdded the propertiesmodel_nameandpropertiesto typesCustomFormModelandCustomFormModelInfoAdded keyword argumentmodel_nametobegin_training()andbegin_create_composed_model()Added model typeCustomFormModelPropertiesthat includes information like if a model is a composed modelAdded propertymodel_idtoCustomFormSubmodelandTrainingDocumentInfoAdded propertiesmodel_idandform_type_confidencetoRecognizedFormappearanceproperty added toFormLineto indicate the style of extracted text - like "handwriting" or "other"Added keyword argumentpagestobegin_recognize_contentandbegin_recognize_content_from_urlto specify the page
numbers to analyzeAdded propertybounding_boxtoFormTableContent-typeimage/bmpnow supported by recognize content and prebuilt modelsAdded keyword argumentlanguagetobegin_recognize_contentandbegin_recognize_content_from_urlto specify
which language to process document inDependency updatesPackage now requiresazure-commonversion 1.13.0.0 (2020-08-20)First stable release of the azure-ai-formrecognizer client library.New featuresClient-level, keyword argumentapi_versioncan be used to specify the service API version to use. Currently only v2.0
is supported. See the enumFormRecognizerApiVersionfor supported API versions.FormWordandFormLinenow have attributekindwhich specifies the kind of element it is, e.g. "word" or "line"3.0.0b1 (2020-08-11)The version of this package now targets the service's v2.0 API.Breaking ChangesClient library version bumped to3.0.0b1Values are now capitalized for enumsFormContentType,LengthUnit,TrainingStatus, andCustomFormModelStatusdocument_namerenamed tonameonTrainingDocumentInfoKeyword argumentinclude_sub_foldersrenamed toinclude_subfoldersonbegin_trainingmethodsNew featuresFormFieldnow has attributevalue_typewhich contains the semantic data type of the field value. The options forvalue_typeare described in the enumFieldValueTypeFixes and improvementsFixes a bug where error code and message weren't being returned onHttpResponseErrorif operation failed during pollingFormFieldpropertyvalue_datais now set toNoneif no values are returned on itsFieldData.
Previouslyvalue_datareturned aFieldDatawith all its attributes set toNonein the above case.1.0.0b4 (2020-07-07)Breaking ChangesRecognizedReceiptsclass has been removed.begin_recognize_receiptsandbegin_recognize_receipts_from_urlnow returnRecognizedForm.requested_onhas been renamed totraining_started_onandcompleted_onrenamed totraining_completed_ononCustomFormModelandCustomFormModelInfoFieldTexthas been renamed toFieldDataFormContenthas been renamed toFormElementParameterinclude_text_contenthas been renamed toinclude_field_elementsforbegin_recognize_receipts,begin_recognize_receipts_from_url,begin_recognize_custom_forms, andbegin_recognize_custom_forms_from_urltext_contenthas been renamed tofield_elementsonFieldDataandFormTableCellFixes and improvementsFixes a bug wheretext_anglewas being returned out of the specified interval (-180, 180]1.0.0b3 (2020-06-10)Breaking ChangesAll asynchronous long running operation methods now return an instance of anAsyncLROPollerfromazure-coreAll asynchronous long running operation methods are renamed with thebegin_prefix to indicate that anAsyncLROPolleris returned:train_modelis renamed tobegin_trainingrecognize_receiptsis renamed tobegin_recognize_receiptsrecognize_receipts_from_urlis renamed tobegin_recognize_receipts_from_urlrecognize_contentis renamed tobegin_recognize_contentrecognize_content_from_urlis renamed tobegin_recognize_content_from_urlrecognize_custom_formsis renamed tobegin_recognize_custom_formsrecognize_custom_forms_from_urlis renamed tobegin_recognize_custom_forms_from_urlSync methodbegin_train_modelrenamed tobegin_trainingtraining_filesparameter ofbegin_trainingis renamed totraining_files_urluse_labelsparameter ofbegin_trainingis renamed touse_training_labelslist_model_infosmethod has been renamed tolist_custom_modelsRemovedget_form_training_clientfromFormRecognizerClientAddedget_form_recognizer_clienttoFormTrainingClientAHttpResponseErroris now raised if a model withstatus=="invalid"is returned from thebegin_trainingmethodsPageRangeis renamed toFormPageRangefirst_pageandlast_pagerenamed tofirst_page_numberandlast_page_number, respectively onFormPageRangeFormFielddoes not have a page_numberuse_training_labelsis now a required positional param in thebegin_trainingAPIsstreamandurlparameters found on methods forFormRecognizerClienthave been renamed toformandform_url, respectivelyForbegin_recognize_receiptmethods, parameters have been renamed toreceiptandreceipt_urlcreated_onandlast_modifiedare renamed torequested_onandcompleted_onin theCustomFormModelandCustomFormModelInfomodelsmodelsproperty ofCustomFormModelis renamed tosubmodelsCustomFormSubModelis renamed toCustomFormSubmodelbegin_recognize_receiptsAPIs now return a list ofRecognizedReceiptinstead ofUSReceiptRemovedUSReceipt. To see how to deal with the return value ofbegin_recognize_receipts, see the recognize receipt samples in thesamples directoryfor details.RemovedUSReceiptItem. To see how to access the individual items on a receipt, see the recognize receipt samples in thesamples directoryfor details.RemovedUSReceiptTypeand thereceipt_typeproperty fromRecognizedReceipt. See the recognize receipt samples in thesamples directoryfor details.New featuresSupport to copy a custom model from one Form Recognizer resource to anotherAuthentication usingazure-identitycredentials now supportedsee theAzure Identity documentationfor more informationpage_numberattribute has been added toFormTableAll long running operation methods now accept the keyword argumentcontinuation_tokento restart the poller from a saved stateDependency updatesAdoptedazure-coreversion 1.6.0 or greater1.0.0b2 (2020-05-06)Fixes and improvementsBug fixed whereconfidence==0.0was erroneously getting set to1.0__repr__has been added to all of the models1.0.0b1 (2020-04-23)Version (1.0.0b1) is the first preview of our efforts to create a user-friendly and Pythonic client library for Azure Form Recognizer.
This library replaces the package found here:https://pypi.org/project/azure-cognitiveservices-formrecognizer/For more information about this, and preview releases of other Azure SDK libraries, please visithttps://azure.github.io/azure-sdk/releases/latest/python.html.Breaking changes: New API designNew namespace/package name:The namespace/package name for the Form Recognizer client library has changed fromazure.cognitiveservices.formrecognizertoazure.ai.formrecognizerTwo client design:FormRecognizerClient to analyze fields/values on custom forms, receipts, and form content/layoutFormTrainingClient to train custom models (with/without labels), and manage the custom models on your accountDifferent analyze methods based on input type: file stream or URL.URL input should use the method with suffixfrom_urlStream methods will automatically detect content-type of the input fileAsynchronous APIs added underazure.ai.formrecognizer.aionamespaceAuthentication with API key supported usingAzureKeyCredential("<api_key>")fromazure.core.credentialsNew underlying REST pipeline implementation based on the azure-core libraryClient and pipeline configuration is now available via keyword arguments at both the client level, and per-operation.
See README for a link to optional configuration argumentsNew error hierarchy:All service errors will now use the base type:azure.core.exceptions.HttpResponseError