add filter samples for list methods (Azure#18480)

* copy samples from tests branch

* added samples for list submitted jobs both sync and async

* fix parameters issues

* create samples for sync client 'list all doc statuses'

* added async test

* move samples to proper directory

* simplify sample name

* expose job_id as env variable

* update sample file name

* update description

* removed unused imports

* update sample docs

* update filter notes

* update filter comment message

sdk/translation/azure-ai-translation-document/samples/async_samples/sample_list_document_statuses_with_filters_async.py

@@ -0,0 +1,92 @@
+# coding=utf-8
+# ------------------------------------
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# ------------------------------------
+
+"""
+FILE: sample_list_document_statuses_with_filters_async.py
+
+DESCRIPTION:
+    This sample demonstrates how to list all the document in a translation job for the resource 
+    using different kind of filters/sorting/paging options
+
+    To set up your containers for translation and generate SAS tokens to your containers (or files)
+    with the appropriate permissions, see the README.
+
+USAGE:
+    python sample_list_document_statuses_with_filters_async.py
+
+    Set the environment variables with your own values before running the sample:
+    1) AZURE_DOCUMENT_TRANSLATION_ENDPOINT - the endpoint to your Document Translation resource.
+    2) AZURE_DOCUMENT_TRANSLATION_KEY - your Document Translation API key.
+    3) JOB_ID - The ID of the translation job
+"""
+
+import os
+import asyncio
+
+async def sample_list_document_statuses_with_filters_async(self, client):
+    # import libraries
+    from azure.core.credentials import AzureKeyCredential
+    from azure.ai.translation.document import (
+        DocumentTranslationClient,
+    )
+    from datetime import datetime
+
+    # obtain client secrets
+    endpoint = os.environ["AZURE_DOCUMENT_TRANSLATION_ENDPOINT"]
+    key = os.environ["AZURE_DOCUMENT_TRANSLATION_KEY"]
+    job_id = os.environ["JOB_ID"]  # this should be the id for the job you'd like to list docs for!
+
+    # authorize client
+    client = DocumentTranslationClient(endpoint, AzureKeyCredential(key))
+
+    # set your filters
+    '''
+        Note:
+            these are just sample values for the filters!
+            please comment/uncomment/change what you are interested in using.
+    '''
+    start = datetime(2021, 4, 12)
+    end = datetime(2021, 4, 14)
+    statuses = ["Cancelled", "Failed"]
+    order_by = ["createdDateTimeUtc desc"]
+    results_per_page = 2
+    skip = 3
+
+    # list jobs
+    async with client:
+        filtered_docs = client.list_all_document_statuses(
+            job_id,
+            # filters
+            statuses=statuses,
+            translated_after=start,
+            translated_before=end,
+            # ordering
+            order_by=order_by,
+            # paging
+            skip=skip,
+            results_per_page=results_per_page
+        ).by_page()
+
+        # check statuses
+        async for page in filtered_docs:
+            async for job in page:
+                display_doc_info(job)
+
+def display_doc_info(document):
+    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))
+
+
+async def main():
+    await sample_list_document_statuses_with_filters_async()
+
+if __name__ == '__main__':
+    loop = asyncio.get_event_loop()
+    loop.run_until_complete(main())

sdk/translation/azure-ai-translation-document/samples/async_samples/sample_list_submitted_jobs_with_filters_async.py

@@ -0,0 +1,92 @@
+# coding=utf-8
+# ------------------------------------
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# ------------------------------------
+
+"""
+FILE: sample_list_submitted_jobs_with_filters_async.py
+
+DESCRIPTION:
+    This sample demonstrates how to list all the submitted translation jobs for the resource 
+    using different kind of filters/sorting/paging options
+
+    To set up your containers for translation and generate SAS tokens to your containers (or files)
+    with the appropriate permissions, see the README.
+
+USAGE:
+    python sample_list_submitted_jobs_with_filters_async.py
+
+    Set the environment variables with your own values before running the sample:
+    1) AZURE_DOCUMENT_TRANSLATION_ENDPOINT - the endpoint to your Document Translation resource.
+    2) AZURE_DOCUMENT_TRANSLATION_KEY - your Document Translation API key.
+"""
+
+import os
+import asyncio
+
+async def sample_list_submitted_jobs_with_filters_async():
+    # import libraries
+    from azure.core.credentials import AzureKeyCredential
+    from azure.ai.translation.document.aio import DocumentTranslationClient
+
+    from datetime import datetime
+
+    # obtain client secrets
+    endpoint = os.environ["AZURE_DOCUMENT_TRANSLATION_ENDPOINT"]
+    key = os.environ["AZURE_DOCUMENT_TRANSLATION_KEY"]
+
+    # authorize client
+    client = DocumentTranslationClient(endpoint, AzureKeyCredential(key))
+    async with client:
+        # set your filters
+        '''
+            Note:
+                these are just sample values for the filters!
+                please comment/uncomment/change what you are interested in using.
+        '''
+        start = datetime(2021, 4, 12)
+        end = datetime(2021, 4, 14)
+        statuses = ["Cancelled", "Failed"]
+        order_by = ["createdDateTimeUtc desc"]
+        results_per_page = 2
+        skip = 3
+
+        # list jobs
+        submitted_jobs = client.list_submitted_jobs(
+            # filters
+            statuses=statuses,
+            created_after=start,
+            created_before=end,
+            # ordering
+            order_by=order_by,
+            # paging
+            skip=skip,
+            results_per_page=results_per_page
+        ).by_page()
+
+        # check statuses
+        async for page in submitted_jobs:
+            async for job in page:
+                display_job_info(job)
+
+
+def display_job_info(job):
+    print("Job ID: {}".format(job.id))
+    print("Job status: {}".format(job.status))
+    print("Job created on: {}".format(job.created_on))
+    print("Job last updated on: {}".format(job.last_updated_on))
+    print("Total number of translations on documents: {}".format(job.documents_total_count))
+    print("Total number of characters charged: {}".format(job.total_characters_charged))
+    print("\nOf total documents...")
+    print("{} failed".format(job.documents_failed_count))
+    print("{} succeeded".format(job.documents_succeeded_count))
+    print("{} cancelled\n".format(job.documents_cancelled_count))
+
+
+async def main():
+    await sample_list_submitted_jobs_with_filters_async()
+
+if __name__ == '__main__':
+    loop = asyncio.get_event_loop()
+    loop.run_until_complete(main())

sdk/translation/azure-ai-translation-document/samples/sample_list_document_statuses_with_filters.py

@@ -0,0 +1,84 @@
+# coding=utf-8
+# ------------------------------------
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# ------------------------------------
+
+"""
+FILE: sample_list_document_statuses_with_filters.py
+
+DESCRIPTION:
+    This sample demonstrates how to list all the document in a translation job for the resource 
+    using different kind of filters/sorting/paging options
+
+    To set up your containers for translation and generate SAS tokens to your containers (or files)
+    with the appropriate permissions, see the README.
+
+USAGE:
+    python sample_list_document_statuses_with_filters.py
+
+    Set the environment variables with your own values before running the sample:
+    1) AZURE_DOCUMENT_TRANSLATION_ENDPOINT - the endpoint to your Document Translation resource.
+    2) AZURE_DOCUMENT_TRANSLATION_KEY - your Document Translation API key.
+    3) JOB_ID - The ID of the translation job
+"""
+
+def sample_list_document_statuses_with_filters(self, client):
+    # import libraries
+    from azure.core.credentials import AzureKeyCredential
+    from azure.ai.translation.document import (
+        DocumentTranslationClient,
+    )
+    import os
+    from datetime import datetime
+
+    # obtain client secrets
+    endpoint = os.environ["AZURE_DOCUMENT_TRANSLATION_ENDPOINT"]
+    key = os.environ["AZURE_DOCUMENT_TRANSLATION_KEY"]
+    job_id = os.environ["JOB_ID"]  # this should be the id for the job you'd like to list docs for!
+
+    # authorize client
+    client = DocumentTranslationClient(endpoint, AzureKeyCredential(key))
+
+    # set your filters
+    '''
+        Note:
+            these are just sample values for the filters!
+            please comment/uncomment/change what you are interested in using.
+    '''
+    start = datetime(2021, 4, 12)
+    end = datetime(2021, 4, 14)
+    statuses = ["Cancelled", "Failed"]
+    order_by = ["createdDateTimeUtc desc"]
+    results_per_page = 2
+    skip = 3
+
+    # list jobs
+    filtered_docs = client.list_all_document_statuses(
+        job_id,
+        # filters
+        statuses=statuses,
+        translated_after=start,
+        translated_before=end,
+        # ordering
+        order_by=order_by,
+        # paging
+        skip=skip,
+        results_per_page=results_per_page
+    ).by_page()
+
+    # check statuses
+    for page in filtered_docs:
+        for job in page:
+            display_doc_info(job)
+
+def display_doc_info(document):
+    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))
+
+if __name__ == '__main__':
+    sample_list_document_statuses_with_filters()

sdk/translation/azure-ai-translation-document/samples/sample_list_submitted_jobs_with_filters.py

@@ -0,0 +1,89 @@
+# coding=utf-8
+# ------------------------------------
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# ------------------------------------
+
+"""
+FILE: sample_list_submitted_jobs_with_filters.py
+
+DESCRIPTION:
+    This sample demonstrates how to list all the submitted translation jobs for the resource 
+    using different kind of filters/sorting/paging options
+
+    To set up your containers for translation and generate SAS tokens to your containers (or files)
+    with the appropriate permissions, see the README.
+
+USAGE:
+    python sample_list_submitted_jobs_with_filters.py
+
+    Set the environment variables with your own values before running the sample:
+    1) AZURE_DOCUMENT_TRANSLATION_ENDPOINT - the endpoint to your Document Translation resource.
+    2) AZURE_DOCUMENT_TRANSLATION_KEY - your Document Translation API key.
+"""
+
+
+
+def sample_list_submitted_jobs_with_filters():
+    # import libraries
+    from azure.core.credentials import AzureKeyCredential
+    from azure.ai.translation.document import (
+        DocumentTranslationClient,
+    )
+    import os
+    from datetime import datetime
+
+    # obtain client secrets
+    endpoint = os.environ["AZURE_DOCUMENT_TRANSLATION_ENDPOINT"]
+    key = os.environ["AZURE_DOCUMENT_TRANSLATION_KEY"]
+
+    # authorize client
+    client = DocumentTranslationClient(endpoint, AzureKeyCredential(key))
+
+    # set your filters
+    '''
+        Note:
+            these are just sample values for the filters!
+            please comment/uncomment/change what you are interested in using.
+    '''
+    start = datetime(2021, 4, 12)
+    end = datetime(2021, 4, 14)
+    statuses = ["Cancelled", "Failed"]
+    order_by = ["createdDateTimeUtc desc"]
+    results_per_page = 2
+    skip = 3
+
+    # list jobs
+    submitted_jobs = client.list_submitted_jobs(
+        # filters
+        statuses=statuses,
+        created_after=start,
+        created_before=end,
+        # ordering
+        order_by=order_by,
+        # paging
+        skip=skip,
+        results_per_page=results_per_page
+    ).by_page()
+
+    # check statuses
+    for page in submitted_jobs:
+        for job in page:
+            display_job_info(job)
+
+
+def display_job_info(job):
+    print("Job ID: {}".format(job.id))
+    print("Job status: {}".format(job.status))
+    print("Job created on: {}".format(job.created_on))
+    print("Job last updated on: {}".format(job.last_updated_on))
+    print("Total number of translations on documents: {}".format(job.documents_total_count))
+    print("Total number of characters charged: {}".format(job.total_characters_charged))
+    print("\nOf total documents...")
+    print("{} failed".format(job.documents_failed_count))
+    print("{} succeeded".format(job.documents_succeeded_count))
+    print("{} cancelled\n".format(job.documents_cancelled_count))
+
+
+if __name__ == '__main__':
+    sample_list_submitted_jobs_with_filters()