[translation] initial library (#16837)

* initial commit

* update samples

* updates from feedback

* johans feedback

* renaming to use job terminology

* update samples - optional src language

* samples hero scenarios (#16936)

* [samples] added 'batch_translation_async' sample

* [samples] added 'batch_translation_with_storage_async' sample

* [samples] added remianing async samples

* [samples] update file names

* [samples] added self to instance methods

* [samples][async] fix import textanalytics :)

* [samples] fix self. when calling instance methods

* [samples] fixed async check status to use AsyncItemPaged used in Async Client

* [samples] async -> some async operations instead of sync ones

* [samples][async] use async blob operations

* [samples][async] blob download async

* [samples][async] check_documents async

* [samples][async] added some missing await methods

* [async samples] change await time to recommended period

* [samples] updated async samples to comply with new changes

* remove 3.5 support

Co-authored-by: Mohamed Shaban <[email protected]>

sdk/documenttranslation/azure-ai-documenttranslation/CHANGELOG.md

@@ -0,0 +1,3 @@
+# Release History
+
+## 1.0.0b1 (Unreleased)

sdk/documenttranslation/azure-ai-documenttranslation/MANIFEST.in

@@ -0,0 +1,5 @@
+recursive-include tests *.py
+recursive-include samples *.py *.md
+include *.md
+include azure/__init__.py
+include azure/ai/__init__.py

sdk/documenttranslation/azure-ai-documenttranslation/README.md

@@ -0,0 +1,35 @@
+[![Build Status](https://dev.azure.com/azure-sdk/public/_apis/build/status/azure-sdk-for-python.client?branchName=master)](https://dev.azure.com/azure-sdk/public/_build/latest?definitionId=46?branchName=master)
+
+# Azure Template Package client library for Python
+
+This template package matches necessary patterns that the development team has established to create a unified sdk functional from Python 2.7 onwards. The packages contained herein can be installed singly or as part of the `azure` namespace. Any other introductory text should go here.
+
+This package has been tested with Python 2.7, 3.5, 3.6, 3.7 and 3.8
+
+For a more complete set of Azure libraries, see https://aka.ms/azsdk/python/all
+
+# Getting started
+
+For a rich example of a well formatted readme, please check [here.](https://github.com/Azure/azure-sdk/blob/master/docs/policies/README-TEMPLATE.md) In addition, this is an [example readme](https://github.com/Azure/azure-sdk/blob/master/docs/policies/README-EXAMPLE.md) that should be emulated. Note that the top-level sections in this template align with that of the [template.](https://github.com/Azure/azure-sdk/blob/master/docs/policies/README-TEMPLATE.md)
+
+# Key concepts
+
+Bullet point list of your library's main concepts.
+
+# Examples
+
+Examples of some of the key concepts for your library.
+
+# Troubleshooting
+
+Running into issues? This section should contain details as to what to do there.
+
+# Next steps
+
+More sample code should go here, along with links out to the appropriate example tests.
+
+# Contributing
+
+If you encounter any bugs or have suggestions, please file an issue in the [Issues](<https://github.com/Azure/azure-sdk-for-python/issues>) section of the project.
+
+![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-python%2Fsdk%2Ftemplate%2Fazure-template%2FREADME.png)

sdk/documenttranslation/azure-ai-documenttranslation/azure/__init__.py

@@ -0,0 +1 @@
+__path__ = __import__('pkgutil').extend_path(__path__, __name__)  # type: ignore

sdk/documenttranslation/azure-ai-documenttranslation/azure/ai/__init__.py

@@ -0,0 +1 @@
+__path__ = __import__('pkgutil').extend_path(__path__, __name__)  # type: ignore

sdk/documenttranslation/azure-ai-documenttranslation/azure/ai/documenttranslation/__init__.py

@@ -0,0 +1,37 @@
+# coding=utf-8
+# ------------------------------------
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# ------------------------------------
+
+from ._version import VERSION
+from ._client import DocumentTranslationClient
+from ._generated.models import (
+    StorageInputType,
+)
+from ._api_version import DocumentTranslationVersion
+from ._models import (
+    StorageTarget,
+    JobStatusDetail,
+    DocumentStatusDetail,
+    DocumentTranslationError,
+    TranslationGlossary,
+    BatchDocumentInput,
+    FileFormat
+)
+
+__VERSION__ = VERSION
+
+
+__all__ = [
+    "DocumentTranslationClient",
+    "DocumentTranslationVersion",
+    "BatchDocumentInput",
+    "TranslationGlossary",
+    "StorageInputType",
+    "FileFormat",
+    "StorageTarget",
+    "JobStatusDetail",
+    "DocumentStatusDetail",
+    "DocumentTranslationError",
+]

sdk/documenttranslation/azure-ai-documenttranslation/azure/ai/documenttranslation/_api_version.py

@@ -0,0 +1,28 @@
+# ------------------------------------
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# ------------------------------------
+
+from enum import Enum
+
+
+class DocumentTranslationVersion(str, Enum):
+    """Document Translation API versions supported by this package"""
+
+    #: This is the default version
+    V1_0_PREVIEW = "1.0-preview.1"
+
+
+def validate_api_version(api_version):
+    # type: (str) -> None
+    """Raise ValueError if api_version is invalid """
+    if not api_version:
+        return
+
+    try:
+        api_version = DocumentTranslationVersion(api_version)
+    except ValueError:
+        raise ValueError(
+            "Unsupported API version '{}'. Please select from:\n{}".format(
+                api_version, ", ".join(v.value for v in DocumentTranslationVersion))
+        )

sdk/documenttranslation/azure-ai-documenttranslation/azure/ai/documenttranslation/_client.py

@@ -0,0 +1,165 @@
+# coding=utf-8
+# ------------------------------------
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# ------------------------------------
+
+from typing import Union, Any, TYPE_CHECKING, List
+from azure.core.tracing.decorator import distributed_trace
+from ._generated import BatchDocumentTranslationClient as _BatchDocumentTranslationClient
+from ._helpers import get_authentication_policy
+from ._user_agent import USER_AGENT
+if TYPE_CHECKING:
+    from azure.core.paging import ItemPaged
+    from azure.core.credentials import AzureKeyCredential, TokenCredential
+    from ._models import JobStatusDetail, DocumentStatusDetail, BatchDocumentInput, FileFormat
+
+
+class DocumentTranslationClient(object):
+    """DocumentTranslationClient
+
+    """
+
+    def __init__(self, endpoint, credential, **kwargs):
+        # type: (str, Union[AzureKeyCredential, TokenCredential], **Any) -> None
+        """
+
+        :param str endpoint:
+        :param credential:
+        :type credential: Union[AzureKeyCredential, TokenCredential]
+        :keyword str api_version:
+        """
+        self._endpoint = endpoint
+        self._credential = credential
+        self._api_version = kwargs.pop('api_version', None)
+
+        authentication_policy = get_authentication_policy(credential)
+        self._client = _BatchDocumentTranslationClient(
+            endpoint=endpoint,
+            credential=credential,  # type: ignore
+            api_version=self._api_version,
+            sdk_moniker=USER_AGENT,
+            authentication_policy=authentication_policy,
+            polling_interval=5,  # TODO what is appropriate polling interval
+            **kwargs
+        )
+
+    @distributed_trace
+    def create_translation_job(self, batch, **kwargs):
+        # type: (List[BatchDocumentInput], **Any) -> JobStatusDetail
+        """
+
+        :param batch:
+        :type batch: List[~azure.ai.documenttranslation.BatchDocumentInput]
+        :return: JobStatusDetail
+        :rtype: JobStatusDetail
+        """
+
+        return self._client.document_translation.begin_submit_batch_request(
+            inputs=batch,
+            polling=True,
+            **kwargs
+        )
+
+    @distributed_trace
+    def get_job_status(self, job_id, **kwargs):
+        # type: (str, **Any) -> JobStatusDetail
+        """
+
+        :param job_id: guid id for job
+        :type job_id: str
+        :rtype: ~azure.ai.documenttranslation.JobStatusDetail
+        """
+
+        return self._client.document_translation.get_operation_status(job_id, **kwargs)
+
+    @distributed_trace
+    def cancel_job(self, job_id, **kwargs):
+        # type: (str, **Any) -> None
+        """
+
+        :param job_id: guid id for job
+        :type job_id: str
+        :rtype: None
+        """
+
+        self._client.document_translation.cancel_operation(job_id, **kwargs)
+
+    @distributed_trace
+    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
+        """
+        pass
+
+    @distributed_trace
+    def list_submitted_jobs(self, **kwargs):
+        # type: (**Any) -> ItemPaged[JobStatusDetail]
+        """
+
+        :keyword int results_per_page:
+        :keyword int skip:
+        :rtype: ~azure.core.polling.ItemPaged[JobStatusDetail]
+        """
+        return self._client.document_translation.get_operations(**kwargs)
+
+    @distributed_trace
+    def list_documents_statuses(self, job_id, **kwargs):
+        # type: (str, **Any) -> ItemPaged[DocumentStatusDetail]
+        """
+
+        :param job_id: guid id for job
+        :type job_id: str
+        :keyword int results_per_page:
+        :keyword int skip:
+        :rtype: ~azure.core.paging.ItemPaged[DocumentStatusDetail]
+        """
+
+        return self._client.document_translation.get_operation_documents_status(job_id, **kwargs)
+
+    @distributed_trace
+    def get_document_status(self, job_id, document_id, **kwargs):
+        # type: (str, str, **Any) -> DocumentStatusDetail
+        """
+
+        :param job_id: guid id for job
+        :type job_id: str
+        :param document_id: guid id for document
+        :type document_id: str
+        :rtype: ~azure.ai.documenttranslation.DocumentStatusDetail
+        """
+        return self._client.document_translation.get_document_status(job_id, document_id, **kwargs)
+
+    @distributed_trace
+    def get_supported_storage_sources(self, **kwargs):
+        # type: (**Any) -> List[str]
+        """
+
+        :rtype: List[str]
+        """
+        return self._client.document_translation.get_document_storage_source(**kwargs)
+
+    @distributed_trace
+    def get_supported_glossary_formats(self, **kwargs):
+        # type: (**Any) -> List[FileFormat]
+        """
+
+        :rtype: List[FileFormat]
+        """
+
+        return self._client.document_translation.get_glossary_formats(**kwargs)
+
+    @distributed_trace
+    def get_supported_document_formats(self, **kwargs):
+        # type: (**Any) -> List[FileFormat]
+        """
+
+        :rtype: List[FileFormat]
+        """
+
+        return self._client.document_translation.get_document_formats(**kwargs)

sdk/documenttranslation/azure-ai-documenttranslation/azure/ai/documenttranslation/_generated/__init__.py

@@ -0,0 +1,16 @@
+# coding=utf-8
+# --------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for license information.
+# Code generated by Microsoft (R) AutoRest Code Generator.
+# Changes may cause incorrect behavior and will be lost if the code is regenerated.
+# --------------------------------------------------------------------------
+
+from ._batch_document_translation_client import BatchDocumentTranslationClient
+__all__ = ['BatchDocumentTranslationClient']
+
+try:
+    from ._patch import patch_sdk  # type: ignore
+    patch_sdk()
+except ImportError:
+    pass

sdk/documenttranslation/azure-ai-documenttranslation/azure/ai/documenttranslation/_generated/_batch_document_translation_client.py

@@ -0,0 +1,67 @@
+# coding=utf-8
+# --------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for license information.
+# Code generated by Microsoft (R) AutoRest Code Generator.
+# Changes may cause incorrect behavior and will be lost if the code is regenerated.
+# --------------------------------------------------------------------------
+
+from typing import TYPE_CHECKING
+
+from azure.core import PipelineClient
+from msrest import Deserializer, Serializer
+
+if TYPE_CHECKING:
+    # pylint: disable=unused-import,ungrouped-imports
+    from typing import Any
+
+    from azure.core.credentials import TokenCredential
+
+from ._configuration import BatchDocumentTranslationClientConfiguration
+from .operations import DocumentTranslationOperations
+from . import models
+
+
+class BatchDocumentTranslationClient(object):
+    """BatchDocumentTranslationClient.
+
+    :ivar document_translation: DocumentTranslationOperations operations
+    :vartype document_translation: azure.ai.documenttranslation.operations.DocumentTranslationOperations
+    :param credential: Credential needed for the client to connect to Azure.
+    :type credential: ~azure.core.credentials.TokenCredential
+    :param endpoint: Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com).
+    :type endpoint: str
+    :keyword int polling_interval: Default waiting time between two polls for LRO operations if no Retry-After header is present.
+    """
+
+    def __init__(
+        self,
+        credential,  # type: "TokenCredential"
+        endpoint,  # type: str
+        **kwargs  # type: Any
+    ):
+        # type: (...) -> None
+        base_url = '{endpoint}/translator/text/batch/v1.0-preview.1'
+        self._config = BatchDocumentTranslationClientConfiguration(credential, endpoint, **kwargs)
+        self._client = PipelineClient(base_url=base_url, config=self._config, **kwargs)
+
+        client_models = {k: v for k, v in models.__dict__.items() if isinstance(v, type)}
+        self._serialize = Serializer(client_models)
+        self._serialize.client_side_validation = False
+        self._deserialize = Deserializer(client_models)
+
+        self.document_translation = DocumentTranslationOperations(
+            self._client, self._config, self._serialize, self._deserialize)
+
+    def close(self):
+        # type: () -> None
+        self._client.close()
+
+    def __enter__(self):
+        # type: () -> BatchDocumentTranslationClient
+        self._client.__enter__()
+        return self
+
+    def __exit__(self, *exc_details):
+        # type: (Any) -> None
+        self._client.__exit__(*exc_details)