def test_post(pipeline_client_builder, deserialization_cb):
# Test POST LRO with both Location and Operation-Location
# The initial response contains both Location and Operation-Location, a 202 and no Body
initial_response = TestBasePolling.mock_send(
'POST', 202, {
'location': 'http://example.org/location',
'operation-location': 'http://example.org/async_monitor',
}, '')
def send(request, **kwargs):
assert request.method == 'GET'
if request.url == 'http://example.org/location':
return TestBasePolling.mock_send('GET',
200,
body={
'location_result': True
}).http_response
elif request.url == 'http://example.org/async_monitor':
return TestBasePolling.mock_send('GET',
200,
body={
'status': 'Succeeded'
}).http_response
else:
pytest.fail("No other query allowed")
client = pipeline_client_builder(send)
# LRO options with Location final state
poll = LROPoller(client, initial_response, deserialization_cb,
LROBasePolling(0))
result = poll.result()
assert result['location_result'] == True
# Location has no body
def send(request, **kwargs):
assert request.method == 'GET'
if request.url == 'http://example.org/location':
return TestBasePolling.mock_send('GET', 200,
body=None).http_response
elif request.url == 'http://example.org/async_monitor':
return TestBasePolling.mock_send('GET',
200,
body={
'status': 'Succeeded'
}).http_response
else:
pytest.fail("No other query allowed")
client = pipeline_client_builder(send)
poll = LROPoller(client, initial_response, deserialization_cb,
LROBasePolling(0))
result = poll.result()
assert result is None
def test_long_running_negative(self):
global LOCATION_BODY
global POLLING_STATUS
# Test LRO PUT throws for invalid json
LOCATION_BODY = '{'
response = TestBasePolling.mock_send('POST', 202,
{'location': LOCATION_URL})
poll = LROPoller(CLIENT, response, TestBasePolling.mock_outputs,
LROBasePolling(0))
with pytest.raises(DecodeError):
poll.result()
LOCATION_BODY = '{\'"}'
response = TestBasePolling.mock_send('POST', 202,
{'location': LOCATION_URL})
poll = LROPoller(CLIENT, response, TestBasePolling.mock_outputs,
LROBasePolling(0))
with pytest.raises(DecodeError):
poll.result()
LOCATION_BODY = '{'
POLLING_STATUS = 203
response = TestBasePolling.mock_send('POST', 202,
{'location': LOCATION_URL})
poll = LROPoller(CLIENT, response, TestBasePolling.mock_outputs,
LROBasePolling(0))
with pytest.raises(
HttpResponseError): # TODO: Node.js raises on deserialization
poll.result()
LOCATION_BODY = json.dumps({'name': TEST_NAME})
POLLING_STATUS = 200
def test_long_running_post_legacy(self):
# Former oooooold tests to refactor one day to something more readble
# Test polling from operation-location header
response = TestBasePolling.mock_send(
'POST', 201,
{'operation-location': ASYNC_URL},
body={'properties':{'provisioningState': 'Succeeded'}})
poll = LROPoller(CLIENT, response,
TestBasePolling.mock_deserialization_no_body,
LROBasePolling(0))
poll.wait()
assert poll._polling_method._pipeline_response.http_response.internal_response.randomFieldFromPollAsyncOpHeader is None
# Test polling from operation-location header
response = TestBasePolling.mock_send(
'POST', 202,
{'operation-location': ASYNC_URL},
body={'properties':{'provisioningState': 'Succeeded'}})
poll = LROPoller(CLIENT, response,
TestBasePolling.mock_deserialization_no_body,
LROBasePolling(0))
poll.wait()
assert poll._polling_method._pipeline_response.http_response.internal_response.randomFieldFromPollAsyncOpHeader is None
# Test polling from location header
response = TestBasePolling.mock_send(
'POST', 202,
{'location': LOCATION_URL},
body={'properties':{'provisioningState': 'Succeeded'}})
poll = LROPoller(CLIENT, response,
TestBasePolling.mock_outputs,
LROBasePolling(0))
assert poll.result().name == TEST_NAME
assert poll._polling_method._pipeline_response.http_response.internal_response.randomFieldFromPollLocationHeader is None
# Test fail to poll from operation-location header
response = TestBasePolling.mock_send(
'POST', 202,
{'operation-location': ERROR})
with pytest.raises(BadEndpointError):
poll = LROPoller(CLIENT, response,
TestBasePolling.mock_outputs,
LROBasePolling(0)).result()
# Test fail to poll from location header
response = TestBasePolling.mock_send(
'POST', 202,
{'location': ERROR})
with pytest.raises(BadEndpointError):
poll = LROPoller(CLIENT, response,
TestBasePolling.mock_outputs,
LROBasePolling(0)).result()
def test_base_polling_continuation_token(client, polling_response):
polling, _ = polling_response
continuation_token = polling.get_continuation_token()
assert isinstance(continuation_token, six.string_types)
polling_args = LROBasePolling.from_continuation_token(
continuation_token,
deserialization_callback="deserialization_callback",
client=client,
)
new_polling = LROBasePolling()
new_polling.initialize(*polling_args)
def test_polling_with_path_format_arguments(client):
method = LROBasePolling(timeout=0,
path_format_arguments={
"host": "host:3000",
"accountName": "local"
})
client._base_url = "http://{accountName}{host}"
method._operation = LocationPolling()
method._operation._location_url = "/results/1"
method._client = client
assert "http://localhost:3000/results/1" == method._client.format_url(
method._operation.get_polling_url(), **method._path_format_arguments)
def polling_response():
polling = LROBasePolling()
headers = {}
response = Response()
response.headers = headers
response.status_code = 200
polling._pipeline_response = PipelineResponse(
None, RequestsTransportResponse(
None,
response,
), PipelineContext(None))
polling._initial_response = polling._pipeline_response
return polling, headers
def begin_recognize_receipts(self, receipt, **kwargs):
# type: (Union[bytes, IO[bytes]], Any) -> LROPoller[List[RecognizedForm]]
"""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'.
See fields found on a receipt here:
https://aka.ms/formrecognizer/receiptfields
: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_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 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:
.. admonition:: Example:
.. literalinclude:: ../samples/sample_recognize_receipts.py
:start-after: [START recognize_receipts]
:end-before: [END recognize_receipts]
:language: python
:dedent: 8
:caption: Recognize US sales receipt fields.
"""
locale = kwargs.pop("locale", None)
polling_interval = kwargs.pop("polling_interval", self._client._config.polling_interval)
continuation_token = kwargs.pop("continuation_token", None)
content_type = kwargs.pop("content_type", None)
include_field_elements = kwargs.pop("include_field_elements", False)
if content_type == "application/json":
raise TypeError("Call begin_recognize_receipts_from_url() to analyze a receipt from a URL.")
cls = kwargs.pop("cls", self._receipt_callback)
polling = LROBasePolling(timeout=polling_interval, **kwargs)
if content_type is None:
content_type = get_content_type(receipt)
if self.api_version == "2.1-preview.1" and locale:
kwargs.update({"locale": locale})
return self._client.begin_analyze_receipt_async( # type: ignore
file_stream=receipt,
content_type=content_type,
include_text_details=include_field_elements,
cls=cls,
polling=polling,
error_map=error_map,
continuation_token=continuation_token,
**kwargs
)
def polling_response():
polling = LROBasePolling()
headers = {}
response = Response()
response.headers = headers
polling._pipeline_response = PipelineResponse(
None,
RequestsTransportResponse(
None,
response,
),
None # context
)
return polling, headers
def begin_selective_restore(self, blob_storage_uri, sas_token, folder_name,
key_name, **kwargs):
# type: (str, str, str, str, **Any) -> LROPoller[SelectiveKeyRestoreOperation]
"""Restore a single key from a full Key Vault backup.
:param str blob_storage_uri: URI of the blob storage resource in which the backup is stored
:param str sas_token: a Shared Access Signature (SAS) token authorizing access to the blob storage resource
:param str folder_name: name of the blob container which contains the backup
:param str key_name: name of the key to restore from the backup
:rtype: ~azure.core.polling.LROPoller[RestoreOperation]
"""
polling_interval = kwargs.pop("_polling_interval", 5)
sas_parameter = self._models.SASTokenParameter(
storage_resource_uri=blob_storage_uri, token=sas_token)
restore_details = self._models.SelectiveKeyRestoreOperationParameters(
sas_token_parameters=sas_parameter,
folder=folder_name,
)
return self._client.begin_selective_key_restore_operation(
vault_base_url=self._vault_url,
key_name=key_name,
restore_blob_details=restore_details,
cls=SelectiveKeyRestoreOperation._wrap_generated,
continuation_token=kwargs.pop("continuation_token", None),
polling=LROBasePolling(
lro_algorithms=[KeyVaultBackupClientPolling()],
timeout=polling_interval,
**kwargs),
**kwargs)
def _callback(http_response, headers={}):
polling = LROBasePolling()
response = Response()
response.headers = headers
response.status_code = 200
response = create_transport_response(
http_response,
None,
response,
)
polling._pipeline_response = PipelineResponse(None, response,
PipelineContext(None))
polling._initial_response = polling._pipeline_response
return polling
def begin_recognize_custom_forms_from_url(self, model_id, url, **kwargs):
# type: (str, str, Any) -> LROPoller
"""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: 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:
"""
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 self._client.begin_analyze_with_custom_model(
file_stream={"source": url},
model_id=model_id,
include_text_details=include_text_content,
cls=deserialization_callback,
polling=LROBasePolling(timeout=POLLING_INTERVAL,
lro_algorithms=[AnalyzePolling()],
**kwargs),
error_map=error_map,
**kwargs)
def begin_recognize_content(self, stream, **kwargs):
# type: (Union[bytes, IO[bytes]], Any) -> LROPoller
"""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 stream: .pdf, .jpg, .png or .tiff type file stream.
:type stream: stream
: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: An instance of an LROPoller. Call `result()` on the poller
object to return a list[:class:`~azure.ai.formrecognizer.FormPage`].
:rtype: ~azure.core.polling.LROPoller[list[~azure.ai.formrecognizer.FormPage]]
:raises ~azure.core.exceptions.HttpResponseError:
"""
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(stream)
return self._client.begin_analyze_layout_async(
file_stream=stream,
content_type=content_type,
cls=kwargs.pop("cls", self._content_callback),
polling=LROBasePolling(timeout=POLLING_INTERVAL, **kwargs),
error_map=error_map,
**kwargs)
def begin_copy_model(
self,
model_id, # type: str
target, # type: Dict
**kwargs # type: Any
):
# type: (...) -> LROPoller
"""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 int polling_interval: Default waiting time between two polls for LRO operations if
no Retry-After header is present.
:return: An instance of an LROPoller. Call `result()` on the poller
object to return a :class:`~azure.ai.formrecognizer.CustomFormModelInfo`.
:rtype: ~azure.core.polling.LROPoller[~azure.ai.formrecognizer.CustomFormModelInfo]
:raises ~azure.core.exceptions.HttpResponseError:
.. admonition:: Example:
.. literalinclude:: ../samples/sample_copy_model.py
:start-after: [START begin_copy_model]
:end-before: [END begin_copy_model]
: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", POLLING_INTERVAL)
def _copy_callback(raw_response, _, headers): # pylint: disable=unused-argument
copy_result = self._client._deserialize(CopyOperationResult,
raw_response)
return CustomFormModelInfo._from_generated(copy_result,
target["modelId"])
return 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"])),
cls=kwargs.pop("cls", _copy_callback),
polling=LROBasePolling(timeout=polling_interval,
lro_algorithms=[CopyPolling()],
**kwargs),
error_map=error_map,
**kwargs)
def begin_debug_spark_job_definition(
self,
properties, # type: "_models.SparkJobDefinition"
**kwargs # type: Any
):
# type: (...) -> LROPoller["_models.SparkBatchJob"]
"""Debug the spark job definition.
:param properties: Properties of spark job definition.
:type properties: ~azure.synapse.artifacts.models.SparkJobDefinition
: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 LROBasePolling.
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.PollingMethod
:keyword int polling_interval: Default waiting time between two polls for LRO operations if no Retry-After header is present.
:return: An instance of LROPoller that returns either SparkBatchJob or the result of cls(response)
:rtype: ~azure.core.polling.LROPoller[~azure.synapse.artifacts.models.SparkBatchJob]
:raises ~azure.core.exceptions.HttpResponseError:
"""
polling = kwargs.pop('polling', True) # type: Union[bool, PollingMethod]
cls = kwargs.pop('cls', None) # type: ClsType["_models.SparkBatchJob"]
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 = self._debug_spark_job_definition_initial(
properties=properties,
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('SparkBatchJob', 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),
}
if polling is True: polling_method = LROBasePolling(lro_delay, lro_options={'final-state-via': 'location'}, path_format_arguments=path_format_arguments, **kwargs)
elif polling is False: polling_method = NoPolling()
else: polling_method = polling
if cont_token:
return LROPoller.from_continuation_token(
polling_method=polling_method,
continuation_token=cont_token,
client=self._client,
deserialization_callback=get_long_running_output
)
else:
return LROPoller(self._client, raw_result, get_long_running_output, polling_method)
def begin_training(self, training_files, use_labels=False, **kwargs):
# type: (str, Optional[bool], Any) -> LROPoller
"""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.
:keyword int polling_interval: Waiting time between two polls for LRO operations
if no Retry-After header is present. Defaults to 5 seconds.
:return: An instance of an LROPoller. Call `result()` on the poller
object to return a :class:`~azure.ai.formrecognizer.CustomFormModel`.
:rtype: ~azure.core.polling.LROPoller[~azure.ai.formrecognizer.CustomFormModel]
:raises ~azure.core.exceptions.HttpResponseError:
.. admonition:: Example:
.. literalinclude:: ../samples/sample_train_unlabeled_model.py
:start-after: [START training]
:end-before: [END training]
:language: python
:dedent: 8
:caption: Training a model with your custom forms.
"""
cls = kwargs.pop("cls", None)
polling_interval = kwargs.pop("polling_interval", POLLING_INTERVAL)
response = self._client.train_custom_model_async( # type: ignore
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
) # type: PipelineResponseType
def callback(raw_response):
model = self._client._deserialize(Model, raw_response)
return CustomFormModel._from_generated(model)
deserialization_callback = cls if cls else callback
return LROPoller(
self._client._client,
response,
deserialization_callback,
LROBasePolling(timeout=polling_interval, lro_algorithms=[TrainingPolling()], **kwargs)
)
def begin_recognize_content_from_url(self, form_url, **kwargs):
# type: (str, Any) -> LROPoller[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 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 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 LROPoller. Call `result()` on the poller
object to return a list[:class:`~azure.ai.formrecognizer.FormPage`].
:rtype: ~azure.core.polling.LROPoller[list[~azure.ai.formrecognizer.FormPage]]
:raises ~azure.core.exceptions.HttpResponseError:
"""
polling_interval = kwargs.pop("polling_interval",
self._client._config.polling_interval)
continuation_token = kwargs.pop("continuation_token", None)
return self._client.begin_analyze_layout_async( # type: ignore
file_stream={"source": form_url},
cls=kwargs.pop("cls", self._content_callback),
polling=LROBasePolling(timeout=polling_interval, **kwargs),
error_map=error_map,
continuation_token=continuation_token,
**kwargs)
def begin_selective_restore(self, folder_url, sas_token, key_name,
**kwargs):
# type: (str, str, str, **Any) -> LROPoller[SelectiveKeyRestoreOperation]
"""Restore a single key from a full Key Vault backup.
:param str folder_url: URL for the blob storage resource, including the path to the blob holding the
backup. This would be the `folder_url` of a :class:`BackupOperation` returned by
:func:`begin_backup` or :func:`get_backup_status`, for example
https://<account>.blob.core.windows.net/backup/mhsm-account-2020090117323313
:param str sas_token: a Shared Access Signature (SAS) token authorizing access to the blob storage resource
:param str key_name: name of the key to restore from the backup
:rtype: ~azure.core.polling.LROPoller[RestoreOperation]
"""
polling_interval = kwargs.pop("_polling_interval", 5)
container_url, folder_name = parse_folder_url(folder_url)
sas_parameter = self._models.SASTokenParameter(
storage_resource_uri=container_url, token=sas_token)
restore_details = self._models.SelectiveKeyRestoreOperationParameters(
sas_token_parameters=sas_parameter, folder=folder_name)
return self._client.begin_selective_key_restore_operation(
vault_base_url=self._vault_url,
key_name=key_name,
restore_blob_details=restore_details,
cls=SelectiveKeyRestoreOperation._wrap_generated,
continuation_token=kwargs.pop("continuation_token", None),
polling=LROBasePolling(
lro_algorithms=[KeyVaultBackupClientPolling()],
timeout=polling_interval,
**kwargs),
**kwargs)
def wait_until_done(self, job_id, **kwargs):
# type: (str, **Any) -> JobStatusDetail
"""
:param job_id: guid id for job
:type job_id: str
:return: JobStatusDetail
:rtype: JobStatusDetail
"""
pipeline_response = 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 JobStatusDetail._from_generated(detail) # pylint: disable=protected-access
poller = LROPoller(
client=self._client._client, # pylint: disable=protected-access
initial_response=pipeline_response,
deserialization_callback=callback,
polling_method=LROBasePolling(
timeout=30, lro_algorithms=[TranslationPolling()], **kwargs),
)
return poller.result()
def begin_extract_receipts_from_url(self, url, **kwargs):
# type: (str, Any) -> LROPoller
"""Extract field text and semantic values from a given receipt document.
The input document must be the location (Url) of the document to be analyzed.
:param url: The url of the receipt.
:type url: str
:keyword bool include_text_details: Include text lines and element references in the result.
:return: LROPoller
:rtype: ~azure.core.polling.LROPoller[list[~azure.ai.formrecognizer.ExtractedReceipt]]
:raises: ~azure.core.exceptions.HttpResponseError
"""
if not isinstance(url, six.string_types):
raise TypeError(
"Call begin_extract_receipts() to analyze a receipt from a stream."
)
include_text_details = kwargs.pop("include_text_details", False)
return self._client.begin_analyze_receipt_async(
file_stream={"source": url},
include_text_details=include_text_details,
cls=kwargs.pop("cls", self._receipt_callback),
polling=LROBasePolling(timeout=POLLING_INTERVAL, **kwargs),
**kwargs)
def begin_extract_receipts(self, stream, **kwargs):
# type: (IO[bytes], Any) -> LROPoller
"""Extract field text and semantic values from a given receipt document.
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.
:type stream: stream
:keyword bool include_text_details: Include text lines and element references in the result.
:keyword str content_type: Media type of the body sent to the API.
:return: LROPoller
:rtype: ~azure.core.polling.LROPoller[list[~azure.ai.formrecognizer.ExtractedReceipt]]
:raises: ~azure.core.exceptions.HttpResponseError
"""
if isinstance(stream, six.string_types):
raise TypeError(
"Call begin_extract_receipts_from_url() to analyze a receipt from a url."
)
include_text_details = kwargs.pop("include_text_details", False)
content_type = kwargs.pop("content_type", None)
if content_type is None:
content_type = get_content_type(stream)
return self._client.begin_analyze_receipt_async(
file_stream=stream,
content_type=content_type,
include_text_details=include_text_details,
cls=kwargs.pop("cls", self._receipt_callback),
polling=LROBasePolling(timeout=POLLING_INTERVAL, **kwargs),
**kwargs)
def begin_extract_layouts(self, stream, **kwargs):
# type: (IO[bytes], Any) -> LROPoller
"""Extract text and 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 stream: .pdf, .jpg, .png or .tiff type file stream.
:type stream: stream
:keyword str content_type: Media type of the body sent to the API.
:return: LROPoller
:rtype: ~azure.core.polling.LROPoller[list[~azure.ai.formrecognizer.ExtractedLayoutPage]]
:raises: ~azure.core.exceptions.HttpResponseError
"""
if isinstance(stream, six.string_types):
raise TypeError(
"Call begin_extract_layouts_from_url() to analyze a document from a url."
)
content_type = kwargs.pop("content_type", None)
if content_type is None:
content_type = get_content_type(stream)
return self._client.begin_analyze_layout_async(
file_stream=stream,
content_type=content_type,
cls=kwargs.pop("cls", self._layout_callback),
polling=LROBasePolling(timeout=POLLING_INTERVAL, **kwargs),
**kwargs)
def begin_recognize_custom_forms_from_url(self, model_id, form_url,
**kwargs):
# type: (str, str, Any) -> LROPoller[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 str continuation_token: A continuation token to restart a poller from a saved state.
: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:
"""
if not model_id:
raise ValueError("model_id cannot be None or empty.")
pages = kwargs.pop("pages", None)
continuation_token = kwargs.pop("continuation_token", None)
include_field_elements = kwargs.pop("include_field_elements", False)
polling_interval = kwargs.pop("polling_interval",
self._client._config.polling_interval)
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 = LROBasePolling(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:
kwargs.update({"pages": pages})
else:
raise ValueError(
"'pages' is only available for API version V2_1 and up")
return 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)
def begin_create_composed_model(self, model_ids, **kwargs):
# type: (List[str], Any) -> DocumentModelAdministrationLROPoller[DocumentModel]
"""Creates a composed model from a collection of existing models.
A composed model allows multiple models to be called with a single model ID. When a document is
submitted to be analyzed with a composed model ID, a classification step is first performed to
route it to the correct custom model.
:param list[str] model_ids: List of model IDs to use in the composed model.
:keyword str model_id: A unique ID for your composed model.
If not specified, a model ID will be created for you.
:keyword str description: An optional description to add to the model.
:keyword str continuation_token: A continuation token to restart a poller from a saved state.
:return: An instance of an DocumentModelAdministrationLROPoller. Call `result()` on the poller
object to return a :class:`~azure.ai.formrecognizer.DocumentModel`.
:rtype: ~azure.ai.formrecognizer.DocumentModelAdministrationLROPoller[DocumentModel]
:raises ~azure.core.exceptions.HttpResponseError:
.. admonition:: Example:
.. literalinclude:: ../samples/v3.2-beta/sample_create_composed_model.py
:start-after: [START composed_model]
:end-before: [END composed_model]
:language: python
:dedent: 4
:caption: Creating a composed model with existing models.
"""
def _compose_callback(raw_response, _, headers): # pylint: disable=unused-argument
op_response = self._deserialize(
self._generated_models.GetOperationResponse, raw_response)
model_info = self._deserialize(self._generated_models.ModelInfo,
op_response.result)
return DocumentModel._from_generated(model_info)
model_id = kwargs.pop("model_id", None)
description = kwargs.pop("description", None)
continuation_token = kwargs.pop("continuation_token", None)
polling_interval = kwargs.pop("polling_interval",
self._client._config.polling_interval)
if model_id is None:
model_id = str(uuid.uuid4())
return self._client.begin_compose_document_model(
compose_request=self._generated_models.ComposeDocumentModelRequest(
model_id=model_id,
description=description,
component_models=[
self._generated_models.ComponentModelInfo(
model_id=model_id) for model_id in model_ids
] if model_ids else [],
),
cls=kwargs.pop("cls", _compose_callback),
polling=LROBasePolling(
timeout=polling_interval,
lro_algorithms=[DocumentModelAdministrationPolling()],
**kwargs),
continuation_token=continuation_token,
**kwargs)
def begin_unsubscribe_trigger_from_events(
self,
trigger_name, # type: str
**kwargs # type: Any
):
# type: (...) -> LROPoller["models.TriggerSubscriptionOperationStatus"]
"""Unsubscribe event trigger from events.
: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.PollingMethod
:keyword int polling_interval: Default waiting time between two polls for LRO operations if no Retry-After header is present.
:return: An instance of LROPoller that returns either TriggerSubscriptionOperationStatus or the result of cls(response)
:rtype: ~azure.core.polling.LROPoller[~azure.synapse.artifacts.models.TriggerSubscriptionOperationStatus]
:raises ~azure.core.exceptions.HttpResponseError:
"""
polling = kwargs.pop('polling',
False) # type: Union[bool, PollingMethod]
cls = kwargs.pop(
'cls',
None) # type: ClsType["models.TriggerSubscriptionOperationStatus"]
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 = self._unsubscribe_trigger_from_events_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):
deserialized = self._deserialize(
'TriggerSubscriptionOperationStatus', pipeline_response)
if cls:
return cls(pipeline_response, deserialized, {})
return deserialized
if polling is True:
polling_method = LROBasePolling(lro_delay, **kwargs)
elif polling is False:
polling_method = NoPolling()
else:
polling_method = polling
if cont_token:
return LROPoller.from_continuation_token(
polling_method=polling_method,
continuation_token=cont_token,
client=self._client,
deserialization_callback=get_long_running_output)
else:
return LROPoller(self._client, raw_result, get_long_running_output,
polling_method)
def begin_compose_document_model(
self,
compose_request, # type: "_models.ComposeDocumentModelRequest"
**kwargs # type: Any
):
# type: (...) -> DocumentModelAdministrationLROPoller[None]
"""Compose model.
Creates a new model from document types of existing models.
:param compose_request: Compose request parameters.
:type compose_request: ~azure.ai.formrecognizer.v2021_09_30_preview.models.ComposeDocumentModelRequest
: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 LROBasePolling.
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.PollingMethod
:keyword int polling_interval: Default waiting time between two polls for LRO operations if no Retry-After header is present.
:return: An instance of DocumentModelAdministrationLROPoller that returns either None or the result of cls(response)
:rtype: ~...._polling.DocumentModelAdministrationLROPoller[None]
:raises ~azure.core.exceptions.HttpResponseError:
"""
polling = kwargs.pop('polling', True) # type: Union[bool, PollingMethod]
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 = self._compose_document_model_initial(
compose_request=compose_request,
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, {})
path_format_arguments = {
'endpoint': self._serialize.url("self._config.endpoint", self._config.endpoint, 'str', skip_quote=True),
}
if polling is True: polling_method = LROBasePolling(lro_delay, path_format_arguments=path_format_arguments, **kwargs)
elif polling is False: polling_method = NoPolling()
else: polling_method = polling
if cont_token:
return DocumentModelAdministrationLROPoller.from_continuation_token(
polling_method=polling_method,
continuation_token=cont_token,
client=self._client,
deserialization_callback=get_long_running_output
)
else:
return DocumentModelAdministrationLROPoller(self._client, raw_result, get_long_running_output, polling_method)
def begin_delete_pipeline(
self,
pipeline_name, # type: str
**kwargs # type: Any
):
# type: (...) -> LROPoller[None]
"""Deletes a pipeline.
:param pipeline_name: The pipeline name.
:type pipeline_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: By default, your polling method will be LROBasePolling.
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.PollingMethod
:keyword int polling_interval: Default waiting time between two polls for LRO operations if no Retry-After header is present.
:return: An instance of LROPoller that returns either None or the result of cls(response)
:rtype: ~azure.core.polling.LROPoller[None]
:raises ~azure.core.exceptions.HttpResponseError:
"""
polling = kwargs.pop('polling', True) # type: Union[bool, PollingMethod]
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 = self._delete_pipeline_initial(
pipeline_name=pipeline_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, {})
path_format_arguments = {
'endpoint': self._serialize.url("self._config.endpoint", self._config.endpoint, 'str', skip_quote=True),
'pipelineName': self._serialize.url("pipeline_name", pipeline_name, 'str', max_length=260, min_length=1, pattern=r'^[A-Za-z0-9_][^<>*#.%&:\\+?/]*$'),
}
if polling is True: polling_method = LROBasePolling(lro_delay, path_format_arguments=path_format_arguments, **kwargs)
elif polling is False: polling_method = NoPolling()
else: polling_method = polling
if cont_token:
return LROPoller.from_continuation_token(
polling_method=polling_method,
continuation_token=cont_token,
client=self._client,
deserialization_callback=get_long_running_output
)
else:
return LROPoller(self._client, raw_result, get_long_running_output, polling_method)
def begin_create_composed_model(self, model_ids, **kwargs):
# type: (List[str], Any) -> LROPoller[CustomFormModel]
"""Creates a composed model from a collection of existing models that were trained with labels.
A composed model allows multiple models to be called with a single model ID. When a document is
submitted to be analyzed with a composed model ID, a classification step is first performed to
route it to the correct custom model
: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 LROPoller. Call `result()` on the poller
object to return a :class:`~azure.ai.formrecognizer.CustomFormModel`.
:rtype: ~azure.core.polling.LROPoller[~azure.ai.formrecognizer.CustomFormModel]
:raises ~azure.core.exceptions.HttpResponseError:
.. versionadded:: v2.1-preview
The *begin_create_composed_model* client method
.. admonition:: Example:
.. literalinclude:: ../samples/sample_create_composed_model.py
:start-after: [START begin_create_composed_model]
:end-before: [END begin_create_composed_model]
: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 self._client.begin_compose_custom_models_async(
{"model_ids": model_ids, "model_name": model_name},
cls=kwargs.pop("cls", _compose_callback),
polling=LROBasePolling(
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"
)
def begin_recognize_custom_forms(self, model_id, stream, **kwargs):
# type: (str, Union[bytes, IO[bytes]], Any) -> LROPoller
"""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: JPEG, PNG, PDF and TIFF type file stream or bytes.
: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: 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:
.. admonition:: Example:
.. literalinclude:: ../samples/sample_recognize_custom_forms.py
:start-after: [START recognize_custom_forms]
:end-before: [END recognize_custom_forms]
: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 self._client.begin_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=LROBasePolling(timeout=polling_interval, lro_algorithms=[AnalyzePolling()], **kwargs),
error_map=error_map,
**kwargs
)
def _callback(request, **kwargs):
initial_response = client.send_request(request=request,
_return_pipeline_response=True)
return LROPoller(
client._client,
initial_response,
deserialization_callback,
LROBasePolling(0, **kwargs),
)
def begin_execute_command(
self,
request, # type: "models.DataFlowDebugCommandRequest"
**kwargs # type: Any
):
# type: (...) -> LROPoller["models.DataFlowDebugCommandResponse"]
"""Execute a data flow debug command.
:param request: Data flow debug command definition.
:type request: ~azure.synapse.artifacts.models.DataFlowDebugCommandRequest
: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.PollingMethod
:keyword int polling_interval: Default waiting time between two polls for LRO operations if no Retry-After header is present.
:return: An instance of LROPoller that returns either DataFlowDebugCommandResponse or the result of cls(response)
:rtype: ~azure.core.polling.LROPoller[~azure.synapse.artifacts.models.DataFlowDebugCommandResponse]
:raises ~azure.core.exceptions.HttpResponseError:
"""
polling = kwargs.pop('polling', False) # type: Union[bool, PollingMethod]
cls = kwargs.pop('cls', None) # type: ClsType["models.DataFlowDebugCommandResponse"]
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 = self._execute_command_initial(
request=request,
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('DataFlowDebugCommandResponse', pipeline_response)
if cls:
return cls(pipeline_response, deserialized, {})
return deserialized
if polling is True: polling_method = LROBasePolling(lro_delay, **kwargs)
elif polling is False: polling_method = NoPolling()
else: polling_method = polling
if cont_token:
return LROPoller.from_continuation_token(
polling_method=polling_method,
continuation_token=cont_token,
client=self._client,
deserialization_callback=get_long_running_output
)
else:
return LROPoller(self._client, raw_result, get_long_running_output, polling_method)
