Microsoft Azure Form Recognizer Client Library for Python
Project description
Azure Form Recognizer client library for Python
Azure 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 and detected languages 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.
Source code | Package (PyPI) | Package (Conda) | API reference documentation | Product documentation | Samples
Getting started
Prerequisites
- Python 3.7 or later is required to use this package.
- You must have an Azure subscription and a Cognitive Services or Form Recognizer resource to use this package.
Install the package
Install the Azure Form Recognizer client library for Python with pip:
pip install azure-ai-formrecognizer --pre
Note: This version of the client library defaults to the
2023-02-28-preview
version of the service.
This table shows the relationship between SDK versions and supported API versions of the service:
SDK version | Supported API version of service |
---|---|
3.3.0bX - Latest beta release | 2.0, 2.1, 2022-08-31, 2023-02-28-preview (default) |
3.2.X - Latest GA release | 2.0, 2.1, 2022-08-31 (default) |
3.1.X | 2.0, 2.1 (default) |
3.0.0 | 2.0 |
Note: Starting with version
3.2.X
, a new set of clients were introduced to leverage the newest features of the Form Recognizer service. Please see the Migration Guide for detailed instructions on how to update application code from client library version3.1.X
or lower to the latest version. Additionally, see the Changelog for more detailed information. The below table describes the relationship of each client and its supported API version(s):
API version | Supported clients |
---|---|
2023-02-28-preview | DocumentAnalysisClient and DocumentModelAdministrationClient |
2022-08-31 | DocumentAnalysisClient and DocumentModelAdministrationClient |
2.1 | FormRecognizerClient and FormTrainingClient |
2.0 | FormRecognizerClient and FormTrainingClient |
Create a Cognitive Services or Form Recognizer resource
Form Recognizer supports both multi-service and single-service access. Create a Cognitive Services resource if you plan to access multiple cognitive services under a single endpoint/key. For Form Recognizer access only, create a Form Recognizer resource. Please note that you will need a single-service resource if you intend to use Azure 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 step
az group create --name <your-resource-name> --location <location>
# Create form recognizer
az cognitiveservices account create \
--name <your-resource-name> \
--resource-group <your-resource-group-name> \
--kind FormRecognizer \
--sku <sku> \
--location <location> \
--yes
For more information about creating the resource or how to get the location and sku information see here.
Authenticate the client
In order to interact with the Form Recognizer service, you will need to create an instance of a client. An endpoint and credential are necessary to instantiate the client object.
Get the endpoint
You can find the endpoint for your Form Recognizer resource using the Azure Portal or Azure CLI:
# Get the endpoint for the form recognizer resource
az cognitiveservices account show --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 consulted here. 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 by single-service resources.
Get the API key
The API key can be found in the Azure Portal or by running the following Azure CLI command:
az cognitiveservices account keys list --name "<resource-name>" --resource-group "<resource-group-name>"
Create the client with AzureKeyCredential
To use an API key as the credential
parameter,
pass the key as a string into an instance of AzureKeyCredential.
from azure.core.credentials import AzureKeyCredential
from azure.ai.formrecognizer import DocumentAnalysisClient
endpoint = "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 credential
AzureKeyCredential
authentication is used in the examples in this getting started guide, but you can also
authenticate with Azure Active Directory using the azure-identity library.
Note that regional endpoints do not support AAD authentication. Create a custom subdomain
name for your resource in order to use this type of authentication.
To use the DefaultAzureCredential type shown below, or other credential types provided
with the Azure SDK, please install the azure-identity
package:
pip install azure-identity
You will also need to register a new AAD application and grant access to Form Recognizer 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 environment
variables: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET
"""
from azure.ai.formrecognizer import DocumentAnalysisClient
from azure.identity import DefaultAzureCredential
endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
credential = DefaultAzureCredential()
document_analysis_client = DocumentAnalysisClient(endpoint, credential)
Key concepts
DocumentAnalysisClient
DocumentAnalysisClient
provides operations for analyzing input documents using prebuilt and custom models through the begin_analyze_document
and begin_analyze_document_from_url
APIs.
Use the model_id
parameter to select the type of model for analysis. See a full list of supported models here.
The DocumentAnalysisClient
also provides operations for classifying documents through the begin_classify_document
and begin_classify_document_from_url
APIs.
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 DocumentAnalysisClient here. More information about analyzing documents, including supported features, locales, and document types can be found in the service documentation.
DocumentModelAdministrationClient
DocumentModelAdministrationClient
provides operations for:
- Building custom models to analyze specific fields you specify by labeling your custom documents. A
DocumentModelDetails
is returned indicating the document type(s) the model can analyze, as well as the estimated confidence for each field. See the service documentation for 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 as Form Recognizer Studio.
Sample code snippets are provided to illustrate using a DocumentModelAdministrationClient here.
Long-running operations
Long-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 a begin_<method-name>
method that returns an LROPoller
or AsyncLROPoller
. Callers should wait
for the operation to complete by calling result()
on the poller object returned from the begin_<method-name>
method.
Sample code snippets are provided to illustrate using long-running operations below.
Examples
The following section provides several code snippets covering some of the most common Form Recognizer tasks, including:
- Extract Layout
- Using the General Document Model
- Using Prebuilt Models
- Build a Custom Model
- Analyze Documents Using a Custom Model
- Manage Your Models
- Classify Documents
Extract Layout
Extract text, selection marks, text styles, and table structures, along with their bounding region coordinates, from documents.
from azure.core.credentials import AzureKeyCredential
from azure.ai.formrecognizer import DocumentAnalysisClient
endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]
document_analysis_client = DocumentAnalysisClient(
endpoint=endpoint, credential=AzureKeyCredential(key)
)
with open(path_to_sample_documents, "rb") as f:
poller = document_analysis_client.begin_analyze_document(
"prebuilt-layout", document=f
)
result = poller.result()
for idx, style in enumerate(result.styles):
print(
"Document contains {} content".format(
"handwritten" if style.is_handwritten else "no handwritten"
)
)
for page in result.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
)
)
for line_idx, line in enumerate(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,
)
)
for word in words:
print(
"......Word '{}' has a confidence of {}".format(
word.content, word.confidence
)
)
for selection_mark in page.selection_marks:
print(
"...Selection mark is '{}' within bounding polygon '{}' and has a confidence of {}".format(
selection_mark.state,
selection_mark.polygon,
selection_mark.confidence,
)
)
for table_idx, table in enumerate(result.tables):
print(
"Table # {} has {} rows and {} columns".format(
table_idx, table.row_count, table.column_count
)
)
for region in table.bounding_regions:
print(
"Table # {} location on page: {} is {}".format(
table_idx,
region.page_number,
region.polygon,
)
)
for cell in table.cells:
print(
"...Cell[{}][{}] has content '{}'".format(
cell.row_index,
cell.column_index,
cell.content,
)
)
for region in cell.bounding_regions:
print(
"...content on page {} is within bounding polygon '{}'".format(
region.page_number,
region.polygon,
)
)
print("----------------------------------------")
Using the General Document Model
Analyze key-value pairs, tables, styles, and selection marks from documents using the general document model provided by the Form Recognizer service.
Select the General Document Model by passing model_id="prebuilt-document"
into the begin_analyze_document
method:
from azure.core.credentials import AzureKeyCredential
from azure.ai.formrecognizer import DocumentAnalysisClient
endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]
document_analysis_client = DocumentAnalysisClient(
endpoint=endpoint, credential=AzureKeyCredential(key)
)
with open(path_to_sample_documents, "rb") as f:
poller = document_analysis_client.begin_analyze_document(
"prebuilt-document", document=f
)
result = poller.result()
for style in result.styles:
if style.is_handwritten:
print("Document contains handwritten content: ")
print(",".join([result.content[span.offset:span.offset + span.length] for span in style.spans]))
print("----Key-value pairs found in document----")
for kv_pair in result.key_value_pairs:
if kv_pair.key:
print(
"Key '{}' found within '{}' bounding regions".format(
kv_pair.key.content,
kv_pair.key.bounding_regions,
)
)
if kv_pair.value:
print(
"Value '{}' found within '{}' bounding regions\n".format(
kv_pair.value.content,
kv_pair.value.bounding_regions,
)
)
for page in result.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
)
)
for line_idx, line in enumerate(page.lines):
words = line.get_words()
print(
"...Line # {} has {} words and text '{}' within bounding polygon '{}'".format(
line_idx,
len(words),
line.content,
line.polygon,
)
)
for word in words:
print(
"......Word '{}' has a confidence of {}".format(
word.content, word.confidence
)
)
for selection_mark in page.selection_marks:
print(
"...Selection mark is '{}' within bounding polygon '{}' and has a confidence of {}".format(
selection_mark.state,
selection_mark.polygon,
selection_mark.confidence,
)
)
for table_idx, table in enumerate(result.tables):
print(
"Table # {} has {} rows and {} columns".format(
table_idx, table.row_count, table.column_count
)
)
for region in table.bounding_regions:
print(
"Table # {} location on page: {} is {}".format(
table_idx,
region.page_number,
region.polygon,
)
)
for cell in table.cells:
print(
"...Cell[{}][{}] has content '{}'".format(
cell.row_index,
cell.column_index,
cell.content,
)
)
for region in cell.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 the
prebuilt-document
model here.
Using Prebuilt Models
Extract 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 Form Recognizer service.
For example, to analyze fields from a sales receipt, use the prebuilt receipt model provided by passing model_id="prebuilt-receipt"
into the begin_analyze_document
method:
from azure.core.credentials import AzureKeyCredential
from azure.ai.formrecognizer import DocumentAnalysisClient
endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]
document_analysis_client = DocumentAnalysisClient(
endpoint=endpoint, credential=AzureKeyCredential(key)
)
with open(path_to_sample_documents, "rb") as f:
poller = document_analysis_client.begin_analyze_document(
"prebuilt-receipt", document=f, locale="en-US"
)
receipts = poller.result()
for idx, receipt in enumerate(receipts.documents):
print("--------Analysis of receipt #{}--------".format(idx + 1))
print("Receipt type: {}".format(receipt.doc_type or "N/A"))
merchant_name = receipt.fields.get("MerchantName")
if merchant_name:
print(
"Merchant Name: {} has confidence: {}".format(
merchant_name.value, merchant_name.confidence
)
)
transaction_date = receipt.fields.get("TransactionDate")
if transaction_date:
print(
"Transaction Date: {} has confidence: {}".format(
transaction_date.value, transaction_date.confidence
)
)
if receipt.fields.get("Items"):
print("Receipt items:")
for idx, item in enumerate(receipt.fields.get("Items").value):
print("...Item #{}".format(idx + 1))
item_description = item.value.get("Description")
if item_description:
print(
"......Item Description: {} has confidence: {}".format(
item_description.value, item_description.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("TotalTax")
if tax:
print("Total 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("--------------------------------------")
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 models here.
Build a Custom Model
Build 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 the service documentation.
from azure.ai.formrecognizer import DocumentModelAdministrationClient, ModelBuildMode
from azure.core.credentials import AzureKeyCredential
endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]
container_sas_url = os.environ["CONTAINER_SAS_URL"]
document_model_admin_client = DocumentModelAdministrationClient(endpoint, AzureKeyCredential(key))
poller = document_model_admin_client.begin_build_document_model(
ModelBuildMode.TEMPLATE, blob_container_url=container_sas_url, description="my model description"
)
model = poller.result()
print("Model ID: {}".format(model.model_id))
print("Description: {}".format(model.description))
print("Model created on: {}\n".format(model.created_on))
print("Doc types the model can recognize:")
for name, doc_type in model.doc_types.items():
print("\nDoc Type: '{}' built with '{}' mode which has the following fields:".format(name, doc_type.build_mode))
for field_name, field in doc_type.field_schema.items():
print("Field: '{}' has type '{}' and confidence score {}".format(
field_name, field["type"], doc_type.field_confidence[field_name]
))
Analyze Documents Using a Custom Model
Analyze 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.
from azure.core.credentials import AzureKeyCredential
from azure.ai.formrecognizer import DocumentAnalysisClient
endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]
model_id = os.getenv("CUSTOM_BUILT_MODEL_ID", custom_model_id)
document_analysis_client = DocumentAnalysisClient(
endpoint=endpoint, credential=AzureKeyCredential(key)
)
# Make sure your document's type is included in the list of document types the custom model can analyze
with open(path_to_sample_documents, "rb") as f:
poller = document_analysis_client.begin_analyze_document(
model_id=model_id, document=f
)
result = poller.result()
for idx, document in enumerate(result.documents):
print("--------Analyzing document #{}--------".format(idx + 1))
print("Document has type {}".format(document.doc_type))
print("Document has confidence {}".format(document.confidence))
print("Document was analyzed by model with ID {}".format(result.model_id))
for name, field in document.fields.items():
field_value = field.value if field.value else field.content
print("......found field of type '{}' with value '{}' and with confidence {}".format(field.value_type, field_value, field.confidence))
# iterate over tables, lines, and selection marks on each page
for page in result.pages:
print("\nLines found on page {}".format(page.page_number))
for line in page.lines:
print("...Line '{}'".format(line.content))
for word in page.words:
print(
"...Word '{}' has a confidence of {}".format(
word.content, word.confidence
)
)
for selection_mark in page.selection_marks:
print(
"...Selection mark is '{}' and has a confidence of {}".format(
selection_mark.state, selection_mark.confidence
)
)
for i, table in enumerate(result.tables):
print("\nTable {} can be found on page:".format(i + 1))
for region in table.bounding_regions:
print("...{}".format(region.page_number))
for cell in table.cells:
print(
"...Cell[{}][{}] has content '{}'".format(
cell.row_index, cell.column_index, cell.content
)
)
print("-----------------------------------")
Alternatively, a document URL can also be used to analyze documents using the begin_analyze_document_from_url
method.
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 Models
Manage the custom models attached to your account.
from azure.ai.formrecognizer import DocumentModelAdministrationClient
from azure.core.credentials import AzureKeyCredential
from azure.core.exceptions import ResourceNotFoundError
endpoint = "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 models
models = document_model_admin_client.list_document_models()
print("We have models with the following ids: {}".format(
", ".join([m.model_id for m in models])
))
# Replace with the custom model ID from the "Build a model" sample
model_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 ID
document_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)
except ResourceNotFoundError:
print("Successfully deleted model with id {}".format(custom_model.model_id))
Troubleshooting
General
Form Recognizer client library will raise exceptions defined in Azure Core. Error codes and messages raised by the Form Recognizer service can be found in the service documentation.
Logging
This library uses the standard logging library for logging.
Basic information about HTTP sessions (URLs, headers, etc.) is logged at INFO
level.
Detailed DEBUG
level logging, including request/response bodies and unredacted
headers, can be enabled on the client or per-operation with the logging_enable
keyword argument.
See full SDK logging documentation with examples here.
Optional Configuration
Optional keyword arguments can be passed in at the client and per-operation level. The azure-core reference documentation describes available configurations for retries, logging, transport protocols, and more.
Next steps
More sample code
See the Sample README for several code snippets illustrating common patterns used in the Form Recognizer Python API.
Additional documentation
For more extensive documentation on Azure Cognitive Services Form Recognizer, see the Form Recognizer documentation on docs.microsoft.com.
Contributing
This 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, visit cla.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 the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.
Release History
3.3.0b1 (2023-04-13)
This version of the client library defaults to the service API version 2023-02-28-preview
.
Features Added
- Added
features
keyword argument onbegin_analyze_document()
andbegin_analyze_document_from_url()
. - Added
query_fields
keyword argument onbegin_analyze_document()
andbegin_analyze_document_from_url()
. - Added
AnalysisFeature
enum with optional document analysis feature to enable. - Added
file_list
keyword argument onbegin_build_document_model()
. - Added the following optional properties on
DocumentStyle
class:similar_font_family
,font_style
,font_weight
,color
,background_color
. - Added support for custom document classification on
DocumentModelAdministrationClient
:begin_build_document_classifier
,list_document_classifiers
,get_document_classifier
, anddelete_document_classifier
. - Added support for classifying documents on
DocumentAnalysisClient
:begin_classify_document
andbegin_classify_document_from_url
. - Added
ClassifierDocumentTypeDetails
to use withbegin_build_document_classifier()
. - Added model
QuotaDetails
and propertycustom_neural_document_model_builds
onResourceDetails
. - Added kind
documentClassifierBuild
toOperationSummary
andOperationDetails
. - Added property
expires_on
toDocumentModelDetails
andDocumentModelSummary
. - Added kind
formulaBlock
toDocumentParagraph
. - Added property
common_name
toDocumentKeyValuePair
. - Added property
code
toCurrencyValue
. - Added properties
unit
,city_district
,state_district
,suburb
,house
, andlevel
toAddressValue
. - Added "boolean"
value_type
andbool
value
toDocumentField
. - Added properties
annotations
,images
,formulas
, andbarcodes
toDocumentPage
. - Added models
DocumentAnnotation
,DocumentImage
,DocumentFormula
, andDocumentBarcode
.
3.2.1 (2023-03-07)
Bugs Fixed
- Corrected typing for
invoice
argument inbegin_recognize_invoices()
on asyncFormRecognizerClient
. - Fixed issue when calling
to_dict()
onDocumentField
wherevalue
is not returned for address and currency fields. - Corrected typing for
form_type_confidence
property onRecognizedForm
. - Corrected typing for
appearance
property onFormLine
.
Other Changes
- Improved static typing.
3.2.0 (2022-09-08)
Features Added
- Content type
image/heif
is supported for document analysis and building models. - Added
custom_document_models
property onResourceDetails
. - Added new
CustomDocumentModelsDetails
model to represent the details of the custom document models in a given Form Recognizer resource.
Breaking Changes
- This library will default to service API version
2022-08-31
going forward. - Removed
kind
property onDocumentPage
. - Renamed
begin_build_model()
tobegin_build_document_model()
on theDocumentModelAdministrationClient
. - Renamed
begin_compose_model()
tobegin_compose_document_model()
on theDocumentModelAdministrationClient
. - Renamed
begin_copy_model_to()
tobegin_copy_document_model_to()
on theDocumentModelAdministrationClient
. - Renamed
list_models()
tolist_document_models()
on theDocumentModelAdministrationClient
. - Renamed
get_model()
toget_document_model()
on theDocumentModelAdministrationClient
. - Renamed
delete_model()
todelete_document_model()
on theDocumentModelAdministrationClient
. - Removed
document_model_count
anddocument_model_limit
properties onResourceDetails
. - Renamed
DocumentModelOperationDetails
toOperationDetails
. - Renamed
DocumentModelOperationSummary
toOperationSummary
. - Removed
DocumentContentElement
. - Removed
kind
andcontent
properties fromDocumentSelectionMark
. - Removed
kind
fromDocumentWord
.
Bugs Fixed
- Added
DocumentParagraph
to__all__
.
3.2.0b6 (2022-08-09)
Features Added
- Added
TargetAuthorization
of typedict[str, str]
.
Breaking Changes
- Renamed
source
argument toblob_container_url
onbegin_build_model()
and made it a required keyword-only argument. - Changed argument order on
begin_build_model()
.build_mode
is the first expected argument, followed byblob_container_url
. - Renamed
begin_create_composed_model()
onDocumentModelAdministrationClient
tobegin_compose_model()
. - Renamed
get_account_info()
onDocumentModelAdministrationClient
toget_resource_details()
. - Renamed
DocumentBuildMode
toModelBuildMode
. - Renamed
AccountInfo
model toResourceDetails
. - Renamed
DocTypeInfo
model toDocumentTypeDetails
. - Renamed
DocumentModelInfo
model toDocumentModelSummary
. - Renamed
DocumentModel
toDocumentModelDetails
. - Renamed
ModelOperation
toDocumentModelOperationDetails
. - Renamed
ModelOperationInfo
toDocumentModelOperationSummary
. - Renamed
model
parameter tomodel_id
onbegin_analyze_document()
andbegin_analyze_document_from_url()
. - Removed
continuation_token
keyword frombegin_analyze_document()
andbegin_analyze_document_from_url()
onDocumentAnalysisClient
and frombegin_build_model()
,begin_compose_model()
andbegin_copy_model_to()
onDocumentModelAdministrationClient
. - Changed return type of
get_copy_authorization()
fromdict[str, str]
toTargetAuthorization
. - Changed expected
target
parameter inbegin_copy_to()
fromdict[str, str]
toTargetAuthorization
. - Long-running operation metadata is now accessible through the
details
property on the returnedDocumentModelAdministrationLROPoller
andAsyncDocumentModelAdministrationLROPoller
instances.
Other Changes
- Python 3.6 is no longer supported in this release. Please use Python 3.7 or later.
3.2.0b5 (2022-06-07)
Features Added
- Added
paragraphs
property onAnalyzeResult
. - Added new
DocumentParagraph
model to represent document paragraphs. - Added new
AddressValue
model to represent address fields found in documents. - Added
kind
property onDocumentPage
.
Breaking Changes
- Renamed
bounding_box
topolygon
onBoundingRegion
,DocumentContentElement
,DocumentLine
,DocumentSelectionMark
,DocumentWord
. - Renamed
language_code
tolocale
onDocumentLanguage
. - Some models that previously returned string for address related fields may now return
AddressValue
. TIP: Useget_model()
onDocumentModelAdministrationClient
to see updated prebuilt model schemas. - Removed
entities
property onAnalyzeResult
. - Removed
DocumentEntity
model.
3.2.0b4 (2022-04-05)
Breaking Changes
- Renamed
begin_copy_model()
tobegin_copy_model_to()
. - In
begin_create_composed_model()
, renamed required parametermodel_ids
tocomponent_model_ids
. - Renamed
model_count
andmodel_limit
onAccountInfo
todocument_model_count
anddocument_model_limit
.
Bugs Fixed
- Fixed
to_dict()
andfrom_dict()
methods onDocumentField
to support converting lists, dictionaries, and CurrenyValue field types to and from a dictionary.
Other Changes
- Renamed
sample_copy_model.py
andsample_copy_model_async.py
tosample_copy_model_to.py
andsample_copy_model_to_async.py
under the3.2-beta
samples folder. Updated the samples to use renamed copy model method.
3.2.0b3 (2022-02-10)
Features Added
- Added new
CurrencyValue
model to represent the amount and currency symbol values found in documents. - Added
DocumentBuildMode
enum with valuestemplate
andneural
. These enum values can be passed in for thebuild_mode
parameter inbegin_build_model()
. - Added
api_version
andtags
properties onModelOperation
,ModelOperationInfo
,DocumentModel
,DocumentModelInfo
. - Added
build_mode
property onDocTypeInfo
. - Added a
tags
keyword argument tobegin_build_model()
,begin_create_composed_model()
, andget_copy_authorization()
. - Added
languages
property onAnalyzeResult
. - Added model
DocumentLanguage
that includes information about the detected languages found in a document. - Added
sample_analyze_read.py
andsample_analyze_read_async.py
under thev3.2-beta
samples directory. These samples use the newprebuilt-read
model added by the service. - Added
sample_analyze_tax_us_w2.py
andsample_analyze_tax_us_w2_async.py
under thev3.2-beta
samples directory. These samples use the newprebuilt-tax.us.w2
model added by the service.
Breaking Changes
- Added new required parameter
build_mode
tobegin_build_model()
. - Some models that previously returned float for currency related fields may now return a
CurrencyValue
. TIP: Useget_model()
onDocumentModelAdministrationClient
to see updated prebuilt model schemas.
Bugs Fixed
- Default the
percent_completed
property to 0 when not returned with model operation information.
Other Changes
- Python 2.7 is no longer supported in this release. Please use Python 3.6 or later.
- Bumped
azure-core
minimum dependency version from1.13.0
to1.20.1
. - Updated samples that call
begin_build_model()
to send thebuild_mode
parameter.
3.2.0b2 (2021-11-09)
Features Added
- Added
get_words()
onDocumentLine
. - Added samples showing how to use
get_words()
on aDocumentLine
under/samples/v3.2-beta
:sample_get_words_on_document_line.py
andsample_get_words_on_document_line_async.py
.
Breaking Changes
- Renamed
DocumentElement
toDocumentContentElement
.
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 the Migration Guide for 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 the README for more information about the library.
Features Added
- Added new
DocumentAnalysisClient
withbegin_analyze_document
andbegin_analyze_document_from_url
methods. 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 new
DocumentAnalysisClient
:AnalyzeResult
,AnalyzedDocument
,BoundingRegion
,DocumentElement
,DocumentEntity
,DocumentField
,DocumentKeyValuePair
,DocumentKeyValueElement
,DocumentLine
,DocumentPage
,DocumentSelectionMark
,DocumentSpan
,DocumentStyle
,DocumentTable
,DocumentTableCell
,DocumentWord
. - Added new
DocumentModelAdministrationClient
with 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 new
DocumentModelAdministrationClient
:DocumentModel
,DocumentModelInfo
,DocTypeInfo
,ModelOperation
,ModelOperationInfo
,AccountInfo
,DocumentAnalysisError
,DocumentAnalysisInnerError
. - Added samples using the
DocumentAnalysisClient
andDocumentModelAdministrationClient
under/samples/v3.2-beta
. - Added
DocumentAnalysisApiVersion
to be used withDocumentAnalysisClient
andDocumentModelAdministrationClient
.
Other Changes
- Python 3.5 is no longer supported in this release.
3.1.2 (2021-08-10)
Bugs Fixed
- A
HttpResponseError
will be immediately raised when the call quota volume is exceeded in aF0
tier Form Recognizer resource.
Other Changes
- Bumped
azure-core
minimum dependency version from1.8.2
to1.13.0
3.1.1 (2021-06-08)
Bug Fixes
- Handles 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.1
Note: this version will be the last to officially support Python 3.5, future versions will require Python 2.7 or Python 3.6+
Breaking Changes
begin_recognize_id_documents
renamed tobegin_recognize_identity_documents
.begin_recognize_id_documents_from_url
renamed tobegin_recognize_identity_documents_from_url
.- The model
TextAppearance
now includes the propertiesstyle_name
andstyle_confidence
that were part of theTextStyle
object. - Removed the model
TextStyle
. - Removed field value types "gender" and "country" from the
FieldValueType
enum. - Added field value type "countryRegion" to the
FieldValueType
enum. - Renamed field name for identity documents from "Country" to "CountryRegion".
New features
- Added
to_dict
andfrom_dict
methods to all of the models
3.1.0b4 (2021-04-06)
New features
- New methods
begin_recognize_id_documents
andbegin_recognize_id_documents_from_url
introduced to the SDK. Use these methods to recognize data from identity documents. - New field value types "gender" and "country" described in the
FieldValueType
enum. - Content-type
image/bmp
now supported by custom forms and training methods. - Added keyword argument
pages
for business cards, receipts, custom forms, and invoices to specify which page to process of the document. - Added keyword argument
reading_order
tobegin_recognize_content
andbegin_recognize_content_from_url
.
Dependency Updates
- Bumped
msrest
requirement from0.6.12
to0.6.21
.
3.1.0b3 (2021-02-09)
Breaking Changes
Appearance
is renamed toTextAppearance
Style
is renamed toTextStyle
- Client property
api_version
is no longer exposed. Pass keyword argumentapi_version
into the client to select the API version
Dependency Updates
- Bumped
six
requirement from1.6
to1.11.0
.
3.1.0b2 (2021-01-12)
Bug Fixes
- Package requires azure-core version 1.8.2 or greater
3.1.0b1 (2020-11-23)
This version of the SDK defaults to the latest supported API version, which currently is v2.1-preview.
New features
- New methods
begin_recognize_business_cards
andbegin_recognize_business_cards_from_url
introduced to the SDK. Use these methods to recognize data from business cards - New methods
begin_recognize_invoices
andbegin_recognize_invoices_from_url
introduced to the SDK. Use these methods to recognize data from invoices - Recognize receipt methods now take keyword argument
locale
to optionally indicate the locale of the receipt for improved results - Added ability to create a composed model from the
FormTrainingClient
by 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 labels
- Added property
selection_marks
toFormPage
which contains a list ofFormSelectionMark
- When passing
include_field_elements=True
, the propertyfield_elements
onFieldData
andFormTableCell
will also be populated with any selection marks found on the page - Added the properties
model_name
andproperties
to typesCustomFormModel
andCustomFormModelInfo
- Added keyword argument
model_name
tobegin_training()
andbegin_create_composed_model()
- Added model type
CustomFormModelProperties
that includes information like if a model is a composed model - Added property
model_id
toCustomFormSubmodel
andTrainingDocumentInfo
- Added properties
model_id
andform_type_confidence
toRecognizedForm
appearance
property added toFormLine
to indicate the style of extracted text - like "handwriting" or "other"- Added keyword argument
pages
tobegin_recognize_content
andbegin_recognize_content_from_url
to specify the page numbers to analyze - Added property
bounding_box
toFormTable
- Content-type
image/bmp
now supported by recognize content and prebuilt models - Added keyword argument
language
tobegin_recognize_content
andbegin_recognize_content_from_url
to specify which language to process document in
Dependency updates
- Package now requires azure-common version 1.1
3.0.0 (2020-08-20)
First stable release of the azure-ai-formrecognizer client library.
New features
- Client-level, keyword argument
api_version
can be used to specify the service API version to use. Currently only v2.0 is supported. See the enumFormRecognizerApiVersion
for supported API versions. FormWord
andFormLine
now have attributekind
which 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 Changes
- Client library version bumped to
3.0.0b1
- Values are now capitalized for enums
FormContentType
,LengthUnit
,TrainingStatus
, andCustomFormModelStatus
document_name
renamed toname
onTrainingDocumentInfo
- Keyword argument
include_sub_folders
renamed toinclude_subfolders
onbegin_training
methods
New features
FormField
now has attributevalue_type
which contains the semantic data type of the field value. The options forvalue_type
are described in the enumFieldValueType
Fixes and improvements
- Fixes a bug where error code and message weren't being returned on
HttpResponseError
if operation failed during polling FormField
propertyvalue_data
is now set toNone
if no values are returned on itsFieldData
. Previouslyvalue_data
returned aFieldData
with all its attributes set toNone
in the above case.
1.0.0b4 (2020-07-07)
Breaking Changes
RecognizedReceipts
class has been removed.begin_recognize_receipts
andbegin_recognize_receipts_from_url
now returnRecognizedForm
.requested_on
has been renamed totraining_started_on
andcompleted_on
renamed totraining_completed_on
onCustomFormModel
andCustomFormModelInfo
FieldText
has been renamed toFieldData
FormContent
has been renamed toFormElement
- Parameter
include_text_content
has been renamed toinclude_field_elements
forbegin_recognize_receipts
,begin_recognize_receipts_from_url
,begin_recognize_custom_forms
, andbegin_recognize_custom_forms_from_url
text_content
has been renamed tofield_elements
onFieldData
andFormTableCell
Fixes and improvements
- Fixes a bug where
text_angle
was being returned out of the specified interval (-180, 180]
1.0.0b3 (2020-06-10)
Breaking Changes
- All asynchronous long running operation methods now return an instance of an
AsyncLROPoller
fromazure-core
- All asynchronous long running operation methods are renamed with the
begin_
prefix to indicate that anAsyncLROPoller
is returned:train_model
is renamed tobegin_training
recognize_receipts
is renamed tobegin_recognize_receipts
recognize_receipts_from_url
is renamed tobegin_recognize_receipts_from_url
recognize_content
is renamed tobegin_recognize_content
recognize_content_from_url
is renamed tobegin_recognize_content_from_url
recognize_custom_forms
is renamed tobegin_recognize_custom_forms
recognize_custom_forms_from_url
is renamed tobegin_recognize_custom_forms_from_url
- Sync method
begin_train_model
renamed tobegin_training
training_files
parameter ofbegin_training
is renamed totraining_files_url
use_labels
parameter ofbegin_training
is renamed touse_training_labels
list_model_infos
method has been renamed tolist_custom_models
- Removed
get_form_training_client
fromFormRecognizerClient
- Added
get_form_recognizer_client
toFormTrainingClient
- A
HttpResponseError
is now raised if a model withstatus=="invalid"
is returned from thebegin_training
methods PageRange
is renamed toFormPageRange
first_page
andlast_page
renamed tofirst_page_number
andlast_page_number
, respectively onFormPageRange
FormField
does not have a page_numberuse_training_labels
is now a required positional param in thebegin_training
APIsstream
andurl
parameters found on methods forFormRecognizerClient
have been renamed toform
andform_url
, respectively- For
begin_recognize_receipt
methods, parameters have been renamed toreceipt
andreceipt_url
created_on
andlast_modified
are renamed torequested_on
andcompleted_on
in theCustomFormModel
andCustomFormModelInfo
modelsmodels
property ofCustomFormModel
is renamed tosubmodels
CustomFormSubModel
is renamed toCustomFormSubmodel
begin_recognize_receipts
APIs now return a list ofRecognizedReceipt
instead ofUSReceipt
- Removed
USReceipt
. To see how to deal with the return value ofbegin_recognize_receipts
, see the recognize receipt samples in the samples directory for details. - Removed
USReceiptItem
. To see how to access the individual items on a receipt, see the recognize receipt samples in the samples directory for details. - Removed
USReceiptType
and thereceipt_type
property fromRecognizedReceipt
. See the recognize receipt samples in the samples directory for details.
New features
- Support to copy a custom model from one Form Recognizer resource to another
- Authentication using
azure-identity
credentials now supported- see the Azure Identity documentation for more information
page_number
attribute has been added toFormTable
- All long running operation methods now accept the keyword argument
continuation_token
to restart the poller from a saved state
Dependency updates
- Adopted azure-core version 1.6.0 or greater
1.0.0b2 (2020-05-06)
Fixes and improvements
- Bug fixed where
confidence
==0.0
was erroneously getting set to1.0
__repr__
has been added to all of the models
1.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 visit https://azure.github.io/azure-sdk/releases/latest/python.html.
Breaking changes: New API design
- New namespace/package name:
- The namespace/package name for the Form Recognizer client library has changed from
azure.cognitiveservices.formrecognizer
toazure.ai.formrecognizer
- The namespace/package name for the Form Recognizer client library has changed from
- Two client design:
- FormRecognizerClient to analyze fields/values on custom forms, receipts, and form content/layout
- FormTrainingClient to train custom models (with/without labels), and manage the custom models on your account
- Different analyze methods based on input type: file stream or URL.
- URL input should use the method with suffix
from_url
- Stream methods will automatically detect content-type of the input file
- URL input should use the method with suffix
- Asynchronous APIs added under
azure.ai.formrecognizer.aio
namespace - Authentication with API key supported using
AzureKeyCredential("<api_key>")
fromazure.core.credentials
- New underlying REST pipeline implementation based on the azure-core library
- Client 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 arguments
- New error hierarchy:
- All service errors will now use the base type:
azure.core.exceptions.HttpResponseError
- All service errors will now use the base type:
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for azure-ai-formrecognizer-3.3.0b1.zip
Algorithm | Hash digest | |
---|---|---|
SHA256 | 42f00910e7ae9ce2a3d5ffa4f7aeed43eaa9a471afd5e4c1d32dcd4efb50e4db |
|
MD5 | aea2a427899ba79a52e31d8e48e11e57 |
|
BLAKE2b-256 | 1d33f46bf39a8714317604d7065068b1b0f0eaac1a7c1d366fb80f5d47617049 |
Hashes for azure_ai_formrecognizer-3.3.0b1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 129660b797b1e7445fd7355d22d2b1294bca4249d57aa87e0d0a8669073ac1cf |
|
MD5 | 3318ddcddb7b84168b9624ce871c73af |
|
BLAKE2b-256 | d5dc37a063af34905dcd0c2e997c99202825ecf5ed2c356866ee243c3684fc2d |