async def recognize_receipts(self, receipt: Union[bytes, IO[bytes]],
**kwargs: Any) -> List["RecognizedReceipt"]:
"""Extract field text and semantic values from a given US sales receipt.
The input document must be of one of the supported content types - 'application/pdf',
'image/jpeg', 'image/png' or 'image/tiff'.
:param receipt: JPEG, PNG, PDF and TIFF type file stream or bytes.
Currently only supports US sales receipts.
:type receipt: bytes or IO[bytes]
:keyword bool include_text_content:
Whether or not to include text elements such as lines and words in addition to form fields.
:keyword str content_type: Media 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`.
:keyword int polling_interval: Waiting time between two polls for LRO operations
if no Retry-After header is present. Defaults to 5 seconds.
:return: A list of RecognizedReceipt.
:rtype: list[~azure.ai.formrecognizer.RecognizedReceipt]
:raises ~azure.core.exceptions.HttpResponseError:
.. admonition:: Example:
.. literalinclude:: ../samples/async_samples/sample_recognize_receipts_async.py
:start-after: [START recognize_receipts_async]
:end-before: [END recognize_receipts_async]
:language: python
:dedent: 8
:caption: Recognize US sales receipt fields.
"""
polling_interval = kwargs.pop("polling_interval", POLLING_INTERVAL)
content_type = kwargs.pop("content_type", None)
if content_type == "application/json":
raise TypeError(
"Call begin_recognize_receipts_from_url() to analyze a receipt from a url."
)
include_text_content = kwargs.pop("include_text_content", False)
if content_type is None:
content_type = get_content_type(receipt)
return await self._client.analyze_receipt_async( # type: ignore
file_stream=receipt,
content_type=content_type,
include_text_details=include_text_content,
cls=kwargs.pop("cls", self._receipt_callback),
polling=AsyncLROBasePolling(timeout=polling_interval, **kwargs),
error_map=error_map,
**kwargs)
async def begin_create_composed_model(
self, model_ids: List[str],
**kwargs: Any) -> AsyncLROPoller[CustomFormModel]:
"""Creates a composed model from a collection of existing trained models with labels.
:param list[str] model_ids: List of model IDs to use in the composed model.
:keyword str model_name: An optional, user-defined name to associate with your model.
:keyword int polling_interval: Default waiting time between two polls for LRO operations if
no Retry-After header is present.
:keyword str continuation_token: A continuation token to restart a poller from a saved state.
:return: An instance of an AsyncLROPoller. Call `result()` on the poller
object to return a :class:`~azure.ai.formrecognizer.CustomFormModel`.
:rtype: ~azure.core.polling.AsyncLROPoller[~azure.ai.formrecognizer.CustomFormModel]
:raises ~azure.core.exceptions.HttpResponseError:
.. admonition:: Example:
.. literalinclude:: ../samples/async_samples/sample_create_composed_model_async.py
:start-after: [START begin_create_composed_model_async]
:end-before: [END begin_create_composed_model_async]
:language: python
:dedent: 8
:caption: Create a composed model
"""
def _compose_callback(raw_response, _, headers): # pylint: disable=unused-argument
model = self._deserialize(self._generated_models.Model,
raw_response)
return CustomFormModel._from_generated_composed(model)
model_name = kwargs.pop("model_name", None)
polling_interval = kwargs.pop("polling_interval",
self._client._config.polling_interval)
continuation_token = kwargs.pop("continuation_token", None)
try:
return await self._client.begin_compose_custom_models_async( # type: ignore
{
"model_ids": model_ids,
"model_name": model_name
},
cls=kwargs.pop("cls", _compose_callback),
polling=AsyncLROBasePolling(timeout=polling_interval,
lro_algorithms=[TrainingPolling()],
**kwargs),
continuation_token=continuation_token,
**kwargs)
except ValueError:
raise ValueError(
"Method 'begin_create_composed_model' is only available for API version V2_1_PREVIEW and up"
)
async def begin_recognize_receipts_from_url(
self, receipt_url: str,
**kwargs: Any) -> AsyncLROPoller[List[RecognizedForm]]:
"""Extract field text and semantic values from a given US sales receipt.
The input document must be the location (URL) of the receipt to be analyzed.
See fields found on a receipt here:
https://aka.ms/formrecognizer/receiptfields
:param str receipt_url: The URL of the receipt to analyze. The input must be a valid, encoded URL
of one of the supported formats: JPEG, PNG, PDF and TIFF. Currently only supports
US sales receipts.
:keyword bool include_field_elements:
Whether or not to include field elements such as lines and words in addition to form fields.
: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.
: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:
.. admonition:: Example:
.. literalinclude:: ../samples/async_samples/sample_recognize_receipts_from_url_async.py
:start-after: [START recognize_receipts_from_url_async]
:end-before: [END recognize_receipts_from_url_async]
:language: python
:dedent: 8
:caption: Recognize US sales receipt fields from a URL.
"""
locale = kwargs.pop("locale", None)
polling_interval = kwargs.pop("polling_interval",
self._client._config.polling_interval)
continuation_token = kwargs.pop("continuation_token", None)
include_field_elements = kwargs.pop("include_field_elements", False)
cls = kwargs.pop("cls", self._receipt_callback)
polling = AsyncLROBasePolling(timeout=polling_interval, **kwargs)
if self.api_version == "2.1-preview.1" and locale:
kwargs.update({"locale": locale})
return await self._client.begin_analyze_receipt_async( # type: ignore
file_stream={"source": receipt_url},
include_text_details=include_field_elements,
cls=cls,
polling=polling,
error_map=error_map,
continuation_token=continuation_token,
**kwargs)
async def begin_stop_trigger(self, trigger_name: str,
**kwargs) -> AsyncLROPoller[None]:
"""Stops a trigger.
:param trigger_name: The trigger name.
:type trigger_name: str
:keyword callable cls: A custom type or function that will be passed the direct response
:keyword str continuation_token: A continuation token to restart a poller from a saved state.
:keyword polling: True for ARMPolling, False for no polling, or a
polling object for personal polling strategy
:paramtype polling: bool or ~azure.core.polling.AsyncPollingMethod
:keyword int polling_interval: Default waiting time between two polls for LRO operations if no Retry-After header is present.
:return: An instance of AsyncLROPoller that returns either None or the result of cls(response)
:rtype: ~azure.core.polling.AsyncLROPoller[None]
:raises ~azure.core.exceptions.HttpResponseError:
"""
polling = kwargs.pop('polling',
False) # type: Union[bool, AsyncPollingMethod]
cls = kwargs.pop('cls', None) # type: ClsType[None]
lro_delay = kwargs.pop('polling_interval',
self._config.polling_interval)
cont_token = kwargs.pop('continuation_token',
None) # type: Optional[str]
if cont_token is None:
raw_result = await self._stop_trigger_initial(
trigger_name=trigger_name, cls=lambda x, y, z: x, **kwargs)
kwargs.pop('error_map', None)
kwargs.pop('content_type', None)
def get_long_running_output(pipeline_response):
if cls:
return cls(pipeline_response, None, {})
if polling is True:
polling_method = AsyncLROBasePolling(lro_delay, **kwargs)
elif polling is False:
polling_method = AsyncNoPolling()
else:
polling_method = polling
if cont_token:
return AsyncLROPoller.from_continuation_token(
polling_method=polling_method,
continuation_token=cont_token,
client=self._client,
deserialization_callback=get_long_running_output)
else:
return AsyncLROPoller(self._client, raw_result,
get_long_running_output, polling_method)
async def begin_recognize_content(
self, form: Union[bytes, IO[bytes]],
**kwargs: Any) -> AsyncLROPoller[List[FormPage]]:
"""Extract text and content/layout information from a given document.
The input document must be of one of the supported content types - 'application/pdf',
'image/jpeg', 'image/png' or 'image/tiff'.
:param form: JPEG, PNG, PDF and TIFF type file stream or bytes.
:type form: bytes or IO[bytes]
:keyword str content_type: Media 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`.
: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.
:return: An instance of an AsyncLROPoller. Call `result()` on the poller
object to return a list[:class:`~azure.ai.formrecognizer.FormPage`].
:rtype: ~azure.core.polling.AsyncLROPoller[list[~azure.ai.formrecognizer.FormPage]]
:raises ~azure.core.exceptions.HttpResponseError:
.. admonition:: Example:
.. literalinclude:: ../samples/async_samples/sample_recognize_content_async.py
:start-after: [START recognize_content_async]
:end-before: [END recognize_content_async]
:language: python
:dedent: 8
:caption: Recognize text and content/layout information from a form.
"""
polling_interval = kwargs.pop("polling_interval", POLLING_INTERVAL)
continuation_token = kwargs.pop("continuation_token", None)
content_type = kwargs.pop("content_type", None)
if content_type == "application/json":
raise TypeError(
"Call begin_recognize_content_from_url() to analyze a document from a url."
)
if content_type is None:
content_type = get_content_type(form)
return await self._client.begin_analyze_layout_async( # type: ignore
file_stream=form,
content_type=content_type,
cls=kwargs.pop("cls", self._content_callback),
polling=AsyncLROBasePolling(timeout=polling_interval, **kwargs),
error_map=error_map,
continuation_token=continuation_token,
**kwargs)
async def analyze_with_custom_model(
self,
model_id: str,
include_text_details: Optional[bool] = False,
file_stream: Optional[Union[str, "models.SourcePath"]] = None,
**kwargs) -> None:
"""Extract key-value pairs, tables, and semantic values from a given document. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg', 'image/png' or 'image/tiff'. Alternatively, use 'application/json' type to specify the location (Uri or local path) of the document to be analyzed.
Analyze Form.
:param model_id: Model identifier.
:type model_id: str
:param include_text_details: Include text lines and element references in the result.
:type include_text_details: bool
:param file_stream: .json, .pdf, .jpg, .png or .tiff type file stream.
:type file_stream: ~azure.ai.formrecognizer.models.SourcePath
:keyword callable cls: A custom type or function that will be passed the direct response
:keyword polling: True for ARMPolling, False for no polling, or a
polling object for personal polling strategy
:paramtype polling: bool or ~azure.core.polling.AsyncPollingMethod
:keyword int polling_interval: Default waiting time between two polls for LRO operations if no Retry-After header is present.
:return: None
:rtype: None
:raises ~azure.core.exceptions.HttpResponseError:
"""
polling = kwargs.pop('polling',
False) # type: Union[bool, AsyncPollingMethod]
cls = kwargs.pop('cls', None) # type: ClsType[None]
lro_delay = kwargs.pop('polling_interval',
self._config.polling_interval)
raw_result = await self._analyze_with_custom_model_initial(
model_id=model_id,
include_text_details=include_text_details,
file_stream=file_stream,
cls=lambda x, y, z: x,
**kwargs)
def get_long_running_output(pipeline_response):
if cls:
return cls(pipeline_response, None, {})
if polling is True:
polling_method = AsyncLROBasePolling(lro_delay, **kwargs)
elif polling is False:
polling_method = AsyncNoPolling()
else:
polling_method = polling
return await async_poller(self._client, raw_result,
get_long_running_output, polling_method)
async def recognize_custom_forms(
self,
model_id: str,
stream: Union[bytes, IO[bytes]],
**kwargs: Any
) -> List["RecognizedForm"]:
"""Analyze a custom form with a model trained with or without labels. The form
to analyze should be of the same type as the forms that were used to train the model.
The input document must be of one of the supported content types - 'application/pdf',
'image/jpeg', 'image/png' or 'image/tiff'.
:param str model_id: Custom model identifier.
:param stream: .pdf, .jpg, .png or .tiff type file stream.
:type stream: stream
:keyword bool include_text_content: Include text lines and element references in the result.
:keyword str content_type: Media 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`.
:return: A list of RecognizedForm.
:rtype: list[~azure.ai.formrecognizer.RecognizedForm]
:raises ~azure.core.exceptions.HttpResponseError:
"""
cls = kwargs.pop("cls", None)
content_type = kwargs.pop("content_type", None)
if content_type == "application/json":
raise TypeError("Call begin_recognize_custom_forms_from_url() to analyze a document from a url.")
include_text_content = kwargs.pop("include_text_content", False)
if content_type is None:
content_type = get_content_type(stream)
def analyze_callback(raw_response, _, headers): # pylint: disable=unused-argument
analyze_result = self._client._deserialize(AnalyzeOperationResult, raw_response)
return prepare_form_result(analyze_result, model_id)
deserialization_callback = cls if cls else analyze_callback
return await self._client.analyze_with_custom_model(
file_stream=stream,
model_id=model_id,
include_text_details=include_text_content,
content_type=content_type,
cls=deserialization_callback,
polling=AsyncLROBasePolling(timeout=POLLING_INTERVAL, lro_algorithms=[AnalyzePolling()], **kwargs),
error_map=error_map,
**kwargs
)
async def begin_recognize_custom_forms_from_url(
self,
model_id: str,
form_url: str,
**kwargs: Any
) -> AsyncLROPoller[List[RecognizedForm]]:
"""Analyze a custom form with a model trained with or without labels. The form
to analyze should be of the same type as the forms that were used to train the model.
The input document must be the location (URL) of the document to be analyzed.
:param str model_id: Custom model identifier.
:param str form_url: The URL of the form to analyze. The input must be a valid, encoded URL
of one of the supported formats: JPEG, PNG, PDF, or TIFF.
:keyword 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.
: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:
"""
if not model_id:
raise ValueError("model_id cannot be None or empty.")
polling_interval = kwargs.pop("polling_interval", self._client._config.polling_interval)
continuation_token = kwargs.pop("continuation_token", None)
include_field_elements = kwargs.pop("include_field_elements", False)
def analyze_callback(raw_response, _, headers): # pylint: disable=unused-argument
analyze_result = self._deserialize(self._generated_models.AnalyzeOperationResult, raw_response)
return prepare_form_result(analyze_result, model_id)
return await self._client.begin_analyze_with_custom_model( # type: ignore
file_stream={"source": form_url},
model_id=model_id,
include_text_details=include_field_elements,
cls=kwargs.pop("cls", analyze_callback),
polling=AsyncLROBasePolling(
timeout=polling_interval,
lro_algorithms=[AnalyzePolling()],
**kwargs
),
continuation_token=continuation_token,
**kwargs
)
async def test_final_get_via_location(port, http_request, deserialization_cb):
client = AsyncTestRestClient(port)
request = http_request(
"PUT",
"http://localhost:{}/polling/polling-with-options".format(port),
)
request.set_json_body({"hello": "world!"})
initial_response = await client._client._pipeline.run(request)
poller = AsyncLROPoller(
client._client,
initial_response,
deserialization_cb,
AsyncLROBasePolling(0, lro_options={"final-state-via": "location"}),
)
result = await poller.result()
assert result == {"returnedFrom": "locationHeaderUrl"}
async def test_post_resource_location(async_pipeline_client_builder, deserialization_cb, http_request, http_response):
# ResourceLocation
# The initial response contains both Location and Operation-Location, a 202 and no Body
initial_response = TestBasePolling.mock_send(
http_request,
http_response,
'POST',
202,
{
'operation-location': 'http://example.org/async_monitor',
},
''
)
async def send(request, **kwargs):
assert request.method == 'GET'
if request.url == 'http://example.org/resource_location':
return TestBasePolling.mock_send(
http_request,
http_response,
'GET',
200,
body={'location_result': True}
).http_response
elif request.url == 'http://example.org/async_monitor':
return TestBasePolling.mock_send(
http_request,
http_response,
'GET',
200,
body={'status': 'Succeeded', 'resourceLocation': 'http://example.org/resource_location'}
).http_response
else:
pytest.fail("No other query allowed")
client = async_pipeline_client_builder(send)
poll = async_poller(
client,
initial_response,
deserialization_cb,
AsyncLROBasePolling(0))
result = await poll
assert result['location_result'] == True
async def test_long_running_delete(http_request, http_response):
# Test polling from operation-location header
CLIENT.http_request_type = http_request
CLIENT.http_response_type = http_response
response = TestBasePolling.mock_send(
http_request,
http_response,
'DELETE', 202,
{'operation-location': ASYNC_URL},
body=""
)
polling_method = AsyncLROBasePolling(0)
poll = await async_poller(CLIENT, response,
TestBasePolling.mock_deserialization_no_body,
polling_method)
assert poll is None
assert polling_method._pipeline_response.http_response.internal_response.randomFieldFromPollAsyncOpHeader is None
async def training(self,
training_files: str,
use_labels: Optional[bool] = False,
**kwargs: Any) -> CustomFormModel:
"""Create and train a custom model. The request must include a training_files parameter that is an
externally accessible Azure storage blob container Uri (preferably a Shared Access Signature Uri).
Models are trained using documents that are of the following content type - 'application/pdf',
'image/jpeg', 'image/png', 'image/tiff'. Other type of content in the container is ignored.
:param str training_files: An Azure Storage blob container's SAS URI.
:param bool use_labels: Whether to train with labels or not. Corresponding labeled files must
exist in the blob container.
:keyword str prefix: A case-sensitive prefix string to filter documents for training.
Use prefix to filter documents themselves, or to restrict sub folders for training
when `include_sub_folders` is set to True. Not supported if training with labels.
:keyword bool include_sub_folders: A flag to indicate if sub folders
will also need to be included when searching for content to be preprocessed.
Use with prefix to filter for only certain sub folders. Not supported if training with labels.
:return: CustomFormModel
:rtype: ~azure.ai.formrecognizer.CustomFormModel
:raises ~azure.core.exceptions.HttpResponseError:
"""
cls = kwargs.pop("cls", None)
response = await self._client.train_custom_model_async(
train_request=TrainRequest(source=training_files,
use_label_file=use_labels,
source_filter=TrainSourceFilter(
prefix=kwargs.pop("prefix", ""),
include_sub_folders=kwargs.pop(
"include_sub_folders", False))),
cls=lambda pipeline_response, _, response_headers:
pipeline_response,
error_map=error_map,
**kwargs)
def callback(raw_response):
model = self._client._deserialize(Model, raw_response)
return CustomFormModel._from_generated(model)
deserialization_callback = cls if cls else callback
return await async_poller(
self._client._client, response, deserialization_callback,
AsyncLROBasePolling(timeout=POLLING_INTERVAL,
lro_algorithms=[TrainingPolling()],
**kwargs))
async def recognize_content_from_url(self, url: str, **kwargs: Any) -> List["FormPage"]:
"""Extract text and layout information from a given document.
The input document must be the location (Url) of the document to be analyzed.
:param url: The url of the document.
:type url: str
:return: A list of FormPage.
:rtype: list[~azure.ai.formrecognizer.FormPage]
:raises ~azure.core.exceptions.HttpResponseError:
"""
return await self._client.analyze_layout_async(
file_stream={"source": url},
cls=kwargs.pop("cls", self._content_callback),
polling=AsyncLROBasePolling(timeout=POLLING_INTERVAL, **kwargs),
error_map=error_map,
**kwargs
)
async def wait_until_done(self, job_id, **kwargs):
# type: (str, **Any) -> JobStatusResult
"""Wait until the translation job is done.
A job is considered "done" when it reaches a terminal state like
Succeeded, Failed, Cancelled.
:param str job_id: The translation job ID.
:return: A JobStatusResult with information on the status of the translation job.
:rtype: ~azure.ai.translation.document.JobStatusResult
:raises ~azure.core.exceptions.HttpResponseError or ~azure.core.exceptions.ResourceNotFoundError:
Will raise if validation fails on the input. E.g. insufficient permissions on the blob containers.
.. admonition:: Example:
.. literalinclude:: ../samples/async_samples/sample_create_translation_job_async.py
:start-after: [START wait_until_done_async]
:end-before: [END wait_until_done_async]
:language: python
:dedent: 4
:caption: Create a translation job and wait until it is done.
"""
pipeline_response = await self._client.document_translation.get_operation_status(
job_id,
cls=lambda pipeline_response, _, response_headers:
pipeline_response)
def callback(raw_response):
detail = self._client._deserialize(_BatchStatusDetail,
raw_response) # pylint: disable=protected-access
return JobStatusResult._from_generated(detail) # pylint: disable=protected-access
poller = AsyncLROPoller(
client=self._client._client, # pylint: disable=protected-access
initial_response=pipeline_response,
deserialization_callback=callback,
polling_method=AsyncLROBasePolling(
timeout=self._client._config.polling_interval, # pylint: disable=protected-access
lro_algorithms=[TranslationPolling()],
**kwargs),
)
return await poller.result()
async def recognize_custom_forms_from_url(
self, model_id: str, form_url: str,
**kwargs: Any) -> List["RecognizedForm"]:
"""Analyze a custom form with a model trained with or without labels. The form
to analyze should be of the same type as the forms that were used to train the model.
The input document must be the location (Url) of the document to be analyzed.
:param str model_id: Custom model identifier.
:param str form_url: The url of the form to analyze. The input must be a valid, encoded url
of one of the supported formats: JPEG, PNG, PDF and TIFF.
:keyword bool include_text_content:
Whether or not to include text elements such as lines and words in addition to form fields.
:keyword int polling_interval: Waiting time between two polls for LRO operations
if no Retry-After header is present. Defaults to 5 seconds.
:return: A list of RecognizedForm.
:rtype: list[~azure.ai.formrecognizer.RecognizedForm]
:raises ~azure.core.exceptions.HttpResponseError:
"""
if not model_id:
raise ValueError("model_id cannot be None or empty.")
cls = kwargs.pop("cls", None)
polling_interval = kwargs.pop("polling_interval", POLLING_INTERVAL)
include_text_content = kwargs.pop("include_text_content", False)
def analyze_callback(raw_response, _, headers): # pylint: disable=unused-argument
analyze_result = self._client._deserialize(AnalyzeOperationResult,
raw_response)
return prepare_form_result(analyze_result, model_id)
deserialization_callback = cls if cls else analyze_callback
return await self._client.analyze_with_custom_model( # type: ignore
file_stream={"source": form_url},
model_id=model_id,
include_text_details=include_text_content,
cls=deserialization_callback,
polling=AsyncLROBasePolling(timeout=polling_interval,
lro_algorithms=[AnalyzePolling()],
**kwargs),
error_map=error_map,
**kwargs)
async def recognize_content_from_url(self, url: str,
**kwargs: Any) -> List["FormPage"]:
"""Extract text and layout information from a given document.
The input document must be the location (Url) of the document to be analyzed.
:param url: The url of the document.
:type url: str
:keyword int polling_interval: Waiting time between two polls for LRO operations
if no Retry-After header is present. Defaults to 5 seconds.
:return: A list of FormPage.
:rtype: list[~azure.ai.formrecognizer.FormPage]
:raises ~azure.core.exceptions.HttpResponseError:
"""
polling_interval = kwargs.pop("polling_interval", POLLING_INTERVAL)
return await self._client.analyze_layout_async( # type: ignore
file_stream={"source": url},
cls=kwargs.pop("cls", self._content_callback),
polling=AsyncLROBasePolling(timeout=polling_interval, **kwargs),
error_map=error_map,
**kwargs)
async def begin_extract_layouts_from_url(
self, url: str, **kwargs: Any) -> List["ExtractedLayoutPage"]:
"""Extract text and layout information from a given document.
The input document must be the location (Url) of the document to be analyzed.
:param url: The url of the document.
:type url: str
:return: LROPoller
:rtype: ~azure.core.polling.LROPoller
:raises: ~azure.core.exceptions.HttpResponseError
"""
if not isinstance(url, six.string_types):
raise TypeError(
"Call begin_extract_layouts() to analyze a document from a stream."
)
return await self._client.analyze_layout_async(
file_stream={"source": url},
cls=kwargs.pop("cls", self._layout_callback),
polling=AsyncLROBasePolling(timeout=POLLING_INTERVAL, **kwargs),
**kwargs)
async def recognize_receipts(
self,
stream: Union[bytes, IO[bytes]],
**kwargs: Any
) -> List["USReceipt"]:
"""Extract field text and semantic values from a given US sales receipt.
The input document must be of one of the supported content types - 'application/pdf',
'image/jpeg', 'image/png' or 'image/tiff'.
:param stream: .pdf, .jpg, .png or .tiff type file stream.
Currently only supports US sales receipts.
:type stream: stream
:keyword bool include_text_content: Include text lines and text content references in the result.
:keyword str content_type: Media 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`.
:return: A list of USReceipt.
:rtype: list[~azure.ai.formrecognizer.USReceipt]
:raises ~azure.core.exceptions.HttpResponseError:
"""
content_type = kwargs.pop("content_type", None)
if content_type == "application/json":
raise TypeError("Call begin_recognize_receipts_from_url() to analyze a receipt from a url.")
include_text_content = kwargs.pop("include_text_content", False)
if content_type is None:
content_type = get_content_type(stream)
return await self._client.analyze_receipt_async(
file_stream=stream,
content_type=content_type,
include_text_details=include_text_content,
cls=kwargs.pop("cls", self._receipt_callback),
polling=AsyncLROBasePolling(timeout=POLLING_INTERVAL, **kwargs),
error_map=error_map,
**kwargs
)
async def begin_full_backup(
self, blob_storage_uri: str, sas_token: str, **kwargs: "Any"
) -> "AsyncLROPoller[BackupOperation]":
"""Begin a full backup of the Key Vault.
:param str blob_storage_uri: URI of the blob storage resource in which the backup will be stored
:param str sas_token: a Shared Access Signature (SAS) token authorizing access to the blob storage resource
:keyword str continuation_token: a continuation token to restart polling from a saved state
:returns: An AsyncLROPoller. Call `result()` on this object to get a :class:`BackupOperation`.
:rtype: ~azure.core.polling.AsyncLROPoller[BackupOperation]
"""
polling_interval = kwargs.pop("_polling_interval", 5)
sas_parameter = self._models.SASTokenParameter(storage_resource_uri=blob_storage_uri, token=sas_token)
return await self._client.begin_full_backup(
vault_base_url=self._vault_url,
azure_storage_blob_container_uri=sas_parameter,
cls=BackupOperation._wrap_generated,
continuation_token=kwargs.pop("continuation_token", None),
polling=AsyncLROBasePolling(
lro_algorithms=[KeyVaultBackupClientPolling()], timeout=polling_interval, **kwargs
),
**kwargs
)
async def recognize_receipts_from_url(
self, receipt_url: str,
**kwargs: Any) -> List["RecognizedReceipt"]:
"""Extract field text and semantic values from a given US sales receipt.
The input document must be the location (Url) of the receipt to be analyzed.
:param str receipt_url: The url of the receipt to analyze. The input must be a valid, encoded url
of one of the supported formats: JPEG, PNG, PDF and TIFF. Currently only supports
US sales receipts.
:keyword bool include_text_content:
Whether or not to include text elements such as lines and words in addition to form fields.
:keyword int polling_interval: Waiting time between two polls for LRO operations
if no Retry-After header is present. Defaults to 5 seconds.
:return: A list of RecognizedReceipt.
:rtype: list[~azure.ai.formrecognizer.RecognizedReceipt]
:raises ~azure.core.exceptions.HttpResponseError:
.. admonition:: Example:
.. literalinclude:: ../samples/async_samples/sample_recognize_receipts_from_url_async.py
:start-after: [START recognize_receipts_from_url_async]
:end-before: [END recognize_receipts_from_url_async]
:language: python
:dedent: 8
:caption: Recognize US sales receipt fields from a URL.
"""
polling_interval = kwargs.pop("polling_interval", POLLING_INTERVAL)
include_text_content = kwargs.pop("include_text_content", False)
return await self._client.analyze_receipt_async( # type: ignore
file_stream={"source": receipt_url},
include_text_details=include_text_content,
cls=kwargs.pop("cls", self._receipt_callback),
polling=AsyncLROBasePolling(timeout=polling_interval, **kwargs),
error_map=error_map,
**kwargs)
async def recognize_custom_forms_from_url(
self,
model_id: str,
url: str,
**kwargs: Any
) -> List["RecognizedForm"]:
"""Analyze a custom form with a model trained with or without labels. The form
to analyze should be of the same type as the forms that were used to train the model.
The input document must be the location (Url) of the document to be analyzed.
:param str model_id: Custom model identifier.
:param url: The url of the document.
:type url: str
:keyword bool include_text_content: Include text lines and element references in the result.
:return: A list of RecognizedForm.
:rtype: list[~azure.ai.formrecognizer.RecognizedForm]
:raises ~azure.core.exceptions.HttpResponseError:
"""
cls = kwargs.pop("cls", None)
include_text_content = kwargs.pop("include_text_content", False)
def analyze_callback(raw_response, _, headers): # pylint: disable=unused-argument
analyze_result = self._client._deserialize(AnalyzeOperationResult, raw_response)
return prepare_form_result(analyze_result, model_id)
deserialization_callback = cls if cls else analyze_callback
return await self._client.analyze_with_custom_model(
file_stream={"source": url},
model_id=model_id,
include_text_details=include_text_content,
cls=deserialization_callback,
polling=AsyncLROBasePolling(timeout=POLLING_INTERVAL, lro_algorithms=[AnalyzePolling()], **kwargs),
error_map=error_map,
**kwargs
)
async def begin_training(
self, training_files_url: str, use_training_labels: bool, **kwargs: Any
) -> AsyncLROPoller[CustomFormModel]:
"""Create and train a custom model. The request must include a `training_files_url` parameter that is an
externally accessible Azure storage blob container URI (preferably a Shared Access Signature URI). Note that
a container URI (without SAS) is accepted only when the container is public.
Models are trained using documents that are of the following content type - 'application/pdf',
'image/jpeg', 'image/png', 'image/tiff', or 'image/bmp'. Other types of content in the container is ignored.
:param str training_files_url: An Azure Storage blob container's SAS URI. A container URI (without SAS)
can be used if the container is public. For more information on setting up a training data set, see:
https://docs.microsoft.com/azure/cognitive-services/form-recognizer/build-training-data-set
:param bool use_training_labels: Whether to train with labels or not. Corresponding labeled files must
exist in the blob container if set to `True`.
:keyword str prefix: A case-sensitive prefix string to filter documents in the source path for
training. For example, when using a Azure storage blob URI, use the prefix to restrict sub
folders for training.
:keyword bool include_subfolders: A flag to indicate if subfolders within the set of prefix folders
will also need to be included when searching for content to be preprocessed. Not supported if
training with labels.
:keyword str model_name: An optional, user-defined name to associate with your model.
:keyword str continuation_token: A continuation token to restart a poller from a saved state.
:return: An instance of an AsyncLROPoller. Call `result()` on the poller
object to return a :class:`~azure.ai.formrecognizer.CustomFormModel`.
:rtype: ~azure.core.polling.AsyncLROPoller[~azure.ai.formrecognizer.CustomFormModel]
:raises ~azure.core.exceptions.HttpResponseError:
Note that if the training fails, the exception is raised, but a model with an
"invalid" status is still created. You can delete this model by calling :func:`~delete_model()`
.. versionadded:: v2.1
The *model_name* keyword argument
.. admonition:: Example:
.. literalinclude:: ../samples/async_samples/sample_train_model_without_labels_async.py
:start-after: [START training_async]
:end-before: [END training_async]
:language: python
:dedent: 8
:caption: Training a model (without labels) with your custom forms.
"""
def callback_v2_0(raw_response):
model = self._deserialize(self._generated_models.Model, raw_response)
return CustomFormModel._from_generated(model, api_version=self._api_version)
def callback_v2_1(raw_response, _, headers): # pylint: disable=unused-argument
model = self._deserialize(self._generated_models.Model, raw_response)
return CustomFormModel._from_generated(model, api_version=self._api_version)
cls = kwargs.pop("cls", None)
model_name = kwargs.pop("model_name", None)
if model_name and self._api_version == "2.0":
raise ValueError(
"'model_name' is only available for API version V2_1 and up"
)
continuation_token = kwargs.pop("continuation_token", None)
polling_interval = kwargs.pop(
"polling_interval", self._client._config.polling_interval
)
if self._api_version == "2.0":
deserialization_callback = cls if cls else callback_v2_0
if continuation_token:
return AsyncLROPoller.from_continuation_token(
polling_method=AsyncLROBasePolling( # type: ignore
timeout=polling_interval,
lro_algorithms=[TrainingPolling()],
**kwargs
),
continuation_token=continuation_token,
client=self._client._client,
deserialization_callback=deserialization_callback,
)
response = await self._client.train_custom_model_async(
train_request=TrainRequest(
source=training_files_url,
use_label_file=use_training_labels,
source_filter=TrainSourceFilter(
prefix=kwargs.pop("prefix", ""),
include_sub_folders=kwargs.pop("include_subfolders", False),
),
),
cls=lambda pipeline_response, _, response_headers: pipeline_response,
**kwargs
)
return AsyncLROPoller(
self._client._client,
response,
deserialization_callback,
AsyncLROBasePolling( # type: ignore
timeout=polling_interval,
lro_algorithms=[TrainingPolling()],
**kwargs
),
)
deserialization_callback = cls if cls else callback_v2_1
return await self._client.begin_train_custom_model_async( # type: ignore
train_request=TrainRequest(
source=training_files_url,
use_label_file=use_training_labels,
source_filter=TrainSourceFilter(
prefix=kwargs.pop("prefix", ""),
include_sub_folders=kwargs.pop("include_subfolders", False),
),
model_name=model_name,
),
cls=deserialization_callback,
continuation_token=continuation_token,
polling=AsyncLROBasePolling(
timeout=polling_interval, lro_algorithms=[TrainingPolling()], **kwargs
),
**kwargs
)
async def begin_copy_model(
self, model_id: str, target: dict, **kwargs: Any
) -> AsyncLROPoller[CustomFormModelInfo]:
"""Copy a custom model stored in this resource (the source) to the user specified
target Form Recognizer resource. This should be called with the source Form Recognizer resource
(with the model that is intended to be copied). The `target` parameter should be supplied from the
target resource's output from calling the :func:`~get_copy_authorization()` method.
:param str model_id: Model identifier of the model to copy to target resource.
:param dict target:
The copy authorization generated from the target resource's call to
:func:`~get_copy_authorization()`.
:keyword str continuation_token: A continuation token to restart a poller from a saved state.
:return: An instance of an AsyncLROPoller. Call `result()` on the poller
object to return a :class:`~azure.ai.formrecognizer.CustomFormModelInfo`.
:rtype: ~azure.core.polling.AsyncLROPoller[~azure.ai.formrecognizer.CustomFormModelInfo]
:raises ~azure.core.exceptions.HttpResponseError:
.. admonition:: Example:
.. literalinclude:: ../samples/async_samples/sample_copy_model_async.py
:start-after: [START copy_model_async]
:end-before: [END copy_model_async]
:language: python
:dedent: 8
:caption: Copy a model from the source resource to the target resource
"""
if not model_id:
raise ValueError("model_id cannot be None or empty.")
polling_interval = kwargs.pop(
"polling_interval", self._client._config.polling_interval
)
continuation_token = kwargs.pop("continuation_token", None)
def _copy_callback(raw_response, _, headers): # pylint: disable=unused-argument
copy_operation = self._deserialize(
self._generated_models.CopyOperationResult, raw_response
)
model_id = (
copy_operation.copy_result.model_id
if hasattr(copy_operation, "copy_result")
else None
)
if model_id:
return CustomFormModelInfo._from_generated(
copy_operation, model_id, api_version=self._api_version
)
if target:
return CustomFormModelInfo._from_generated(
copy_operation, target["model_id"], api_version=self._api_version
)
return CustomFormModelInfo._from_generated(
copy_operation, None, api_version=self._api_version
)
return await self._client.begin_copy_custom_model( # type: ignore
model_id=model_id,
copy_request=CopyRequest(
target_resource_id=target["resourceId"],
target_resource_region=target["resourceRegion"],
copy_authorization=CopyAuthorizationResult(
access_token=target["accessToken"],
model_id=target["modelId"],
expiration_date_time_ticks=target["expirationDateTimeTicks"],
),
)
if target
else None,
cls=kwargs.pop("cls", _copy_callback),
polling=AsyncLROBasePolling(
timeout=polling_interval, lro_algorithms=[CopyPolling()], **kwargs
),
continuation_token=continuation_token,
**kwargs
)
async def begin_create_cascade_delete_job(
self, job_id: str, farmer_id: str, farm_id: str,
**kwargs: Any) -> AsyncLROPoller["_models.CascadeDeleteJob"]:
"""Create a cascade delete job for specified farm.
:param job_id: Job ID supplied by end user.
:type job_id: str
:param farmer_id: ID of the associated farmer.
:type farmer_id: str
:param farm_id: ID of the farm to be deleted.
:type farm_id: str
:keyword callable cls: A custom type or function that will be passed the direct response
:keyword str continuation_token: A continuation token to restart a poller from a saved state.
:keyword polling: By default, your polling method will be AsyncLROBasePolling.
Pass in False for this operation to not poll, or pass in your own initialized polling object for a personal polling strategy.
:paramtype polling: bool or ~azure.core.polling.AsyncPollingMethod
:keyword int polling_interval: Default waiting time between two polls for LRO operations if no Retry-After header is present.
:return: An instance of AsyncLROPoller that returns either CascadeDeleteJob or the result of cls(response)
:rtype: ~azure.core.polling.AsyncLROPoller[~azure.agrifood.farming.models.CascadeDeleteJob]
:raises ~azure.core.exceptions.HttpResponseError:
"""
polling = kwargs.pop('polling',
True) # type: Union[bool, AsyncPollingMethod]
cls = kwargs.pop('cls',
None) # type: ClsType["_models.CascadeDeleteJob"]
lro_delay = kwargs.pop('polling_interval',
self._config.polling_interval)
cont_token = kwargs.pop('continuation_token',
None) # type: Optional[str]
if cont_token is None:
raw_result = await self._create_cascade_delete_job_initial(
job_id=job_id,
farmer_id=farmer_id,
farm_id=farm_id,
cls=lambda x, y, z: x,
**kwargs)
kwargs.pop('error_map', None)
kwargs.pop('content_type', None)
def get_long_running_output(pipeline_response):
deserialized = self._deserialize('CascadeDeleteJob',
pipeline_response)
if cls:
return cls(pipeline_response, deserialized, {})
return deserialized
path_format_arguments = {
'Endpoint':
self._serialize.url("self._config.endpoint",
self._config.endpoint,
'str',
skip_quote=True),
'jobId':
self._serialize.url("job_id", job_id, 'str'),
}
if polling is True:
polling_method = AsyncLROBasePolling(
lro_delay,
lro_options={'final-state-via': 'location'},
path_format_arguments=path_format_arguments,
**kwargs)
elif polling is False:
polling_method = AsyncNoPolling()
else:
polling_method = polling
if cont_token:
return AsyncLROPoller.from_continuation_token(
polling_method=polling_method,
continuation_token=cont_token,
client=self._client,
deserialization_callback=get_long_running_output)
else:
return AsyncLROPoller(self._client, raw_result,
get_long_running_output, polling_method)
async def recognize_custom_forms(self, model_id: str,
stream: Union[bytes, IO[bytes]],
**kwargs: Any) -> List["RecognizedForm"]:
"""Analyze a custom form with a model trained with or without labels. The form
to analyze should be of the same type as the forms that were used to train the model.
The input document must be of one of the supported content types - 'application/pdf',
'image/jpeg', 'image/png' or 'image/tiff'.
:param str model_id: Custom model identifier.
:param stream: .pdf, .jpg, .png or .tiff type file stream.
:type stream: bytes or IO[bytes]
:keyword bool include_text_content:
Whether or not to include text elements such as lines and words in addition to form fields.
:keyword str content_type: Media 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`.
:keyword int polling_interval: Waiting time between two polls for LRO operations
if no Retry-After header is present. Defaults to 5 seconds.
:return: A list of RecognizedForm.
:rtype: list[~azure.ai.formrecognizer.RecognizedForm]
:raises ~azure.core.exceptions.HttpResponseError:
.. admonition:: Example:
.. literalinclude:: ../samples/async_samples/sample_recognize_custom_forms_async.py
:start-after: [START recognize_custom_forms_async]
:end-before: [END recognize_custom_forms_async]
:language: python
:dedent: 8
:caption: Recognize fields and values from a custom form.
"""
cls = kwargs.pop("cls", None)
polling_interval = kwargs.pop("polling_interval", POLLING_INTERVAL)
content_type = kwargs.pop("content_type", None)
if content_type == "application/json":
raise TypeError(
"Call begin_recognize_custom_forms_from_url() to analyze a document from a url."
)
include_text_content = kwargs.pop("include_text_content", False)
if content_type is None:
content_type = get_content_type(stream)
def analyze_callback(raw_response, _, headers): # pylint: disable=unused-argument
analyze_result = self._client._deserialize(AnalyzeOperationResult,
raw_response)
return prepare_form_result(analyze_result, model_id)
deserialization_callback = cls if cls else analyze_callback
return await self._client.analyze_with_custom_model( # type: ignore
file_stream=stream,
model_id=model_id,
include_text_details=include_text_content,
content_type=content_type,
cls=deserialization_callback,
polling=AsyncLROBasePolling(timeout=polling_interval,
lro_algorithms=[AnalyzePolling()],
**kwargs),
error_map=error_map,
**kwargs)
async def begin_conversation_analysis(
self,
task: JSON,
**kwargs: Any
) -> AsyncLROPoller[JSON]:
"""Submit analysis job for conversations.
Submit a collection of conversations for analysis. Specify one or more unique tasks to be
executed.
:param task: The collection of conversations to analyze and one or more tasks to execute.
:type task: JSON
:keyword str continuation_token: A continuation token to restart a poller from a saved state.
:keyword polling: By default, your polling method will be AsyncLROBasePolling. Pass in False
for this operation to not poll, or pass in your own initialized polling object for a personal
polling strategy.
:paramtype polling: bool or ~azure.core.polling.AsyncPollingMethod
:keyword int polling_interval: Default waiting time between two polls for LRO operations if no
Retry-After header is present.
:return: An instance of AsyncLROPoller that returns JSON object
:rtype: ~azure.core.polling.AsyncLROPoller[JSON]
:raises: ~azure.core.exceptions.HttpResponseError
Example:
.. code-block:: python
# JSON input template you can fill out and use as your body input.
task = {
"analysisInput": {
"conversations": [
{
"domain": "str", # Optional. Enumeration of
supported conversational domains. Known values are: "finance",
"healthcare", "generic".
"id": "str", # Required. Unique identifier for the
conversation.
"language": "str", # Required. The language of the
conversation item in BCP-47 format.
modality: modality
}
]
},
"displayName": "str", # Optional. Optional display name for the analysis
job.
"tasks": [
{
"taskName": "str", # Optional. Required. The set of tasks to
execute on the input conversation.
kind: AnalyzeConversationLROTask
}
]
}
# response body for status code(s): 200
response.json() == {
"createdDateTime": "2020-02-20 00:00:00", # Required.
"displayName": "str", # Optional.
"errors": [
{
"code": "str", # Required. One of a server-defined set of
error codes. Known values are: "InvalidRequest", "InvalidArgument",
"Unauthorized", "Forbidden", "NotFound", "ProjectNotFound",
"OperationNotFound", "AzureCognitiveSearchNotFound",
"AzureCognitiveSearchIndexNotFound", "TooManyRequests",
"AzureCognitiveSearchThrottling",
"AzureCognitiveSearchIndexLimitReached", "InternalServerError",
"ServiceUnavailable", "Timeout", "QuotaExceeded", "Conflict", "Warning".
"details": [
...
],
"innererror": {
"code": "str", # Required. One of a server-defined
set of error codes. Known values are: "InvalidRequest",
"InvalidParameterValue", "KnowledgeBaseNotFound",
"AzureCognitiveSearchNotFound", "AzureCognitiveSearchThrottling",
"ExtractionFailure", "InvalidRequestBodyFormat", "EmptyRequest",
"MissingInputDocuments", "InvalidDocument", "ModelVersionIncorrect",
"InvalidDocumentBatch", "UnsupportedLanguageCode",
"InvalidCountryHint".
"details": {
"str": "str" # Optional. Error details.
},
"innererror": ...,
"message": "str", # Required. Error message.
"target": "str" # Optional. Error target.
},
"message": "str", # Required. A human-readable
representation of the error.
"target": "str" # Optional. The target of the error.
}
],
"expirationDateTime": "2020-02-20 00:00:00", # Optional.
"jobId": "str", # Required.
"lastUpdatedDateTime": "2020-02-20 00:00:00", # Required.
"nextLink": "str", # Optional.
"statistics": {
"conversationsCount": 0, # Required. Number of conversations
submitted in the request.
"erroneousConversationsCount": 0, # Required. Number of invalid
documents. This includes empty, over-size limit or non-supported languages
documents.
"transactionsCount": 0.0, # Required. Number of transactions for the
request.
"validConversationsCount": 0 # Required. Number of conversations
documents. This excludes empty, over-size limit or non-supported languages
documents.
},
"status": "str", # Required. Known values are: "notStarted", "running",
"succeeded", "partiallyCompleted", "failed", "cancelled", "cancelling".
"tasks": {
"completed": 0, # Required. Count of tasks completed successfully.
"failed": 0, # Required. Count of tasks that failed.
"inProgress": 0, # Required. Count of tasks in progress currently.
"items": [
{
"lastUpdateDateTime": "2020-02-20 00:00:00", #
Required. The last updated time in UTC for the task.
"status": "str", # Required. The status of the task
at the mentioned last update time. Known values are: "notStarted",
"running", "succeeded", "failed", "cancelled", "cancelling".
"taskName": "str", # Optional. List of results from
tasks (if available).
kind: AnalyzeConversationJobResult
}
],
"total": 0 # Required. Total count of tasks submitted as part of the
job.
}
}
"""
_headers = case_insensitive_dict(kwargs.pop("headers", {}) or {})
_params = case_insensitive_dict(kwargs.pop("params", {}) or {})
api_version = kwargs.pop('api_version', _params.pop('api-version', "2022-05-15-preview")) # type: str
content_type = kwargs.pop('content_type', _headers.pop('Content-Type', "application/json")) # type: Optional[str]
cls = kwargs.pop('cls', None) # type: ClsType[JSON]
polling = kwargs.pop('polling', True) # type: Union[bool, AsyncPollingMethod]
lro_delay = kwargs.pop(
'polling_interval',
self._config.polling_interval
)
cont_token = kwargs.pop('continuation_token', None) # type: Optional[str]
if cont_token is None:
raw_result = await self._conversation_analysis_initial( # type: ignore
task=task,
api_version=api_version,
content_type=content_type,
cls=lambda x,y,z: x,
headers=_headers,
params=_params,
**kwargs
)
kwargs.pop('error_map', None)
def get_long_running_output(pipeline_response):
response = pipeline_response.http_response
if response.content:
deserialized = response.json()
else:
deserialized = None
if cls:
return cls(pipeline_response, deserialized, {})
return deserialized
path_format_arguments = {
"Endpoint": self._serialize.url("self._config.endpoint", self._config.endpoint, 'str', skip_quote=True),
}
if polling is True:
polling_method = cast(AsyncPollingMethod, AsyncLROBasePolling(
lro_delay,
path_format_arguments=path_format_arguments,
**kwargs
)) # type: AsyncPollingMethod
elif polling is False: polling_method = cast(AsyncPollingMethod, AsyncNoPolling())
else: polling_method = polling
if cont_token:
return AsyncLROPoller.from_continuation_token(
polling_method=polling_method,
continuation_token=cont_token,
client=self._client,
deserialization_callback=get_long_running_output
)
return AsyncLROPoller(self._client, raw_result, get_long_running_output, polling_method)
async def begin_recognize_custom_forms(
self,
model_id: str,
form: Union[bytes, IO[bytes]],
**kwargs: Any
) -> AsyncLROPoller[List[RecognizedForm]]:
"""Analyze a custom form with a model trained with or without labels. The form
to analyze should be of the same type as the forms that were used to train the model.
The input document must be of one of the supported content types - 'application/pdf',
'image/jpeg', 'image/png' or 'image/tiff'.
:param str model_id: Custom model identifier.
:param form: JPEG, PNG, PDF and TIFF type file stream or bytes.
:type form: bytes or IO[bytes]
:keyword bool include_field_elements:
Whether or not to include field elements such as lines and words in addition to form fields.
:keyword content_type: Media 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.
: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:
.. admonition:: Example:
.. literalinclude:: ../samples/async_samples/sample_recognize_custom_forms_async.py
:start-after: [START recognize_custom_forms_async]
:end-before: [END recognize_custom_forms_async]
:language: python
:dedent: 8
:caption: Recognize fields and values from a custom form.
"""
if not model_id:
raise ValueError("model_id cannot be None or empty.")
polling_interval = kwargs.pop("polling_interval", self._client._config.polling_interval)
content_type = kwargs.pop("content_type", None)
continuation_token = kwargs.pop("continuation_token", None)
if content_type == "application/json":
raise TypeError("Call begin_recognize_custom_forms_from_url() to analyze a document from a URL.")
include_field_elements = kwargs.pop("include_field_elements", False)
if content_type is None:
content_type = get_content_type(form)
def analyze_callback(raw_response, _, headers): # pylint: disable=unused-argument
analyze_result = self._deserialize(self._generated_models.AnalyzeOperationResult, raw_response)
return prepare_form_result(analyze_result, model_id)
return await self._client.begin_analyze_with_custom_model( # type: ignore
file_stream=form,
model_id=model_id,
include_text_details=include_field_elements,
content_type=content_type,
cls=kwargs.pop("cls", analyze_callback),
polling=AsyncLROBasePolling(
timeout=polling_interval,
lro_algorithms=[AnalyzePolling()],
**kwargs
),
continuation_token=continuation_token,
**kwargs
)
async def begin_recognize_custom_forms(
self, model_id: str, form: Union[bytes, IO[bytes]],
**kwargs: Any) -> AsyncLROPoller[List[RecognizedForm]]:
"""Analyze a custom form with a model trained with or without labels. The form
to analyze should be of the same type as the forms that were used to train the model.
The input document must be of one of the supported content types - 'application/pdf',
'image/jpeg', 'image/png', 'image/tiff', or 'image/bmp'.
:param str model_id: Custom model identifier.
:param form: JPEG, PNG, PDF, TIFF, or BMP type file stream or bytes.
:type form: 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 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.
: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.
: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:
.. admonition:: Example:
.. literalinclude:: ../samples/async_samples/sample_recognize_custom_forms_async.py
:start-after: [START recognize_custom_forms_async]
:end-before: [END recognize_custom_forms_async]
:language: python
:dedent: 8
:caption: Recognize fields and values from a custom form.
"""
if not model_id:
raise ValueError("model_id cannot be None or empty.")
polling_interval = kwargs.pop("polling_interval",
self._client._config.polling_interval)
content_type = kwargs.pop("content_type", None)
continuation_token = kwargs.pop("continuation_token", None)
if content_type == "application/json":
raise TypeError(
"Call begin_recognize_custom_forms_from_url() to analyze a document from a URL."
)
if content_type is None and continuation_token is None:
content_type = get_content_type(form)
pages = kwargs.pop("pages", None)
include_field_elements = kwargs.pop("include_field_elements", False)
def analyze_callback(raw_response, _, headers): # pylint: disable=unused-argument
analyze_result = self._deserialize(
self._generated_models.AnalyzeOperationResult, raw_response)
return prepare_form_result(analyze_result, model_id)
callback = kwargs.pop("cls", analyze_callback)
polling = AsyncLROBasePolling(timeout=polling_interval,
lro_algorithms=[AnalyzePolling()],
**kwargs)
# FIXME: part of this code will be removed once autorest can handle diff mixin
# signatures across API versions
if pages:
if self._api_version == FormRecognizerApiVersion.V2_1_PREVIEW:
kwargs.update({"pages": pages})
else:
raise ValueError(
"'pages' is only available for API version V2_1_PREVIEW and up"
)
return await self._client.begin_analyze_with_custom_model( # type: ignore
file_stream=form,
model_id=model_id,
include_text_details=include_field_elements,
content_type=content_type,
cls=callback,
polling=polling,
continuation_token=continuation_token,
**kwargs)
async def begin_recognize_custom_forms_from_url(
self, model_id: str, form_url: str,
**kwargs: Any) -> AsyncLROPoller[List[RecognizedForm]]:
"""Analyze a custom form with a model trained with or without labels. The form
to analyze should be of the same type as the forms that were used to train the model.
The input document must be the location (URL) of the document to be analyzed.
:param str model_id: Custom model identifier.
:param str form_url: The URL of the form to analyze. The input must be a valid, encoded URL
of one of the supported formats: JPEG, PNG, PDF, TIFF, or BMP.
:keyword 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 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.
: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.
: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:
"""
if not model_id:
raise ValueError("model_id cannot be None or empty.")
polling_interval = kwargs.pop("polling_interval",
self._client._config.polling_interval)
pages = kwargs.pop("pages", None)
continuation_token = kwargs.pop("continuation_token", None)
include_field_elements = kwargs.pop("include_field_elements", False)
def analyze_callback(raw_response, _, headers): # pylint: disable=unused-argument
analyze_result = self._deserialize(
self._generated_models.AnalyzeOperationResult, raw_response)
return prepare_form_result(analyze_result, model_id)
callback = kwargs.pop("cls", analyze_callback)
polling = AsyncLROBasePolling(timeout=polling_interval,
lro_algorithms=[AnalyzePolling()],
**kwargs)
# FIXME: part of this code will be removed once autorest can handle diff mixin
# signatures across API versions
if pages:
if self._api_version == FormRecognizerApiVersion.V2_1_PREVIEW:
kwargs.update({"pages": pages})
else:
raise ValueError(
"'pages' is only available for API version V2_1_PREVIEW and up"
)
return await self._client.begin_analyze_with_custom_model( # type: ignore
file_stream={"source": form_url},
model_id=model_id,
include_text_details=include_field_elements,
cls=callback,
polling=polling,
continuation_token=continuation_token,
**kwargs)
async def begin_create_or_update_data_flow(
self,
data_flow_name: str,
properties: "models.DataFlow",
if_match: Optional[str] = None,
**kwargs
) -> AsyncLROPoller["models.DataFlowResource"]:
"""Creates or updates a data flow.
:param data_flow_name: The data flow name.
:type data_flow_name: str
:param properties: Data flow properties.
:type properties: ~azure.synapse.artifacts.models.DataFlow
:param if_match: ETag of the data flow entity. Should only be specified for update, for which
it should match existing entity or can be * for unconditional update.
:type if_match: str
:keyword callable cls: A custom type or function that will be passed the direct response
:keyword str continuation_token: A continuation token to restart a poller from a saved state.
:keyword polling: True for ARMPolling, False for no polling, or a
polling object for personal polling strategy
:paramtype polling: bool or ~azure.core.polling.AsyncPollingMethod
:keyword int polling_interval: Default waiting time between two polls for LRO operations if no Retry-After header is present.
:return: An instance of AsyncLROPoller that returns either DataFlowResource or the result of cls(response)
:rtype: ~azure.core.polling.AsyncLROPoller[~azure.synapse.artifacts.models.DataFlowResource]
:raises ~azure.core.exceptions.HttpResponseError:
"""
polling = kwargs.pop('polling', False) # type: Union[bool, AsyncPollingMethod]
cls = kwargs.pop('cls', None) # type: ClsType["models.DataFlowResource"]
lro_delay = kwargs.pop(
'polling_interval',
self._config.polling_interval
)
cont_token = kwargs.pop('continuation_token', None) # type: Optional[str]
if cont_token is None:
raw_result = await self._create_or_update_data_flow_initial(
data_flow_name=data_flow_name,
properties=properties,
if_match=if_match,
cls=lambda x,y,z: x,
**kwargs
)
kwargs.pop('error_map', None)
kwargs.pop('content_type', None)
def get_long_running_output(pipeline_response):
deserialized = self._deserialize('DataFlowResource', pipeline_response)
if cls:
return cls(pipeline_response, deserialized, {})
return deserialized
if polling is True: polling_method = AsyncLROBasePolling(lro_delay, **kwargs)
elif polling is False: polling_method = AsyncNoPolling()
else: polling_method = polling
if cont_token:
return AsyncLROPoller.from_continuation_token(
polling_method=polling_method,
continuation_token=cont_token,
client=self._client,
deserialization_callback=get_long_running_output
)
else:
return AsyncLROPoller(self._client, raw_result, get_long_running_output, polling_method)