Skip to content

Commit

Permalink
[formrecognizer] Add Identity Documents APIs (#17128)
Browse files Browse the repository at this point in the history
* Adding ID docs APIs and tests

* comment test assertions, add recordings

* pylint

* fix type declaration

* update changelog and descriptions
  • Loading branch information
catalinaperalta authored Mar 8, 2021
1 parent a20c361 commit ee1b90d
Show file tree
Hide file tree
Showing 41 changed files with 5,238 additions and 0 deletions.
1 change: 1 addition & 0 deletions sdk/formrecognizer/azure-ai-formrecognizer/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@

**New features**

- New methods `begin_recognize_id_documents` and `begin_recognize_id_documents_from_url` introduced to the SDK. Use these methods to recognize data from identity documents.
- Content-type `image/bmp` now supported by custom forms and training methods.

**Dependency Updates**
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -336,6 +336,121 @@ def begin_recognize_business_cards_from_url(self, business_card_url, **kwargs):
)
raise e

@distributed_trace
def begin_recognize_id_documents(self, id_document, **kwargs):
# type: (Union[bytes, IO[bytes]], Any) -> LROPoller[List[RecognizedForm]]
"""Extract field text and semantic values from a given ID document.
The input document must be of one of the supported content types - 'application/pdf',
'image/jpeg', 'image/png', 'image/tiff' or 'image/bmp'.
See fields found on an ID document here:
https://aka.ms/formrecognizer/TODO
:param id_document: JPEG, PNG, PDF, TIFF, or BMP type file stream or bytes.
:type id_document: bytes or IO[bytes]
:keyword bool include_field_elements:
Whether or not to include all lines per page and field elements such as lines, words,
and selection marks for each form field.
:keyword content_type: Content-type of the body sent to the API. Content-type is
auto-detected, but can be overridden by passing this keyword argument. For options,
see :class:`~azure.ai.formrecognizer.FormContentType`.
:paramtype content_type: str or ~azure.ai.formrecognizer.FormContentType
:keyword int polling_interval: Waiting time between two polls for LRO operations
if no Retry-After header is present. Defaults to 5 seconds.
:keyword str continuation_token: A continuation token to restart a poller from a saved state.
:keyword list[str] pages: Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers
and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like
`pages=["1-3", "5-6"]`. Separate each page number or range with a comma.
:return: An instance of an LROPoller. Call `result()` on the poller
object to return a list[:class:`~azure.ai.formrecognizer.RecognizedForm`].
:rtype: ~azure.core.polling.LROPoller[list[~azure.ai.formrecognizer.RecognizedForm]]
:raises ~azure.core.exceptions.HttpResponseError:
.. versionadded:: v2.1-preview
The *begin_recognize_id_documents* client method
.. admonition:: Example:
.. literalinclude:: ../samples/sample_recognize_id_documents.py
:start-after: [START recognize_id_documents]
:end-before: [END recognize_id_documents]
:language: python
:dedent: 8
:caption: Recognize ID document fields.
"""
content_type = kwargs.pop("content_type", None)
if content_type == "application/json":
raise TypeError(
"Call begin_recognize_id_documents_from_url() to analyze an ID document from a URL."
)
if content_type is None and kwargs.get("continuation_token", None) is None:
content_type = get_content_type(id_document)

include_field_elements = kwargs.pop("include_field_elements", False)

try:
return self._client.begin_analyze_id_document_async( # type: ignore
file_stream=id_document,
content_type=content_type,
include_text_details=include_field_elements,
cls=kwargs.pop("cls", self._prebuilt_callback),
polling=True,
**kwargs
)
except ValueError as e:
if "begin_analyze_id_document_async" in str(e):
raise ValueError(
"Method 'begin_recognize_id_documents' is only available for API version V2_1_PREVIEW and up"
)
raise e

@distributed_trace
def begin_recognize_id_documents_from_url(self, id_document_url, **kwargs):
# type: (str, Any) -> LROPoller[List[RecognizedForm]]
"""Extract field text and semantic values from a given ID document.
The input document must be the location (URL) of the ID document to be analyzed.
See fields found on an ID document here:
https://aka.ms/formrecognizer/TODO
:param str id_document_url: The URL of the ID document to analyze. The input must be a valid, encoded URL
of one of the supported formats: JPEG, PNG, PDF, TIFF, or BMP.
:keyword bool include_field_elements:
Whether or not to include all lines per page and field elements such as lines, words,
and selection marks for each form field.
:keyword int polling_interval: Waiting time between two polls for LRO operations
if no Retry-After header is present. Defaults to 5 seconds.
:keyword str continuation_token: A continuation token to restart a poller from a saved state.
:keyword list[str] pages: Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers
and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like
`pages=["1-3", "5-6"]`. Separate each page number or range with a comma.
:return: An instance of an LROPoller. Call `result()` on the poller
object to return a list[:class:`~azure.ai.formrecognizer.RecognizedForm`].
:rtype: ~azure.core.polling.LROPoller[list[~azure.ai.formrecognizer.RecognizedForm]]
:raises ~azure.core.exceptions.HttpResponseError:
.. versionadded:: v2.1-preview
The *begin_recognize_id_documents_from_url* client method
"""

include_field_elements = kwargs.pop("include_field_elements", False)

try:
return self._client.begin_analyze_id_document_async( # type: ignore
file_stream={"source": id_document_url},
include_text_details=include_field_elements,
cls=kwargs.pop("cls", self._prebuilt_callback),
polling=True,
**kwargs
)
except ValueError as e:
if "begin_analyze_id_document_async" in str(e):
raise ValueError(
"Method 'begin_recognize_id_documents_from_url' is "
"only available for API version V2_1_PREVIEW and up"
)
raise e

@distributed_trace
def begin_recognize_invoices(self, invoice, **kwargs):
# type: (Union[bytes, IO[bytes]], Any) -> LROPoller[List[RecognizedForm]]
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -342,6 +342,124 @@ async def begin_recognize_business_cards_from_url(
)
raise e

@distributed_trace_async
async def begin_recognize_id_documents(
self, id_document: Union[bytes, IO[bytes]], **kwargs: Any
) -> AsyncLROPoller[List[RecognizedForm]]:
"""Extract field text and semantic values from a given ID document.
The input document must be of one of the supported content types - 'application/pdf',
'image/jpeg', 'image/png', 'image/tiff' or 'image/bmp'.
See fields found on an ID document here:
https://aka.ms/formrecognizer/TODO
:param id_document: JPEG, PNG, PDF, TIFF, or BMP type file stream or bytes.
:type id_document: bytes or IO[bytes]
:keyword bool include_field_elements:
Whether or not to include all lines per page and field elements such as lines, words,
and selection marks for each form field.
:keyword content_type: Content-type of the body sent to the API. Content-type is
auto-detected, but can be overridden by passing this keyword argument. For options,
see :class:`~azure.ai.formrecognizer.FormContentType`.
:paramtype content_type: str or ~azure.ai.formrecognizer.FormContentType
:keyword int polling_interval: Waiting time between two polls for LRO operations
if no Retry-After header is present. Defaults to 5 seconds.
:keyword str continuation_token: A continuation token to restart a poller from a saved state.
:keyword list[str] pages: Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers
and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like
`pages=["1-3", "5-6"]`. Separate each page number or range with a comma.
:return: An instance of an AsyncLROPoller. Call `result()` on the poller
object to return a list[:class:`~azure.ai.formrecognizer.RecognizedForm`].
:rtype: ~azure.core.polling.AsyncLROPoller[list[~azure.ai.formrecognizer.RecognizedForm]]
:raises ~azure.core.exceptions.HttpResponseError:
.. versionadded:: v2.1-preview
The *begin_recognize_id_documents* client method
.. admonition:: Example:
.. literalinclude:: ../samples/async_samples/sample_recognize_id_documents_async.py
:start-after: [START recognize_id_documents_async]
:end-before: [END recognize_id_documents_async]
:language: python
:dedent: 8
:caption: Recognize ID documents from a file.
"""
content_type = kwargs.pop("content_type", None)
if content_type == "application/json":
raise TypeError(
"Call begin_recognize_id_documents_from_url() to analyze an ID document from a URL."
)

include_field_elements = kwargs.pop("include_field_elements", False)

if content_type is None and kwargs.get("continuation_token", None) is None:
content_type = get_content_type(id_document)

try:
return await self._client.begin_analyze_id_document_async( # type: ignore
file_stream=id_document,
content_type=content_type,
include_text_details=include_field_elements,
cls=kwargs.pop("cls", self._prebuilt_callback),
polling=True,
**kwargs
)
except ValueError as e:
if "begin_analyze_id_document_async" in str(e):
raise ValueError(
"Method 'begin_recognize_id_documents' is only available for API version V2_1_PREVIEW and up"
)
raise e

@distributed_trace_async
async def begin_recognize_id_documents_from_url(
self, id_document_url: str, **kwargs: Any
) -> AsyncLROPoller[List[RecognizedForm]]:
"""Extract field text and semantic values from a given ID document.
The input document must be the location (URL) of the ID document to be analyzed.
See fields found on an ID document here:
https://aka.ms/formrecognizer/TODO
:param str id_document_url: The URL of the ID document to analyze. The input must be a valid, encoded URL
of one of the supported formats: JPEG, PNG, PDF, TIFF, or BMP.
:keyword bool include_field_elements:
Whether or not to include all lines per page and field elements such as lines, words,
and selection marks for each form field.
:keyword int polling_interval: Waiting time between two polls for LRO operations
if no Retry-After header is present. Defaults to 5 seconds.
:keyword str continuation_token: A continuation token to restart a poller from a saved state.
:keyword list[str] pages: Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers
and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like
`pages=["1-3", "5-6"]`. Separate each page number or range with a comma.
:return: An instance of an AsyncLROPoller. Call `result()` on the poller
object to return a list[:class:`~azure.ai.formrecognizer.RecognizedForm`].
:rtype: ~azure.core.polling.AsyncLROPoller[list[~azure.ai.formrecognizer.RecognizedForm]]
:raises ~azure.core.exceptions.HttpResponseError:
.. versionadded:: v2.1-preview
The *begin_recognize_id_documents_from_url* client method
"""

include_field_elements = kwargs.pop("include_field_elements", False)

try:
return await self._client.begin_analyze_id_document_async( # type: ignore
file_stream={"source": id_document_url},
include_text_details=include_field_elements,
cls=kwargs.pop("cls", self._prebuilt_callback),
polling=True,
**kwargs
)
except ValueError as e:
if "begin_analyze_id_document_async" in str(e):
raise ValueError(
"Method 'begin_recognize_id_documents_from_url' is "
"only available for API version V2_1_PREVIEW and up"
)
raise e

@distributed_trace_async
async def begin_recognize_invoices(
self, invoice: str, **kwargs: Any
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
interactions:
- request:
body: xx
headers:
Accept:
- application/json
Accept-Encoding:
- gzip, deflate
Connection:
- keep-alive
Content-Length:
- '2'
Content-Type:
- image/jpeg
User-Agent:
- azsdk-python-ai-formrecognizer/3.1.0b4 Python/3.8.5 (Windows-10-10.0.19041-SP0)
method: POST
uri: https://region.api.cognitive.microsoft.com/formrecognizer/v2.1-preview.3/prebuilt/idDocument/analyze?includeTextDetails=false
response:
body:
string: '{"error": {"code": "401", "message": "Access denied due to invalid
subscription key or wrong API endpoint. Make sure to provide a valid key for
an active subscription and use a correct regional API endpoint for your resource."}}'
headers:
content-length:
- '224'
date:
- Fri, 05 Mar 2021 17:44:04 GMT
status:
code: 401
message: PermissionDenied
version: 1
Loading

0 comments on commit ee1b90d

Please sign in to comment.