[translation] poller design (Azure#19041)

* add polling implementation

* add polling generation transforms and regenerate

* add tests and recordings

* samples, readme, changelog

* update changelog

* pylint

* some docs updates

* missed an await

eng/.docsettings.yml

@@ -84,6 +84,7 @@ known_content_issues:
   - ['sdk/monitor/azure-monitor-opentelemetry-exporter/README.md', '#4554']
   - ['sdk/digitaltwins/azure-digitaltwins-core/swagger/README.md', '#4554']
   - ['sdk/textanalytics/azure-ai-textanalytics/swagger/README.md', '#4554']
+  - ['sdk/translation/azure-ai-translation-document/swagger/README.md', '#4554']
   - ['sdk/purview/azure-purview-catalog/swagger/README.md',  '#4554']
   - ['sdk/purview/azure-purview-scanning/swagger/README.md',  '#4554']
   - ['sdk/agrifood/azure-agrifood-farming/swagger/README.md',  '#4554']

sdk/translation/azure-ai-translation-document/CHANGELOG.md

@@ -4,6 +4,18 @@
 
 This version of the SDK defaults to the latest supported service version, which currently is v1.0
 
+**Breaking changes**
+
+- `create_translation_job` was removed and replaced with `begin_translation` which follows a long-running operation (LRO)
+approach. The client method now returns a `DocumentTranslationPoller` (or `AsyncDocumentTranslationPoller`) to begin the 
+long-running operation. A call to `.result()` can be made on the poller object to wait until the translation is complete. 
+See the [README](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/translation/azure-ai-translation-document/README.md) for more information about LROs.
+- Upon completion of the LRO, `begin_translation` now returns a pageable of `DocumentStatusResult`. All job-level metadata can still
+be found on `poller.details`.
+- `has_completed` has been removed from `JobStatusResult` and `DocumentStatusResult`. Use `poller.done()` to check if the 
+translation has completed.
+- Client method `wait_until_done` has been removed. Use `poller.result()` to wait for the LRO to complete.
+
 **New features**
 
 - Authentication using `azure-identity` credentials now supported.

sdk/translation/azure-ai-translation-document/README.md

@@ -4,7 +4,7 @@ Azure Cognitive Services Document Translation is a cloud service that translates
 and dialects while preserving document structure and data format. Use the client library for Document Translation to:
 
 * Translate numerous, large files from an Azure Blob Storage container to a target container in your language of choice.
-* Check the translation status and progress of each document in the translation job.
+* Check the translation status and progress of each document in the translation operation.
 * Apply a custom translation model or glossaries to tailor translation to your specific case.
 
 [Source code][python-dt-src] | [Package (PyPI)][python-dt-pypi] | [API reference documentation][python-dt-ref-docs] | [Product documentation][python-dt-product-docs] | [Samples][python-dt-samples]
@@ -130,14 +130,14 @@ the service documentation:
 Interaction with the Document Translation client library begins with an instance of the `DocumentTranslationClient`.
 The client provides operations for:
 
- - Creating a translation job to translate documents in your source container(s) and write results to you target container(s).
- - Checking the status of individual documents in the translation job and monitoring each document's progress.
- - Enumerating all past and current translation jobs with the option to wait until the job(s) finish.
+ - Creating a translation operation to translate documents in your source container(s) and write results to you target container(s).
+ - Checking the status of individual documents in the translation operation and monitoring each document's progress.
+ - Enumerating all past and current translations operations.
  - Identifying supported glossary and document formats.
 
 ### Translation Input
 
-To create a translation job, pass a list of `DocumentTranslationInput` into the `create_translation_job` client method.
+To begin translating your documents, pass a list of `DocumentTranslationInput` into the `begin_translation` client method.
 Constructing a `DocumentTranslationInput` requires that you pass the SAS URLs to your source and target containers (or files)
 and the target language(s) for translation.
 
@@ -191,20 +191,22 @@ my_input = [
 
 See the service documentation for all [supported languages][supported_languages].
 
-### Return value
+### Long-Running Operations
+Long-running operations are operations which consist of an initial request sent to the service to start an operation,
+followed by polling the service at intervals to determine whether the operation has completed or failed, and if it has
+succeeded, to get the result.
 
-There are primarily two types of return values when checking on the result of a translation job - `JobStatusResult` and `DocumentStatusResult`.
-* A `JobStatusResult` will contain the details of the entire job, such as it's status, ID, any errors, and status summaries of the documents in the job.
-* A `DocumentStatusResult` will contain the details of an individual document, such as it's status, translation progress, any errors,
-and the URLs to the source document and translated document.
+Methods that translate documents are modeled as long-running operations.
+The client exposes a `begin_<method-name>` method that returns a `DocumentTranslationPoller` or `AsyncDocumentTranslationPoller`. Callers should wait
+for the operation to complete by calling `result()` on the poller object returned from the `begin_<method-name>` method.
+Sample code snippets are provided to illustrate using long-running operations [below](#examples "Examples").
 
 ## Examples
 
 The following section provides several code snippets covering some of the most common Document Translation tasks, including:
 
 * [Translate your documents](#translate-your-documents "Translate Your Documents")
-* [Check status on individual documents](#check-status-on-individual-documents "Check Status On Individual Documents")
-* [List translation jobs](#list-translation-jobs "List Translation Jobs")
+* [List translation operations](#list-translation-operations "List Translation Operations")
 
 ### Translate your documents
 Translate the documents in your source container to the target containers.
@@ -221,7 +223,7 @@ target_container_sas_url_fr = "<sas-url-fr>"
 
 document_translation_client = DocumentTranslationClient(endpoint, credential)
 
-job = document_translation_client.create_translation_job(
+poller = document_translation_client.begin_translation(
     [
         DocumentTranslationInput(
             source_url=source_container_sas_url_en,
@@ -231,59 +233,32 @@ job = document_translation_client.create_translation_job(
             ],
         )
     ]
-)  # type: JobStatusResult
-
-job_result = document_translation_client.wait_until_done(job.id)  # type: JobStatusResult
-
-print("Job created on: {}".format(job_result.created_on))
-print("Job last updated on: {}".format(job_result.last_updated_on))
-print("Total number of translations on documents: {}".format(job_result.documents_total_count))
-
-print("Of total documents...")
-print("{} failed".format(job_result.documents_failed_count))
-print("{} succeeded".format(job_result.documents_succeeded_count))
-
-if job_result.status == "Succeeded":
-    print("Our translation job succeeded")
-
-if job_result.status == "Failed":
-    print("All documents failed in the translation job")
-
-# check document statuses... see next sample
-```
-
-### Check status on individual documents
-Check status and translation progress of each document under a job.
-
-```python
-from azure.core.credentials import AzureKeyCredential
-from azure.ai.translation.document import DocumentTranslationClient
-
-endpoint = "https://<resource-name>.cognitiveservices.azure.com/"
-credential = AzureKeyCredential("<api_key>")
-job_id = "<job-id>"
-
-document_translation_client = DocumentTranslationClient(endpoint, credential)
+)
 
-documents =  document_translation_client.list_all_document_statuses(job_id)  # type: ItemPaged[DocumentStatusResult]
-
-for doc in documents:
-    if doc.status == "Succeeded":
-        print("Document at {} was translated to {} language".format(
-            doc.translated_document_url, doc.translate_to
-        ))
-    if doc.status == "Running":
-        print("Document ID: {}, translation progress is {} percent".format(
-            doc.id, doc.translation_progress*100
-        ))
-    if doc.status == "Failed":
-        print("Document ID: {}, Error Code: {}, Message: {}".format(
-            doc.id, doc.error.code, doc.error.message
-        ))
+result = poller.result()
+
+print("Status: {}".format(poller.status()))
+print("Created on: {}".format(poller.details.created_on))
+print("Last updated on: {}".format(poller.details.last_updated_on))
+print("Total number of translations on documents: {}".format(poller.details.documents_total_count))
+
+print("\nOf total documents...")
+print("{} failed".format(poller.details.documents_failed_count))
+print("{} succeeded".format(poller.details.documents_succeeded_count))
+
+for document in result:
+    print("Document ID: {}".format(document.id))
+    print("Document status: {}".format(document.status))
+    if document.status == "Succeeded":
+        print("Source document location: {}".format(document.source_document_url))
+        print("Translated document location: {}".format(document.translated_document_url))
+        print("Translated to language: {}\n".format(document.translate_to))
+    else:
+        print("Error Code: {}, Message: {}\n".format(document.error.code, document.error.message))
 ```
 
-### List translation jobs
-Enumerate over the translation jobs submitted for the resource.
+### List translation operations
+Enumerate over the translation operations submitted for the resource.
 
 ```python
 from azure.core.credentials import AzureKeyCredential
@@ -297,9 +272,6 @@ document_translation_client = DocumentTranslationClient(endpoint, credential)
 jobs = document_translation_client.list_submitted_jobs()  # type: ItemPaged[JobStatusResult]
 
 for job in jobs:
-    if not job.has_completed:
-        job = document_translation_client.wait_until_done(job.id)
-
     print("Job ID: {}".format(job.id))
     print("Job status: {}".format(job.status))
     print("Job created on: {}".format(job.created_on))
@@ -348,7 +320,7 @@ The following section provides several code snippets illustrating common pattern
 These code samples show common scenario operations with the Azure Document Translation client library.
 
 * Client authentication: [sample_authentication.py][sample_authentication]
-* Create a translation job: [sample_create_translation_job.py][sample_create_translation_job]
+* Begin translating documents: [sample_begin_translation.py][sample_begin_translation]
 * Check the status of documents: [sample_check_document_statuses.py][sample_check_document_statuses]
 * List all submitted translation jobs: [sample_list_all_submitted_jobs.py][sample_list_all_submitted_jobs]
 * Apply a custom glossary to translation: [sample_translation_with_glossaries.py][sample_translation_with_glossaries]
@@ -361,7 +333,7 @@ first install an async transport, such as [aiohttp](https://pypi.org/project/aio
 are found under the `azure.ai.translation.document.aio` namespace.
 
 * Client authentication: [sample_authentication_async.py][sample_authentication_async]
-* Create a translation job: [sample_create_translation_job_async.py][sample_create_translation_job_async]
+* Begin translating documents: [sample_begin_translation_async.py][sample_begin_translation_async]
 * Check the status of documents: [sample_check_document_statuses_async.py][sample_check_document_statuses_async]
 * List all submitted translation jobs: [sample_list_all_submitted_jobs_async.py][sample_list_all_submitted_jobs_async]
 * Apply a custom glossary to translation: [sample_translation_with_glossaries_async.py][sample_translation_with_glossaries_async]
@@ -416,8 +388,8 @@ This project has adopted the [Microsoft Open Source Code of Conduct][code_of_con
 
 [sample_authentication]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/translation/azure-ai-translation-document/samples/sample_authentication.py
 [sample_authentication_async]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/translation/azure-ai-translation-document/samples/async_samples/sample_authentication_async.py
-[sample_create_translation_job]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/translation/azure-ai-translation-document/samples/sample_create_translation_job.py
-[sample_create_translation_job_async]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/translation/azure-ai-translation-document/samples/async_samples/sample_create_translation_job_async.py
+[sample_begin_translation]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/translation/azure-ai-translation-document/samples/sample_begin_translation.py
+[sample_begin_translation_async]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/translation/azure-ai-translation-document/samples/async_samples/sample_begin_translation_async.py
 [sample_check_document_statuses]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/translation/azure-ai-translation-document/samples/sample_check_document_statuses.py
 [sample_check_document_statuses_async]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/translation/azure-ai-translation-document/samples/async_samples/sample_check_document_statuses_async.py
 [sample_list_all_submitted_jobs]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/translation/azure-ai-translation-document/samples/sample_list_all_submitted_jobs.py

sdk/translation/azure-ai-translation-document/azure/ai/translation/document/__init__.py

@@ -10,6 +10,7 @@
     StorageInputType,
 )
 from ._api_version import DocumentTranslationApiVersion
+from ._polling import DocumentTranslationPoller
 from ._models import (
     TranslationTarget,
     JobStatusResult,
@@ -34,4 +35,5 @@
     "JobStatusResult",
     "DocumentStatusResult",
     "DocumentTranslationError",
+    "DocumentTranslationPoller"
 ]