diff --git a/sdk/translation/azure-ai-translation-document/CHANGELOG.md b/sdk/translation/azure-ai-translation-document/CHANGELOG.md index 5f035cf8118c..b457c194ffd0 100644 --- a/sdk/translation/azure-ai-translation-document/CHANGELOG.md +++ b/sdk/translation/azure-ai-translation-document/CHANGELOG.md @@ -1,15 +1,43 @@ # Release History -## 1.1.1 (Unreleased) +## 2.0.0 (2026-08-01) ### Features Added +- Added support for the `2026-03-01` service API version, which is now the default. +- Added image translation support: the `translate_text_within_image` keyword on `begin_translation` + for batch requests, and a `translate_text_within_image` keyword on `SingleDocumentTranslationClient.translate` + for single document requests. When enabled, each document's status also reports image scan usage. +- Added the `deployment_name` property to `TranslationTarget` and the `deployment_name` keyword to + `begin_translation` to specify the deployment name of the custom translation model for a batch + translation request. +- Added the `deployment_name` keyword to `SingleDocumentTranslationClient.translate` for single + document translation requests. +- Added the `deployment_name` property to `DocumentStatus`, exposing the deployment name of the + custom translation model used for the translation. +- Added image scan reporting to `DocumentStatus`: `image_characters_detected`, `images_charged`, + `total_image_scans_succeeded`, and `total_image_scans_failed`. +- Added image scan totals to `TranslationStatusSummary`: `total_image_scans_succeeded`, + `total_image_scans_failed`, and `total_images_charged`. +- Added the `BatchOptions` model for specifying batch translation options. + ### Breaking Changes -### Bugs Fixed +- Changed the default service API version from `2024-05-01` to `2026-03-01`. To keep the previous + behavior, pass `api_version="2024-05-01"` when constructing the client. +- Models are no longer re-exported from the top-level `azure.ai.translation.document` namespace and + must now be imported from `azure.ai.translation.document.models`. This affects `TranslationGlossary`, + `TranslationTarget`, `DocumentTranslationInput`, `TranslationStatus`, `DocumentStatus`, + `DocumentTranslationError`, `DocumentTranslationFileFormat`, and `StorageInputType`. For example, + replace `from azure.ai.translation.document import TranslationStatus` with + `from azure.ai.translation.document.models import TranslationStatus`. The clients + (`DocumentTranslationClient`, `SingleDocumentTranslationClient`), `DocumentTranslationApiVersion`, + and `DocumentTranslationLROPoller` remain available at the top level. ### Other Changes +- This version and all future versions will require Python 3.9+. Python 3.8 is no longer supported. + ## 1.1.0 (2024-11-15) ### Other Changes diff --git a/sdk/translation/azure-ai-translation-document/MANIFEST.in b/sdk/translation/azure-ai-translation-document/MANIFEST.in index 094e4c15616f..c2a75e806cf7 100644 --- a/sdk/translation/azure-ai-translation-document/MANIFEST.in +++ b/sdk/translation/azure-ai-translation-document/MANIFEST.in @@ -6,4 +6,3 @@ recursive-include samples *.py *.md include azure/__init__.py include azure/ai/__init__.py include azure/ai/translation/__init__.py -recursive-include doc *.rst diff --git a/sdk/translation/azure-ai-translation-document/README.md b/sdk/translation/azure-ai-translation-document/README.md index 345bbf7767ba..bb9635f756e1 100644 --- a/sdk/translation/azure-ai-translation-document/README.md +++ b/sdk/translation/azure-ai-translation-document/README.md @@ -30,10 +30,10 @@ _Azure SDK Python packages support for Python 2.7 has ended 01 January 2022. For Install the Azure Document Translation client library for Python with [pip][pip]: ```bash -pip install --pre azure-ai-translation-document +pip install azure-ai-translation-document ``` -> Note: This version of the client library defaults to the v2024-05-01 version of the service +> Note: This version of the client library defaults to the `2026-03-01` version of the service. #### Create a Translator resource @@ -179,7 +179,8 @@ poller = document_translation_client.begin_translation("", "< ```python import os from azure.core.credentials import AzureKeyCredential -from azure.ai.translation.document import DocumentTranslationClient, DocumentTranslationInput, TranslationTarget +from azure.ai.translation.document import DocumentTranslationClient +from azure.ai.translation.document.models import DocumentTranslationInput, TranslationTarget endpoint = os.environ["AZURE_DOCUMENT_TRANSLATION_ENDPOINT"] key = os.environ["AZURE_DOCUMENT_TRANSLATION_KEY"] @@ -302,7 +303,8 @@ Begin translating with documents in multiple source containers to multiple targe ```python import os from azure.core.credentials import AzureKeyCredential -from azure.ai.translation.document import DocumentTranslationClient, DocumentTranslationInput, TranslationTarget +from azure.ai.translation.document import DocumentTranslationClient +from azure.ai.translation.document.models import DocumentTranslationInput, TranslationTarget endpoint = os.environ["AZURE_DOCUMENT_TRANSLATION_ENDPOINT"] key = os.environ["AZURE_DOCUMENT_TRANSLATION_KEY"] diff --git a/sdk/translation/azure-ai-translation-document/_metadata.json b/sdk/translation/azure-ai-translation-document/_metadata.json new file mode 100644 index 000000000000..afebd739178c --- /dev/null +++ b/sdk/translation/azure-ai-translation-document/_metadata.json @@ -0,0 +1,6 @@ +{ + "apiVersion": "2026-03-01", + "apiVersions": { + "DocumentTranslation": "2026-03-01" + } +} \ No newline at end of file diff --git a/sdk/translation/azure-ai-translation-document/api.md b/sdk/translation/azure-ai-translation-document/api.md new file mode 100644 index 000000000000..5100f98a8b60 --- /dev/null +++ b/sdk/translation/azure-ai-translation-document/api.md @@ -0,0 +1,826 @@ +```py +namespace azure.ai.translation.document + + class azure.ai.translation.document.DocumentTranslationApiVersion(str, Enum, metaclass=CaseInsensitiveEnumMeta): + V2024_05_01 = "2024-05-01" + V2026_03_01 = "2026-03-01" + + + class azure.ai.translation.document.DocumentTranslationClient(DocumentTranslationClientOperationsMixin, GeneratedDocumentTranslationClient): implements ContextManager + + def __init__( + self, + endpoint: str, + credential: Union[AzureKeyCredential, TokenCredential], + *, + api_version: Union[str, DocumentTranslationApiVersion] = ..., + **kwargs: Any + ) -> None: ... + + @overload + def begin_translation( + self, + source_url: str, + target_url: str, + target_language: str, + *, + category_id: Optional[str] = ..., + deployment_name: Optional[str] = ..., + glossaries: Optional[List[TranslationGlossary]] = ..., + prefix: Optional[str] = ..., + source_language: Optional[str] = ..., + storage_type: Optional[Union[str, StorageInputType]] = ..., + suffix: Optional[str] = ..., + translate_text_within_image: Optional[bool] = ..., + **kwargs: Any + ) -> DocumentTranslationLROPoller[ItemPaged[DocumentStatus]]: ... + + @overload + def begin_translation( + self, + inputs: StartTranslationDetails, + **kwargs: Any + ) -> DocumentTranslationLROPoller[ItemPaged[DocumentStatus]]: ... + + @overload + def begin_translation( + self, + inputs: JSON, + **kwargs: Any + ) -> DocumentTranslationLROPoller[ItemPaged[DocumentStatus]]: ... + + @overload + def begin_translation( + self, + inputs: IO[bytes], + **kwargs: Any + ) -> DocumentTranslationLROPoller[ItemPaged[DocumentStatus]]: ... + + @overload + def begin_translation( + self, + inputs: List[DocumentTranslationInput], + **kwargs: Any + ) -> DocumentTranslationLROPoller[ItemPaged[DocumentStatus]]: ... + + @distributed_trace + def cancel_translation( + self, + translation_id: str, + **kwargs: Any + ) -> None: ... + + def close(self) -> None: ... + + @distributed_trace + def get_document_status( + self, + translation_id: str, + document_id: str, + **kwargs: Any + ) -> DocumentStatus: ... + + @distributed_trace + def get_supported_document_formats(self, **kwargs: Any) -> List[DocumentTranslationFileFormat]: ... + + @distributed_trace + def get_supported_glossary_formats(self, **kwargs: Any) -> List[DocumentTranslationFileFormat]: ... + + @distributed_trace + def get_translation_status( + self, + translation_id: str, + **kwargs: Any + ) -> TranslationStatus: ... + + @distributed_trace + def list_document_statuses( + self, + translation_id: str, + *, + created_after: Optional[Union[str, datetime]] = ..., + created_before: Optional[Union[str, datetime]] = ..., + document_ids: Optional[List[str]] = ..., + order_by: Optional[List[str]] = ..., + skip: Optional[int] = ..., + statuses: Optional[List[str]] = ..., + top: Optional[int] = ..., + **kwargs: Any + ) -> ItemPaged[DocumentStatus]: ... + + @distributed_trace + def list_translation_statuses( + self, + *, + created_after: Optional[Union[str, datetime]] = ..., + created_before: Optional[Union[str, datetime]] = ..., + order_by: Optional[List[str]] = ..., + skip: Optional[int] = ..., + statuses: Optional[List[str]] = ..., + top: Optional[int] = ..., + translation_ids: Optional[List[str]] = ..., + **kwargs: Any + ) -> ItemPaged[TranslationStatus]: ... + + def send_request( + self, + request: HttpRequest, + *, + stream: bool = False, + **kwargs: Any + ) -> HttpResponse: ... + + + class azure.ai.translation.document.DocumentTranslationLROPoller(LROPoller[PollingReturnType_co]): + property details: TranslationStatus # Read-only + property id: str # Read-only + + @classmethod + def from_continuation_token( + cls, + polling_method, + continuation_token, + **kwargs: Any + ): ... + + + class azure.ai.translation.document.SingleDocumentTranslationClient(SingleDocumentTranslationClientOperationsMixin, GeneratedSingleDocumentTranslationClient): implements ContextManager + + def __init__( + self, + endpoint: str, + credential: Union[AzureKeyCredential, TokenCredential], + *, + api_version: Union[str, DocumentTranslationApiVersion] = ..., + **kwargs: Any + ) -> None: ... + + def close(self) -> None: ... + + def send_request( + self, + request: HttpRequest, + *, + stream: bool = False, + **kwargs: Any + ) -> HttpResponse: ... + + @overload + def translate( + self, + body: DocumentTranslateContent, + *, + allow_fallback: Optional[bool] = ..., + category: Optional[str] = ..., + deployment_name: Optional[str] = ..., + source_language: Optional[str] = ..., + target_language: str, + translate_text_within_image: Optional[bool] = ..., + **kwargs: Any + ) -> Iterator[bytes]: ... + + @overload + def translate( + self, + body: JSON, + *, + allow_fallback: Optional[bool] = ..., + category: Optional[str] = ..., + deployment_name: Optional[str] = ..., + source_language: Optional[str] = ..., + target_language: str, + translate_text_within_image: Optional[bool] = ..., + **kwargs: Any + ) -> Iterator[bytes]: ... + + +namespace azure.ai.translation.document.aio + + class azure.ai.translation.document.aio.AsyncDocumentTranslationLROPoller(AsyncLROPoller[PollingReturnType_co]): + property details: TranslationStatus # Read-only + property id: str # Read-only + + @classmethod + def from_continuation_token( + cls, + polling_method, + continuation_token, + **kwargs + ): ... + + + class azure.ai.translation.document.aio.DocumentTranslationClient(DocumentTranslationClientOperationsMixin, GeneratedDocumentTranslationClient): implements AsyncContextManager + + def __init__( + self, + endpoint: str, + credential: Union[AzureKeyCredential, AsyncTokenCredential], + *, + api_version: Union[str, DocumentTranslationApiVersion] = ..., + **kwargs: Any + ) -> None: ... + + @overload + async def begin_translation( + self, + source_url: str, + target_url: str, + target_language: str, + *, + category_id: Optional[str] = ..., + deployment_name: Optional[str] = ..., + glossaries: Optional[List[TranslationGlossary]] = ..., + prefix: Optional[str] = ..., + source_language: Optional[str] = ..., + storage_type: Optional[Union[str, StorageInputType]] = ..., + suffix: Optional[str] = ..., + translate_text_within_image: Optional[bool] = ..., + **kwargs: Any + ) -> AsyncDocumentTranslationLROPoller[AsyncItemPaged[DocumentStatus]]: ... + + @overload + async def begin_translation( + self, + inputs: StartTranslationDetails, + **kwargs: Any + ) -> AsyncDocumentTranslationLROPoller[AsyncItemPaged[DocumentStatus]]: ... + + @overload + async def begin_translation( + self, + inputs: JSON, + **kwargs: Any + ) -> AsyncDocumentTranslationLROPoller[AsyncItemPaged[DocumentStatus]]: ... + + @overload + async def begin_translation( + self, + inputs: IO[bytes], + **kwargs: Any + ) -> AsyncDocumentTranslationLROPoller[AsyncItemPaged[DocumentStatus]]: ... + + @overload + async def begin_translation( + self, + inputs: List[DocumentTranslationInput], + **kwargs: Any + ) -> AsyncDocumentTranslationLROPoller[AsyncItemPaged[DocumentStatus]]: ... + + @distributed_trace_async + async def cancel_translation( + self, + translation_id: str, + **kwargs: Any + ) -> TranslationStatus: ... + + async def close(self) -> None: ... + + @distributed_trace_async + async def get_document_status( + self, + translation_id: str, + document_id: str, + **kwargs: Any + ) -> DocumentStatus: ... + + @distributed_trace_async + async def get_supported_document_formats(self, **kwargs: Any) -> List[DocumentTranslationFileFormat]: ... + + @distributed_trace_async + async def get_supported_glossary_formats(self, **kwargs: Any) -> List[DocumentTranslationFileFormat]: ... + + @distributed_trace_async + async def get_translation_status( + self, + translation_id: str, + **kwargs: Any + ) -> TranslationStatus: ... + + @distributed_trace + def list_document_statuses( + self, + translation_id: str, + *, + created_after: Optional[Union[str, datetime]] = ..., + created_before: Optional[Union[str, datetime]] = ..., + document_ids: Optional[List[str]] = ..., + order_by: Optional[List[str]] = ..., + skip: Optional[int] = ..., + statuses: Optional[List[str]] = ..., + top: Optional[int] = ..., + **kwargs: Any + ) -> AsyncItemPaged[DocumentStatus]: ... + + @distributed_trace + def list_translation_statuses( + self, + *, + created_after: Optional[Union[str, datetime]] = ..., + created_before: Optional[Union[str, datetime]] = ..., + order_by: Optional[List[str]] = ..., + skip: Optional[int] = ..., + statuses: Optional[List[str]] = ..., + top: Optional[int] = ..., + translation_ids: Optional[List[str]] = ..., + **kwargs: Any + ) -> AsyncItemPaged[TranslationStatus]: ... + + def send_request( + self, + request: HttpRequest, + *, + stream: bool = False, + **kwargs: Any + ) -> Awaitable[AsyncHttpResponse]: ... + + + class azure.ai.translation.document.aio.SingleDocumentTranslationClient(SingleDocumentTranslationClientOperationsMixin, GeneratedSingleDocumentTranslationClient): implements AsyncContextManager + + def __init__( + self, + endpoint: str, + credential: Union[AzureKeyCredential, AsyncTokenCredential], + *, + api_version: Union[str, DocumentTranslationApiVersion] = ..., + **kwargs: Any + ) -> None: ... + + async def close(self) -> None: ... + + def send_request( + self, + request: HttpRequest, + *, + stream: bool = False, + **kwargs: Any + ) -> Awaitable[AsyncHttpResponse]: ... + + @overload + async def translate( + self, + body: DocumentTranslateContent, + *, + allow_fallback: Optional[bool] = ..., + category: Optional[str] = ..., + deployment_name: Optional[str] = ..., + source_language: Optional[str] = ..., + target_language: str, + translate_text_within_image: Optional[bool] = ..., + **kwargs: Any + ) -> AsyncIterator[bytes]: ... + + @overload + async def translate( + self, + body: JSON, + *, + allow_fallback: Optional[bool] = ..., + category: Optional[str] = ..., + deployment_name: Optional[str] = ..., + source_language: Optional[str] = ..., + target_language: str, + translate_text_within_image: Optional[bool] = ..., + **kwargs: Any + ) -> AsyncIterator[bytes]: ... + + +namespace azure.ai.translation.document.models + + class azure.ai.translation.document.models.BatchOptions(_Model): + translate_text_within_image: Optional[bool] + + @overload + def __init__( + self, + *, + translate_text_within_image: Optional[bool] = ... + ) -> None: ... + + @overload + def __init__(self, mapping: Mapping[str, Any]) -> None: ... + + + class azure.ai.translation.document.models.DocumentBatch(_Model): + source: SourceInput + storage_type: Optional[Union[str, StorageInputType]] + targets: list[TranslationTarget] + + @overload + def __init__( + self, + *, + source: SourceInput, + storage_type: Optional[Union[str, StorageInputType]] = ..., + targets: list[TranslationTarget] + ) -> None: ... + + @overload + def __init__(self, mapping: Mapping[str, Any]) -> None: ... + + + class azure.ai.translation.document.models.DocumentFilter(_Model): + prefix: Optional[str] + suffix: Optional[str] + + @overload + def __init__( + self, + *, + prefix: Optional[str] = ..., + suffix: Optional[str] = ... + ) -> None: ... + + @overload + def __init__(self, mapping: Mapping[str, Any]) -> None: ... + + + class azure.ai.translation.document.models.DocumentStatus(GeneratedDocumentStatus): + characters_charged: Optional[int] + created_on: datetime + deployment_name: Optional[str] + error: Optional[DocumentTranslationError] + id: str + image_characters_detected: Optional[int] + images_charged: Optional[int] + last_updated_on: datetime + source_document_url: str + status: Union[str, Status] + total_image_scans_failed: Optional[int] + total_image_scans_succeeded: Optional[int] + translated_document_url: Optional[str] + translated_to: str + translation_progress: float + + @overload + def __init__( + self, + *, + characters_charged: Optional[int] = ..., + created_on: datetime, + deployment_name: Optional[str] = ..., + error: Optional[DocumentTranslationError] = ..., + id: str, + image_characters_detected: Optional[int] = ..., + images_charged: Optional[int] = ..., + last_updated_on: datetime, + source_document_url: str, + status: Union[str, Status], + total_image_scans_failed: Optional[int] = ..., + total_image_scans_succeeded: Optional[int] = ..., + translated_document_url: Optional[str] = ..., + translated_to: str, + translation_progress: float + ): ... + + @overload + def __init__(self, mapping: Mapping[str, Any]): ... + + + class azure.ai.translation.document.models.DocumentTranslateContent(_Model): + document: Union[str, bytes, IO[str], IO[bytes], tuple[Optional[str], Union[str, bytes, IO[str], IO[bytes]]], tuple[Optional[str], Union[str, bytes, IO[str], IO[bytes]], Optional[str]]] + glossary: Optional[list[Union[str, bytes, IO[str], IO[bytes], tuple[Optional[str], Union[str, bytes, IO[str], IO[bytes]]], tuple[Optional[str], Union[str, bytes, IO[str], IO[bytes]], Optional[str]]]]] + + @overload + def __init__( + self, + *, + document: FileType, + glossary: Optional[list[FileType]] = ... + ) -> None: ... + + @overload + def __init__(self, mapping: Mapping[str, Any]) -> None: ... + + + class azure.ai.translation.document.models.DocumentTranslationError(_Model): + code: Union[str, TranslationErrorCode] + inner_error: Optional[InnerTranslationError] + message: str + target: Optional[str] + + @overload + def __init__( + self, + *, + code: Union[str, TranslationErrorCode], + inner_error: Optional[InnerTranslationError] = ..., + message: str + ) -> None: ... + + @overload + def __init__(self, mapping: Mapping[str, Any]) -> None: ... + + + class azure.ai.translation.document.models.DocumentTranslationFileFormat(_Model): + content_types: list[str] + default_format_version: Optional[str] + file_extensions: list[str] + file_format: str + format_versions: Optional[list[str]] + type: Optional[Union[str, FileFormatType]] + + @overload + def __init__( + self, + *, + content_types: list[str], + default_format_version: Optional[str] = ..., + file_extensions: list[str], + file_format: str, + format_versions: Optional[list[str]] = ..., + type: Optional[Union[str, FileFormatType]] = ... + ) -> None: ... + + @overload + def __init__(self, mapping: Mapping[str, Any]) -> None: ... + + + class azure.ai.translation.document.models.DocumentTranslationInput: + prefix: Optional[str] + source_language: Optional[str] + source_url: str + storage_source: Optional[str] + storage_type: Optional[Union[str, StorageInputType]] + suffix: Optional[str] + targets: List[TranslationTarget] + + def __init__( + self, + source_url: str, + targets: List[TranslationTarget], + *, + prefix: Optional[str] = ..., + source_language: Optional[str] = ..., + storage_source: Optional[str] = ..., + storage_type: Optional[Union[str, StorageInputType]] = ..., + suffix: Optional[str] = ... + ) -> None: ... + + def __repr__(self) -> str: ... + + + class azure.ai.translation.document.models.FileFormatType(str, Enum, metaclass=CaseInsensitiveEnumMeta): + DOCUMENT = "Document" + GLOSSARY = "Glossary" + + + class azure.ai.translation.document.models.InnerTranslationError(_Model): + code: str + inner_error: Optional[InnerTranslationError] + message: str + target: Optional[str] + + @overload + def __init__( + self, + *, + code: str, + inner_error: Optional[InnerTranslationError] = ..., + message: str + ) -> None: ... + + @overload + def __init__(self, mapping: Mapping[str, Any]) -> None: ... + + + class azure.ai.translation.document.models.SourceInput(_Model): + filter: Optional[DocumentFilter] + language: Optional[str] + source_url: str + storage_source: Optional[Union[str, TranslationStorageSource]] + + @overload + def __init__( + self, + *, + filter: Optional[DocumentFilter] = ..., + language: Optional[str] = ..., + source_url: str, + storage_source: Optional[Union[str, TranslationStorageSource]] = ... + ) -> None: ... + + @overload + def __init__(self, mapping: Mapping[str, Any]) -> None: ... + + + class azure.ai.translation.document.models.StartTranslationDetails(_Model): + inputs: list[DocumentBatch] + options: Optional[BatchOptions] + + @overload + def __init__( + self, + *, + inputs: list[DocumentBatch], + options: Optional[BatchOptions] = ... + ) -> None: ... + + @overload + def __init__(self, mapping: Mapping[str, Any]) -> None: ... + + + class azure.ai.translation.document.models.Status(str, Enum, metaclass=CaseInsensitiveEnumMeta): + CANCELED = "Cancelled" + CANCELING = "Cancelling" + FAILED = "Failed" + NOT_STARTED = "NotStarted" + RUNNING = "Running" + SUCCEEDED = "Succeeded" + VALIDATION_FAILED = "ValidationFailed" + + + class azure.ai.translation.document.models.StorageInputType(str, Enum, metaclass=CaseInsensitiveEnumMeta): + FILE = "File" + FOLDER = "Folder" + + + class azure.ai.translation.document.models.TranslationErrorCode(str, Enum, metaclass=CaseInsensitiveEnumMeta): + INTERNAL_SERVER_ERROR = "InternalServerError" + INVALID_ARGUMENT = "InvalidArgument" + INVALID_REQUEST = "InvalidRequest" + REQUEST_RATE_TOO_HIGH = "RequestRateTooHigh" + RESOURCE_NOT_FOUND = "ResourceNotFound" + SERVICE_UNAVAILABLE = "ServiceUnavailable" + UNAUTHORIZED = "Unauthorized" + + + class azure.ai.translation.document.models.TranslationGlossary(GeneratedTranslationGlossary): + file_format: str + format_version: Optional[str] + glossary_url: str + storage_source: Optional[Union[str, TranslationStorageSource]] + + @overload + def __init__( + self, + glossary_url: str, + file_format: str, + *, + format_version: Optional[str] = ..., + storage_source: Optional[Union[str, TranslationStorageSource]] = ... + ): ... + + @overload + def __init__(self, mapping: Mapping[str, Any]): ... + + + class azure.ai.translation.document.models.TranslationStatus(GeneratedTranslationStatus): + created_on: datetime + error: Optional[DocumentTranslationError] + id: str + last_updated_on: datetime + status: Union[str, Status] + summary: TranslationStatusSummary + + def __getattr__(self, name: str) -> Any: ... + + @overload + def __init__( + self, + *, + created_on: datetime, + error: Optional[DocumentTranslationError] = ..., + id: str, + last_updated_on: datetime, + status: Union[str, Status], + summary: TranslationStatusSummary + ): ... + + @overload + def __init__(self, mapping: Mapping[str, Any]): ... + + + class azure.ai.translation.document.models.TranslationStatusSummary(_Model): + canceled: int + failed: int + in_progress: int + not_yet_started: int + success: int + total: int + total_characters_charged: int + total_image_scans_failed: Optional[int] + total_image_scans_succeeded: Optional[int] + total_images_charged: Optional[int] + + @overload + def __init__( + self, + *, + canceled: int, + failed: int, + in_progress: int, + not_yet_started: int, + success: int, + total: int, + total_characters_charged: int, + total_image_scans_failed: Optional[int] = ..., + total_image_scans_succeeded: Optional[int] = ..., + total_images_charged: Optional[int] = ... + ) -> None: ... + + @overload + def __init__(self, mapping: Mapping[str, Any]) -> None: ... + + + class azure.ai.translation.document.models.TranslationStorageSource(str, Enum, metaclass=CaseInsensitiveEnumMeta): + AZURE_BLOB = "AzureBlob" + + + class azure.ai.translation.document.models.TranslationTarget(GeneratedTranslationTarget): + property category_id: Optional[str] + category_id: str + deployment_name: Optional[str] + glossaries: Optional[List[TranslationGlossary]] + language: str + storage_source: Optional[Union[str, TranslationStorageSource]] + target_url: str + + @overload + def __init__( + self, + target_url: str, + language: str, + *, + category_id: Optional[str] = ..., + deployment_name: Optional[str] = ..., + glossaries: Optional[List[TranslationGlossary]] = ..., + storage_source: Optional[Union[str, TranslationStorageSource]] = ... + ): ... + + @overload + def __init__(self, mapping: Mapping[str, Any]): ... + + +namespace azure.ai.translation.document.types + + class azure.ai.translation.document.types.BatchOptions(TypedDict, total=False): + key "translateTextWithinImage": bool + translate_text_within_image: bool + + + class azure.ai.translation.document.types.DocumentBatch(TypedDict, total=False): + key "source": Required[SourceInput] + key "storageType": Union[str, StorageInputType] + key "targets": Required[list[TranslationTarget]] + source: SourceInput + storage_type: Union[str, StorageInputType] + targets: list[TranslationTarget] + + + class azure.ai.translation.document.types.DocumentFilter(TypedDict, total=False): + key "prefix": str + key "suffix": str + prefix: str + suffix: str + + + class azure.ai.translation.document.types.DocumentTranslateContent(TypedDict, total=False): + key "document": Required[Union[str, bytes, IO[str], IO[bytes], tuple[Optional[str], Union[str, bytes, IO[str], IO[bytes]]], tuple[Optional[str], Union[str, bytes, IO[str], IO[bytes]], Optional[str]]]] + document: FileType + glossary: list[Union[str, bytes, IO[str], IO[bytes], tuple[Optional[str], Union[str, bytes, IO[str], IO[bytes]]], tuple[Optional[str], Union[str, bytes, IO[str], IO[bytes]], Optional[str]]]] + + + class azure.ai.translation.document.types.SourceInput(TypedDict, total=False): + key "filter": ForwardRef('DocumentFilter', module='types') + key "language": str + key "sourceUrl": Required[str] + key "storageSource": Union[str, TranslationStorageSource] + filter: DocumentFilter + language: str + source_url: str + storage_source: Union[str, TranslationStorageSource] + + + class azure.ai.translation.document.types.StartTranslationDetails(TypedDict, total=False): + key "inputs": Required[list[DocumentBatch]] + key "options": ForwardRef('BatchOptions', module='types') + inputs: list[DocumentBatch] + options: BatchOptions + + + class azure.ai.translation.document.types.TranslationGlossary(TypedDict, total=False): + key "format": Required[str] + key "glossaryUrl": Required[str] + key "storageSource": Union[str, TranslationStorageSource] + key "version": str + file_format: str + format_version: str + glossary_url: str + storage_source: Union[str, TranslationStorageSource] + + + class azure.ai.translation.document.types.TranslationTarget(TypedDict, total=False): + key "category": str + key "deploymentName": str + key "language": Required[str] + key "storageSource": Union[str, TranslationStorageSource] + key "targetUrl": Required[str] + category: str + deployment_name: str + glossaries: list[TranslationGlossary] + language: str + storage_source: Union[str, TranslationStorageSource] + target_url: str + + +``` \ No newline at end of file diff --git a/sdk/translation/azure-ai-translation-document/api.metadata.yml b/sdk/translation/azure-ai-translation-document/api.metadata.yml new file mode 100644 index 000000000000..18b51079eba7 --- /dev/null +++ b/sdk/translation/azure-ai-translation-document/api.metadata.yml @@ -0,0 +1,3 @@ +apiMdSha256: 57f8bcee3f3f83bd54368f76eb9e30944fea82e1caf2de2e1f561e4f97049f24 +parserVersion: 0.3.30 +pythonVersion: 3.13.14 diff --git a/sdk/translation/azure-ai-translation-document/apiview-properties.json b/sdk/translation/azure-ai-translation-document/apiview-properties.json new file mode 100644 index 000000000000..2511ee505393 --- /dev/null +++ b/sdk/translation/azure-ai-translation-document/apiview-properties.json @@ -0,0 +1,39 @@ +{ + "CrossLanguagePackageId": "DocumentTranslation", + "CrossLanguageDefinitionId": { + "azure.ai.translation.document.models.BatchOptions": "DocumentTranslation.BatchOptions", + "azure.ai.translation.document.models.DocumentBatch": "DocumentTranslation.BatchRequest", + "azure.ai.translation.document.models.DocumentFilter": "DocumentTranslation.DocumentFilter", + "azure.ai.translation.document.models.DocumentStatus": "DocumentTranslation.DocumentStatus", + "azure.ai.translation.document.models.DocumentTranslateContent": "DocumentTranslation.DocumentTranslateContent", + "azure.ai.translation.document.models.DocumentTranslationError": "DocumentTranslation.TranslationError", + "azure.ai.translation.document.models.DocumentTranslationFileFormat": "DocumentTranslation.FileFormat", + "azure.ai.translation.document.models.InnerTranslationError": "DocumentTranslation.InnerTranslationError", + "azure.ai.translation.document.models.SourceInput": "DocumentTranslation.SourceInput", + "azure.ai.translation.document.models.StartTranslationDetails": "DocumentTranslation.StartTranslationDetails", + "azure.ai.translation.document.models.TranslationGlossary": "DocumentTranslation.Glossary", + "azure.ai.translation.document.models.TranslationStatus": "DocumentTranslation.TranslationStatus", + "azure.ai.translation.document.models.TranslationStatusSummary": "DocumentTranslation.StatusSummary", + "azure.ai.translation.document.models.TranslationTarget": "DocumentTranslation.TargetInput", + "azure.ai.translation.document.models.Status": "DocumentTranslation.Status", + "azure.ai.translation.document.models.TranslationErrorCode": "DocumentTranslation.TranslationErrorCode", + "azure.ai.translation.document.models.TranslationStorageSource": "DocumentTranslation.StorageSource", + "azure.ai.translation.document.models.StorageInputType": "DocumentTranslation.StorageInputType", + "azure.ai.translation.document.models.FileFormatType": "DocumentTranslation.FileFormatType", + "azure.ai.translation.document.DocumentTranslationClient.begin_translation": "ClientCustomizations.DocumentTranslationClient.startTranslation", + "azure.ai.translation.document.aio.DocumentTranslationClient.begin_translation": "ClientCustomizations.DocumentTranslationClient.startTranslation", + "azure.ai.translation.document.DocumentTranslationClient.list_translation_statuses": "ClientCustomizations.DocumentTranslationClient.getTranslationsStatus", + "azure.ai.translation.document.aio.DocumentTranslationClient.list_translation_statuses": "ClientCustomizations.DocumentTranslationClient.getTranslationsStatus", + "azure.ai.translation.document.DocumentTranslationClient.get_document_status": "ClientCustomizations.DocumentTranslationClient.getDocumentStatus", + "azure.ai.translation.document.aio.DocumentTranslationClient.get_document_status": "ClientCustomizations.DocumentTranslationClient.getDocumentStatus", + "azure.ai.translation.document.DocumentTranslationClient.get_translation_status": "ClientCustomizations.DocumentTranslationClient.getTranslationStatus", + "azure.ai.translation.document.aio.DocumentTranslationClient.get_translation_status": "ClientCustomizations.DocumentTranslationClient.getTranslationStatus", + "azure.ai.translation.document.DocumentTranslationClient.cancel_translation": "ClientCustomizations.DocumentTranslationClient.cancelTranslation", + "azure.ai.translation.document.aio.DocumentTranslationClient.cancel_translation": "ClientCustomizations.DocumentTranslationClient.cancelTranslation", + "azure.ai.translation.document.DocumentTranslationClient.list_document_statuses": "ClientCustomizations.DocumentTranslationClient.getDocumentsStatus", + "azure.ai.translation.document.aio.DocumentTranslationClient.list_document_statuses": "ClientCustomizations.DocumentTranslationClient.getDocumentsStatus", + "azure.ai.translation.document.SingleDocumentTranslationClient.translate": "ClientCustomizations.SingleDocumentTranslationClient.documentTranslate", + "azure.ai.translation.document.aio.SingleDocumentTranslationClient.translate": "ClientCustomizations.SingleDocumentTranslationClient.documentTranslate" + }, + "CrossLanguageVersion": "dad507433880" +} \ No newline at end of file diff --git a/sdk/translation/azure-ai-translation-document/assets.json b/sdk/translation/azure-ai-translation-document/assets.json index cda670f2d9e0..2accda79ccdc 100644 --- a/sdk/translation/azure-ai-translation-document/assets.json +++ b/sdk/translation/azure-ai-translation-document/assets.json @@ -2,5 +2,5 @@ "AssetsRepo": "Azure/azure-sdk-assets", "AssetsRepoPrefixPath": "python", "TagPrefix": "python/translation/azure-ai-translation-document", - "Tag": "python/translation/azure-ai-translation-document_c043fc2ede" + "Tag": "python/translation/azure-ai-translation-document_6c2363121f" } diff --git a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/__init__.py b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/__init__.py index d4b4d4d35fa9..1731c5d4d5ee 100644 --- a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/__init__.py +++ b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/__init__.py @@ -5,40 +5,30 @@ # Code generated by Microsoft (R) Python Code Generator. # Changes may cause incorrect behavior and will be lost if the code is regenerated. # -------------------------------------------------------------------------- +# pylint: disable=wrong-import-position -from ._patch import DocumentTranslationClient -from ._client import SingleDocumentTranslationClient +from typing import TYPE_CHECKING + +if TYPE_CHECKING: + from ._patch import * # pylint: disable=unused-wildcard-import + +from ._client import DocumentTranslationClient # type: ignore +from ._client import SingleDocumentTranslationClient # type: ignore from ._version import VERSION __version__ = VERSION - -from ._patch import DocumentTranslationApiVersion -from ._patch import DocumentTranslationLROPoller -from ._patch import TranslationGlossary -from ._patch import TranslationTarget -from ._patch import DocumentTranslationInput -from ._patch import TranslationStatus -from ._patch import DocumentStatus -from ._patch import DocumentTranslationError -from ._patch import DocumentTranslationFileFormat -from ._patch import StorageInputType +try: + from ._patch import __all__ as _patch_all + from ._patch import * +except ImportError: + _patch_all = [] from ._patch import patch_sdk as _patch_sdk __all__ = [ - "DocumentTranslationApiVersion", - "DocumentTranslationLROPoller", - "TranslationGlossary", - "TranslationTarget", - "DocumentTranslationInput", - "TranslationStatus", - "DocumentStatus", - "DocumentTranslationError", - "DocumentTranslationFileFormat", - "StorageInputType", "DocumentTranslationClient", "SingleDocumentTranslationClient", ] - +__all__.extend([p for p in _patch_all if p not in __all__]) # pyright: ignore _patch_sdk() diff --git a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_client.py b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_client.py index 36fb2051321e..40905d648cdf 100644 --- a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_client.py +++ b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_client.py @@ -7,8 +7,8 @@ # -------------------------------------------------------------------------- from copy import deepcopy +import sys from typing import Any, TYPE_CHECKING, Union -from typing_extensions import Self from azure.core import PipelineClient from azure.core.credentials import AzureKeyCredential @@ -16,24 +16,30 @@ from azure.core.rest import HttpRequest, HttpResponse from ._configuration import DocumentTranslationClientConfiguration, SingleDocumentTranslationClientConfiguration -from ._operations import DocumentTranslationClientOperationsMixin, SingleDocumentTranslationClientOperationsMixin -from ._serialization import Deserializer, Serializer +from ._operations import _DocumentTranslationClientOperationsMixin, _SingleDocumentTranslationClientOperationsMixin +from ._utils.serialization import Deserializer, Serializer + +if sys.version_info >= (3, 11): + from typing import Self +else: + from typing_extensions import Self # type: ignore if TYPE_CHECKING: from azure.core.credentials import TokenCredential -class DocumentTranslationClient(DocumentTranslationClientOperationsMixin): +class DocumentTranslationClient(_DocumentTranslationClientOperationsMixin): """DocumentTranslationClient. :param endpoint: Supported document Translation endpoint, protocol and hostname, for example: https://{TranslatorResourceName}.cognitiveservices.azure.com/translator. Required. :type endpoint: str - :param credential: Credential used to authenticate requests to the service. Is either a - AzureKeyCredential type or a TokenCredential type. Required. + :param credential: Credential used to authenticate requests to the service. Is either a key + credential type or a token credential type. Required. :type credential: ~azure.core.credentials.AzureKeyCredential or ~azure.core.credentials.TokenCredential - :keyword api_version: The API version to use for this operation. Default value is "2024-05-01". + :keyword api_version: The API version to use for this operation. Known values are "2026-03-01" + and None. Default value is None. If not set, the operation's default API version will be used. Note that overriding this default value may result in unsupported behavior. :paramtype api_version: str :keyword int polling_interval: Default waiting time between two polls for LRO operations if no @@ -43,6 +49,7 @@ class DocumentTranslationClient(DocumentTranslationClientOperationsMixin): def __init__(self, endpoint: str, credential: Union[AzureKeyCredential, "TokenCredential"], **kwargs: Any) -> None: _endpoint = "{endpoint}/translator" self._config = DocumentTranslationClientConfiguration(endpoint=endpoint, credential=credential, **kwargs) + _policies = kwargs.pop("policies", None) if _policies is None: _policies = [ @@ -103,17 +110,18 @@ def __exit__(self, *exc_details: Any) -> None: self._client.__exit__(*exc_details) -class SingleDocumentTranslationClient(SingleDocumentTranslationClientOperationsMixin): +class SingleDocumentTranslationClient(_SingleDocumentTranslationClientOperationsMixin): """SingleDocumentTranslationClient. :param endpoint: Supported document Translation endpoint, protocol and hostname, for example: https://{TranslatorResourceName}.cognitiveservices.azure.com/translator. Required. :type endpoint: str - :param credential: Credential used to authenticate requests to the service. Is either a - AzureKeyCredential type or a TokenCredential type. Required. + :param credential: Credential used to authenticate requests to the service. Is either a key + credential type or a token credential type. Required. :type credential: ~azure.core.credentials.AzureKeyCredential or ~azure.core.credentials.TokenCredential - :keyword api_version: The API version to use for this operation. Default value is "2024-05-01". + :keyword api_version: The API version to use for this operation. Known values are "2026-03-01" + and None. Default value is None. If not set, the operation's default API version will be used. Note that overriding this default value may result in unsupported behavior. :paramtype api_version: str """ @@ -121,6 +129,7 @@ class SingleDocumentTranslationClient(SingleDocumentTranslationClientOperationsM def __init__(self, endpoint: str, credential: Union[AzureKeyCredential, "TokenCredential"], **kwargs: Any) -> None: _endpoint = "{endpoint}/translator" self._config = SingleDocumentTranslationClientConfiguration(endpoint=endpoint, credential=credential, **kwargs) + _policies = kwargs.pop("policies", None) if _policies is None: _policies = [ diff --git a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_configuration.py b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_configuration.py index df7480f5c50e..ce489f7137a2 100644 --- a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_configuration.py +++ b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_configuration.py @@ -26,17 +26,18 @@ class DocumentTranslationClientConfiguration: # pylint: disable=too-many-instan :param endpoint: Supported document Translation endpoint, protocol and hostname, for example: https://{TranslatorResourceName}.cognitiveservices.azure.com/translator. Required. :type endpoint: str - :param credential: Credential used to authenticate requests to the service. Is either a - AzureKeyCredential type or a TokenCredential type. Required. + :param credential: Credential used to authenticate requests to the service. Is either a key + credential type or a token credential type. Required. :type credential: ~azure.core.credentials.AzureKeyCredential or ~azure.core.credentials.TokenCredential - :keyword api_version: The API version to use for this operation. Default value is "2024-05-01". + :keyword api_version: The API version to use for this operation. Known values are "2026-03-01" + and None. Default value is None. If not set, the operation's default API version will be used. Note that overriding this default value may result in unsupported behavior. :paramtype api_version: str """ def __init__(self, endpoint: str, credential: Union[AzureKeyCredential, "TokenCredential"], **kwargs: Any) -> None: - api_version: str = kwargs.pop("api_version", "2024-05-01") + api_version: str = kwargs.pop("api_version", "2026-03-01") if endpoint is None: raise ValueError("Parameter 'endpoint' must not be None.") @@ -81,17 +82,18 @@ class SingleDocumentTranslationClientConfiguration: # pylint: disable=too-many- :param endpoint: Supported document Translation endpoint, protocol and hostname, for example: https://{TranslatorResourceName}.cognitiveservices.azure.com/translator. Required. :type endpoint: str - :param credential: Credential used to authenticate requests to the service. Is either a - AzureKeyCredential type or a TokenCredential type. Required. + :param credential: Credential used to authenticate requests to the service. Is either a key + credential type or a token credential type. Required. :type credential: ~azure.core.credentials.AzureKeyCredential or ~azure.core.credentials.TokenCredential - :keyword api_version: The API version to use for this operation. Default value is "2024-05-01". + :keyword api_version: The API version to use for this operation. Known values are "2026-03-01" + and None. Default value is None. If not set, the operation's default API version will be used. Note that overriding this default value may result in unsupported behavior. :paramtype api_version: str """ def __init__(self, endpoint: str, credential: Union[AzureKeyCredential, "TokenCredential"], **kwargs: Any) -> None: - api_version: str = kwargs.pop("api_version", "2024-05-01") + api_version: str = kwargs.pop("api_version", "2026-03-01") if endpoint is None: raise ValueError("Parameter 'endpoint' must not be None.") diff --git a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_operations/__init__.py b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_operations/__init__.py index 9e327bba3bf1..e08ac6325259 100644 --- a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_operations/__init__.py +++ b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_operations/__init__.py @@ -5,16 +5,20 @@ # Code generated by Microsoft (R) Python Code Generator. # Changes may cause incorrect behavior and will be lost if the code is regenerated. # -------------------------------------------------------------------------- +# pylint: disable=wrong-import-position -from ._patch import DocumentTranslationClientOperationsMixin -from ._patch import SingleDocumentTranslationClientOperationsMixin +from typing import TYPE_CHECKING +if TYPE_CHECKING: + from ._patch import * # pylint: disable=unused-wildcard-import -from ._patch import patch_sdk as _patch_sdk +from ._operations import _DocumentTranslationClientOperationsMixin # type: ignore # pylint: disable=unused-import +from ._operations import _SingleDocumentTranslationClientOperationsMixin # type: ignore # pylint: disable=unused-import -__all__ = [ - "DocumentTranslationClientOperationsMixin", - "SingleDocumentTranslationClientOperationsMixin", -] +from ._patch import __all__ as _patch_all +from ._patch import * +from ._patch import patch_sdk as _patch_sdk +__all__ = [] +__all__.extend([p for p in _patch_all if p not in __all__]) # pyright: ignore _patch_sdk() diff --git a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_operations/_operations.py b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_operations/_operations.py index e86f7ccb4210..1ff1486f9bb6 100644 --- a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_operations/_operations.py +++ b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_operations/_operations.py @@ -6,13 +6,14 @@ # Code generated by Microsoft (R) Python Code Generator. # Changes may cause incorrect behavior and will be lost if the code is regenerated. # -------------------------------------------------------------------------- +from collections.abc import MutableMapping import datetime from io import IOBase import json -import sys -from typing import Any, Callable, Dict, IO, Iterable, Iterator, List, Optional, TypeVar, Union, cast, overload +from typing import Any, Callable, IO, Iterator, Optional, TypeVar, Union, cast, overload import urllib.parse +from azure.core import PipelineClient from azure.core.exceptions import ( ClientAuthenticationError, HttpResponseError, @@ -31,37 +32,26 @@ from azure.core.tracing.decorator import distributed_trace from azure.core.utils import case_insensitive_dict -from .. import _model_base, models as _models -from .._model_base import SdkJSONEncoder, _deserialize -from .._serialization import Serializer -from .._vendor import ( - DocumentTranslationClientMixinABC, - SingleDocumentTranslationClientMixinABC, - prepare_multipart_form_data, -) +from .. import models as _models, types as _types +from .._configuration import DocumentTranslationClientConfiguration, SingleDocumentTranslationClientConfiguration +from .._utils.model_base import Model as _Model, SdkJSONEncoder, _deserialize +from .._utils.serialization import Serializer +from .._utils.utils import ClientMixinABC, prepare_multipart_form_data +from .._validation import api_version_validation -if sys.version_info >= (3, 9): - from collections.abc import MutableMapping -else: - from typing import MutableMapping # type: ignore -JSON = MutableMapping[str, Any] # pylint: disable=unsubscriptable-object T = TypeVar("T") -ClsType = Optional[Callable[[PipelineResponse[HttpRequest, HttpResponse], T, Dict[str, Any]], Any]] +ClsType = Optional[Callable[[PipelineResponse[HttpRequest, HttpResponse], T, dict[str, Any]], Any]] _SERIALIZER = Serializer() _SERIALIZER.client_side_validation = False -def build_document_translation__begin_translation_request( # pylint: disable=name-too-long - **kwargs: Any, -) -> HttpRequest: +def build_document_translation_begin_translation_request(**kwargs: Any) -> HttpRequest: # pylint: disable=name-too-long _headers = case_insensitive_dict(kwargs.pop("headers", {}) or {}) _params = case_insensitive_dict(kwargs.pop("params", {}) or {}) content_type: Optional[str] = kwargs.pop("content_type", _headers.pop("Content-Type", None)) - api_version: str = kwargs.pop("api_version", _params.pop("api-version", "2024-05-01")) - accept = _headers.pop("Accept", "application/json") - + api_version: str = kwargs.pop("api_version", _params.pop("api-version", "2026-03-01")) # Construct URL _url = "/document/batches" @@ -71,7 +61,6 @@ def build_document_translation__begin_translation_request( # pylint: disable=na # Construct headers if content_type is not None: _headers["Content-Type"] = _SERIALIZER.header("content_type", content_type, "str") - _headers["Accept"] = _SERIALIZER.header("accept", accept, "str") return HttpRequest(method="POST", url=_url, params=_params, headers=_headers, **kwargs) @@ -81,17 +70,17 @@ def build_document_translation_list_translation_statuses_request( # pylint: dis top: Optional[int] = None, skip: Optional[int] = None, maxpagesize: Optional[int] = None, - translation_ids: Optional[List[str]] = None, - statuses: Optional[List[str]] = None, + translation_ids: Optional[list[str]] = None, + statuses: Optional[list[str]] = None, created_date_time_utc_start: Optional[datetime.datetime] = None, created_date_time_utc_end: Optional[datetime.datetime] = None, - orderby: Optional[List[str]] = None, - **kwargs: Any, + orderby: Optional[list[str]] = None, + **kwargs: Any ) -> HttpRequest: _headers = case_insensitive_dict(kwargs.pop("headers", {}) or {}) _params = case_insensitive_dict(kwargs.pop("params", {}) or {}) - api_version: str = kwargs.pop("api_version", _params.pop("api-version", "2024-05-01")) + api_version: str = kwargs.pop("api_version", _params.pop("api-version", "2026-03-01")) accept = _headers.pop("Accept", "application/json") # Construct URL @@ -132,7 +121,7 @@ def build_document_translation_get_document_status_request( # pylint: disable=n _headers = case_insensitive_dict(kwargs.pop("headers", {}) or {}) _params = case_insensitive_dict(kwargs.pop("params", {}) or {}) - api_version: str = kwargs.pop("api_version", _params.pop("api-version", "2024-05-01")) + api_version: str = kwargs.pop("api_version", _params.pop("api-version", "2026-03-01")) accept = _headers.pop("Accept", "application/json") # Construct URL @@ -159,7 +148,7 @@ def build_document_translation_get_translation_status_request( # pylint: disabl _headers = case_insensitive_dict(kwargs.pop("headers", {}) or {}) _params = case_insensitive_dict(kwargs.pop("params", {}) or {}) - api_version: str = kwargs.pop("api_version", _params.pop("api-version", "2024-05-01")) + api_version: str = kwargs.pop("api_version", _params.pop("api-version", "2026-03-01")) accept = _headers.pop("Accept", "application/json") # Construct URL @@ -185,7 +174,7 @@ def build_document_translation_cancel_translation_request( # pylint: disable=na _headers = case_insensitive_dict(kwargs.pop("headers", {}) or {}) _params = case_insensitive_dict(kwargs.pop("params", {}) or {}) - api_version: str = kwargs.pop("api_version", _params.pop("api-version", "2024-05-01")) + api_version: str = kwargs.pop("api_version", _params.pop("api-version", "2026-03-01")) accept = _headers.pop("Accept", "application/json") # Construct URL @@ -211,17 +200,17 @@ def build_document_translation_list_document_statuses_request( # pylint: disabl top: Optional[int] = None, skip: Optional[int] = None, maxpagesize: Optional[int] = None, - document_ids: Optional[List[str]] = None, - statuses: Optional[List[str]] = None, + document_ids: Optional[list[str]] = None, + statuses: Optional[list[str]] = None, created_date_time_utc_start: Optional[datetime.datetime] = None, created_date_time_utc_end: Optional[datetime.datetime] = None, - orderby: Optional[List[str]] = None, - **kwargs: Any, + orderby: Optional[list[str]] = None, + **kwargs: Any ) -> HttpRequest: _headers = case_insensitive_dict(kwargs.pop("headers", {}) or {}) _params = case_insensitive_dict(kwargs.pop("params", {}) or {}) - api_version: str = kwargs.pop("api_version", _params.pop("api-version", "2024-05-01")) + api_version: str = kwargs.pop("api_version", _params.pop("api-version", "2026-03-01")) accept = _headers.pop("Accept", "application/json") # Construct URL @@ -262,12 +251,12 @@ def build_document_translation_list_document_statuses_request( # pylint: disabl def build_document_translation_get_supported_formats_request( # pylint: disable=name-too-long - *, type: Optional[Union[str, _models.FileFormatType]] = None, **kwargs: Any + *, type: Union[str, _models.FileFormatType], **kwargs: Any ) -> HttpRequest: _headers = case_insensitive_dict(kwargs.pop("headers", {}) or {}) _params = case_insensitive_dict(kwargs.pop("params", {}) or {}) - api_version: str = kwargs.pop("api_version", _params.pop("api-version", "2024-05-01")) + api_version: str = kwargs.pop("api_version", _params.pop("api-version", "2026-03-01")) accept = _headers.pop("Accept", "application/json") # Construct URL @@ -275,8 +264,7 @@ def build_document_translation_get_supported_formats_request( # pylint: disable # Construct parameters _params["api-version"] = _SERIALIZER.query("api_version", api_version, "str") - if type is not None: - _params["type"] = _SERIALIZER.query("type", type, "str") + _params["type"] = _SERIALIZER.query("type", type, "str") # Construct headers _headers["Accept"] = _SERIALIZER.header("accept", accept, "str") @@ -289,13 +277,15 @@ def build_single_document_translation_translate_request( # pylint: disable=name target_language: str, source_language: Optional[str] = None, category: Optional[str] = None, + deployment_name: Optional[str] = None, allow_fallback: Optional[bool] = None, - **kwargs: Any, + translate_text_within_image: Optional[bool] = None, + **kwargs: Any ) -> HttpRequest: _headers = case_insensitive_dict(kwargs.pop("headers", {}) or {}) _params = case_insensitive_dict(kwargs.pop("params", {}) or {}) - api_version: str = kwargs.pop("api_version", _params.pop("api-version", "2024-05-01")) + api_version: str = kwargs.pop("api_version", _params.pop("api-version", "2026-03-01")) accept = _headers.pop("Accept", "application/octet-stream") # Construct URL @@ -308,8 +298,14 @@ def build_single_document_translation_translate_request( # pylint: disable=name _params["targetLanguage"] = _SERIALIZER.query("target_language", target_language, "str") if category is not None: _params["category"] = _SERIALIZER.query("category", category, "str") + if deployment_name is not None: + _params["deploymentName"] = _SERIALIZER.query("deployment_name", deployment_name, "str") if allow_fallback is not None: _params["allowFallback"] = _SERIALIZER.query("allow_fallback", allow_fallback, "bool") + if translate_text_within_image is not None: + _params["translateTextWithinImage"] = _SERIALIZER.query( + "translate_text_within_image", translate_text_within_image, "bool" + ) # Construct headers _headers["Accept"] = _SERIALIZER.header("accept", accept, "str") @@ -317,10 +313,12 @@ def build_single_document_translation_translate_request( # pylint: disable=name return HttpRequest(method="POST", url=_url, params=_params, headers=_headers, **kwargs) -class DocumentTranslationClientOperationsMixin(DocumentTranslationClientMixinABC): +class _DocumentTranslationClientOperationsMixin( + ClientMixinABC[PipelineClient[HttpRequest, HttpResponse], DocumentTranslationClientConfiguration] +): - def __begin_translation_initial( - self, body: Union[_models.StartTranslationDetails, JSON, IO[bytes]], **kwargs: Any + def _begin_translation_initial( + self, body: Union[_models.StartTranslationDetails, _types.StartTranslationDetails, IO[bytes]], **kwargs: Any ) -> Iterator[bytes]: error_map: MutableMapping = { 401: ClientAuthenticationError, @@ -343,7 +341,7 @@ def __begin_translation_initial( else: _content = json.dumps(body, cls=SdkJSONEncoder, exclude_readonly=True) # type: ignore - _request = build_document_translation__begin_translation_request( + _request = build_document_translation_begin_translation_request( content_type=content_type, api_version=self._config.api_version, content=_content, @@ -355,6 +353,7 @@ def __begin_translation_initial( } _request.url = self._client.format_url(_request.url, **path_format_arguments) + _decompress = kwargs.pop("decompress", True) _stream = True pipeline_response: PipelineResponse = self._client._pipeline.run( # pylint: disable=protected-access _request, stream=_stream, **kwargs @@ -373,7 +372,7 @@ def __begin_translation_initial( response_headers = {} response_headers["Operation-Location"] = self._deserialize("str", response.headers.get("Operation-Location")) - deserialized = response.iter_bytes() + deserialized = response.iter_bytes() if _decompress else response.iter_raw() if cls: return cls(pipeline_response, deserialized, response_headers) # type: ignore @@ -381,30 +380,19 @@ def __begin_translation_initial( return deserialized # type: ignore @overload - def _begin_translation( + def begin_translation( self, body: _models.StartTranslationDetails, *, content_type: str = "application/json", **kwargs: Any ) -> LROPoller[_models.TranslationStatus]: """Submit a document translation request to the Document Translation service. - Use this API to submit a bulk (batch) translation request to the Document - Translation service. - Each request can contain multiple documents and must - contain a source and destination container for each document. - - The - prefix and suffix filter (if supplied) are used to filter folders. The prefix - is applied to the subpath after the container name. - - Glossaries / - Translation memory can be included in the request and are applied by the - service when the document is translated. - - If the glossary is - invalid or unreachable during translation, an error is indicated in the - document status. - If a file with the same name already exists at the - destination, it will be overwritten. The targetUrl for each target language - must be unique. + Use this API to submit a bulk (batch) translation request to the Document Translation service. + Each request can contain multiple documents and must contain a source and destination container + for each document. The prefix and suffix filter (if supplied) are used to filter folders. The + prefix is applied to the subpath after the container name. Glossaries / Translation memory can + be included in the request and are applied by the service when the document is translated. If + the glossary is invalid or unreachable during translation, an error is indicated in the + document status. If a file with the same name already exists at the destination, it will be + overwritten. The targetUrl for each target language must be unique. :param body: Translation job submission batch request. Required. :type body: ~azure.ai.translation.document.models.StartTranslationDetails @@ -418,33 +406,22 @@ def _begin_translation( """ @overload - def _begin_translation( - self, body: JSON, *, content_type: str = "application/json", **kwargs: Any + def begin_translation( + self, body: _types.StartTranslationDetails, *, content_type: str = "application/json", **kwargs: Any ) -> LROPoller[_models.TranslationStatus]: """Submit a document translation request to the Document Translation service. - Use this API to submit a bulk (batch) translation request to the Document - Translation service. - Each request can contain multiple documents and must - contain a source and destination container for each document. - - The - prefix and suffix filter (if supplied) are used to filter folders. The prefix - is applied to the subpath after the container name. - - Glossaries / - Translation memory can be included in the request and are applied by the - service when the document is translated. - - If the glossary is - invalid or unreachable during translation, an error is indicated in the - document status. - If a file with the same name already exists at the - destination, it will be overwritten. The targetUrl for each target language - must be unique. + Use this API to submit a bulk (batch) translation request to the Document Translation service. + Each request can contain multiple documents and must contain a source and destination container + for each document. The prefix and suffix filter (if supplied) are used to filter folders. The + prefix is applied to the subpath after the container name. Glossaries / Translation memory can + be included in the request and are applied by the service when the document is translated. If + the glossary is invalid or unreachable during translation, an error is indicated in the + document status. If a file with the same name already exists at the destination, it will be + overwritten. The targetUrl for each target language must be unique. :param body: Translation job submission batch request. Required. - :type body: JSON + :type body: ~azure.ai.translation.document.types.StartTranslationDetails :keyword content_type: Body Parameter content-type. Content type parameter for JSON body. Default value is "application/json". :paramtype content_type: str @@ -455,30 +432,19 @@ def _begin_translation( """ @overload - def _begin_translation( + def begin_translation( self, body: IO[bytes], *, content_type: str = "application/json", **kwargs: Any ) -> LROPoller[_models.TranslationStatus]: """Submit a document translation request to the Document Translation service. - Use this API to submit a bulk (batch) translation request to the Document - Translation service. - Each request can contain multiple documents and must - contain a source and destination container for each document. - - The - prefix and suffix filter (if supplied) are used to filter folders. The prefix - is applied to the subpath after the container name. - - Glossaries / - Translation memory can be included in the request and are applied by the - service when the document is translated. - - If the glossary is - invalid or unreachable during translation, an error is indicated in the - document status. - If a file with the same name already exists at the - destination, it will be overwritten. The targetUrl for each target language - must be unique. + Use this API to submit a bulk (batch) translation request to the Document Translation service. + Each request can contain multiple documents and must contain a source and destination container + for each document. The prefix and suffix filter (if supplied) are used to filter folders. The + prefix is applied to the subpath after the container name. Glossaries / Translation memory can + be included in the request and are applied by the service when the document is translated. If + the glossary is invalid or unreachable during translation, an error is indicated in the + document status. If a file with the same name already exists at the destination, it will be + overwritten. The targetUrl for each target language must be unique. :param body: Translation job submission batch request. Required. :type body: IO[bytes] @@ -492,34 +458,24 @@ def _begin_translation( """ @distributed_trace - def _begin_translation( - self, body: Union[_models.StartTranslationDetails, JSON, IO[bytes]], **kwargs: Any + def begin_translation( + self, body: Union[_models.StartTranslationDetails, _types.StartTranslationDetails, IO[bytes]], **kwargs: Any ) -> LROPoller[_models.TranslationStatus]: """Submit a document translation request to the Document Translation service. - Use this API to submit a bulk (batch) translation request to the Document - Translation service. - Each request can contain multiple documents and must - contain a source and destination container for each document. - - The - prefix and suffix filter (if supplied) are used to filter folders. The prefix - is applied to the subpath after the container name. - - Glossaries / - Translation memory can be included in the request and are applied by the - service when the document is translated. - - If the glossary is - invalid or unreachable during translation, an error is indicated in the - document status. - If a file with the same name already exists at the - destination, it will be overwritten. The targetUrl for each target language - must be unique. - - :param body: Translation job submission batch request. Is one of the following types: - StartTranslationDetails, JSON, IO[bytes] Required. - :type body: ~azure.ai.translation.document.models.StartTranslationDetails or JSON or IO[bytes] + Use this API to submit a bulk (batch) translation request to the Document Translation service. + Each request can contain multiple documents and must contain a source and destination container + for each document. The prefix and suffix filter (if supplied) are used to filter folders. The + prefix is applied to the subpath after the container name. Glossaries / Translation memory can + be included in the request and are applied by the service when the document is translated. If + the glossary is invalid or unreachable during translation, an error is indicated in the + document status. If a file with the same name already exists at the destination, it will be + overwritten. The targetUrl for each target language must be unique. + + :param body: Translation job submission batch request. Is either a StartTranslationDetails type + or a IO[bytes] type. Required. + :type body: ~azure.ai.translation.document.models.StartTranslationDetails or + ~azure.ai.translation.document.types.StartTranslationDetails or IO[bytes] :return: An instance of LROPoller that returns TranslationStatus. The TranslationStatus is compatible with MutableMapping :rtype: ~azure.core.polling.LROPoller[~azure.ai.translation.document.models.TranslationStatus] @@ -534,7 +490,7 @@ def _begin_translation( lro_delay = kwargs.pop("polling_interval", self._config.polling_interval) cont_token: Optional[str] = kwargs.pop("continuation_token", None) if cont_token is None: - raw_result = self.__begin_translation_initial( + raw_result = self._begin_translation_initial( body=body, content_type=content_type, cls=lambda x, y, z: x, headers=_headers, params=_params, **kwargs ) raw_result.http_response.read() # type: ignore @@ -581,13 +537,13 @@ def list_translation_statuses( *, top: Optional[int] = None, skip: Optional[int] = None, - translation_ids: Optional[List[str]] = None, - statuses: Optional[List[str]] = None, + translation_ids: Optional[list[str]] = None, + statuses: Optional[list[str]] = None, created_date_time_utc_start: Optional[datetime.datetime] = None, created_date_time_utc_end: Optional[datetime.datetime] = None, - orderby: Optional[List[str]] = None, - **kwargs: Any, - ) -> Iterable["_models.TranslationStatus"]: + orderby: Optional[list[str]] = None, + **kwargs: Any + ) -> ItemPaged["_models.TranslationStatus"]: """Returns a list of batch requests submitted and the status for each request. Returns a list of batch requests submitted and the status for each @@ -615,6 +571,7 @@ def list_translation_statuses( requested via top (or top is not specified and there are more items to be returned), @nextLink will contain the link to the next page. + orderby query parameter can be used to sort the returned list (ex "orderby=createdDateTimeUtc asc" or "orderby=createdDateTimeUtc desc"). @@ -633,6 +590,7 @@ def list_translation_statuses( the values specified by the client. However, clients must be prepared to handle responses that contain a different page size or contain a continuation token. + When both top and skip are included, the server should first apply skip and then top on the collection. Note: If the server can't honor top @@ -689,7 +647,7 @@ def list_translation_statuses( _params = kwargs.pop("params", {}) or {} maxpagesize = kwargs.pop("maxpagesize", None) - cls: ClsType[List[_models.TranslationStatus]] = kwargs.pop("cls", None) + cls: ClsType[list[_models.TranslationStatus]] = kwargs.pop("cls", None) error_map: MutableMapping = { 401: ClientAuthenticationError, @@ -733,7 +691,10 @@ def prepare_request(next_link=None): ) _next_request_params["api-version"] = self._config.api_version _request = HttpRequest( - "GET", urllib.parse.urljoin(next_link, _parsed_next_link.path), params=_next_request_params + "GET", + urllib.parse.urljoin(next_link, _parsed_next_link.path), + headers=_headers, + params=_next_request_params, ) path_format_arguments = { "endpoint": self._serialize.url( @@ -746,7 +707,10 @@ def prepare_request(next_link=None): def extract_data(pipeline_response): deserialized = pipeline_response.http_response.json() - list_of_elem = _deserialize(List[_models.TranslationStatus], deserialized["value"]) + list_of_elem = _deserialize( + list[_models.TranslationStatus], + deserialized.get("value", []), + ) if cls: list_of_elem = cls(list_of_elem) # type: ignore return deserialized.get("nextLink") or None, iter(list_of_elem) @@ -772,8 +736,7 @@ def get_next(next_link=None): def get_document_status(self, translation_id: str, document_id: str, **kwargs: Any) -> _models.DocumentStatus: """Returns the status for a specific document. - Returns the translation status for a specific document based on the request Id - and document Id. + Returns the translation status for a specific document based on the request Id and document Id. :param translation_id: Format - uuid. The batch id. Required. :type translation_id: str @@ -808,6 +771,7 @@ def get_document_status(self, translation_id: str, document_id: str, **kwargs: A } _request.url = self._client.format_url(_request.url, **path_format_arguments) + _decompress = kwargs.pop("decompress", True) _stream = kwargs.pop("stream", False) pipeline_response: PipelineResponse = self._client._pipeline.run( # pylint: disable=protected-access _request, stream=_stream, **kwargs @@ -825,7 +789,7 @@ def get_document_status(self, translation_id: str, document_id: str, **kwargs: A raise HttpResponseError(response=response) if _stream: - deserialized = response.iter_bytes() + deserialized = response.iter_bytes() if _decompress else response.iter_raw() else: deserialized = _deserialize(_models.DocumentStatus, response.json()) @@ -838,10 +802,8 @@ def get_document_status(self, translation_id: str, document_id: str, **kwargs: A def get_translation_status(self, translation_id: str, **kwargs: Any) -> _models.TranslationStatus: """Returns the status for a document translation request. - Returns the status for a document translation request. - The status includes the - overall request status, as well as the status for documents that are being - translated as part of that request. + Returns the status for a document translation request. The status includes the overall request + status, as well as the status for documents that are being translated as part of that request. :param translation_id: Format - uuid. The operation id. Required. :type translation_id: str @@ -873,6 +835,7 @@ def get_translation_status(self, translation_id: str, **kwargs: Any) -> _models. } _request.url = self._client.format_url(_request.url, **path_format_arguments) + _decompress = kwargs.pop("decompress", True) _stream = kwargs.pop("stream", False) pipeline_response: PipelineResponse = self._client._pipeline.run( # pylint: disable=protected-access _request, stream=_stream, **kwargs @@ -890,7 +853,7 @@ def get_translation_status(self, translation_id: str, **kwargs: Any) -> _models. raise HttpResponseError(response=response) if _stream: - deserialized = response.iter_bytes() + deserialized = response.iter_bytes() if _decompress else response.iter_raw() else: deserialized = _deserialize(_models.TranslationStatus, response.json()) @@ -903,14 +866,10 @@ def get_translation_status(self, translation_id: str, **kwargs: Any) -> _models. def cancel_translation(self, translation_id: str, **kwargs: Any) -> _models.TranslationStatus: """Cancel a currently processing or queued translation. - Cancel a currently processing or queued translation. - A translation will not be - cancelled if it is already completed or failed or cancelling. A bad request - will be returned. - All documents that have completed translation will not be - cancelled and will be charged. - All pending documents will be cancelled if - possible. + Cancel a currently processing or queued translation. A translation will not be cancelled if it + is already completed or failed or cancelling. A bad request will be returned. All documents + that have completed translation will not be cancelled and will be charged. All pending + documents will be cancelled if possible. :param translation_id: Format - uuid. The operation-id. Required. :type translation_id: str @@ -942,6 +901,7 @@ def cancel_translation(self, translation_id: str, **kwargs: Any) -> _models.Tran } _request.url = self._client.format_url(_request.url, **path_format_arguments) + _decompress = kwargs.pop("decompress", True) _stream = kwargs.pop("stream", False) pipeline_response: PipelineResponse = self._client._pipeline.run( # pylint: disable=protected-access _request, stream=_stream, **kwargs @@ -959,7 +919,7 @@ def cancel_translation(self, translation_id: str, **kwargs: Any) -> _models.Tran raise HttpResponseError(response=response) if _stream: - deserialized = response.iter_bytes() + deserialized = response.iter_bytes() if _decompress else response.iter_raw() else: deserialized = _deserialize(_models.TranslationStatus, response.json()) @@ -975,59 +935,36 @@ def list_document_statuses( *, top: Optional[int] = None, skip: Optional[int] = None, - document_ids: Optional[List[str]] = None, - statuses: Optional[List[str]] = None, + document_ids: Optional[list[str]] = None, + statuses: Optional[list[str]] = None, created_date_time_utc_start: Optional[datetime.datetime] = None, created_date_time_utc_end: Optional[datetime.datetime] = None, - orderby: Optional[List[str]] = None, - **kwargs: Any, - ) -> Iterable["_models.DocumentStatus"]: + orderby: Optional[list[str]] = None, + **kwargs: Any + ) -> ItemPaged["_models.DocumentStatus"]: """Returns the status for all documents in a batch document translation request. - Returns the status for all documents in a batch document translation request. - - If the number of documents in the response exceeds our paging limit, - server-side paging is used. - Paginated responses indicate a partial result and - include a continuation token in the response. The absence of a continuation - token means that no additional pages are available. - - top, skip - and maxpagesize query parameters can be used to specify a number of results to - return and an offset for the collection. - - top indicates the total - number of records the user wants to be returned across all pages. - skip - indicates the number of records to skip from the list of document status held - by the server based on the sorting method specified. By default, we sort by - descending start time. - maxpagesize is the maximum items returned in a page. - If more items are requested via top (or top is not specified and there are - more items to be returned), @nextLink will contain the link to the next page. - - orderby query parameter can be used to sort the returned list (ex - "orderby=createdDateTimeUtc asc" or "orderby=createdDateTimeUtc - desc"). - The default sorting is descending by createdDateTimeUtc. - Some query - parameters can be used to filter the returned list (ex: - "status=Succeeded,Cancelled") will only return succeeded and cancelled - documents. - createdDateTimeUtcStart and createdDateTimeUtcEnd can be used - combined or separately to specify a range of datetime to filter the returned - list by. - The supported filtering query parameters are (status, ids, - createdDateTimeUtcStart, createdDateTimeUtcEnd). - - When both top - and skip are included, the server should first apply skip and then top on - the collection. - Note: If the server can't honor top and/or skip, the server - must return an error to the client informing about it instead of just ignoring - the query options. - This reduces the risk of the client making assumptions about - the data returned. + Returns the status for all documents in a batch document translation request. If the number of + documents in the response exceeds our paging limit, server-side paging is used. Paginated + responses indicate a partial result and include a continuation token in the response. The + absence of a continuation token means that no additional pages are available. top, skip and + maxpagesize query parameters can be used to specify a number of results to return and an offset + for the collection. top indicates the total number of records the user wants to be returned + across all pages. skip indicates the number of records to skip from the list of document status + held by the server based on the sorting method specified. By default, we sort by descending + start time. maxpagesize is the maximum items returned in a page. If more items are requested + via top (or top is not specified and there are more items to be returned), @nextLink will + contain the link to the next page. orderby query parameter can be used to sort the returned + list (ex "orderby=createdDateTimeUtc asc" or "orderby=createdDateTimeUtc desc"). The default + sorting is descending by createdDateTimeUtc. Some query parameters can be used to filter the + returned list (ex: "status=Succeeded,Cancelled") will only return succeeded and cancelled + documents. createdDateTimeUtcStart and createdDateTimeUtcEnd can be used combined or separately + to specify a range of datetime to filter the returned list by. The supported filtering query + parameters are (status, ids, createdDateTimeUtcStart, createdDateTimeUtcEnd). When both top and + skip are included, the server should first apply skip and then top on the collection. Note: If + the server can't honor top and/or skip, the server must return an error to the client informing + about it instead of just ignoring the query options. This reduces the risk of the client making + assumptions about the data returned. :param translation_id: Format - uuid. The operation id. Required. :type translation_id: str @@ -1079,7 +1016,7 @@ def list_document_statuses( _params = kwargs.pop("params", {}) or {} maxpagesize = kwargs.pop("maxpagesize", None) - cls: ClsType[List[_models.DocumentStatus]] = kwargs.pop("cls", None) + cls: ClsType[list[_models.DocumentStatus]] = kwargs.pop("cls", None) error_map: MutableMapping = { 401: ClientAuthenticationError, @@ -1124,7 +1061,10 @@ def prepare_request(next_link=None): ) _next_request_params["api-version"] = self._config.api_version _request = HttpRequest( - "GET", urllib.parse.urljoin(next_link, _parsed_next_link.path), params=_next_request_params + "GET", + urllib.parse.urljoin(next_link, _parsed_next_link.path), + headers=_headers, + params=_next_request_params, ) path_format_arguments = { "endpoint": self._serialize.url( @@ -1137,7 +1077,10 @@ def prepare_request(next_link=None): def extract_data(pipeline_response): deserialized = pipeline_response.http_response.json() - list_of_elem = _deserialize(List[_models.DocumentStatus], deserialized["value"]) + list_of_elem = _deserialize( + list[_models.DocumentStatus], + deserialized.get("value", []), + ) if cls: list_of_elem = cls(list_of_elem) # type: ignore return deserialized.get("nextLink") or None, iter(list_of_elem) @@ -1161,17 +1104,15 @@ def get_next(next_link=None): @distributed_trace def _get_supported_formats( - self, *, type: Optional[Union[str, _models.FileFormatType]] = None, **kwargs: Any + self, *, type: Union[str, _models.FileFormatType], **kwargs: Any ) -> _models._models.SupportedFileFormats: """Returns a list of supported document formats. - The list of supported formats supported by the Document Translation - service. - The list includes the common file extension, as well as the - content-type if using the upload API. + The list of supported formats supported by the Document Translation service. The list includes + the common file extension, as well as the content-type if using the upload API. - :keyword type: the type of format like document or glossary. Known values are: "document" and - "glossary". Default value is None. + :keyword type: the type of format like document or glossary. Known values are: "Document" and + "Glossary". Required. :paramtype type: str or ~azure.ai.translation.document.models.FileFormatType :return: SupportedFileFormats. The SupportedFileFormats is compatible with MutableMapping :rtype: ~azure.ai.translation.document.models._models.SupportedFileFormats @@ -1201,6 +1142,7 @@ def _get_supported_formats( } _request.url = self._client.format_url(_request.url, **path_format_arguments) + _decompress = kwargs.pop("decompress", True) _stream = kwargs.pop("stream", False) pipeline_response: PipelineResponse = self._client._pipeline.run( # pylint: disable=protected-access _request, stream=_stream, **kwargs @@ -1218,7 +1160,7 @@ def _get_supported_formats( raise HttpResponseError(response=response) if _stream: - deserialized = response.iter_bytes() + deserialized = response.iter_bytes() if _decompress else response.iter_raw() else: deserialized = _deserialize( _models._models.SupportedFileFormats, response.json() # pylint: disable=protected-access @@ -1230,8 +1172,8 @@ def _get_supported_formats( return deserialized # type: ignore -class SingleDocumentTranslationClientOperationsMixin( # pylint: disable=name-too-long - SingleDocumentTranslationClientMixinABC +class _SingleDocumentTranslationClientOperationsMixin( + ClientMixinABC[PipelineClient[HttpRequest, HttpResponse], SingleDocumentTranslationClientConfiguration] ): @overload @@ -1242,8 +1184,10 @@ def translate( target_language: str, source_language: Optional[str] = None, category: Optional[str] = None, + deployment_name: Optional[str] = None, allow_fallback: Optional[bool] = None, - **kwargs: Any, + translate_text_within_image: Optional[bool] = None, + **kwargs: Any ) -> Iterator[bytes]: """Submit a single document translation request to the Document Translation service. @@ -1269,10 +1213,16 @@ def translate( project details to this parameter to use your deployed customized system. Default value is: general. Default value is None. :paramtype category: str + :keyword deployment_name: Deployment name of the custom translation model for the translation + request. Default value is None. + :paramtype deployment_name: str :keyword allow_fallback: Specifies that the service is allowed to fall back to a general system when a custom system doesn't exist. Possible values are: true (default) or false. Default value is None. :paramtype allow_fallback: bool + :keyword translate_text_within_image: Optional boolean parameter to translate text within an + image in the document. Default value is None. + :paramtype translate_text_within_image: bool :return: Iterator[bytes] :rtype: Iterator[bytes] :raises ~azure.core.exceptions.HttpResponseError: @@ -1281,20 +1231,22 @@ def translate( @overload def translate( self, - body: JSON, + body: _types.DocumentTranslateContent, *, target_language: str, source_language: Optional[str] = None, category: Optional[str] = None, + deployment_name: Optional[str] = None, allow_fallback: Optional[bool] = None, - **kwargs: Any, + translate_text_within_image: Optional[bool] = None, + **kwargs: Any ) -> Iterator[bytes]: """Submit a single document translation request to the Document Translation service. Use this API to submit a single translation request to the Document Translation Service. :param body: Document Translate Request Content. Required. - :type body: JSON + :type body: ~azure.ai.translation.document.types.DocumentTranslateContent :keyword target_language: Specifies the language of the output document. The target language must be one of the supported languages included in the translation scope. For example if you want to translate the document in German language, then use @@ -1313,33 +1265,46 @@ def translate( project details to this parameter to use your deployed customized system. Default value is: general. Default value is None. :paramtype category: str + :keyword deployment_name: Deployment name of the custom translation model for the translation + request. Default value is None. + :paramtype deployment_name: str :keyword allow_fallback: Specifies that the service is allowed to fall back to a general system when a custom system doesn't exist. Possible values are: true (default) or false. Default value is None. :paramtype allow_fallback: bool + :keyword translate_text_within_image: Optional boolean parameter to translate text within an + image in the document. Default value is None. + :paramtype translate_text_within_image: bool :return: Iterator[bytes] :rtype: Iterator[bytes] :raises ~azure.core.exceptions.HttpResponseError: """ @distributed_trace + @api_version_validation( + params_added_on={"2026-03-01": ["deployment_name"], "2024-11-01-preview": ["translate_text_within_image"]}, + api_versions_list=["2024-05-01", "2024-11-01-preview", "2025-12-01-preview", "2026-03-01"], + ) def translate( self, - body: Union[_models.DocumentTranslateContent, JSON], + body: Union[_models.DocumentTranslateContent, _types.DocumentTranslateContent], *, target_language: str, source_language: Optional[str] = None, category: Optional[str] = None, + deployment_name: Optional[str] = None, allow_fallback: Optional[bool] = None, - **kwargs: Any, + translate_text_within_image: Optional[bool] = None, + **kwargs: Any ) -> Iterator[bytes]: """Submit a single document translation request to the Document Translation service. Use this API to submit a single translation request to the Document Translation Service. - :param body: Document Translate Request Content. Is either a DocumentTranslateContent type or a - JSON type. Required. - :type body: ~azure.ai.translation.document.models.DocumentTranslateContent or JSON + :param body: Document Translate Request Content. Is one of the following types: + DocumentTranslateContent Required. + :type body: ~azure.ai.translation.document.models.DocumentTranslateContent or + ~azure.ai.translation.document.types.DocumentTranslateContent :keyword target_language: Specifies the language of the output document. The target language must be one of the supported languages included in the translation scope. For example if you want to translate the document in German language, then use @@ -1358,10 +1323,16 @@ def translate( project details to this parameter to use your deployed customized system. Default value is: general. Default value is None. :paramtype category: str + :keyword deployment_name: Deployment name of the custom translation model for the translation + request. Default value is None. + :paramtype deployment_name: str :keyword allow_fallback: Specifies that the service is allowed to fall back to a general system when a custom system doesn't exist. Possible values are: true (default) or false. Default value is None. :paramtype allow_fallback: bool + :keyword translate_text_within_image: Optional boolean parameter to translate text within an + image in the document. Default value is None. + :paramtype translate_text_within_image: bool :return: Iterator[bytes] :rtype: Iterator[bytes] :raises ~azure.core.exceptions.HttpResponseError: @@ -1379,19 +1350,20 @@ def translate( cls: ClsType[Iterator[bytes]] = kwargs.pop("cls", None) - _body = body.as_dict() if isinstance(body, _model_base.Model) else body - _file_fields: List[str] = ["document", "glossary"] - _data_fields: List[str] = [] - _files, _data = prepare_multipart_form_data(_body, _file_fields, _data_fields) + _body = body.as_dict() if isinstance(body, _Model) else body + _file_fields: list[str] = ["document", "glossary"] + _data_fields: list[str] = [] + _files = prepare_multipart_form_data(_body, _file_fields, _data_fields) _request = build_single_document_translation_translate_request( target_language=target_language, source_language=source_language, category=category, + deployment_name=deployment_name, allow_fallback=allow_fallback, + translate_text_within_image=translate_text_within_image, api_version=self._config.api_version, files=_files, - data=_data, headers=_headers, params=_params, ) @@ -1400,6 +1372,7 @@ def translate( } _request.url = self._client.format_url(_request.url, **path_format_arguments) + _decompress = kwargs.pop("decompress", True) _stream = kwargs.pop("stream", True) pipeline_response: PipelineResponse = self._client._pipeline.run( # pylint: disable=protected-access _request, stream=_stream, **kwargs @@ -1417,12 +1390,19 @@ def translate( raise HttpResponseError(response=response) response_headers = {} + response_headers["x-metered-usage"] = self._deserialize("int", response.headers.get("x-metered-usage")) + response_headers["total-image-scans-succeeded"] = self._deserialize( + "int", response.headers.get("total-image-scans-succeeded") + ) + response_headers["total-image-scans-failed"] = self._deserialize( + "int", response.headers.get("total-image-scans-failed") + ) response_headers["x-ms-client-request-id"] = self._deserialize( "str", response.headers.get("x-ms-client-request-id") ) response_headers["content-type"] = self._deserialize("str", response.headers.get("content-type")) - deserialized = response.iter_bytes() + deserialized = response.iter_bytes() if _decompress else response.iter_raw() if cls: return cls(pipeline_response, deserialized, response_headers) # type: ignore diff --git a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_operations/_patch.py b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_operations/_patch.py index 0c597a6d71d5..ebc53ca72631 100644 --- a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_operations/_patch.py +++ b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_operations/_patch.py @@ -1,3 +1,4 @@ +# pylint: disable=line-too-long,useless-suppression # ------------------------------------ # Copyright (c) Microsoft Corporation. # Licensed under the MIT License. @@ -32,20 +33,21 @@ OperationFailed, _raise_if_bad_http_status_and_method, ) -from .. import _model_base, models as _models +from .. import models as _models +from .._utils import model_base as _model_base from ..models import ( TranslationStatus, ) -from .._model_base import _deserialize +from .._utils.model_base import _deserialize from ._operations import ( - DocumentTranslationClientOperationsMixin as GeneratedDocumentTranslationClientOperationsMixin, - SingleDocumentTranslationClientOperationsMixin as GeneratedSingleDocumentTranslationClientOperationsMixin, - JSON, + _DocumentTranslationClientOperationsMixin as GeneratedDocumentTranslationClientOperationsMixin, + _SingleDocumentTranslationClientOperationsMixin as GeneratedSingleDocumentTranslationClientOperationsMixin, ClsType, build_single_document_translation_translate_request, ) -from .._vendor import prepare_multipart_form_data +from .._utils.utils import prepare_multipart_form_data +from .._validation import api_version_validation if sys.version_info >= (3, 9): from collections.abc import MutableMapping @@ -80,7 +82,7 @@ def convert_status(status, ll=False): class DocumentTranslationLROPoller(LROPoller[PollingReturnType_co]): """A custom poller implementation for Document Translation. Call `result()` on the poller to return - a pageable of :class:`~azure.ai.translation.document.DocumentStatus`.""" + a pageable of :class:`~azure.ai.translation.document.models.DocumentStatus`.""" _polling_method: "DocumentTranslationLROPollingMethod" @@ -92,7 +94,7 @@ def id(self) -> str: :rtype: str """ # pylint: disable=protected-access - if self._polling_method._current_body: + if self._polling_method._current_body and self._polling_method._current_body.id: return self._polling_method._current_body.id return self._polling_method._get_id_from_headers() @@ -101,7 +103,7 @@ def details(self) -> TranslationStatus: """The details for the translation operation :return: The details for the translation operation. - :rtype: ~azure.ai.translation.document.TranslationStatus + :rtype: ~azure.ai.translation.document.models.TranslationStatus """ # pylint: disable=protected-access if self._polling_method._current_body: @@ -134,7 +136,12 @@ def __init__(self, *args, **kwargs): @property def _current_body(self) -> TranslationStatus: try: - return TranslationStatus(self._pipeline_response.http_response.json()) + response = self._pipeline_response.http_response + # Ignore non-success responses (e.g. a transient polling error) so they do not + # corrupt the operation status, id, or details reported by the poller. + if not 200 <= response.status_code < 300: + return TranslationStatus() # type: ignore[call-overload] + return TranslationStatus(response.json()) except Exception: # pylint: disable=broad-exception-caught return TranslationStatus() # type: ignore[call-overload] @@ -291,8 +298,13 @@ def _begin_translation( # type: ignore[override] lro_delay = kwargs.pop("polling_interval", self._config.polling_interval) cont_token: Optional[str] = kwargs.pop("continuation_token", None) if cont_token is None: - raw_result = self.__begin_translation_initial( # type: ignore[func-returns-value] - body=body, content_type=content_type, cls=lambda x, y, z: x, headers=_headers, params=_params, **kwargs + raw_result = self._begin_translation_initial( # type: ignore[func-returns-value] + body=body, # type: ignore[arg-type] + content_type=content_type, + cls=lambda x, y, z: x, + headers=_headers, + params=_params, + **kwargs ) kwargs.pop("error_map", None) @@ -328,7 +340,10 @@ def get_long_running_output(pipeline_response): deserialization_callback=get_long_running_output, ) return DocumentTranslationLROPoller[_models.TranslationStatus]( - self._client, raw_result, get_long_running_output, polling_method # pylint: disable=possibly-used-before-assignment + self._client, + raw_result, + get_long_running_output, + polling_method, # pylint: disable=possibly-used-before-assignment ) @@ -336,7 +351,7 @@ class SingleDocumentTranslationClientOperationsMixin( GeneratedSingleDocumentTranslationClientOperationsMixin ): # pylint: disable=name-too-long - @overload + @overload # type: ignore[override] def translate( self, body: _models.DocumentTranslateContent, @@ -344,7 +359,9 @@ def translate( target_language: str, source_language: Optional[str] = None, category: Optional[str] = None, + deployment_name: Optional[str] = None, allow_fallback: Optional[bool] = None, + translate_text_within_image: Optional[bool] = None, **kwargs: Any ) -> Iterator[bytes]: """Submit a single document translation request to the Document Translation service. @@ -371,10 +388,16 @@ def translate( project details to this parameter to use your deployed customized system. Default value is: general. Default value is None. :paramtype category: str + :keyword deployment_name: Deployment name of the custom translation model for the translation + request. Default value is None. + :paramtype deployment_name: str :keyword allow_fallback: Specifies that the service is allowed to fall back to a general system when a custom system doesn't exist. Possible values are: true (default) or false. Default value is None. :paramtype allow_fallback: bool + :keyword translate_text_within_image: Optional boolean parameter to translate text within an + image in the document. Default value is None. + :paramtype translate_text_within_image: bool :return: Iterator[bytes] :rtype: Iterator[bytes] :raises ~azure.core.exceptions.HttpResponseError: @@ -397,7 +420,9 @@ def translate( target_language: str, source_language: Optional[str] = None, category: Optional[str] = None, + deployment_name: Optional[str] = None, allow_fallback: Optional[bool] = None, + translate_text_within_image: Optional[bool] = None, **kwargs: Any ) -> Iterator[bytes]: """Submit a single document translation request to the Document Translation service. @@ -424,16 +449,26 @@ def translate( project details to this parameter to use your deployed customized system. Default value is: general. Default value is None. :paramtype category: str + :keyword deployment_name: Deployment name of the custom translation model for the translation + request. Default value is None. + :paramtype deployment_name: str :keyword allow_fallback: Specifies that the service is allowed to fall back to a general system when a custom system doesn't exist. Possible values are: true (default) or false. Default value is None. :paramtype allow_fallback: bool + :keyword translate_text_within_image: Optional boolean parameter to translate text within an + image in the document. Default value is None. + :paramtype translate_text_within_image: bool :return: Iterator[bytes] :rtype: Iterator[bytes] :raises ~azure.core.exceptions.HttpResponseError: """ @distributed_trace + @api_version_validation( + params_added_on={"2026-03-01": ["deployment_name"], "2024-11-01-preview": ["translate_text_within_image"]}, + api_versions_list=["2024-05-01", "2024-11-01-preview", "2025-12-01-preview", "2026-03-01"], + ) def translate( self, body: Union[_models.DocumentTranslateContent, JSON], @@ -441,7 +476,9 @@ def translate( target_language: str, source_language: Optional[str] = None, category: Optional[str] = None, + deployment_name: Optional[str] = None, allow_fallback: Optional[bool] = None, + translate_text_within_image: Optional[bool] = None, **kwargs: Any ) -> Iterator[bytes]: """Submit a single document translation request to the Document Translation service. @@ -468,10 +505,16 @@ def translate( project details to this parameter to use your deployed customized system. Default value is: general. Default value is None. :paramtype category: str + :keyword deployment_name: Deployment name of the custom translation model for the translation + request. Default value is None. + :paramtype deployment_name: str :keyword allow_fallback: Specifies that the service is allowed to fall back to a general system when a custom system doesn't exist. Possible values are: true (default) or false. Default value is None. :paramtype allow_fallback: bool + :keyword translate_text_within_image: Optional boolean parameter to translate text within an + image in the document. Default value is None. + :paramtype translate_text_within_image: bool :return: Iterator[bytes] :rtype: Iterator[bytes] :raises ~azure.core.exceptions.HttpResponseError: @@ -501,16 +544,17 @@ def translate( _body = body.as_dict() if isinstance(body, _model_base.Model) else body _file_fields: List[str] = ["document", "glossary"] _data_fields: List[str] = [] - _files, _data = prepare_multipart_form_data(_body, _file_fields, _data_fields) + _files = prepare_multipart_form_data(_body, _file_fields, _data_fields) _request = build_single_document_translation_translate_request( target_language=target_language, source_language=source_language, category=category, + deployment_name=deployment_name, allow_fallback=allow_fallback, + translate_text_within_image=translate_text_within_image, api_version=self._config.api_version, files=_files, - data=_data, headers=_headers, params=_params, ) diff --git a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_patch.py b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_patch.py index 00f24ba7de30..f19f41f42fd5 100644 --- a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_patch.py +++ b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_patch.py @@ -1,3 +1,4 @@ +# pylint: disable=line-too-long,useless-suppression # ------------------------------------ # Copyright (c) Microsoft Corporation. # Licensed under the MIT License. @@ -17,6 +18,9 @@ from ._operations._patch import DocumentTranslationLROPoller, DocumentTranslationLROPollingMethod, TranslationPolling from ._client import DocumentTranslationClient as GeneratedDocumentTranslationClient +from ._client import SingleDocumentTranslationClient as GeneratedSingleDocumentTranslationClient +from ._operations._patch import DocumentTranslationClientOperationsMixin +from ._operations._patch import SingleDocumentTranslationClientOperationsMixin from .models import ( DocumentBatch, SourceInput, @@ -27,9 +31,10 @@ StartTranslationDetails, StorageInputType, DocumentTranslationFileFormat, + FileFormatType, TranslationStatus, - DocumentTranslationError, DocumentTranslationInput, + BatchOptions, ) from .models._patch import convert_status @@ -61,9 +66,11 @@ def convert_order_by(orderby: Optional[List[str]]) -> Optional[List[str]]: class DocumentTranslationApiVersion(str, Enum, metaclass=CaseInsensitiveEnumMeta): """Document Translation API versions supported by this package""" - #: This is the default version V2024_05_01 = "2024-05-01" + #: This is the default version + V2026_03_01 = "2026-03-01" + def get_translation_input(args, kwargs, continuation_token): if continuation_token: @@ -82,8 +89,16 @@ def get_translation_input(args, kwargs, continuation_token): request = inputs # backcompatibility elif len(inputs) > 0 and isinstance(inputs[0], DocumentTranslationInput): + translate_text_within_image = kwargs.pop("translate_text_within_image", None) # pylint: disable=protected-access - request = StartTranslationDetails(inputs=[input._to_generated() for input in inputs]) + request = StartTranslationDetails( + inputs=[input._to_generated() for input in inputs], + options=( + BatchOptions(translate_text_within_image=translate_text_within_image) + if translate_text_within_image is not None + else None + ), + ) else: try: source_url = kwargs.pop("source_url", None) @@ -102,6 +117,8 @@ def get_translation_input(args, kwargs, continuation_token): suffix = kwargs.pop("suffix", None) storage_type = kwargs.pop("storage_type", None) category_id = kwargs.pop("category_id", None) + deployment_name = kwargs.pop("deployment_name", None) + translate_text_within_image = kwargs.pop("translate_text_within_image", None) glossaries = kwargs.pop("glossaries", None) request = StartTranslationDetails( @@ -118,11 +135,17 @@ def get_translation_input(args, kwargs, continuation_token): language=target_language, glossaries=glossaries, category_id=category_id, + deployment_name=deployment_name, ) ], storage_type=storage_type, ) - ] + ], + options=( + BatchOptions(translate_text_within_image=translate_text_within_image) + if translate_text_within_image is not None + else None + ), ) except (AttributeError, TypeError, IndexError) as exc: raise ValueError( @@ -163,7 +186,7 @@ def get_http_logging_policy(**kwargs): return http_logging_policy -class DocumentTranslationClient(GeneratedDocumentTranslationClient): +class DocumentTranslationClient(DocumentTranslationClientOperationsMixin, GeneratedDocumentTranslationClient): def __init__(self, endpoint: str, credential: Union[AzureKeyCredential, TokenCredential], **kwargs: Any) -> None: """DocumentTranslationClient is your interface to the Document Translation service. Use the client to translate whole documents while preserving source document @@ -222,7 +245,7 @@ def close(self) -> None: """Close the :class:`~azure.ai.translation.document.DocumentTranslationClient` session.""" return self._client.close() - @overload + @overload # type: ignore[override] def begin_translation( self, source_url: str, @@ -235,6 +258,8 @@ def begin_translation( storage_type: Optional[Union[str, StorageInputType]] = None, category_id: Optional[str] = None, glossaries: Optional[List[TranslationGlossary]] = None, + deployment_name: Optional[str] = None, + translate_text_within_image: Optional[bool] = None, **kwargs: Any ) -> DocumentTranslationLROPoller[ItemPaged[DocumentStatus]]: """Begin translating the document(s) in your source container to your target container @@ -261,10 +286,14 @@ def begin_translation( translation. This is most often use for file extensions. :keyword storage_type: Storage type of the input documents source string. Possible values include: "Folder", "File". - :paramtype storage_type: str or ~azure.ai.translation.document.StorageInputType + :paramtype storage_type: str or ~azure.ai.translation.document.models.StorageInputType :keyword str category_id: Category / custom model ID for using custom translation. :keyword glossaries: Glossaries to apply to translation. - :paramtype glossaries: list[~azure.ai.translation.document.TranslationGlossary] + :paramtype glossaries: list[~azure.ai.translation.document.models.TranslationGlossary] + :keyword str deployment_name: Deployment name of the custom translation model for the + translation request. + :keyword bool translate_text_within_image: Whether to translate text embedded within images + in the documents. :return: An instance of a DocumentTranslationLROPoller. Call `result()` on the poller object to return a pageable of DocumentStatus. A DocumentStatus will be returned for each translation on a document. @@ -273,7 +302,7 @@ def begin_translation( """ @overload - def begin_translation( + def begin_translation( # pylint: disable=arguments-renamed self, inputs: StartTranslationDetails, **kwargs: Any ) -> DocumentTranslationLROPoller[ItemPaged[DocumentStatus]]: """Begin translating the document(s) in your source container to your target container @@ -294,7 +323,9 @@ def begin_translation( """ @overload - def begin_translation(self, inputs: JSON, **kwargs: Any) -> DocumentTranslationLROPoller[ItemPaged[DocumentStatus]]: + def begin_translation( # pylint: disable=arguments-renamed + self, inputs: JSON, **kwargs: Any + ) -> DocumentTranslationLROPoller[ItemPaged[DocumentStatus]]: """Begin translating the document(s) in your source container to your target container in the given language. @@ -350,7 +381,7 @@ def begin_translation(self, inputs: JSON, **kwargs: Any) -> DocumentTranslationL """ @overload - def begin_translation( + def begin_translation( # pylint: disable=arguments-renamed self, inputs: IO[bytes], **kwargs: Any ) -> DocumentTranslationLROPoller[ItemPaged[DocumentStatus]]: """Begin translating the document(s) in your source container to your target container @@ -371,7 +402,7 @@ def begin_translation( """ @overload - def begin_translation( + def begin_translation( # pylint: disable=arguments-renamed self, inputs: List[DocumentTranslationInput], **kwargs: Any ) -> DocumentTranslationLROPoller[ItemPaged[DocumentStatus]]: """Begin translating the document(s) in your source container to your target container @@ -383,7 +414,7 @@ def begin_translation( :param inputs: A list of translation inputs. Each individual input has a single source URL to documents and can contain multiple TranslationTargets (one for each language) for the destination to write translated documents. - :type inputs: List[~azure.ai.translation.document.DocumentTranslationInput] + :type inputs: List[~azure.ai.translation.document.models.DocumentTranslationInput] :return: An instance of a DocumentTranslationLROPoller. Call `result()` on the poller object to return a pageable of DocumentStatus. A DocumentStatus will be returned for each translation on a document. @@ -404,7 +435,7 @@ def begin_translation( # pylint: disable=docstring-missing-param,docstring-shou :param inputs: The translation inputs. Each individual input has a single source URL to documents and can contain multiple targets (one for each language) for the destination to write translated documents. - :type inputs: List[~azure.ai.translation.document.DocumentTranslationInput] or + :type inputs: List[~azure.ai.translation.document.models.DocumentTranslationInput] or IO[bytes] or JSON or ~azure.ai.translation.document.models.StartTranslationDetails :param str source_url: The source SAS URL to the Azure Blob container containing the documents to be translated. See the service documentation for the supported SAS permissions for accessing @@ -424,10 +455,10 @@ def begin_translation( # pylint: disable=docstring-missing-param,docstring-shou translation. This is most often use for file extensions. :keyword storage_type: Storage type of the input documents source string. Possible values include: "Folder", "File". - :paramtype storage_type: str or ~azure.ai.translation.document.StorageInputType + :paramtype storage_type: str or ~azure.ai.translation.document.models.StorageInputType :keyword str category_id: Category / custom model ID for using custom translation. :keyword glossaries: Glossaries to apply to translation. - :paramtype glossaries: list[~azure.ai.translation.document.TranslationGlossary] + :paramtype glossaries: list[~azure.ai.translation.document.models.TranslationGlossary] :return: An instance of a DocumentTranslationLROPoller. Call `result()` on the poller object to return a pageable of DocumentStatus. A DocumentStatus will be returned for each translation on a document. @@ -635,7 +666,7 @@ def get_supported_glossary_formats(self, **kwargs: Any) -> List[DocumentTranslat :raises ~azure.core.exceptions.HttpResponseError: """ - return super()._get_supported_formats(type="glossary", **kwargs).value + return super()._get_supported_formats(type=FileFormatType.GLOSSARY, **kwargs).value @distributed_trace def get_supported_document_formats(self, **kwargs: Any) -> List[DocumentTranslationFileFormat]: @@ -646,22 +677,34 @@ def get_supported_document_formats(self, **kwargs: Any) -> List[DocumentTranslat :raises ~azure.core.exceptions.HttpResponseError: """ - return super()._get_supported_formats(type="document", **kwargs).value + return super()._get_supported_formats(type=FileFormatType.DOCUMENT, **kwargs).value + + +class SingleDocumentTranslationClient( + SingleDocumentTranslationClientOperationsMixin, GeneratedSingleDocumentTranslationClient +): + """SingleDocumentTranslationClient is your interface to the Document Translation service to + translate a single document. + + :param endpoint: Supported document Translation endpoint, protocol and hostname, for example: + https://{TranslatorResourceName}.cognitiveservices.azure.com/translator. Required. + :type endpoint: str + :param credential: Credential used to authenticate requests to the service. Is either a key + credential type or a token credential type. Required. + :type credential: ~azure.core.credentials.AzureKeyCredential or + ~azure.core.credentials.TokenCredential + :keyword api_version: + The API version of the service to use for requests. It defaults to the latest service version. + Setting to an older version may result in reduced feature compatibility. + :paramtype api_version: str or ~azure.ai.translation.document.DocumentTranslationApiVersion + """ __all__: List[str] = [ "DocumentTranslationClient", + "SingleDocumentTranslationClient", "DocumentTranslationApiVersion", "DocumentTranslationLROPoller", - # re-export models at this level for backwards compatibility - "TranslationGlossary", - "TranslationTarget", - "DocumentTranslationInput", - "TranslationStatus", - "DocumentStatus", - "DocumentTranslationError", - "DocumentTranslationFileFormat", - "StorageInputType", ] # Add all objects you want publicly available to users at this package level diff --git a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_utils/__init__.py b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_utils/__init__.py new file mode 100644 index 000000000000..8026245c2abc --- /dev/null +++ b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_utils/__init__.py @@ -0,0 +1,6 @@ +# -------------------------------------------------------------------------- +# 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) Python Code Generator. +# Changes may cause incorrect behavior and will be lost if the code is regenerated. +# -------------------------------------------------------------------------- diff --git a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_model_base.py b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_utils/model_base.py similarity index 54% rename from sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_model_base.py rename to sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_utils/model_base.py index 382d5b2dffb0..0f2c5bdfe70f 100644 --- a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_model_base.py +++ b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_utils/model_base.py @@ -1,9 +1,10 @@ -# pylint: disable=too-many-lines +# pylint: disable=line-too-long,useless-suppression,too-many-lines # 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. +# Licensed under the MIT License. See License.txt in the project root for license information. +# Code generated by Microsoft (R) Python Code Generator. +# Changes may cause incorrect behavior and will be lost if the code is regenerated. # -------------------------------------------------------------------------- # pylint: disable=protected-access, broad-except @@ -21,17 +22,19 @@ from datetime import datetime, date, time, timedelta, timezone from json import JSONEncoder import xml.etree.ElementTree as ET -from typing_extensions import Self +from collections.abc import MutableMapping import isodate from azure.core.exceptions import DeserializationError from azure.core import CaseInsensitiveEnumMeta from azure.core.pipeline import PipelineResponse from azure.core.serialization import _Null -if sys.version_info >= (3, 9): - from collections.abc import MutableMapping +from azure.core.rest import HttpResponse + +if sys.version_info >= (3, 11): + from typing import Self else: - from typing import MutableMapping + from typing_extensions import Self _LOGGER = logging.getLogger(__name__) @@ -39,6 +42,7 @@ TZ_UTC = timezone.utc _T = typing.TypeVar("_T") +_NONE_TYPE = type(None) def _timedelta_as_isostr(td: timedelta) -> str: @@ -105,6 +109,29 @@ def _serialize_bytes(o, format: typing.Optional[str] = None) -> str: return encoded +def _serialize_duration(td: timedelta, format: typing.Optional[str] = None): + """Serialize a timedelta to its wire representation. + + For the ``seconds``/``milliseconds`` encodings the value is converted to a + numeric value, otherwise it falls back to an ISO 8601 duration string. + + :param timedelta td: The timedelta to serialize. + :param str format: The duration encoding format. + :rtype: int or float or str + :return: serialized duration + """ + seconds = td.total_seconds() + if format == "duration-seconds-int": + return int(seconds) + if format == "duration-seconds-float": + return seconds + if format == "duration-milliseconds-int": + return int(seconds * 1000) + if format == "duration-milliseconds-float": + return seconds * 1000 + return _timedelta_as_isostr(td) + + def _serialize_datetime(o, format: typing.Optional[str] = None): if hasattr(o, "year") and hasattr(o, "hour"): if format == "rfc7231": @@ -173,6 +200,21 @@ def default(self, o): # pylint: disable=too-many-return-statements r"(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\s\d{4}\s\d{2}:\d{2}:\d{2}\sGMT" ) +_ARRAY_ENCODE_MAPPING = { + "pipeDelimited": "|", + "spaceDelimited": " ", + "commaDelimited": ",", + "newlineDelimited": "\n", +} + + +def _deserialize_array_encoded(delimit: str, attr): + if isinstance(attr, str): + if attr == "": + return [] + return attr.split(delimit) + return attr + def _deserialize_datetime(attr: typing.Union[str, datetime]) -> datetime: """Deserialize ISO-8601 formatted string into Datetime object. @@ -204,7 +246,7 @@ def _deserialize_datetime(attr: typing.Union[str, datetime]) -> datetime: test_utc = date_obj.utctimetuple() if test_utc.tm_year > 9999 or test_utc.tm_year < 1: raise OverflowError("Hit max or min date") - return date_obj + return date_obj # type: ignore[no-any-return] def _deserialize_datetime_rfc7231(attr: typing.Union[str, datetime]) -> datetime: @@ -258,7 +300,7 @@ def _deserialize_time(attr: typing.Union[str, time]) -> time: """ if isinstance(attr, time): return attr - return isodate.parse_time(attr) + return isodate.parse_time(attr) # type: ignore[no-any-return] def _deserialize_bytes(attr): @@ -282,6 +324,12 @@ def _deserialize_duration(attr): return isodate.parse_duration(attr) +def _deserialize_duration_numeric(attr, unit): + if isinstance(attr, timedelta): + return attr + return timedelta(**{unit: float(attr)}) + + def _deserialize_decimal(attr): if isinstance(attr, decimal.Decimal): return attr @@ -311,12 +359,18 @@ def _deserialize_int_as_str(attr): "unix-timestamp": _deserialize_datetime_unix_timestamp, "base64": _deserialize_bytes, "base64url": _deserialize_bytes_base64, + "duration-seconds-int": functools.partial(_deserialize_duration_numeric, unit="seconds"), + "duration-seconds-float": functools.partial(_deserialize_duration_numeric, unit="seconds"), + "duration-milliseconds-int": functools.partial(_deserialize_duration_numeric, unit="milliseconds"), + "duration-milliseconds-float": functools.partial(_deserialize_duration_numeric, unit="milliseconds"), } def get_deserializer(annotation: typing.Any, rf: typing.Optional["_RestField"] = None): if annotation is int and rf and rf._format == "str": return _deserialize_int_as_str + if annotation is str and rf and rf._format in _ARRAY_ENCODE_MAPPING: + return functools.partial(_deserialize_array_encoded, _ARRAY_ENCODE_MAPPING[rf._format]) if rf and rf._format: return _DESERIALIZE_MAPPING_WITHFORMAT.get(rf._format) return _DESERIALIZE_MAPPING.get(annotation) # pyright: ignore @@ -347,17 +401,47 @@ def _get_model(module_name: str, model_name: str): _UNSET = object() -class _MyMutableMapping(MutableMapping[str, typing.Any]): # pylint: disable=unsubscriptable-object - def __init__(self, data: typing.Dict[str, typing.Any]) -> None: +class _MyMutableMapping(MutableMapping[str, typing.Any]): + def __init__(self, data: dict[str, typing.Any]) -> None: self._data = data def __contains__(self, key: typing.Any) -> bool: return key in self._data def __getitem__(self, key: str) -> typing.Any: + # If this key has been deserialized (for mutable types), we need to handle serialization + if hasattr(self, "_attr_to_rest_field"): + cache_attr = f"_deserialized_{key}" + if hasattr(self, cache_attr): + rf = _get_rest_field(getattr(self, "_attr_to_rest_field"), key) + if rf: + value = self._data.get(key) + if isinstance(value, (dict, list, set)): + # For mutable types, serialize and return + # But also update _data with serialized form and clear flag + # so mutations via this returned value affect _data + serialized = _serialize(value, rf._format) + # If serialized form is same type (no transformation needed), + # return _data directly so mutations work + if isinstance(serialized, type(value)) and serialized == value: + return self._data.get(key) + # Otherwise return serialized copy and clear flag + try: + object.__delattr__(self, cache_attr) + except AttributeError: + pass + # Store serialized form back + self._data[key] = serialized + return serialized return self._data.__getitem__(key) def __setitem__(self, key: str, value: typing.Any) -> None: + # Clear any cached deserialized value when setting through dictionary access + cache_attr = f"_deserialized_{key}" + try: + object.__delattr__(self, cache_attr) + except AttributeError: + pass self._data.__setitem__(key, value) def __delitem__(self, key: str) -> None: @@ -373,55 +457,105 @@ def __ne__(self, other: typing.Any) -> bool: return not self.__eq__(other) def keys(self) -> typing.KeysView[str]: + """ + :returns: a set-like object providing a view on the mapping's keys + :rtype: ~typing.KeysView + """ return self._data.keys() def values(self) -> typing.ValuesView[typing.Any]: + """ + :returns: an object providing a view on the mapping's values + :rtype: ~typing.ValuesView + """ return self._data.values() def items(self) -> typing.ItemsView[str, typing.Any]: + """ + :returns: a set-like object providing a view on the mapping's items + :rtype: ~typing.ItemsView + """ return self._data.items() def get(self, key: str, default: typing.Any = None) -> typing.Any: + """ + Get the value for key if key is in the dictionary, else default. + :param str key: The key to look up. + :param any default: The value to return if key is not in the dictionary. Defaults to None + :returns: The value for key if key is in the dictionary, else default. + :rtype: any + """ try: return self[key] except KeyError: return default @typing.overload - def pop(self, key: str) -> typing.Any: ... + def pop(self, key: str) -> typing.Any: ... # pylint: disable=arguments-differ @typing.overload - def pop(self, key: str, default: _T) -> _T: ... + def pop(self, key: str, default: _T) -> _T: ... # pylint: disable=signature-differs @typing.overload - def pop(self, key: str, default: typing.Any) -> typing.Any: ... + def pop(self, key: str, default: typing.Any) -> typing.Any: ... # pylint: disable=signature-differs def pop(self, key: str, default: typing.Any = _UNSET) -> typing.Any: + """ + Removes specified key and return the corresponding value. + :param str key: The key to pop. + :param any default: The value to return if key is not in the dictionary + :returns: The value corresponding to the key. + :rtype: any + :raises KeyError: If key is not found and default is not given. + """ if default is _UNSET: return self._data.pop(key) return self._data.pop(key, default) - def popitem(self) -> typing.Tuple[str, typing.Any]: + def popitem(self) -> tuple[str, typing.Any]: + """ + Removes and returns some (key, value) pair + :returns: The (key, value) pair. + :rtype: tuple + :raises KeyError: if the dictionary is empty. + """ return self._data.popitem() def clear(self) -> None: + """ + Remove all items from the dictionary. + """ self._data.clear() - def update(self, *args: typing.Any, **kwargs: typing.Any) -> None: + def update(self, *args: typing.Any, **kwargs: typing.Any) -> None: # pylint: disable=arguments-differ + """ + Update the dictionary from a mapping or an iterable of key-value pairs. + :param any args: Either a mapping object or an iterable of key-value pairs. + """ self._data.update(*args, **kwargs) @typing.overload def setdefault(self, key: str, default: None = None) -> None: ... @typing.overload - def setdefault(self, key: str, default: typing.Any) -> typing.Any: ... + def setdefault(self, key: str, default: typing.Any) -> typing.Any: ... # pylint: disable=signature-differs def setdefault(self, key: str, default: typing.Any = _UNSET) -> typing.Any: + """ + Return the value for key if key is in the dictionary; otherwise set the key to + default and return default. + :param str key: The key to look up. + :param any default: The value to set if key is not in the dictionary + :returns: The value for key if key is in the dictionary, else default. + :rtype: any + """ if default is _UNSET: return self._data.setdefault(key) return self._data.setdefault(key, default) def __eq__(self, other: typing.Any) -> bool: + if isinstance(other, _MyMutableMapping): + return self._data == other._data try: other_model = self.__class__(other) except Exception: @@ -438,6 +572,8 @@ def _is_model(obj: typing.Any) -> bool: def _serialize(o, format: typing.Optional[str] = None): # pylint: disable=too-many-return-statements if isinstance(o, list): + if format in _ARRAY_ENCODE_MAPPING and all(isinstance(x, str) for x in o): + return _ARRAY_ENCODE_MAPPING[format].join(o) return [_serialize(x, format) for x in o] if isinstance(o, dict): return {k: _serialize(v, format) for k, v in o.items()} @@ -462,16 +598,14 @@ def _serialize(o, format: typing.Optional[str] = None): # pylint: disable=too-m pass # Last, try datetime.timedelta try: - return _timedelta_as_isostr(o) + return _serialize_duration(o, format) except AttributeError: # This will be raised when it hits value.total_seconds in the method above pass return o -def _get_rest_field( - attr_to_rest_field: typing.Dict[str, "_RestField"], rest_name: str -) -> typing.Optional["_RestField"]: +def _get_rest_field(attr_to_rest_field: dict[str, "_RestField"], rest_name: str) -> typing.Optional["_RestField"]: try: return next(rf for rf in attr_to_rest_field.values() if rf._rest_name == rest_name) except StopIteration: @@ -490,69 +624,253 @@ def _create_value(rf: typing.Optional["_RestField"], value: typing.Any) -> typin return _serialize(value, rf._format) +# ============================================================================ +# Fast-path scalar deserializer functions for rest_field(deserializer=...) +# These are referenced from rest_field declarations to bypass the generic +# _deserialize -> _deserialize_with_callable chain. +# Only simple/primitive types — no models or container types. +# ============================================================================ + + +def _xml_deser_str(value): + if isinstance(value, ET.Element): + return value.text or "" + return str(value) if value is not None else None + + +def _xml_deser_int(value): + if isinstance(value, ET.Element): + return int(value.text) if value.text else None + return int(value) if value is not None else None + + +def _xml_deser_float(value): + if isinstance(value, ET.Element): + return float(value.text) if value.text else None + return float(value) if value is not None else None + + +def _xml_deser_bool(value): + if isinstance(value, ET.Element): + text = value.text + else: + text = value + if text is None: + return None + if text in (True, False): + return text + return text.lower() == "true" + + +# pylint: disable=docstring-missing-param +def _xml_deser_bytes(value): + """Deserialize bytes from XML (base64).""" + if isinstance(value, ET.Element): + text = value.text + else: + text = value + if text is None: + return None + return _deserialize_bytes(text) + + +def _xml_deser_bytes_base64url(value): + """Deserialize bytes from XML (base64url).""" + if isinstance(value, ET.Element): + text = value.text + else: + text = value + if text is None: + return None + return _deserialize_bytes_base64(text) + + +def _xml_deser_datetime(value): + """Deserialize a datetime from XML (ISO 8601 / rfc3339).""" + if isinstance(value, ET.Element): + text = value.text + else: + text = value + if text is None: + return None + return _deserialize_datetime(text) + + +def _xml_deser_datetime_rfc7231(value): + """Deserialize a datetime from XML (RFC7231 format).""" + if isinstance(value, ET.Element): + text = value.text + else: + text = value + if text is None: + return None + return _deserialize_datetime_rfc7231(text) + + +def _xml_deser_datetime_unix_timestamp(value): + """Deserialize a datetime from XML (Unix timestamp).""" + if isinstance(value, ET.Element): + text = value.text + else: + text = value + if text is None: + return None + return _deserialize_datetime_unix_timestamp(float(text)) + + +def _xml_deser_date(value): + """Deserialize a date from XML (ISO 8601).""" + if isinstance(value, ET.Element): + text = value.text + else: + text = value + if text is None: + return None + return _deserialize_date(text) + + +def _xml_deser_time(value): + """Deserialize a time from XML (ISO 8601).""" + if isinstance(value, ET.Element): + text = value.text + else: + text = value + if text is None: + return None + return _deserialize_time(text) + + +def _xml_deser_duration(value): + """Deserialize a timedelta from XML (ISO 8601 duration).""" + if isinstance(value, ET.Element): + text = value.text + else: + text = value + if text is None: + return None + return _deserialize_duration(text) + + +def _xml_deser_decimal(value): + """Deserialize a Decimal from XML.""" + if isinstance(value, ET.Element): + text = value.text + else: + text = value + if text is None: + return None + return _deserialize_decimal(text) + + +def _xml_deser_enum_or_str(enum_cls, value): + """Deserialize a Union[EnumType, str] from XML.""" + text = value.text if isinstance(value, ET.Element) else value + if text is None: + return None + try: + return enum_cls(text) + except ValueError: + return text + + +def _extract_xml_model_type(rf_type): + """Extract the concrete Model class from a resolved rf._type partial chain. + + Unwraps ``Optional[Model]`` and ``_deserialize_model(Model, ...)`` + wrappers. Only handles Model and Optional[Model] — other composite + types (List, Dict, Union, etc.) return None and fall through to the + generic ``_deserialize`` path at runtime. + """ + if rf_type is None: + return None + if isinstance(rf_type, type) and _is_model(rf_type): + return rf_type + if not isinstance(rf_type, functools.partial): + return None + func = rf_type.func + args = rf_type.args + if func is _deserialize_with_optional and args: + return _extract_xml_model_type(args[0]) + if func is _deserialize_model and args: + cls = args[0] + return cls if isinstance(cls, type) and _is_model(cls) else None + return None + + +def _build_xml_field_plan( # pylint: disable=docstring-missing-return, docstring-missing-rtype, unused-variable + cls, attr_to_rest_field: dict +) -> list: + """Build a precomputed XML field plan for fast _init_from_xml iteration. + + Called once per model class in __new__. Returns a list of tuples: + (rest_name, xml_name, kind, deser, rf_type, is_optional, items_name) + + kind: 0=wrapped, 1=attribute, 2=unwrapped, 3=text + + For Model and Optional[Model] fields that lack a scalar + ``_deserializer``, this function precomputes the Model class as the + deserializer so ``_init_from_xml`` can call ``ModelClass(element)`` + directly instead of going through the expensive + ``_get_deserialize_callable_from_annotation`` chain at runtime. + """ + model_meta = getattr(cls, "_xml", {}) + model_ns = model_meta.get("ns") or model_meta.get("namespace") + plan = [] + + for rf in attr_to_rest_field.values(): + prop_meta = getattr(rf, "_xml", {}) + deser = rf._deserializer + + xml_name = prop_meta.get("name", rf._rest_name) + xml_ns = _resolve_xml_ns(prop_meta, model_meta) + if xml_ns: + xml_name = "{" + xml_ns + "}" + xml_name + + is_optional = rf._is_optional + + # For Model / Optional[Model] fields without a scalar deserializer, + # precompute the Model class as the deserializer. + if deser is None and rf._type is not None: + model_cls = _extract_xml_model_type(rf._type) + if model_cls is not None: + deser = model_cls + + if prop_meta.get("attribute", False): + plan.append((rf._rest_name, xml_name, 1, deser, rf._type, is_optional, None)) + elif prop_meta.get("unwrapped", False): + items_name = prop_meta.get("itemsName") + if items_name: + items_ns = prop_meta.get("itemsNs") + if items_ns is not None: + xml_ns = items_ns + if xml_ns: + items_name = "{" + xml_ns + "}" + items_name + else: + items_name = xml_name + plan.append((rf._rest_name, xml_name, 2, deser, rf._type, is_optional, items_name)) + elif prop_meta.get("text", False): + plan.append((rf._rest_name, xml_name, 3, deser, rf._type, is_optional, None)) + else: + plan.append((rf._rest_name, xml_name, 0, deser, rf._type, is_optional, None)) + + return plan + + +# pylint: enable=docstring-missing-param class Model(_MyMutableMapping): _is_model = True # label whether current class's _attr_to_rest_field has been calculated # could not see _attr_to_rest_field directly because subclass inherits it from parent class - _calculated: typing.Set[str] = set() + _calculated: set[str] = set() def __init__(self, *args: typing.Any, **kwargs: typing.Any) -> None: class_name = self.__class__.__name__ if len(args) > 1: raise TypeError(f"{class_name}.__init__() takes 2 positional arguments but {len(args) + 1} were given") - dict_to_pass = { - rest_field._rest_name: rest_field._default - for rest_field in self._attr_to_rest_field.values() - if rest_field._default is not _UNSET - } - if args: # pylint: disable=too-many-nested-blocks + dict_to_pass: dict[str, typing.Any] = {} + if args: if isinstance(args[0], ET.Element): - existed_attr_keys = [] - model_meta = getattr(self, "_xml", {}) - - for rf in self._attr_to_rest_field.values(): - prop_meta = getattr(rf, "_xml", {}) - xml_name = prop_meta.get("name", rf._rest_name) - xml_ns = prop_meta.get("ns", model_meta.get("ns", None)) - if xml_ns: - xml_name = "{" + xml_ns + "}" + xml_name - - # attribute - if prop_meta.get("attribute", False) and args[0].get(xml_name) is not None: - existed_attr_keys.append(xml_name) - dict_to_pass[rf._rest_name] = _deserialize(rf._type, args[0].get(xml_name)) - continue - - # unwrapped element is array - if prop_meta.get("unwrapped", False): - # unwrapped array could either use prop items meta/prop meta - if prop_meta.get("itemsName"): - xml_name = prop_meta.get("itemsName") - xml_ns = prop_meta.get("itemNs") - if xml_ns: - xml_name = "{" + xml_ns + "}" + xml_name - items = args[0].findall(xml_name) # pyright: ignore - if len(items) > 0: - existed_attr_keys.append(xml_name) - dict_to_pass[rf._rest_name] = _deserialize(rf._type, items) - continue - - # text element is primitive type - if prop_meta.get("text", False): - if args[0].text is not None: - dict_to_pass[rf._rest_name] = _deserialize(rf._type, args[0].text) - continue - - # wrapped element could be normal property or array, it should only have one element - item = args[0].find(xml_name) - if item is not None: - existed_attr_keys.append(xml_name) - dict_to_pass[rf._rest_name] = _deserialize(rf._type, item) - - # rest thing is additional properties - for e in args[0]: - if e.tag not in existed_attr_keys: - dict_to_pass[e.tag] = _convert_element(e) + dict_to_pass.update(self._init_from_xml(args[0])) else: dict_to_pass.update( {k: _create_value(_get_rest_field(self._attr_to_rest_field, k), v) for k, v in args[0].items()} @@ -569,8 +887,117 @@ def __init__(self, *args: typing.Any, **kwargs: typing.Any) -> None: if v is not None } ) + # Apply client default values for fields the caller didn't set so that + # defaults are part of `_data` and therefore included during serialization. + for rf in self._attr_to_rest_field.values(): + if rf._default is _UNSET: + continue + if rf._rest_name in dict_to_pass: + continue + dict_to_pass[rf._rest_name] = _create_value(rf, rf._default) super().__init__(dict_to_pass) + def _init_from_xml( # pylint: disable=too-many-branches, too-many-statements + self, element: ET.Element + ) -> dict[str, typing.Any]: + """Deserialize an XML element into a dict mapping rest field names to values. + + :param ET.Element element: The XML element to deserialize from. + :returns: A dictionary of rest_name to deserialized value pairs. + :rtype: dict + """ + result: dict[str, typing.Any] = {} + existed_attr_keys: list[str] = [] + + field_plan = getattr(self, "_xml_field_plan", None) + if field_plan: + for rest_name, xml_name, kind, deser, rf_type, is_optional, items_name in field_plan: + if kind == 0: # wrapped element (most common) + item = element.find(xml_name) + if item is not None: + existed_attr_keys.append(xml_name) + if deser: + result[rest_name] = deser(item) + else: + result[rest_name] = _deserialize(rf_type, item) + elif kind == 1: # attribute + attr_val = element.get(xml_name) + if attr_val is not None: + existed_attr_keys.append(xml_name) + if deser: + result[rest_name] = deser(attr_val) + else: + result[rest_name] = attr_val + elif kind == 2: # unwrapped array + items = element.findall(items_name) # pyright: ignore + if len(items) > 0: + existed_attr_keys.append(items_name) + if deser: + result[rest_name] = deser(items) + else: + result[rest_name] = _deserialize(rf_type, items) + elif not is_optional: + existed_attr_keys.append(items_name) + result[rest_name] = [] + elif kind == 3: # text + if element.text is not None: + if deser: + result[rest_name] = deser(element.text) + else: + result[rest_name] = element.text + else: + model_meta = getattr(self, "_xml", {}) + for rf in self._attr_to_rest_field.values(): + prop_meta = getattr(rf, "_xml", {}) + xml_name = prop_meta.get("name", rf._rest_name) + xml_ns = _resolve_xml_ns(prop_meta, model_meta) + if xml_ns: + xml_name = "{" + xml_ns + "}" + xml_name + + # attribute + if prop_meta.get("attribute", False) and element.get(xml_name) is not None: + existed_attr_keys.append(xml_name) + result[rf._rest_name] = _deserialize(rf._type, element.get(xml_name)) + continue + + # unwrapped element is array + if prop_meta.get("unwrapped", False): + _items_name = prop_meta.get("itemsName") + if _items_name: + xml_name = _items_name + _items_ns = prop_meta.get("itemsNs") + if _items_ns is not None: + xml_ns = _items_ns + if xml_ns: + xml_name = "{" + xml_ns + "}" + xml_name + items = element.findall(xml_name) # pyright: ignore + if len(items) > 0: + existed_attr_keys.append(xml_name) + result[rf._rest_name] = _deserialize(rf._type, items) + elif not rf._is_optional: + existed_attr_keys.append(xml_name) + result[rf._rest_name] = [] + continue + + # text element is primitive type + if prop_meta.get("text", False): + if element.text is not None: + result[rf._rest_name] = _deserialize(rf._type, element.text) + continue + + # wrapped element could be normal property or array + item = element.find(xml_name) + if item is not None: + existed_attr_keys.append(xml_name) + result[rf._rest_name] = _deserialize(rf._type, item) + + # rest thing is additional properties + for e in element: + if e.tag not in existed_attr_keys: + result[e.tag] = _convert_element(e) + + return result + def copy(self) -> "Model": return Model(self.__dict__) @@ -579,7 +1006,7 @@ def __new__(cls, *args: typing.Any, **kwargs: typing.Any) -> Self: # we know the last nine classes in mro are going to be 'Model', '_MyMutableMapping', 'MutableMapping', # 'Mapping', 'Collection', 'Sized', 'Iterable', 'Container' and 'object' mros = cls.__mro__[:-9][::-1] # ignore parents, and reverse the mro order - attr_to_rest_field: typing.Dict[str, _RestField] = { # map attribute name to rest_field property + attr_to_rest_field: dict[str, _RestField] = { # map attribute name to rest_field property k: v for mro_class in mros for k, v in mro_class.__dict__.items() if k[0] != "_" and hasattr(v, "_type") } annotations = { @@ -594,10 +1021,13 @@ def __new__(cls, *args: typing.Any, **kwargs: typing.Any) -> Self: rf._type = rf._get_deserialize_callable_from_annotation(annotations.get(attr, None)) if not rf._rest_name_input: rf._rest_name_input = attr - cls._attr_to_rest_field: typing.Dict[str, _RestField] = dict(attr_to_rest_field.items()) + cls._attr_to_rest_field: dict[str, _RestField] = dict(attr_to_rest_field.items()) + # Build XML field plan for fast _init_from_xml (only for XML models) + if getattr(cls, "_xml", None): + cls._xml_field_plan = _build_xml_field_plan(cls, attr_to_rest_field) cls._calculated.add(f"{cls.__module__}.{cls.__qualname__}") - return super().__new__(cls) # pylint: disable=no-value-for-parameter + return super().__new__(cls) def __init_subclass__(cls, discriminator: typing.Optional[str] = None) -> None: for base in cls.__bases__: @@ -623,7 +1053,7 @@ def _deserialize(cls, data, exist_discriminators): model_meta = getattr(cls, "_xml", {}) prop_meta = getattr(discriminator, "_xml", {}) xml_name = prop_meta.get("name", discriminator._rest_name) - xml_ns = prop_meta.get("ns", model_meta.get("ns", None)) + xml_ns = _resolve_xml_ns(prop_meta, model_meta) if xml_ns: xml_name = "{" + xml_ns + "}" + xml_name @@ -636,7 +1066,7 @@ def _deserialize(cls, data, exist_discriminators): mapped_cls = cls.__mapping__.get(discriminator_value, cls) # pyright: ignore # pylint: disable=no-member return mapped_cls._deserialize(data, exist_discriminators) - def as_dict(self, *, exclude_readonly: bool = False) -> typing.Dict[str, typing.Any]: + def as_dict(self, *, exclude_readonly: bool = False) -> dict[str, typing.Any]: """Return a dict that can be turned into json using json.dump. :keyword bool exclude_readonly: Whether to remove the readonly properties. @@ -696,7 +1126,7 @@ def _deserialize_with_union(deserializers, obj): def _deserialize_dict( value_deserializer: typing.Optional[typing.Callable], module: typing.Optional[str], - obj: typing.Dict[typing.Any, typing.Any], + obj: dict[typing.Any, typing.Any], ): if obj is None: return obj @@ -706,7 +1136,7 @@ def _deserialize_dict( def _deserialize_multiple_sequence( - entry_deserializers: typing.List[typing.Optional[typing.Callable]], + entry_deserializers: list[typing.Optional[typing.Callable]], module: typing.Optional[str], obj, ): @@ -715,6 +1145,14 @@ def _deserialize_multiple_sequence( return type(obj)(_deserialize(deserializer, entry, module) for entry, deserializer in zip(obj, entry_deserializers)) +def _is_array_encoded_deserializer(deserializer: functools.partial) -> bool: + return ( + isinstance(deserializer, functools.partial) + and isinstance(deserializer.args[0], functools.partial) + and deserializer.args[0].func == _deserialize_array_encoded # pylint: disable=comparison-with-callable + ) + + def _deserialize_sequence( deserializer: typing.Optional[typing.Callable], module: typing.Optional[str], @@ -724,17 +1162,30 @@ def _deserialize_sequence( return obj if isinstance(obj, ET.Element): obj = list(obj) + + # encoded string may be deserialized to sequence + if isinstance(obj, str) and isinstance(deserializer, functools.partial): + # for list[str] + if _is_array_encoded_deserializer(deserializer): + return deserializer(obj) + + # for list[Union[...]] + if isinstance(deserializer.args[0], list): + for sub_deserializer in deserializer.args[0]: + if _is_array_encoded_deserializer(sub_deserializer): + return sub_deserializer(obj) + return type(obj)(_deserialize(deserializer, entry, module) for entry in obj) -def _sorted_annotations(types: typing.List[typing.Any]) -> typing.List[typing.Any]: +def _sorted_annotations(types: list[typing.Any]) -> list[typing.Any]: return sorted( types, key=lambda x: hasattr(x, "__name__") and x.__name__.lower() in ("str", "float", "int", "bool"), ) -def _get_deserialize_callable_from_annotation( # pylint: disable=too-many-return-statements, too-many-branches +def _get_deserialize_callable_from_annotation( # pylint: disable=too-many-return-statements, too-many-statements, too-many-branches annotation: typing.Any, module: typing.Optional[str], rf: typing.Optional["_RestField"] = None, @@ -754,7 +1205,7 @@ def _get_deserialize_callable_from_annotation( # pylint: disable=too-many-retur except AttributeError: model_name = annotation if module is not None: - annotation = _get_model(module, model_name) + annotation = _get_model(module, model_name) # type: ignore try: if module and _is_model(annotation): @@ -774,16 +1225,18 @@ def _get_deserialize_callable_from_annotation( # pylint: disable=too-many-retur # is it optional? try: - if any(a for a in annotation.__args__ if a == type(None)): # pyright: ignore # pylint: disable=unidiomatic-typecheck + if any(a is _NONE_TYPE for a in annotation.__args__): # pyright: ignore + if rf: + rf._is_optional = True if len(annotation.__args__) <= 2: # pyright: ignore if_obj_deserializer = _get_deserialize_callable_from_annotation( - next(a for a in annotation.__args__ if a != type(None)), module, rf # pyright: ignore # pylint: disable=unidiomatic-typecheck + next(a for a in annotation.__args__ if a is not _NONE_TYPE), module, rf # pyright: ignore ) return functools.partial(_deserialize_with_optional, if_obj_deserializer) # the type is Optional[Union[...]], we need to remove the None type from the Union annotation_copy = copy.copy(annotation) - annotation_copy.__args__ = [a for a in annotation_copy.__args__ if a != type(None)] # pyright: ignore # pylint: disable=unidiomatic-typecheck + annotation_copy.__args__ = [a for a in annotation_copy.__args__ if a is not _NONE_TYPE] # pyright: ignore return _get_deserialize_callable_from_annotation(annotation_copy, module, rf) except AttributeError: pass @@ -799,7 +1252,10 @@ def _get_deserialize_callable_from_annotation( # pylint: disable=too-many-retur return functools.partial(_deserialize_with_union, deserializers) try: - if annotation._name == "Dict": # pyright: ignore + annotation_name = ( + annotation.__name__ if hasattr(annotation, "__name__") else annotation._name # pyright: ignore + ) + if annotation_name.lower() == "dict": value_deserializer = _get_deserialize_callable_from_annotation( annotation.__args__[1], module, rf # pyright: ignore ) @@ -812,7 +1268,10 @@ def _get_deserialize_callable_from_annotation( # pylint: disable=too-many-retur except (AttributeError, IndexError): pass try: - if annotation._name in ["List", "Set", "Tuple", "Sequence"]: # pyright: ignore + annotation_name = ( + annotation.__name__ if hasattr(annotation, "__name__") else annotation._name # pyright: ignore + ) + if annotation_name.lower() in ["list", "set", "tuple", "sequence"]: if len(annotation.__args__) > 1: # pyright: ignore entry_deserializers = [ _get_deserialize_callable_from_annotation(dt, module, rf) @@ -861,16 +1320,20 @@ def _deserialize_with_callable( return float(value.text) if value.text else None if deserializer is bool: return value.text == "true" if value.text else None + if deserializer and deserializer in _DESERIALIZE_MAPPING.values(): + return deserializer(value.text) if value.text else None + if deserializer and deserializer in _DESERIALIZE_MAPPING_WITHFORMAT.values(): + return deserializer(value.text) if value.text else None if deserializer is None: return value if deserializer in [int, float, bool]: return deserializer(value) if isinstance(deserializer, CaseInsensitiveEnumMeta): try: - return deserializer(value) + return deserializer(value.text if isinstance(value, ET.Element) else value) except ValueError: # for unknown value, return raw value - return value + return value.text if isinstance(value, ET.Element) else value if isinstance(deserializer, type) and issubclass(deserializer, Model): return deserializer._deserialize(value, []) return typing.cast(typing.Callable[[typing.Any], typing.Any], deserializer)(value) @@ -894,6 +1357,36 @@ def _deserialize( return _deserialize_with_callable(deserializer, value) +def _failsafe_deserialize( + deserializer: typing.Any, + response: HttpResponse, + module: typing.Optional[str] = None, + rf: typing.Optional["_RestField"] = None, + format: typing.Optional[str] = None, +) -> typing.Any: + try: + return _deserialize(deserializer, response.json(), module, rf, format) + except Exception: # pylint: disable=broad-except + _LOGGER.warning( + "Ran into a deserialization error. Ignoring since this is failsafe deserialization", exc_info=True + ) + return None + + +def _failsafe_deserialize_xml( + deserializer: typing.Any, + response: HttpResponse, +) -> typing.Any: + try: + return _deserialize_xml(deserializer, response.text()) + except Exception: # pylint: disable=broad-except + _LOGGER.warning( + "Ran into a deserialization error. Ignoring since this is failsafe deserialization", exc_info=True + ) + return None + + +# pylint: disable=too-many-instance-attributes class _RestField: def __init__( self, @@ -901,11 +1394,12 @@ def __init__( name: typing.Optional[str] = None, type: typing.Optional[typing.Callable] = None, # pylint: disable=redefined-builtin is_discriminator: bool = False, - visibility: typing.Optional[typing.List[str]] = None, + visibility: typing.Optional[list[str]] = None, default: typing.Any = _UNSET, format: typing.Optional[str] = None, is_multipart_file_input: bool = False, - xml: typing.Optional[typing.Dict[str, typing.Any]] = None, + xml: typing.Optional[dict[str, typing.Any]] = None, + deserializer: typing.Optional[typing.Callable] = None, ): self._type = type self._rest_name_input = name @@ -913,14 +1407,20 @@ def __init__( self._is_discriminator = is_discriminator self._visibility = visibility self._is_model = False + self._is_optional = False self._default = default self._format = format self._is_multipart_file_input = is_multipart_file_input self._xml = xml if xml is not None else {} + self._deserializer = deserializer @property def _class_type(self) -> typing.Any: - return getattr(self._type, "args", [None])[0] + result = getattr(self._type, "args", [None])[0] + # type may be wrapped by nested functools.partial so we need to check for that + if isinstance(result, functools.partial): + return getattr(result, "args", [None])[0] + return result @property def _rest_name(self) -> str: @@ -931,14 +1431,44 @@ def _rest_name(self) -> str: def __get__(self, obj: Model, type=None): # pylint: disable=redefined-builtin # by this point, type and rest_name will have a value bc we default # them in __new__ of the Model class - item = obj.get(self._rest_name) + # Use _data.get() directly to avoid triggering __getitem__ which clears the cache + item = obj._data.get(self._rest_name, _UNSET) + if item is _UNSET: + # Field not set by user; return the client default if one exists, otherwise None + return self._default if self._default is not _UNSET else None if item is None: return item if self._is_model: return item - return _deserialize(self._type, _serialize(item, self._format), rf=self) + + # For mutable types, we want mutations to directly affect _data + # Check if we've already deserialized this value + cache_attr = f"_deserialized_{self._rest_name}" + if hasattr(obj, cache_attr): + # Return the value from _data directly (it's been deserialized in place) + return obj._data.get(self._rest_name) + + # Fast path: use _deserializer directly (avoids _serialize/_deserialize chain) + if self._deserializer: + deserialized = self._deserializer(item) + else: + deserialized = _deserialize(self._type, _serialize(item, self._format), rf=self) + + # For mutable types, store the deserialized value back in _data + # so mutations directly affect _data + if isinstance(deserialized, (dict, list, set)): + obj._data[self._rest_name] = deserialized + object.__setattr__(obj, cache_attr, True) # Mark as deserialized + return deserialized + + return deserialized def __set__(self, obj: Model, value) -> None: + # Clear the cached deserialized object when setting a new value + cache_attr = f"_deserialized_{self._rest_name}" + if hasattr(obj, cache_attr): + object.__delattr__(obj, cache_attr) + if value is None: # we want to wipe out entries if users set attr to None try: @@ -963,11 +1493,12 @@ def rest_field( *, name: typing.Optional[str] = None, type: typing.Optional[typing.Callable] = None, # pylint: disable=redefined-builtin - visibility: typing.Optional[typing.List[str]] = None, + visibility: typing.Optional[list[str]] = None, default: typing.Any = _UNSET, format: typing.Optional[str] = None, is_multipart_file_input: bool = False, - xml: typing.Optional[typing.Dict[str, typing.Any]] = None, + xml: typing.Optional[dict[str, typing.Any]] = None, + deserializer: typing.Optional[typing.Callable] = None, ) -> typing.Any: return _RestField( name=name, @@ -977,6 +1508,7 @@ def rest_field( format=format, is_multipart_file_input=is_multipart_file_input, xml=xml, + deserializer=deserializer, ) @@ -984,8 +1516,8 @@ def rest_discriminator( *, name: typing.Optional[str] = None, type: typing.Optional[typing.Callable] = None, # pylint: disable=redefined-builtin - visibility: typing.Optional[typing.List[str]] = None, - xml: typing.Optional[typing.Dict[str, typing.Any]] = None, + visibility: typing.Optional[list[str]] = None, + xml: typing.Optional[dict[str, typing.Any]] = None, ) -> typing.Any: return _RestField(name=name, type=type, is_discriminator=True, visibility=visibility, xml=xml) @@ -1001,21 +1533,77 @@ def serialize_xml(model: Model, exclude_readonly: bool = False) -> str: return ET.tostring(_get_element(model, exclude_readonly), encoding="unicode") # type: ignore +def _get_xml_ns(meta: dict[str, typing.Any]) -> typing.Optional[str]: + """Return the XML namespace from a metadata dict, checking both 'ns' (old-style) and 'namespace' (DPG) keys. + + :param dict meta: The metadata dictionary to extract namespace from. + :returns: The namespace string if 'ns' or 'namespace' key is present, None otherwise. + :rtype: str or None + """ + ns = meta.get("ns") + if ns is None: + ns = meta.get("namespace") + return ns + + +def _resolve_xml_ns( + prop_meta: dict[str, typing.Any], model_meta: typing.Optional[dict[str, typing.Any]] = None +) -> typing.Optional[str]: + """Resolve XML namespace for a property, falling back to model namespace when appropriate. + + Checks the property metadata first; if no namespace is found and the model does not declare + an explicit prefix, falls back to the model-level namespace. + + :param dict prop_meta: The property metadata dictionary. + :param dict model_meta: The model metadata dictionary, used as fallback. + :returns: The resolved namespace string, or None. + :rtype: str or None + """ + ns = _get_xml_ns(prop_meta) + if ns is None and model_meta is not None and not model_meta.get("prefix"): + ns = _get_xml_ns(model_meta) + return ns + + +def _set_xml_attribute(element: ET.Element, name: str, value: typing.Any, prop_meta: dict[str, typing.Any]) -> None: + """Set an XML attribute on an element, handling namespace prefix registration. + + :param ET.Element element: The element to set the attribute on. + :param str name: The default attribute name (wire name). + :param any value: The attribute value. + :param dict prop_meta: The property metadata dictionary. + """ + xml_name = prop_meta.get("name", name) + _attr_ns = _get_xml_ns(prop_meta) + if _attr_ns: + _attr_prefix = prop_meta.get("prefix") + if _attr_prefix: + _safe_register_namespace(_attr_prefix, _attr_ns) + xml_name = "{" + _attr_ns + "}" + xml_name + element.set(xml_name, _get_primitive_type_value(value)) + + def _get_element( o: typing.Any, exclude_readonly: bool = False, - parent_meta: typing.Optional[typing.Dict[str, typing.Any]] = None, + parent_meta: typing.Optional[dict[str, typing.Any]] = None, wrapped_element: typing.Optional[ET.Element] = None, -) -> typing.Union[ET.Element, typing.List[ET.Element]]: +) -> typing.Union[ET.Element, list[ET.Element]]: if _is_model(o): model_meta = getattr(o, "_xml", {}) # if prop is a model, then use the prop element directly, else generate a wrapper of model if wrapped_element is None: + # When serializing as an array item (parent_meta is set), check if the parent has an + # explicit itemsName. This ensures correct element names for unwrapped arrays (where + # the element tag is the property/items name, not the model type name). + _items_name = parent_meta.get("itemsName") if parent_meta is not None else None + element_name = _items_name if _items_name else (model_meta.get("name") or o.__class__.__name__) + _model_ns = _get_xml_ns(model_meta) wrapped_element = _create_xml_element( - model_meta.get("name", o.__class__.__name__), + element_name, model_meta.get("prefix"), - model_meta.get("ns"), + _model_ns, ) readonly_props = [] @@ -1037,7 +1625,9 @@ def _get_element( # additional properties will not have rest field, use the wire name as xml name prop_meta = {"name": k} - # if no ns for prop, use model's + # Propagate model namespace to properties only for old-style "ns"-keyed models. + # DPG-generated models use the "namespace" key and explicitly declare namespace on + # each property that needs it, so propagation is intentionally skipped for them. if prop_meta.get("ns") is None and model_meta.get("ns"): prop_meta["ns"] = model_meta.get("ns") prop_meta["prefix"] = model_meta.get("prefix") @@ -1049,12 +1639,7 @@ def _get_element( # text could only set on primitive type wrapped_element.text = _get_primitive_type_value(v) elif prop_meta.get("attribute", False): - xml_name = prop_meta.get("name", k) - if prop_meta.get("ns"): - ET.register_namespace(prop_meta.get("prefix"), prop_meta.get("ns")) # pyright: ignore - xml_name = "{" + prop_meta.get("ns") + "}" + xml_name # pyright: ignore - # attribute should be primitive type - wrapped_element.set(xml_name, _get_primitive_type_value(v)) + _set_xml_attribute(wrapped_element, k, v, prop_meta) else: # other wrapped prop element wrapped_element.append(_get_wrapped_element(v, exclude_readonly, prop_meta)) @@ -1063,6 +1648,7 @@ def _get_element( return [_get_element(x, exclude_readonly, parent_meta) for x in o] # type: ignore if isinstance(o, dict): result = [] + _dict_ns = _get_xml_ns(parent_meta) if parent_meta else None for k, v in o.items(): result.append( _get_wrapped_element( @@ -1070,7 +1656,7 @@ def _get_element( exclude_readonly, { "name": k, - "ns": parent_meta.get("ns") if parent_meta else None, + "ns": _dict_ns, "prefix": parent_meta.get("prefix") if parent_meta else None, }, ) @@ -1079,13 +1665,16 @@ def _get_element( # primitive case need to create element based on parent_meta if parent_meta: + _items_ns = parent_meta.get("itemsNs") + if _items_ns is None: + _items_ns = _get_xml_ns(parent_meta) return _get_wrapped_element( o, exclude_readonly, { "name": parent_meta.get("itemsName", parent_meta.get("name")), "prefix": parent_meta.get("itemsPrefix", parent_meta.get("prefix")), - "ns": parent_meta.get("itemsNs", parent_meta.get("ns")), + "ns": _items_ns, }, ) @@ -1095,10 +1684,11 @@ def _get_element( def _get_wrapped_element( v: typing.Any, exclude_readonly: bool, - meta: typing.Optional[typing.Dict[str, typing.Any]], + meta: typing.Optional[dict[str, typing.Any]], ) -> ET.Element: + _meta_ns = _get_xml_ns(meta) if meta else None wrapped_element = _create_xml_element( - meta.get("name") if meta else None, meta.get("prefix") if meta else None, meta.get("ns") if meta else None + meta.get("name") if meta else None, meta.get("prefix") if meta else None, _meta_ns ) if isinstance(v, (dict, list)): wrapped_element.extend(_get_element(v, exclude_readonly, meta)) @@ -1106,7 +1696,7 @@ def _get_wrapped_element( _get_element(v, exclude_readonly, meta, wrapped_element) else: wrapped_element.text = _get_primitive_type_value(v) - return wrapped_element + return wrapped_element # type: ignore[no-any-return] def _get_primitive_type_value(v) -> str: @@ -1119,9 +1709,29 @@ def _get_primitive_type_value(v) -> str: return str(v) -def _create_xml_element(tag, prefix=None, ns=None): - if prefix and ns: +def _safe_register_namespace(prefix: str, ns: str) -> None: + """Register an XML namespace prefix, handling reserved prefix patterns. + + Some prefixes (e.g. 'ns2') match Python's reserved 'ns\\d+' pattern used for + auto-generated prefixes, causing register_namespace to raise ValueError. + Falls back to directly registering in the internal namespace map. + + :param str prefix: The namespace prefix to register. + :param str ns: The namespace URI. + """ + try: ET.register_namespace(prefix, ns) + except ValueError: + _ns_map = getattr(ET, "_namespace_map", None) + if _ns_map is not None: + _ns_map[ns] = prefix + + +def _create_xml_element( + tag: typing.Any, prefix: typing.Optional[str] = None, ns: typing.Optional[str] = None +) -> ET.Element: + if prefix and ns: + _safe_register_namespace(prefix, ns) if ns: return ET.Element("{" + ns + "}" + tag) return ET.Element(tag) @@ -1132,13 +1742,15 @@ def _deserialize_xml( value: str, ) -> typing.Any: element = ET.fromstring(value) # nosec + if _is_model(deserializer): + return deserializer._deserialize(element, []) return _deserialize(deserializer, element) def _convert_element(e: ET.Element): # dict case if len(e.attrib) > 0 or len({child.tag for child in e}) > 1: - dict_result: typing.Dict[str, typing.Any] = {} + dict_result: dict[str, typing.Any] = {} for child in e: if dict_result.get(child.tag) is not None: if isinstance(dict_result[child.tag], list): @@ -1151,7 +1763,7 @@ def _convert_element(e: ET.Element): return dict_result # array case if len(e) > 0: - array_result: typing.List[typing.Any] = [] + array_result: list[typing.Any] = [] for child in e: array_result.append(_convert_element(child)) return array_result diff --git a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_serialization.py b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_utils/serialization.py similarity index 88% rename from sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_serialization.py rename to sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_utils/serialization.py index 046f0d04d22a..75906e2eb77f 100644 --- a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_serialization.py +++ b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_utils/serialization.py @@ -1,28 +1,10 @@ -# pylint: disable=too-many-lines +# pylint: disable=line-too-long,useless-suppression,too-many-lines +# coding=utf-8 # -------------------------------------------------------------------------- -# # Copyright (c) Microsoft Corporation. All rights reserved. -# -# The MIT License (MIT) -# -# Permission is hereby granted, free of charge, to any person obtaining a copy -# of this software and associated documentation files (the ""Software""), to -# deal in the Software without restriction, including without limitation the -# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or -# sell copies of the Software, and to permit persons to whom the Software is -# furnished to do so, subject to the following conditions: -# -# The above copyright notice and this permission notice shall be included in -# all copies or substantial portions of the Software. -# -# THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING -# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS -# IN THE SOFTWARE. -# +# Licensed under the MIT License. See License.txt in the project root for license information. +# Code generated by Microsoft (R) Python Code Generator. +# Changes may cause incorrect behavior and will be lost if the code is regenerated. # -------------------------------------------------------------------------- # pyright: reportUnnecessaryTypeIgnoreComment=false @@ -39,7 +21,6 @@ import sys import codecs from typing import ( - Dict, Any, cast, Optional, @@ -48,10 +29,7 @@ IO, Mapping, Callable, - TypeVar, MutableMapping, - Type, - List, ) try: @@ -65,9 +43,13 @@ from azure.core.exceptions import DeserializationError, SerializationError from azure.core.serialization import NULL as CoreNull +if sys.version_info >= (3, 11): + from typing import Self +else: + from typing_extensions import Self + _BOM = codecs.BOM_UTF8.decode(encoding="utf-8") -ModelType = TypeVar("ModelType", bound="Model") JSON = MutableMapping[str, Any] @@ -185,73 +167,7 @@ def deserialize_from_http_generics(cls, body_bytes: Optional[Union[AnyStr, IO]], except NameError: _long_type = int - -class UTC(datetime.tzinfo): - """Time Zone info for handling UTC""" - - def utcoffset(self, dt): # pylint: disable=unused-argument - """UTF offset for UTC is 0. - - :param datetime.datetime dt: The datetime - :returns: The offset - :rtype: datetime.timedelta - """ - return datetime.timedelta(0) - - def tzname(self, dt): # pylint: disable=unused-argument - """Timestamp representation. - - :param datetime.datetime dt: The datetime - :returns: The timestamp representation - :rtype: str - """ - return "Z" - - def dst(self, dt): # pylint: disable=unused-argument - """No daylight saving for UTC. - - :param datetime.datetime dt: The datetime - :returns: The daylight saving time - :rtype: datetime.timedelta - """ - return datetime.timedelta(hours=1) - - -try: - from datetime import timezone as _FixedOffset # type: ignore -except ImportError: # Python 2.7 - - class _FixedOffset(datetime.tzinfo): # type: ignore - """Fixed offset in minutes east from UTC. - Copy/pasted from Python doc - :param datetime.timedelta offset: offset in timedelta format - """ - - def __init__(self, offset) -> None: - self.__offset = offset - - def utcoffset(self, dt): # pylint: disable=unused-argument - return self.__offset - - def tzname(self, dt): # pylint: disable=unused-argument - return str(self.__offset.total_seconds() / 3600) - - def __repr__(self): - return "".format(self.tzname(None)) - - def dst(self, dt): # pylint: disable=unused-argument - return datetime.timedelta(0) - - def __getinitargs__(self): - return (self.__offset,) - - -try: - from datetime import timezone - - TZ_UTC = timezone.utc -except ImportError: - TZ_UTC = UTC() # type: ignore +TZ_UTC = datetime.timezone.utc _FLATTEN = re.compile(r"(? None: - self.additional_properties: Optional[Dict[str, Any]] = {} + self.additional_properties: Optional[dict[str, Any]] = {} for k in kwargs: # pylint: disable=consider-using-dict-items if k not in self._attribute_map: _LOGGER.warning("%s is not a known attribute of class %s and will be ignored", k, self.__class__) @@ -397,7 +313,7 @@ def serialize(self, keep_readonly: bool = False, **kwargs: Any) -> JSON: def as_dict( self, keep_readonly: bool = True, - key_transformer: Callable[[str, Dict[str, Any], Any], Any] = attribute_transformer, + key_transformer: Callable[[str, dict[str, Any], Any], Any] = attribute_transformer, **kwargs: Any ) -> JSON: """Return a dict that can be serialized using json.dump. @@ -450,25 +366,25 @@ def _infer_class_models(cls): return client_models @classmethod - def deserialize(cls: Type[ModelType], data: Any, content_type: Optional[str] = None) -> ModelType: + def deserialize(cls, data: Any, content_type: Optional[str] = None) -> Self: """Parse a str using the RestAPI syntax and return a model. :param str data: A str using RestAPI structure. JSON by default. :param str content_type: JSON by default, set application/xml if XML. :returns: An instance of this model - :raises: DeserializationError if something went wrong - :rtype: ModelType + :raises DeserializationError: if something went wrong + :rtype: Self """ deserializer = Deserializer(cls._infer_class_models()) return deserializer(cls.__name__, data, content_type=content_type) # type: ignore @classmethod def from_dict( - cls: Type[ModelType], + cls, data: Any, - key_extractors: Optional[Callable[[str, Dict[str, Any], Any], Any]] = None, + key_extractors: Optional[Callable[[str, dict[str, Any], Any], Any]] = None, content_type: Optional[str] = None, - ) -> ModelType: + ) -> Self: """Parse a dict using given key extractor return a model. By default consider key @@ -479,8 +395,8 @@ def from_dict( :param function key_extractors: A key extractor function. :param str content_type: JSON by default, set application/xml if XML. :returns: An instance of this model - :raises: DeserializationError if something went wrong - :rtype: ModelType + :raises DeserializationError: if something went wrong + :rtype: Self """ deserializer = Deserializer(cls._infer_class_models()) deserializer.key_extractors = ( # type: ignore @@ -500,7 +416,7 @@ def _flatten_subtype(cls, key, objects): return {} result = dict(cls._subtype_map[key]) for valuetype in cls._subtype_map[key].values(): - result.update(objects[valuetype]._flatten_subtype(key, objects)) # pylint: disable=protected-access + result |= objects[valuetype]._flatten_subtype(key, objects) # pylint: disable=protected-access return result @classmethod @@ -563,7 +479,7 @@ def _decode_attribute_map_key(key): return key.replace("\\.", ".") -class Serializer(object): # pylint: disable=too-many-public-methods +class Serializer: # pylint: disable=too-many-public-methods """Request object model serializer.""" basic_types = {str: "str", int: "int", bool: "bool", float: "float"} @@ -604,6 +520,10 @@ def __init__(self, classes: Optional[Mapping[str, type]] = None) -> None: "rfc-1123": Serializer.serialize_rfc, "unix-time": Serializer.serialize_unix, "duration": Serializer.serialize_duration, + "duration-seconds-int": Serializer.serialize_duration_seconds_int, + "duration-seconds-float": Serializer.serialize_duration_seconds_float, + "duration-milliseconds-int": Serializer.serialize_duration_milliseconds_int, + "duration-milliseconds-float": Serializer.serialize_duration_milliseconds_float, "date": Serializer.serialize_date, "time": Serializer.serialize_time, "decimal": Serializer.serialize_decimal, @@ -614,7 +534,7 @@ def __init__(self, classes: Optional[Mapping[str, type]] = None) -> None: "[]": self.serialize_iter, "{}": self.serialize_dict, } - self.dependencies: Dict[str, type] = dict(classes) if classes else {} + self.dependencies: dict[str, type] = dict(classes) if classes else {} self.key_transformer = full_restapi_key_transformer self.client_side_validation = True @@ -626,7 +546,7 @@ def _serialize( # pylint: disable=too-many-nested-blocks, too-many-branches, to :param object target_obj: The data to be serialized. :param str data_type: The type to be serialized from. :rtype: str, dict - :raises: SerializationError if serialization fails. + :raises SerializationError: if serialization fails. :returns: The serialized data. """ key_transformer = kwargs.get("key_transformer", self.key_transformer) @@ -665,7 +585,7 @@ def _serialize( # pylint: disable=too-many-nested-blocks, too-many-branches, to if attr_name == "additional_properties" and attr_desc["key"] == "": if target_obj.additional_properties is not None: - serialized.update(target_obj.additional_properties) + serialized |= target_obj.additional_properties continue try: @@ -736,8 +656,8 @@ def body(self, data, data_type, **kwargs): :param object data: The data to be serialized. :param str data_type: The type to be serialized from. :rtype: dict - :raises: SerializationError if serialization fails. - :raises: ValueError if data is None + :raises SerializationError: if serialization fails. + :raises ValueError: if data is None :returns: The serialized request body """ @@ -781,8 +701,8 @@ def url(self, name, data, data_type, **kwargs): :param str data_type: The type to be serialized from. :rtype: str :returns: The serialized URL path - :raises: TypeError if serialization fails. - :raises: ValueError if data is None + :raises TypeError: if serialization fails. + :raises ValueError: if data is None """ try: output = self.serialize_data(data, data_type, **kwargs) @@ -805,8 +725,8 @@ def query(self, name, data, data_type, **kwargs): :param object data: The data to be serialized. :param str data_type: The type to be serialized from. :rtype: str, list - :raises: TypeError if serialization fails. - :raises: ValueError if data is None + :raises TypeError: if serialization fails. + :raises ValueError: if data is None :returns: The serialized query parameter """ try: @@ -835,8 +755,8 @@ def header(self, name, data, data_type, **kwargs): :param object data: The data to be serialized. :param str data_type: The type to be serialized from. :rtype: str - :raises: TypeError if serialization fails. - :raises: ValueError if data is None + :raises TypeError: if serialization fails. + :raises ValueError: if data is None :returns: The serialized header """ try: @@ -855,9 +775,9 @@ def serialize_data(self, data, data_type, **kwargs): :param object data: The data to be serialized. :param str data_type: The type to be serialized from. - :raises: AttributeError if required data is None. - :raises: ValueError if data is None - :raises: SerializationError if serialization fails. + :raises AttributeError: if required data is None. + :raises ValueError: if data is None + :raises SerializationError: if serialization fails. :returns: The serialized data. :rtype: str, int, float, bool, dict, list """ @@ -875,7 +795,7 @@ def serialize_data(self, data, data_type, **kwargs): # If dependencies is empty, try with current data class # It has to be a subclass of Enum anyway - enum_type = self.dependencies.get(data_type, data.__class__) + enum_type = self.dependencies.get(data_type, cast(type, data.__class__)) if issubclass(enum_type, Enum): return Serializer.serialize_enum(data, enum_obj=enum_type) @@ -909,13 +829,20 @@ def serialize_basic(cls, data, data_type, **kwargs): :param str data_type: Type of object in the iterable. :rtype: str, int, float, bool :return: serialized object + :raises TypeError: raise if data_type is not one of str, int, float, bool. """ custom_serializer = cls._get_custom_serializers(data_type, **kwargs) if custom_serializer: return custom_serializer(data) if data_type == "str": return cls.serialize_unicode(data) - return eval(data_type)(data) # nosec # pylint: disable=eval-used + if data_type == "int": + return int(data) + if data_type == "float": + return float(data) + if data_type == "bool": + return bool(data) + raise TypeError("Unknown basic data type: {}".format(data_type)) @classmethod def serialize_unicode(cls, data): @@ -1186,13 +1113,68 @@ def serialize_duration(attr, **kwargs): # pylint: disable=unused-argument attr = isodate.parse_duration(attr) return isodate.duration_isoformat(attr) + @staticmethod + def _serialize_duration_numeric(attr, scale, as_int): + """Serialize a TimeDelta into a numeric value scaled to the wire unit. + + :param TimeDelta attr: Object to be serialized. + :param int scale: Multiplier applied to total seconds (1 for seconds, 1000 for milliseconds). + :param bool as_int: Whether to truncate the result to an int. + :rtype: int or float + :return: serialized duration + """ + if isinstance(attr, str): + attr = isodate.parse_duration(attr) + value = attr.total_seconds() * scale if isinstance(attr, datetime.timedelta) else attr + return int(value) if as_int else float(value) + + @staticmethod + def serialize_duration_seconds_int(attr, **kwargs): # pylint: disable=unused-argument + """Serialize TimeDelta object into an integer number of seconds. + + :param TimeDelta attr: Object to be serialized. + :rtype: int + :return: serialized duration + """ + return Serializer._serialize_duration_numeric(attr, 1, True) + + @staticmethod + def serialize_duration_seconds_float(attr, **kwargs): # pylint: disable=unused-argument + """Serialize TimeDelta object into a floating point number of seconds. + + :param TimeDelta attr: Object to be serialized. + :rtype: float + :return: serialized duration + """ + return Serializer._serialize_duration_numeric(attr, 1, False) + + @staticmethod + def serialize_duration_milliseconds_int(attr, **kwargs): # pylint: disable=unused-argument + """Serialize TimeDelta object into an integer number of milliseconds. + + :param TimeDelta attr: Object to be serialized. + :rtype: int + :return: serialized duration + """ + return Serializer._serialize_duration_numeric(attr, 1000, True) + + @staticmethod + def serialize_duration_milliseconds_float(attr, **kwargs): # pylint: disable=unused-argument + """Serialize TimeDelta object into a floating point number of milliseconds. + + :param TimeDelta attr: Object to be serialized. + :rtype: float + :return: serialized duration + """ + return Serializer._serialize_duration_numeric(attr, 1000, False) + @staticmethod def serialize_rfc(attr, **kwargs): # pylint: disable=unused-argument """Serialize Datetime object into RFC-1123 formatted string. :param Datetime attr: Object to be serialized. :rtype: str - :raises: TypeError if format invalid. + :raises TypeError: if format invalid. :return: serialized rfc """ try: @@ -1218,7 +1200,7 @@ def serialize_iso(attr, **kwargs): # pylint: disable=unused-argument :param Datetime attr: Object to be serialized. :rtype: str - :raises: SerializationError if format invalid. + :raises SerializationError: if format invalid. :return: serialized iso """ if isinstance(attr, str): @@ -1251,7 +1233,7 @@ def serialize_unix(attr, **kwargs): # pylint: disable=unused-argument :param Datetime attr: Object to be serialized. :rtype: int - :raises: SerializationError if format invalid + :raises SerializationError: if format invalid :return: serialied unix """ if isinstance(attr, int): @@ -1270,7 +1252,7 @@ def rest_key_extractor(attr, attr_desc, data): # pylint: disable=unused-argumen while "." in key: # Need the cast, as for some reasons "split" is typed as list[str | Any] - dict_keys = cast(List[str], _FLATTEN.split(key)) + dict_keys = cast(list[str], _FLATTEN.split(key)) if len(dict_keys) == 1: key = _decode_attribute_map_key(dict_keys[0]) break @@ -1429,7 +1411,7 @@ def xml_key_extractor(attr, attr_desc, data): # pylint: disable=unused-argument # Iter and wrapped, should have found one node only (the wrap one) if len(children) != 1: raise DeserializationError( - "Tried to deserialize an array not wrapped, and found several nodes '{}'. Maybe you should declare this array as wrapped?".format( # pylint: disable=line-too-long + "Tried to deserialize an array not wrapped, and found several nodes '{}'. Maybe you should declare this array as wrapped?".format( xml_name ) ) @@ -1441,7 +1423,7 @@ def xml_key_extractor(attr, attr_desc, data): # pylint: disable=unused-argument return children[0] -class Deserializer(object): +class Deserializer: """Response object model deserializer. :param dict classes: Class type dictionary for deserializing complex types. @@ -1458,6 +1440,10 @@ def __init__(self, classes: Optional[Mapping[str, type]] = None) -> None: "rfc-1123": Deserializer.deserialize_rfc, "unix-time": Deserializer.deserialize_unix, "duration": Deserializer.deserialize_duration, + "duration-seconds-int": Deserializer.deserialize_duration_seconds, + "duration-seconds-float": Deserializer.deserialize_duration_seconds, + "duration-milliseconds-int": Deserializer.deserialize_duration_milliseconds, + "duration-milliseconds-float": Deserializer.deserialize_duration_milliseconds, "date": Deserializer.deserialize_date, "time": Deserializer.deserialize_time, "decimal": Deserializer.deserialize_decimal, @@ -1470,9 +1456,13 @@ def __init__(self, classes: Optional[Mapping[str, type]] = None) -> None: } self.deserialize_expected_types = { "duration": (isodate.Duration, datetime.timedelta), + "duration-seconds-int": (isodate.Duration, datetime.timedelta), + "duration-seconds-float": (isodate.Duration, datetime.timedelta), + "duration-milliseconds-int": (isodate.Duration, datetime.timedelta), + "duration-milliseconds-float": (isodate.Duration, datetime.timedelta), "iso-8601": (datetime.datetime), } - self.dependencies: Dict[str, type] = dict(classes) if classes else {} + self.dependencies: dict[str, type] = dict(classes) if classes else {} self.key_extractors = [rest_key_extractor, xml_key_extractor] # Additional properties only works if the "rest_key_extractor" is used to # extract the keys. Making it to work whatever the key extractor is too much @@ -1482,16 +1472,37 @@ def __init__(self, classes: Optional[Mapping[str, type]] = None) -> None: # Otherwise, result are unexpected self.additional_properties_detection = True - def __call__(self, target_obj, response_data, content_type=None): + def __call__(self, target_obj, response_data, content_type=None): # pylint: disable=too-many-return-statements """Call the deserializer to process a REST response. :param str target_obj: Target data type to deserialize to. :param requests.Response response_data: REST response object. :param str content_type: Swagger "produces" if available. - :raises: DeserializationError if deserialization fails. + :raises DeserializationError: if deserialization fails. :return: Deserialized object. :rtype: object """ + # Fast path for header deserialization: response_data is a plain str or None + # and target_obj is a simple scalar type. This avoids the expensive + # _unpack_content → _deserialize → _classify_target → deserialize_data chain. + if response_data is None: + return None + if target_obj == "str" and isinstance(response_data, str): + return response_data + if isinstance(response_data, str): + if target_obj == "int": + return int(response_data) + if target_obj == "bool": + if response_data in ("true", "1", "True"): + return True + if response_data in ("false", "0", "False"): + return False + return bool(response_data) + if target_obj == "rfc-1123": + return Deserializer.deserialize_rfc(response_data) + if target_obj == "bytearray": + return Deserializer.deserialize_bytearray(response_data) + data = self._unpack_content(response_data, content_type) return self._deserialize(target_obj, data) @@ -1502,7 +1513,7 @@ def _deserialize(self, target_obj, data): # pylint: disable=inconsistent-return :param str target_obj: Target data type to deserialize to. :param object data: Object to deserialize. - :raises: DeserializationError if deserialization fails. + :raises DeserializationError: if deserialization fails. :return: Deserialized object. :rtype: object """ @@ -1683,17 +1694,21 @@ def _instantiate_model(self, response, attrs, additional_properties=None): subtype = getattr(response, "_subtype_map", {}) try: readonly = [ - k for k, v in response._validation.items() if v.get("readonly") # pylint: disable=protected-access + k + for k, v in response._validation.items() # pylint: disable=protected-access # type: ignore + if v.get("readonly") ] const = [ - k for k, v in response._validation.items() if v.get("constant") # pylint: disable=protected-access + k + for k, v in response._validation.items() # pylint: disable=protected-access # type: ignore + if v.get("constant") ] kwargs = {k: v for k, v in attrs.items() if k not in subtype and k not in readonly + const} response_obj = response(**kwargs) for attr in readonly: setattr(response_obj, attr, attrs.get(attr)) if additional_properties: - response_obj.additional_properties = additional_properties + response_obj.additional_properties = additional_properties # type: ignore return response_obj except TypeError as err: msg = "Unable to deserialize {} into model {}. ".format(kwargs, response) # type: ignore @@ -1713,7 +1728,7 @@ def deserialize_data(self, data, data_type): # pylint: disable=too-many-return- :param str data: The response string to be deserialized. :param str data_type: The type to deserialize to. - :raises: DeserializationError if deserialization fails. + :raises DeserializationError: if deserialization fails. :return: Deserialized object. :rtype: object """ @@ -1795,7 +1810,7 @@ def deserialize_object(self, attr, **kwargs): # pylint: disable=too-many-return :param dict attr: Dictionary to be deserialized. :return: Deserialized object. :rtype: dict - :raises: TypeError if non-builtin datatype encountered. + :raises TypeError: if non-builtin datatype encountered. """ if attr is None: return None @@ -1841,7 +1856,7 @@ def deserialize_basic(self, attr, data_type): # pylint: disable=too-many-return :param str data_type: deserialization data type. :return: Deserialized basic type. :rtype: str, int, float or bool - :raises: TypeError if string format is not valid. + :raises TypeError: if string format is not valid or data_type is not one of str, int, float, bool. """ # If we're here, data is supposed to be a basic type. # If it's still an XML node, take the text @@ -1867,7 +1882,11 @@ def deserialize_basic(self, attr, data_type): # pylint: disable=too-many-return if data_type == "str": return self.deserialize_unicode(attr) - return eval(data_type)(attr) # nosec # pylint: disable=eval-used + if data_type == "int": + return int(attr) + if data_type == "float": + return float(attr) + raise TypeError("Unknown basic data type: {}".format(data_type)) @staticmethod def deserialize_unicode(data): @@ -1932,7 +1951,7 @@ def deserialize_bytearray(attr): :param str attr: response string to be deserialized. :return: Deserialized bytearray :rtype: bytearray - :raises: TypeError if string format invalid. + :raises TypeError: if string format invalid. """ if isinstance(attr, ET.Element): attr = attr.text @@ -1945,7 +1964,7 @@ def deserialize_base64(attr): :param str attr: response string to be deserialized. :return: Deserialized base64 string :rtype: bytearray - :raises: TypeError if string format invalid. + :raises TypeError: if string format invalid. """ if isinstance(attr, ET.Element): attr = attr.text @@ -1960,7 +1979,7 @@ def deserialize_decimal(attr): :param str attr: response string to be deserialized. :return: Deserialized decimal - :raises: DeserializationError if string format invalid. + :raises DeserializationError: if string format invalid. :rtype: decimal """ if isinstance(attr, ET.Element): @@ -1978,7 +1997,7 @@ def deserialize_long(attr): :param str attr: response string to be deserialized. :return: Deserialized int :rtype: long or int - :raises: ValueError if string format invalid. + :raises ValueError: if string format invalid. """ if isinstance(attr, ET.Element): attr = attr.text @@ -1991,7 +2010,7 @@ def deserialize_duration(attr): :param str attr: response string to be deserialized. :return: Deserialized duration :rtype: TimeDelta - :raises: DeserializationError if string format invalid. + :raises DeserializationError: if string format invalid. """ if isinstance(attr, ET.Element): attr = attr.text @@ -2002,6 +2021,48 @@ def deserialize_duration(attr): raise DeserializationError(msg) from err return duration + @staticmethod + def _deserialize_duration_numeric(attr, unit): + """Deserialize a numeric duration value into a TimeDelta object. + + :param float attr: response value to be deserialized. + :param str unit: The wire unit, used as the ``timedelta`` keyword + (``"seconds"`` or ``"milliseconds"``). + :return: Deserialized duration + :rtype: TimeDelta + :raises DeserializationError: if value is invalid. + """ + if isinstance(attr, ET.Element): + attr = attr.text + try: + duration = datetime.timedelta(**{unit: float(attr)}) # type: ignore + except (ValueError, OverflowError, TypeError) as err: + msg = "Cannot deserialize duration object." + raise DeserializationError(msg) from err + return duration + + @staticmethod + def deserialize_duration_seconds(attr): + """Deserialize a numeric number of seconds into a TimeDelta object. + + :param float attr: response value to be deserialized. + :return: Deserialized duration + :rtype: TimeDelta + :raises DeserializationError: if value is invalid. + """ + return Deserializer._deserialize_duration_numeric(attr, "seconds") + + @staticmethod + def deserialize_duration_milliseconds(attr): + """Deserialize a numeric number of milliseconds into a TimeDelta object. + + :param float attr: response value to be deserialized. + :return: Deserialized duration + :rtype: TimeDelta + :raises DeserializationError: if value is invalid. + """ + return Deserializer._deserialize_duration_numeric(attr, "milliseconds") + @staticmethod def deserialize_date(attr): """Deserialize ISO-8601 formatted string into Date object. @@ -2009,7 +2070,7 @@ def deserialize_date(attr): :param str attr: response string to be deserialized. :return: Deserialized date :rtype: Date - :raises: DeserializationError if string format invalid. + :raises DeserializationError: if string format invalid. """ if isinstance(attr, ET.Element): attr = attr.text @@ -2025,7 +2086,7 @@ def deserialize_time(attr): :param str attr: response string to be deserialized. :return: Deserialized time :rtype: datetime.time - :raises: DeserializationError if string format invalid. + :raises DeserializationError: if string format invalid. """ if isinstance(attr, ET.Element): attr = attr.text @@ -2040,14 +2101,14 @@ def deserialize_rfc(attr): :param str attr: response string to be deserialized. :return: Deserialized RFC datetime :rtype: Datetime - :raises: DeserializationError if string format invalid. + :raises DeserializationError: if string format invalid. """ if isinstance(attr, ET.Element): attr = attr.text try: parsed_date = email.utils.parsedate_tz(attr) # type: ignore date_obj = datetime.datetime( - *parsed_date[:6], tzinfo=_FixedOffset(datetime.timedelta(minutes=(parsed_date[9] or 0) / 60)) + *parsed_date[:6], tzinfo=datetime.timezone(datetime.timedelta(minutes=(parsed_date[9] or 0) / 60)) ) if not date_obj.tzinfo: date_obj = date_obj.astimezone(tz=TZ_UTC) @@ -2063,7 +2124,7 @@ def deserialize_iso(attr): :param str attr: response string to be deserialized. :return: Deserialized ISO datetime :rtype: Datetime - :raises: DeserializationError if string format invalid. + :raises DeserializationError: if string format invalid. """ if isinstance(attr, ET.Element): attr = attr.text @@ -2101,7 +2162,7 @@ def deserialize_unix(attr): :param int attr: Object to be serialized. :return: Deserialized datetime :rtype: Datetime - :raises: DeserializationError if format invalid + :raises DeserializationError: if format invalid """ if isinstance(attr, ET.Element): attr = int(attr.text) # type: ignore diff --git a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_utils/utils.py b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_utils/utils.py new file mode 100644 index 000000000000..8a9421358d75 --- /dev/null +++ b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_utils/utils.py @@ -0,0 +1,107 @@ +# -------------------------------------------------------------------------- +# 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) Python Code Generator. +# Changes may cause incorrect behavior and will be lost if the code is regenerated. +# -------------------------------------------------------------------------- + +from abc import ABC +import json +import os +from typing import Any, Generic, IO, Mapping, Optional, TYPE_CHECKING, TypeVar, Union + +from .._utils.model_base import Model, SdkJSONEncoder + +if TYPE_CHECKING: + from .serialization import Deserializer, Serializer + + +TClient = TypeVar("TClient") +TConfig = TypeVar("TConfig") + + +class ClientMixinABC(ABC, Generic[TClient, TConfig]): + """DO NOT use this class. It is for internal typing use only.""" + + _client: TClient + _config: TConfig + _serialize: "Serializer" + _deserialize: "Deserializer" + + +# file-like tuple could be `(filename, IO (or bytes))` or `(filename, IO (or bytes), content_type)` +FileContent = Union[str, bytes, IO[str], IO[bytes]] + +FileType = Union[ + # file (or bytes) + FileContent, + # (filename, file (or bytes)) + tuple[Optional[str], FileContent], + # (filename, file (or bytes), content_type) + tuple[Optional[str], FileContent, Optional[str]], +] + + +def serialize_multipart_data_entry(data_entry: Any) -> Any: + if isinstance(data_entry, (list, tuple, dict, Model)): + return json.dumps(data_entry, cls=SdkJSONEncoder, exclude_readonly=True) + return data_entry + + +def _normalize_multipart_file_entry(field_name: str, entry: Any, index: int) -> Any: + """Ensure a multipart file entry carries a filename for Content-Disposition. + + Servers distinguish file parts from plain form fields by the presence of + ``filename=`` in the ``Content-Disposition`` header. When callers pass + bare bytes/str/IO the HTTP client omits the filename and the server may + reject the upload. This helper wraps bare values into a (filename, content) + tuple, deriving the name from IO.name when available. + + :param str field_name: The multipart field name used as a filename fallback. + :param entry: The user-provided file entry (tuple, bytes, str, or IO). + :type entry: any + :param int index: The positional index of the entry within the field, used + to disambiguate fallback filenames when multiple entries are provided. + :return: Either the original tuple entry, or a ``(filename, content)`` tuple + wrapping the bare value. + :rtype: any + """ + if isinstance(entry, tuple): + return entry + filename: Optional[str] = None + name_attr = getattr(entry, "name", None) + if isinstance(name_attr, str) and name_attr: + filename = os.path.basename(name_attr) + if not filename: + filename = f"{field_name}_{index}" if index else field_name + + # Return a 3-tuple with an explicit "application/octet-stream" content type. + # A 2-tuple (filename, content) would leave the part's Content-Type unset, and + # the sdk core library only defaults to "application/octet-stream" for bare + # (non-tuple) values - a tuple bypasses that default and falls back to the + # HTTP "text/plain" default instead. Setting it explicitly preserves the + # pre-existing behavior for bare bytes/IO across all transports. + return (filename, entry, "application/octet-stream") + + +def prepare_multipart_form_data( + body: Mapping[str, Any], multipart_fields: list[str], data_fields: list[str] +) -> list[FileType]: + files: list[FileType] = [] + + # Data fields first so streaming server-side parsers see metadata before + # binary file parts. + for data_field in data_fields: + data_entry = body.get(data_field) + if data_entry: + files.append((data_field, str(serialize_multipart_data_entry(data_entry)))) + + for multipart_field in multipart_fields: + multipart_entry = body.get(multipart_field) + if isinstance(multipart_entry, list): + for idx, e in enumerate(multipart_entry): + files.append((multipart_field, _normalize_multipart_file_entry(multipart_field, e, idx))) + elif multipart_entry is not None: + files.append((multipart_field, _normalize_multipart_file_entry(multipart_field, multipart_entry, 0))) + + return files diff --git a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_validation.py b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_validation.py new file mode 100644 index 000000000000..f5af3a4eb8a2 --- /dev/null +++ b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_validation.py @@ -0,0 +1,66 @@ +# -------------------------------------------------------------------------- +# 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) Python Code Generator. +# Changes may cause incorrect behavior and will be lost if the code is regenerated. +# -------------------------------------------------------------------------- +import functools + + +def api_version_validation(**kwargs): + params_added_on = kwargs.pop("params_added_on", {}) + method_added_on = kwargs.pop("method_added_on", "") + api_versions_list = kwargs.pop("api_versions_list", []) + + def _index_with_default(value: str, default: int = -1) -> int: + """Get the index of value in lst, or return default if not found. + + :param value: The value to search for in the api_versions_list. + :type value: str + :param default: The default value to return if the value is not found. + :type default: int + :return: The index of the value in the list, or the default value if not found. + :rtype: int + """ + try: + return api_versions_list.index(value) + except ValueError: + return default + + def decorator(func): + @functools.wraps(func) + def wrapper(*args, **kwargs): + try: + # this assumes the client has an _api_version attribute + client = args[0] + client_api_version = client._config.api_version # pylint: disable=protected-access + except AttributeError: + return func(*args, **kwargs) + + if _index_with_default(method_added_on) > _index_with_default(client_api_version): + raise ValueError( + f"'{func.__name__}' is not available in API version " + f"{client_api_version}. Pass service API version {method_added_on} or newer to your client." + ) + + unsupported = { + parameter: api_version + for api_version, parameters in params_added_on.items() + for parameter in parameters + if parameter in kwargs and _index_with_default(api_version) > _index_with_default(client_api_version) + } + if unsupported: + raise ValueError( + "".join( + [ + f"'{param}' is not available in API version {client_api_version}. " + f"Use service API version {version} or newer.\n" + for param, version in unsupported.items() + ] + ) + ) + return func(*args, **kwargs) + + return wrapper + + return decorator diff --git a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_vendor.py b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_vendor.py deleted file mode 100644 index 37e545b1c5a4..000000000000 --- a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_vendor.py +++ /dev/null @@ -1,75 +0,0 @@ -# -------------------------------------------------------------------------- -# 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) Python Code Generator. -# Changes may cause incorrect behavior and will be lost if the code is regenerated. -# -------------------------------------------------------------------------- - -from abc import ABC -import json -from typing import Any, Dict, IO, List, Mapping, Optional, TYPE_CHECKING, Tuple, Union - -from ._configuration import DocumentTranslationClientConfiguration, SingleDocumentTranslationClientConfiguration -from ._model_base import Model, SdkJSONEncoder - -if TYPE_CHECKING: - from azure.core import PipelineClient - - from ._serialization import Deserializer, Serializer - - -class DocumentTranslationClientMixinABC(ABC): - """DO NOT use this class. It is for internal typing use only.""" - - _client: "PipelineClient" - _config: DocumentTranslationClientConfiguration - _serialize: "Serializer" - _deserialize: "Deserializer" - - -class SingleDocumentTranslationClientMixinABC(ABC): - """DO NOT use this class. It is for internal typing use only.""" - - _client: "PipelineClient" - _config: SingleDocumentTranslationClientConfiguration - _serialize: "Serializer" - _deserialize: "Deserializer" - - -# file-like tuple could be `(filename, IO (or bytes))` or `(filename, IO (or bytes), content_type)` -FileContent = Union[str, bytes, IO[str], IO[bytes]] - -FileType = Union[ - # file (or bytes) - FileContent, - # (filename, file (or bytes)) - Tuple[Optional[str], FileContent], - # (filename, file (or bytes), content_type) - Tuple[Optional[str], FileContent, Optional[str]], -] - - -def serialize_multipart_data_entry(data_entry: Any) -> Any: - if isinstance(data_entry, (list, tuple, dict, Model)): - return json.dumps(data_entry, cls=SdkJSONEncoder, exclude_readonly=True) - return data_entry - - -def prepare_multipart_form_data( - body: Mapping[str, Any], multipart_fields: List[str], data_fields: List[str] -) -> Tuple[List[FileType], Dict[str, Any]]: - files: List[FileType] = [] - data: Dict[str, Any] = {} - for multipart_field in multipart_fields: - multipart_entry = body.get(multipart_field) - if isinstance(multipart_entry, list): - files.extend([(multipart_field, e) for e in multipart_entry]) - elif multipart_entry: - files.append((multipart_field, multipart_entry)) - - for data_field in data_fields: - data_entry = body.get(data_field) - if data_entry: - data[data_field] = serialize_multipart_data_entry(data_entry) - - return files, data diff --git a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_version.py b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_version.py index 3dcc33575aad..8f2350dd3b0c 100644 --- a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_version.py +++ b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_version.py @@ -6,4 +6,4 @@ # Changes may cause incorrect behavior and will be lost if the code is regenerated. # -------------------------------------------------------------------------- -VERSION = "1.1.1" +VERSION = "2.0.0" diff --git a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/aio/__init__.py b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/aio/__init__.py index ddf8855b2d9b..b358b68ef553 100644 --- a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/aio/__init__.py +++ b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/aio/__init__.py @@ -5,19 +5,27 @@ # Code generated by Microsoft (R) Python Code Generator. # Changes may cause incorrect behavior and will be lost if the code is regenerated. # -------------------------------------------------------------------------- +# pylint: disable=wrong-import-position -from ._patch import DocumentTranslationClient -from ._client import SingleDocumentTranslationClient +from typing import TYPE_CHECKING +if TYPE_CHECKING: + from ._patch import * # pylint: disable=unused-wildcard-import -from ._patch import AsyncDocumentTranslationLROPoller +from ._client import DocumentTranslationClient # type: ignore +from ._client import SingleDocumentTranslationClient # type: ignore + +try: + from ._patch import __all__ as _patch_all + from ._patch import * +except ImportError: + _patch_all = [] from ._patch import patch_sdk as _patch_sdk __all__ = [ - "AsyncDocumentTranslationLROPoller", "DocumentTranslationClient", "SingleDocumentTranslationClient", ] - +__all__.extend([p for p in _patch_all if p not in __all__]) # pyright: ignore _patch_sdk() diff --git a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/aio/_client.py b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/aio/_client.py index d8e017fc4f57..6962bbf181ba 100644 --- a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/aio/_client.py +++ b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/aio/_client.py @@ -7,33 +7,39 @@ # -------------------------------------------------------------------------- from copy import deepcopy +import sys from typing import Any, Awaitable, TYPE_CHECKING, Union -from typing_extensions import Self from azure.core import AsyncPipelineClient from azure.core.credentials import AzureKeyCredential from azure.core.pipeline import policies from azure.core.rest import AsyncHttpResponse, HttpRequest -from .._serialization import Deserializer, Serializer +from .._utils.serialization import Deserializer, Serializer from ._configuration import DocumentTranslationClientConfiguration, SingleDocumentTranslationClientConfiguration -from ._operations import DocumentTranslationClientOperationsMixin, SingleDocumentTranslationClientOperationsMixin +from ._operations import _DocumentTranslationClientOperationsMixin, _SingleDocumentTranslationClientOperationsMixin + +if sys.version_info >= (3, 11): + from typing import Self +else: + from typing_extensions import Self # type: ignore if TYPE_CHECKING: from azure.core.credentials_async import AsyncTokenCredential -class DocumentTranslationClient(DocumentTranslationClientOperationsMixin): +class DocumentTranslationClient(_DocumentTranslationClientOperationsMixin): """DocumentTranslationClient. :param endpoint: Supported document Translation endpoint, protocol and hostname, for example: https://{TranslatorResourceName}.cognitiveservices.azure.com/translator. Required. :type endpoint: str - :param credential: Credential used to authenticate requests to the service. Is either a - AzureKeyCredential type or a TokenCredential type. Required. + :param credential: Credential used to authenticate requests to the service. Is either a key + credential type or a token credential type. Required. :type credential: ~azure.core.credentials.AzureKeyCredential or ~azure.core.credentials_async.AsyncTokenCredential - :keyword api_version: The API version to use for this operation. Default value is "2024-05-01". + :keyword api_version: The API version to use for this operation. Known values are "2026-03-01" + and None. Default value is None. If not set, the operation's default API version will be used. Note that overriding this default value may result in unsupported behavior. :paramtype api_version: str :keyword int polling_interval: Default waiting time between two polls for LRO operations if no @@ -45,6 +51,7 @@ def __init__( ) -> None: _endpoint = "{endpoint}/translator" self._config = DocumentTranslationClientConfiguration(endpoint=endpoint, credential=credential, **kwargs) + _policies = kwargs.pop("policies", None) if _policies is None: _policies = [ @@ -107,17 +114,18 @@ async def __aexit__(self, *exc_details: Any) -> None: await self._client.__aexit__(*exc_details) -class SingleDocumentTranslationClient(SingleDocumentTranslationClientOperationsMixin): +class SingleDocumentTranslationClient(_SingleDocumentTranslationClientOperationsMixin): """SingleDocumentTranslationClient. :param endpoint: Supported document Translation endpoint, protocol and hostname, for example: https://{TranslatorResourceName}.cognitiveservices.azure.com/translator. Required. :type endpoint: str - :param credential: Credential used to authenticate requests to the service. Is either a - AzureKeyCredential type or a TokenCredential type. Required. + :param credential: Credential used to authenticate requests to the service. Is either a key + credential type or a token credential type. Required. :type credential: ~azure.core.credentials.AzureKeyCredential or ~azure.core.credentials_async.AsyncTokenCredential - :keyword api_version: The API version to use for this operation. Default value is "2024-05-01". + :keyword api_version: The API version to use for this operation. Known values are "2026-03-01" + and None. Default value is None. If not set, the operation's default API version will be used. Note that overriding this default value may result in unsupported behavior. :paramtype api_version: str """ @@ -127,6 +135,7 @@ def __init__( ) -> None: _endpoint = "{endpoint}/translator" self._config = SingleDocumentTranslationClientConfiguration(endpoint=endpoint, credential=credential, **kwargs) + _policies = kwargs.pop("policies", None) if _policies is None: _policies = [ diff --git a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/aio/_configuration.py b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/aio/_configuration.py index f0876e7f2d08..da4df1e05a43 100644 --- a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/aio/_configuration.py +++ b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/aio/_configuration.py @@ -26,11 +26,12 @@ class DocumentTranslationClientConfiguration: # pylint: disable=too-many-instan :param endpoint: Supported document Translation endpoint, protocol and hostname, for example: https://{TranslatorResourceName}.cognitiveservices.azure.com/translator. Required. :type endpoint: str - :param credential: Credential used to authenticate requests to the service. Is either a - AzureKeyCredential type or a TokenCredential type. Required. + :param credential: Credential used to authenticate requests to the service. Is either a key + credential type or a token credential type. Required. :type credential: ~azure.core.credentials.AzureKeyCredential or ~azure.core.credentials_async.AsyncTokenCredential - :keyword api_version: The API version to use for this operation. Default value is "2024-05-01". + :keyword api_version: The API version to use for this operation. Known values are "2026-03-01" + and None. Default value is None. If not set, the operation's default API version will be used. Note that overriding this default value may result in unsupported behavior. :paramtype api_version: str """ @@ -38,7 +39,7 @@ class DocumentTranslationClientConfiguration: # pylint: disable=too-many-instan def __init__( self, endpoint: str, credential: Union[AzureKeyCredential, "AsyncTokenCredential"], **kwargs: Any ) -> None: - api_version: str = kwargs.pop("api_version", "2024-05-01") + api_version: str = kwargs.pop("api_version", "2026-03-01") if endpoint is None: raise ValueError("Parameter 'endpoint' must not be None.") @@ -83,11 +84,12 @@ class SingleDocumentTranslationClientConfiguration: # pylint: disable=too-many- :param endpoint: Supported document Translation endpoint, protocol and hostname, for example: https://{TranslatorResourceName}.cognitiveservices.azure.com/translator. Required. :type endpoint: str - :param credential: Credential used to authenticate requests to the service. Is either a - AzureKeyCredential type or a TokenCredential type. Required. + :param credential: Credential used to authenticate requests to the service. Is either a key + credential type or a token credential type. Required. :type credential: ~azure.core.credentials.AzureKeyCredential or ~azure.core.credentials_async.AsyncTokenCredential - :keyword api_version: The API version to use for this operation. Default value is "2024-05-01". + :keyword api_version: The API version to use for this operation. Known values are "2026-03-01" + and None. Default value is None. If not set, the operation's default API version will be used. Note that overriding this default value may result in unsupported behavior. :paramtype api_version: str """ @@ -95,7 +97,7 @@ class SingleDocumentTranslationClientConfiguration: # pylint: disable=too-many- def __init__( self, endpoint: str, credential: Union[AzureKeyCredential, "AsyncTokenCredential"], **kwargs: Any ) -> None: - api_version: str = kwargs.pop("api_version", "2024-05-01") + api_version: str = kwargs.pop("api_version", "2026-03-01") if endpoint is None: raise ValueError("Parameter 'endpoint' must not be None.") diff --git a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/aio/_operations/__init__.py b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/aio/_operations/__init__.py index 9e327bba3bf1..e08ac6325259 100644 --- a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/aio/_operations/__init__.py +++ b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/aio/_operations/__init__.py @@ -5,16 +5,20 @@ # Code generated by Microsoft (R) Python Code Generator. # Changes may cause incorrect behavior and will be lost if the code is regenerated. # -------------------------------------------------------------------------- +# pylint: disable=wrong-import-position -from ._patch import DocumentTranslationClientOperationsMixin -from ._patch import SingleDocumentTranslationClientOperationsMixin +from typing import TYPE_CHECKING +if TYPE_CHECKING: + from ._patch import * # pylint: disable=unused-wildcard-import -from ._patch import patch_sdk as _patch_sdk +from ._operations import _DocumentTranslationClientOperationsMixin # type: ignore # pylint: disable=unused-import +from ._operations import _SingleDocumentTranslationClientOperationsMixin # type: ignore # pylint: disable=unused-import -__all__ = [ - "DocumentTranslationClientOperationsMixin", - "SingleDocumentTranslationClientOperationsMixin", -] +from ._patch import __all__ as _patch_all +from ._patch import * +from ._patch import patch_sdk as _patch_sdk +__all__ = [] +__all__.extend([p for p in _patch_all if p not in __all__]) # pyright: ignore _patch_sdk() diff --git a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/aio/_operations/_operations.py b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/aio/_operations/_operations.py index 6b8361f2d71a..5af317647dda 100644 --- a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/aio/_operations/_operations.py +++ b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/aio/_operations/_operations.py @@ -1,4 +1,4 @@ -# pylint: disable=too-many-lines +# pylint: disable=line-too-long,useless-suppression,too-many-lines # coding=utf-8 # -------------------------------------------------------------------------- # Copyright (c) Microsoft Corporation. All rights reserved. @@ -6,13 +6,14 @@ # Code generated by Microsoft (R) Python Code Generator. # Changes may cause incorrect behavior and will be lost if the code is regenerated. # -------------------------------------------------------------------------- +from collections.abc import MutableMapping import datetime from io import IOBase import json -import sys -from typing import Any, AsyncIterable, AsyncIterator, Callable, Dict, IO, List, Optional, TypeVar, Union, cast, overload +from typing import Any, AsyncIterator, Callable, IO, Optional, TypeVar, Union, cast, overload import urllib.parse +from azure.core import AsyncPipelineClient from azure.core.async_paging import AsyncItemPaged, AsyncList from azure.core.exceptions import ( ClientAuthenticationError, @@ -32,10 +33,9 @@ from azure.core.tracing.decorator_async import distributed_trace_async from azure.core.utils import case_insensitive_dict -from ... import _model_base, models as _models -from ..._model_base import SdkJSONEncoder, _deserialize +from ... import models as _models, types as _types from ..._operations._operations import ( - build_document_translation__begin_translation_request, + build_document_translation_begin_translation_request, build_document_translation_cancel_translation_request, build_document_translation_get_document_status_request, build_document_translation_get_supported_formats_request, @@ -44,22 +44,21 @@ build_document_translation_list_translation_statuses_request, build_single_document_translation_translate_request, ) -from ..._vendor import prepare_multipart_form_data -from .._vendor import DocumentTranslationClientMixinABC, SingleDocumentTranslationClientMixinABC - -if sys.version_info >= (3, 9): - from collections.abc import MutableMapping -else: - from typing import MutableMapping # type: ignore -JSON = MutableMapping[str, Any] # pylint: disable=unsubscriptable-object +from ..._utils.model_base import Model as _Model, SdkJSONEncoder, _deserialize +from ..._utils.utils import ClientMixinABC, prepare_multipart_form_data +from ..._validation import api_version_validation +from .._configuration import DocumentTranslationClientConfiguration, SingleDocumentTranslationClientConfiguration + T = TypeVar("T") -ClsType = Optional[Callable[[PipelineResponse[HttpRequest, AsyncHttpResponse], T, Dict[str, Any]], Any]] +ClsType = Optional[Callable[[PipelineResponse[HttpRequest, AsyncHttpResponse], T, dict[str, Any]], Any]] -class DocumentTranslationClientOperationsMixin(DocumentTranslationClientMixinABC): +class _DocumentTranslationClientOperationsMixin( + ClientMixinABC[AsyncPipelineClient[HttpRequest, AsyncHttpResponse], DocumentTranslationClientConfiguration] +): - async def __begin_translation_initial( - self, body: Union[_models.StartTranslationDetails, JSON, IO[bytes]], **kwargs: Any + async def _begin_translation_initial( + self, body: Union[_models.StartTranslationDetails, _types.StartTranslationDetails, IO[bytes]], **kwargs: Any ) -> AsyncIterator[bytes]: error_map: MutableMapping = { 401: ClientAuthenticationError, @@ -82,7 +81,7 @@ async def __begin_translation_initial( else: _content = json.dumps(body, cls=SdkJSONEncoder, exclude_readonly=True) # type: ignore - _request = build_document_translation__begin_translation_request( + _request = build_document_translation_begin_translation_request( content_type=content_type, api_version=self._config.api_version, content=_content, @@ -94,6 +93,7 @@ async def __begin_translation_initial( } _request.url = self._client.format_url(_request.url, **path_format_arguments) + _decompress = kwargs.pop("decompress", True) _stream = True pipeline_response: PipelineResponse = await self._client._pipeline.run( # type: ignore # pylint: disable=protected-access _request, stream=_stream, **kwargs @@ -112,7 +112,7 @@ async def __begin_translation_initial( response_headers = {} response_headers["Operation-Location"] = self._deserialize("str", response.headers.get("Operation-Location")) - deserialized = response.iter_bytes() + deserialized = response.iter_bytes() if _decompress else response.iter_raw() if cls: return cls(pipeline_response, deserialized, response_headers) # type: ignore @@ -120,30 +120,19 @@ async def __begin_translation_initial( return deserialized # type: ignore @overload - async def _begin_translation( + async def begin_translation( self, body: _models.StartTranslationDetails, *, content_type: str = "application/json", **kwargs: Any ) -> AsyncLROPoller[_models.TranslationStatus]: """Submit a document translation request to the Document Translation service. - Use this API to submit a bulk (batch) translation request to the Document - Translation service. - Each request can contain multiple documents and must - contain a source and destination container for each document. - - The - prefix and suffix filter (if supplied) are used to filter folders. The prefix - is applied to the subpath after the container name. - - Glossaries / - Translation memory can be included in the request and are applied by the - service when the document is translated. - - If the glossary is - invalid or unreachable during translation, an error is indicated in the - document status. - If a file with the same name already exists at the - destination, it will be overwritten. The targetUrl for each target language - must be unique. + Use this API to submit a bulk (batch) translation request to the Document Translation service. + Each request can contain multiple documents and must contain a source and destination container + for each document. The prefix and suffix filter (if supplied) are used to filter folders. The + prefix is applied to the subpath after the container name. Glossaries / Translation memory can + be included in the request and are applied by the service when the document is translated. If + the glossary is invalid or unreachable during translation, an error is indicated in the + document status. If a file with the same name already exists at the destination, it will be + overwritten. The targetUrl for each target language must be unique. :param body: Translation job submission batch request. Required. :type body: ~azure.ai.translation.document.models.StartTranslationDetails @@ -158,33 +147,22 @@ async def _begin_translation( """ @overload - async def _begin_translation( - self, body: JSON, *, content_type: str = "application/json", **kwargs: Any + async def begin_translation( + self, body: _types.StartTranslationDetails, *, content_type: str = "application/json", **kwargs: Any ) -> AsyncLROPoller[_models.TranslationStatus]: """Submit a document translation request to the Document Translation service. - Use this API to submit a bulk (batch) translation request to the Document - Translation service. - Each request can contain multiple documents and must - contain a source and destination container for each document. - - The - prefix and suffix filter (if supplied) are used to filter folders. The prefix - is applied to the subpath after the container name. - - Glossaries / - Translation memory can be included in the request and are applied by the - service when the document is translated. - - If the glossary is - invalid or unreachable during translation, an error is indicated in the - document status. - If a file with the same name already exists at the - destination, it will be overwritten. The targetUrl for each target language - must be unique. + Use this API to submit a bulk (batch) translation request to the Document Translation service. + Each request can contain multiple documents and must contain a source and destination container + for each document. The prefix and suffix filter (if supplied) are used to filter folders. The + prefix is applied to the subpath after the container name. Glossaries / Translation memory can + be included in the request and are applied by the service when the document is translated. If + the glossary is invalid or unreachable during translation, an error is indicated in the + document status. If a file with the same name already exists at the destination, it will be + overwritten. The targetUrl for each target language must be unique. :param body: Translation job submission batch request. Required. - :type body: JSON + :type body: ~azure.ai.translation.document.types.StartTranslationDetails :keyword content_type: Body Parameter content-type. Content type parameter for JSON body. Default value is "application/json". :paramtype content_type: str @@ -196,30 +174,19 @@ async def _begin_translation( """ @overload - async def _begin_translation( + async def begin_translation( self, body: IO[bytes], *, content_type: str = "application/json", **kwargs: Any ) -> AsyncLROPoller[_models.TranslationStatus]: """Submit a document translation request to the Document Translation service. - Use this API to submit a bulk (batch) translation request to the Document - Translation service. - Each request can contain multiple documents and must - contain a source and destination container for each document. - - The - prefix and suffix filter (if supplied) are used to filter folders. The prefix - is applied to the subpath after the container name. - - Glossaries / - Translation memory can be included in the request and are applied by the - service when the document is translated. - - If the glossary is - invalid or unreachable during translation, an error is indicated in the - document status. - If a file with the same name already exists at the - destination, it will be overwritten. The targetUrl for each target language - must be unique. + Use this API to submit a bulk (batch) translation request to the Document Translation service. + Each request can contain multiple documents and must contain a source and destination container + for each document. The prefix and suffix filter (if supplied) are used to filter folders. The + prefix is applied to the subpath after the container name. Glossaries / Translation memory can + be included in the request and are applied by the service when the document is translated. If + the glossary is invalid or unreachable during translation, an error is indicated in the + document status. If a file with the same name already exists at the destination, it will be + overwritten. The targetUrl for each target language must be unique. :param body: Translation job submission batch request. Required. :type body: IO[bytes] @@ -234,34 +201,24 @@ async def _begin_translation( """ @distributed_trace_async - async def _begin_translation( - self, body: Union[_models.StartTranslationDetails, JSON, IO[bytes]], **kwargs: Any + async def begin_translation( + self, body: Union[_models.StartTranslationDetails, _types.StartTranslationDetails, IO[bytes]], **kwargs: Any ) -> AsyncLROPoller[_models.TranslationStatus]: """Submit a document translation request to the Document Translation service. - Use this API to submit a bulk (batch) translation request to the Document - Translation service. - Each request can contain multiple documents and must - contain a source and destination container for each document. - - The - prefix and suffix filter (if supplied) are used to filter folders. The prefix - is applied to the subpath after the container name. - - Glossaries / - Translation memory can be included in the request and are applied by the - service when the document is translated. - - If the glossary is - invalid or unreachable during translation, an error is indicated in the - document status. - If a file with the same name already exists at the - destination, it will be overwritten. The targetUrl for each target language - must be unique. - - :param body: Translation job submission batch request. Is one of the following types: - StartTranslationDetails, JSON, IO[bytes] Required. - :type body: ~azure.ai.translation.document.models.StartTranslationDetails or JSON or IO[bytes] + Use this API to submit a bulk (batch) translation request to the Document Translation service. + Each request can contain multiple documents and must contain a source and destination container + for each document. The prefix and suffix filter (if supplied) are used to filter folders. The + prefix is applied to the subpath after the container name. Glossaries / Translation memory can + be included in the request and are applied by the service when the document is translated. If + the glossary is invalid or unreachable during translation, an error is indicated in the + document status. If a file with the same name already exists at the destination, it will be + overwritten. The targetUrl for each target language must be unique. + + :param body: Translation job submission batch request. Is either a StartTranslationDetails type + or a IO[bytes] type. Required. + :type body: ~azure.ai.translation.document.models.StartTranslationDetails or + ~azure.ai.translation.document.types.StartTranslationDetails or IO[bytes] :return: An instance of AsyncLROPoller that returns TranslationStatus. The TranslationStatus is compatible with MutableMapping :rtype: @@ -277,7 +234,7 @@ async def _begin_translation( lro_delay = kwargs.pop("polling_interval", self._config.polling_interval) cont_token: Optional[str] = kwargs.pop("continuation_token", None) if cont_token is None: - raw_result = await self.__begin_translation_initial( + raw_result = await self._begin_translation_initial( body=body, content_type=content_type, cls=lambda x, y, z: x, headers=_headers, params=_params, **kwargs ) await raw_result.http_response.read() # type: ignore @@ -325,13 +282,13 @@ def list_translation_statuses( *, top: Optional[int] = None, skip: Optional[int] = None, - translation_ids: Optional[List[str]] = None, - statuses: Optional[List[str]] = None, + translation_ids: Optional[list[str]] = None, + statuses: Optional[list[str]] = None, created_date_time_utc_start: Optional[datetime.datetime] = None, created_date_time_utc_end: Optional[datetime.datetime] = None, - orderby: Optional[List[str]] = None, + orderby: Optional[list[str]] = None, **kwargs: Any - ) -> AsyncIterable["_models.TranslationStatus"]: + ) -> AsyncItemPaged["_models.TranslationStatus"]: """Returns a list of batch requests submitted and the status for each request. Returns a list of batch requests submitted and the status for each @@ -359,6 +316,7 @@ def list_translation_statuses( requested via top (or top is not specified and there are more items to be returned), @nextLink will contain the link to the next page. + orderby query parameter can be used to sort the returned list (ex "orderby=createdDateTimeUtc asc" or "orderby=createdDateTimeUtc desc"). @@ -377,6 +335,7 @@ def list_translation_statuses( the values specified by the client. However, clients must be prepared to handle responses that contain a different page size or contain a continuation token. + When both top and skip are included, the server should first apply skip and then top on the collection. Note: If the server can't honor top @@ -434,7 +393,7 @@ def list_translation_statuses( _params = kwargs.pop("params", {}) or {} maxpagesize = kwargs.pop("maxpagesize", None) - cls: ClsType[List[_models.TranslationStatus]] = kwargs.pop("cls", None) + cls: ClsType[list[_models.TranslationStatus]] = kwargs.pop("cls", None) error_map: MutableMapping = { 401: ClientAuthenticationError, @@ -478,7 +437,10 @@ def prepare_request(next_link=None): ) _next_request_params["api-version"] = self._config.api_version _request = HttpRequest( - "GET", urllib.parse.urljoin(next_link, _parsed_next_link.path), params=_next_request_params + "GET", + urllib.parse.urljoin(next_link, _parsed_next_link.path), + headers=_headers, + params=_next_request_params, ) path_format_arguments = { "endpoint": self._serialize.url( @@ -491,7 +453,10 @@ def prepare_request(next_link=None): async def extract_data(pipeline_response): deserialized = pipeline_response.http_response.json() - list_of_elem = _deserialize(List[_models.TranslationStatus], deserialized["value"]) + list_of_elem = _deserialize( + list[_models.TranslationStatus], + deserialized.get("value", []), + ) if cls: list_of_elem = cls(list_of_elem) # type: ignore return deserialized.get("nextLink") or None, AsyncList(list_of_elem) @@ -517,8 +482,7 @@ async def get_next(next_link=None): async def get_document_status(self, translation_id: str, document_id: str, **kwargs: Any) -> _models.DocumentStatus: """Returns the status for a specific document. - Returns the translation status for a specific document based on the request Id - and document Id. + Returns the translation status for a specific document based on the request Id and document Id. :param translation_id: Format - uuid. The batch id. Required. :type translation_id: str @@ -553,6 +517,7 @@ async def get_document_status(self, translation_id: str, document_id: str, **kwa } _request.url = self._client.format_url(_request.url, **path_format_arguments) + _decompress = kwargs.pop("decompress", True) _stream = kwargs.pop("stream", False) pipeline_response: PipelineResponse = await self._client._pipeline.run( # type: ignore # pylint: disable=protected-access _request, stream=_stream, **kwargs @@ -570,7 +535,7 @@ async def get_document_status(self, translation_id: str, document_id: str, **kwa raise HttpResponseError(response=response) if _stream: - deserialized = response.iter_bytes() + deserialized = response.iter_bytes() if _decompress else response.iter_raw() else: deserialized = _deserialize(_models.DocumentStatus, response.json()) @@ -583,10 +548,8 @@ async def get_document_status(self, translation_id: str, document_id: str, **kwa async def get_translation_status(self, translation_id: str, **kwargs: Any) -> _models.TranslationStatus: """Returns the status for a document translation request. - Returns the status for a document translation request. - The status includes the - overall request status, as well as the status for documents that are being - translated as part of that request. + Returns the status for a document translation request. The status includes the overall request + status, as well as the status for documents that are being translated as part of that request. :param translation_id: Format - uuid. The operation id. Required. :type translation_id: str @@ -618,6 +581,7 @@ async def get_translation_status(self, translation_id: str, **kwargs: Any) -> _m } _request.url = self._client.format_url(_request.url, **path_format_arguments) + _decompress = kwargs.pop("decompress", True) _stream = kwargs.pop("stream", False) pipeline_response: PipelineResponse = await self._client._pipeline.run( # type: ignore # pylint: disable=protected-access _request, stream=_stream, **kwargs @@ -635,7 +599,7 @@ async def get_translation_status(self, translation_id: str, **kwargs: Any) -> _m raise HttpResponseError(response=response) if _stream: - deserialized = response.iter_bytes() + deserialized = response.iter_bytes() if _decompress else response.iter_raw() else: deserialized = _deserialize(_models.TranslationStatus, response.json()) @@ -648,14 +612,10 @@ async def get_translation_status(self, translation_id: str, **kwargs: Any) -> _m async def cancel_translation(self, translation_id: str, **kwargs: Any) -> _models.TranslationStatus: """Cancel a currently processing or queued translation. - Cancel a currently processing or queued translation. - A translation will not be - cancelled if it is already completed or failed or cancelling. A bad request - will be returned. - All documents that have completed translation will not be - cancelled and will be charged. - All pending documents will be cancelled if - possible. + Cancel a currently processing or queued translation. A translation will not be cancelled if it + is already completed or failed or cancelling. A bad request will be returned. All documents + that have completed translation will not be cancelled and will be charged. All pending + documents will be cancelled if possible. :param translation_id: Format - uuid. The operation-id. Required. :type translation_id: str @@ -687,6 +647,7 @@ async def cancel_translation(self, translation_id: str, **kwargs: Any) -> _model } _request.url = self._client.format_url(_request.url, **path_format_arguments) + _decompress = kwargs.pop("decompress", True) _stream = kwargs.pop("stream", False) pipeline_response: PipelineResponse = await self._client._pipeline.run( # type: ignore # pylint: disable=protected-access _request, stream=_stream, **kwargs @@ -704,7 +665,7 @@ async def cancel_translation(self, translation_id: str, **kwargs: Any) -> _model raise HttpResponseError(response=response) if _stream: - deserialized = response.iter_bytes() + deserialized = response.iter_bytes() if _decompress else response.iter_raw() else: deserialized = _deserialize(_models.TranslationStatus, response.json()) @@ -720,59 +681,36 @@ def list_document_statuses( *, top: Optional[int] = None, skip: Optional[int] = None, - document_ids: Optional[List[str]] = None, - statuses: Optional[List[str]] = None, + document_ids: Optional[list[str]] = None, + statuses: Optional[list[str]] = None, created_date_time_utc_start: Optional[datetime.datetime] = None, created_date_time_utc_end: Optional[datetime.datetime] = None, - orderby: Optional[List[str]] = None, + orderby: Optional[list[str]] = None, **kwargs: Any - ) -> AsyncIterable["_models.DocumentStatus"]: + ) -> AsyncItemPaged["_models.DocumentStatus"]: """Returns the status for all documents in a batch document translation request. - Returns the status for all documents in a batch document translation request. - - If the number of documents in the response exceeds our paging limit, - server-side paging is used. - Paginated responses indicate a partial result and - include a continuation token in the response. The absence of a continuation - token means that no additional pages are available. - - top, skip - and maxpagesize query parameters can be used to specify a number of results to - return and an offset for the collection. - - top indicates the total - number of records the user wants to be returned across all pages. - skip - indicates the number of records to skip from the list of document status held - by the server based on the sorting method specified. By default, we sort by - descending start time. - maxpagesize is the maximum items returned in a page. - If more items are requested via top (or top is not specified and there are - more items to be returned), @nextLink will contain the link to the next page. - - orderby query parameter can be used to sort the returned list (ex - "orderby=createdDateTimeUtc asc" or "orderby=createdDateTimeUtc - desc"). - The default sorting is descending by createdDateTimeUtc. - Some query - parameters can be used to filter the returned list (ex: - "status=Succeeded,Cancelled") will only return succeeded and cancelled - documents. - createdDateTimeUtcStart and createdDateTimeUtcEnd can be used - combined or separately to specify a range of datetime to filter the returned - list by. - The supported filtering query parameters are (status, ids, - createdDateTimeUtcStart, createdDateTimeUtcEnd). - - When both top - and skip are included, the server should first apply skip and then top on - the collection. - Note: If the server can't honor top and/or skip, the server - must return an error to the client informing about it instead of just ignoring - the query options. - This reduces the risk of the client making assumptions about - the data returned. + Returns the status for all documents in a batch document translation request. If the number of + documents in the response exceeds our paging limit, server-side paging is used. Paginated + responses indicate a partial result and include a continuation token in the response. The + absence of a continuation token means that no additional pages are available. top, skip and + maxpagesize query parameters can be used to specify a number of results to return and an offset + for the collection. top indicates the total number of records the user wants to be returned + across all pages. skip indicates the number of records to skip from the list of document status + held by the server based on the sorting method specified. By default, we sort by descending + start time. maxpagesize is the maximum items returned in a page. If more items are requested + via top (or top is not specified and there are more items to be returned), @nextLink will + contain the link to the next page. orderby query parameter can be used to sort the returned + list (ex "orderby=createdDateTimeUtc asc" or "orderby=createdDateTimeUtc desc"). The default + sorting is descending by createdDateTimeUtc. Some query parameters can be used to filter the + returned list (ex: "status=Succeeded,Cancelled") will only return succeeded and cancelled + documents. createdDateTimeUtcStart and createdDateTimeUtcEnd can be used combined or separately + to specify a range of datetime to filter the returned list by. The supported filtering query + parameters are (status, ids, createdDateTimeUtcStart, createdDateTimeUtcEnd). When both top and + skip are included, the server should first apply skip and then top on the collection. Note: If + the server can't honor top and/or skip, the server must return an error to the client informing + about it instead of just ignoring the query options. This reduces the risk of the client making + assumptions about the data returned. :param translation_id: Format - uuid. The operation id. Required. :type translation_id: str @@ -825,7 +763,7 @@ def list_document_statuses( _params = kwargs.pop("params", {}) or {} maxpagesize = kwargs.pop("maxpagesize", None) - cls: ClsType[List[_models.DocumentStatus]] = kwargs.pop("cls", None) + cls: ClsType[list[_models.DocumentStatus]] = kwargs.pop("cls", None) error_map: MutableMapping = { 401: ClientAuthenticationError, @@ -870,7 +808,10 @@ def prepare_request(next_link=None): ) _next_request_params["api-version"] = self._config.api_version _request = HttpRequest( - "GET", urllib.parse.urljoin(next_link, _parsed_next_link.path), params=_next_request_params + "GET", + urllib.parse.urljoin(next_link, _parsed_next_link.path), + headers=_headers, + params=_next_request_params, ) path_format_arguments = { "endpoint": self._serialize.url( @@ -883,7 +824,10 @@ def prepare_request(next_link=None): async def extract_data(pipeline_response): deserialized = pipeline_response.http_response.json() - list_of_elem = _deserialize(List[_models.DocumentStatus], deserialized["value"]) + list_of_elem = _deserialize( + list[_models.DocumentStatus], + deserialized.get("value", []), + ) if cls: list_of_elem = cls(list_of_elem) # type: ignore return deserialized.get("nextLink") or None, AsyncList(list_of_elem) @@ -907,17 +851,15 @@ async def get_next(next_link=None): @distributed_trace_async async def _get_supported_formats( - self, *, type: Optional[Union[str, _models.FileFormatType]] = None, **kwargs: Any + self, *, type: Union[str, _models.FileFormatType], **kwargs: Any ) -> _models._models.SupportedFileFormats: """Returns a list of supported document formats. - The list of supported formats supported by the Document Translation - service. - The list includes the common file extension, as well as the - content-type if using the upload API. + The list of supported formats supported by the Document Translation service. The list includes + the common file extension, as well as the content-type if using the upload API. - :keyword type: the type of format like document or glossary. Known values are: "document" and - "glossary". Default value is None. + :keyword type: the type of format like document or glossary. Known values are: "Document" and + "Glossary". Required. :paramtype type: str or ~azure.ai.translation.document.models.FileFormatType :return: SupportedFileFormats. The SupportedFileFormats is compatible with MutableMapping :rtype: ~azure.ai.translation.document.models._models.SupportedFileFormats @@ -947,6 +889,7 @@ async def _get_supported_formats( } _request.url = self._client.format_url(_request.url, **path_format_arguments) + _decompress = kwargs.pop("decompress", True) _stream = kwargs.pop("stream", False) pipeline_response: PipelineResponse = await self._client._pipeline.run( # type: ignore # pylint: disable=protected-access _request, stream=_stream, **kwargs @@ -964,7 +907,7 @@ async def _get_supported_formats( raise HttpResponseError(response=response) if _stream: - deserialized = response.iter_bytes() + deserialized = response.iter_bytes() if _decompress else response.iter_raw() else: deserialized = _deserialize( _models._models.SupportedFileFormats, response.json() # pylint: disable=protected-access @@ -976,8 +919,8 @@ async def _get_supported_formats( return deserialized # type: ignore -class SingleDocumentTranslationClientOperationsMixin( # pylint: disable=name-too-long - SingleDocumentTranslationClientMixinABC +class _SingleDocumentTranslationClientOperationsMixin( + ClientMixinABC[AsyncPipelineClient[HttpRequest, AsyncHttpResponse], SingleDocumentTranslationClientConfiguration] ): @overload @@ -988,7 +931,9 @@ async def translate( target_language: str, source_language: Optional[str] = None, category: Optional[str] = None, + deployment_name: Optional[str] = None, allow_fallback: Optional[bool] = None, + translate_text_within_image: Optional[bool] = None, **kwargs: Any ) -> AsyncIterator[bytes]: """Submit a single document translation request to the Document Translation service. @@ -1015,10 +960,16 @@ async def translate( project details to this parameter to use your deployed customized system. Default value is: general. Default value is None. :paramtype category: str + :keyword deployment_name: Deployment name of the custom translation model for the translation + request. Default value is None. + :paramtype deployment_name: str :keyword allow_fallback: Specifies that the service is allowed to fall back to a general system when a custom system doesn't exist. Possible values are: true (default) or false. Default value is None. :paramtype allow_fallback: bool + :keyword translate_text_within_image: Optional boolean parameter to translate text within an + image in the document. Default value is None. + :paramtype translate_text_within_image: bool :return: AsyncIterator[bytes] :rtype: AsyncIterator[bytes] :raises ~azure.core.exceptions.HttpResponseError: @@ -1027,12 +978,14 @@ async def translate( @overload async def translate( self, - body: JSON, + body: _types.DocumentTranslateContent, *, target_language: str, source_language: Optional[str] = None, category: Optional[str] = None, + deployment_name: Optional[str] = None, allow_fallback: Optional[bool] = None, + translate_text_within_image: Optional[bool] = None, **kwargs: Any ) -> AsyncIterator[bytes]: """Submit a single document translation request to the Document Translation service. @@ -1040,7 +993,7 @@ async def translate( Use this API to submit a single translation request to the Document Translation Service. :param body: Document Translate Request Content. Required. - :type body: JSON + :type body: ~azure.ai.translation.document.types.DocumentTranslateContent :keyword target_language: Specifies the language of the output document. The target language must be one of the supported languages included in the translation scope. For example if you want to translate the document in German language, then use @@ -1059,33 +1012,46 @@ async def translate( project details to this parameter to use your deployed customized system. Default value is: general. Default value is None. :paramtype category: str + :keyword deployment_name: Deployment name of the custom translation model for the translation + request. Default value is None. + :paramtype deployment_name: str :keyword allow_fallback: Specifies that the service is allowed to fall back to a general system when a custom system doesn't exist. Possible values are: true (default) or false. Default value is None. :paramtype allow_fallback: bool + :keyword translate_text_within_image: Optional boolean parameter to translate text within an + image in the document. Default value is None. + :paramtype translate_text_within_image: bool :return: AsyncIterator[bytes] :rtype: AsyncIterator[bytes] :raises ~azure.core.exceptions.HttpResponseError: """ @distributed_trace_async + @api_version_validation( + params_added_on={"2026-03-01": ["deployment_name"], "2024-11-01-preview": ["translate_text_within_image"]}, + api_versions_list=["2024-05-01", "2024-11-01-preview", "2025-12-01-preview", "2026-03-01"], + ) async def translate( self, - body: Union[_models.DocumentTranslateContent, JSON], + body: Union[_models.DocumentTranslateContent, _types.DocumentTranslateContent], *, target_language: str, source_language: Optional[str] = None, category: Optional[str] = None, + deployment_name: Optional[str] = None, allow_fallback: Optional[bool] = None, + translate_text_within_image: Optional[bool] = None, **kwargs: Any ) -> AsyncIterator[bytes]: """Submit a single document translation request to the Document Translation service. Use this API to submit a single translation request to the Document Translation Service. - :param body: Document Translate Request Content. Is either a DocumentTranslateContent type or a - JSON type. Required. - :type body: ~azure.ai.translation.document.models.DocumentTranslateContent or JSON + :param body: Document Translate Request Content. Is one of the following types: + DocumentTranslateContent Required. + :type body: ~azure.ai.translation.document.models.DocumentTranslateContent or + ~azure.ai.translation.document.types.DocumentTranslateContent :keyword target_language: Specifies the language of the output document. The target language must be one of the supported languages included in the translation scope. For example if you want to translate the document in German language, then use @@ -1104,10 +1070,16 @@ async def translate( project details to this parameter to use your deployed customized system. Default value is: general. Default value is None. :paramtype category: str + :keyword deployment_name: Deployment name of the custom translation model for the translation + request. Default value is None. + :paramtype deployment_name: str :keyword allow_fallback: Specifies that the service is allowed to fall back to a general system when a custom system doesn't exist. Possible values are: true (default) or false. Default value is None. :paramtype allow_fallback: bool + :keyword translate_text_within_image: Optional boolean parameter to translate text within an + image in the document. Default value is None. + :paramtype translate_text_within_image: bool :return: AsyncIterator[bytes] :rtype: AsyncIterator[bytes] :raises ~azure.core.exceptions.HttpResponseError: @@ -1125,19 +1097,20 @@ async def translate( cls: ClsType[AsyncIterator[bytes]] = kwargs.pop("cls", None) - _body = body.as_dict() if isinstance(body, _model_base.Model) else body - _file_fields: List[str] = ["document", "glossary"] - _data_fields: List[str] = [] - _files, _data = prepare_multipart_form_data(_body, _file_fields, _data_fields) + _body = body.as_dict() if isinstance(body, _Model) else body + _file_fields: list[str] = ["document", "glossary"] + _data_fields: list[str] = [] + _files = prepare_multipart_form_data(_body, _file_fields, _data_fields) _request = build_single_document_translation_translate_request( target_language=target_language, source_language=source_language, category=category, + deployment_name=deployment_name, allow_fallback=allow_fallback, + translate_text_within_image=translate_text_within_image, api_version=self._config.api_version, files=_files, - data=_data, headers=_headers, params=_params, ) @@ -1146,6 +1119,7 @@ async def translate( } _request.url = self._client.format_url(_request.url, **path_format_arguments) + _decompress = kwargs.pop("decompress", True) _stream = kwargs.pop("stream", True) pipeline_response: PipelineResponse = await self._client._pipeline.run( # type: ignore # pylint: disable=protected-access _request, stream=_stream, **kwargs @@ -1163,12 +1137,19 @@ async def translate( raise HttpResponseError(response=response) response_headers = {} + response_headers["x-metered-usage"] = self._deserialize("int", response.headers.get("x-metered-usage")) + response_headers["total-image-scans-succeeded"] = self._deserialize( + "int", response.headers.get("total-image-scans-succeeded") + ) + response_headers["total-image-scans-failed"] = self._deserialize( + "int", response.headers.get("total-image-scans-failed") + ) response_headers["x-ms-client-request-id"] = self._deserialize( "str", response.headers.get("x-ms-client-request-id") ) response_headers["content-type"] = self._deserialize("str", response.headers.get("content-type")) - deserialized = response.iter_bytes() + deserialized = response.iter_bytes() if _decompress else response.iter_raw() if cls: return cls(pipeline_response, deserialized, response_headers) # type: ignore diff --git a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/aio/_operations/_patch.py b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/aio/_operations/_patch.py index 1961b4fee008..e8418a0c6fc4 100644 --- a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/aio/_operations/_patch.py +++ b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/aio/_operations/_patch.py @@ -1,3 +1,4 @@ +# pylint: disable=line-too-long,useless-suppression # ------------------------------------ # Copyright (c) Microsoft Corporation. # Licensed under the MIT License. @@ -29,18 +30,19 @@ OperationFailed, _raise_if_bad_http_status_and_method, ) -from ..._vendor import prepare_multipart_form_data -from ... import _model_base, models as _models +from ..._utils.utils import prepare_multipart_form_data +from ..._validation import api_version_validation +from ... import models as _models +from ..._utils import model_base as _model_base -from ..._model_base import _deserialize +from ..._utils.model_base import _deserialize from ...models import ( TranslationStatus, ) from ._operations import ( - DocumentTranslationClientOperationsMixin as GeneratedDocumentTranslationClientOperationsMixin, - SingleDocumentTranslationClientOperationsMixin as GeneratedSingleDocumentTranslationClientOperationsMixin, + _DocumentTranslationClientOperationsMixin as GeneratedDocumentTranslationClientOperationsMixin, + _SingleDocumentTranslationClientOperationsMixin as GeneratedSingleDocumentTranslationClientOperationsMixin, build_single_document_translation_translate_request, - JSON, ClsType, ) @@ -61,7 +63,7 @@ class AsyncDocumentTranslationLROPoller(AsyncLROPoller[PollingReturnType_co]): """An async custom poller implementation for Document Translation. Call `result()` on the poller to return - a pageable of :class:`~azure.ai.translation.document.DocumentStatus`.""" + a pageable of :class:`~azure.ai.translation.document.models.DocumentStatus`.""" _polling_method: "AsyncDocumentTranslationLROPollingMethod" @@ -72,7 +74,7 @@ def id(self) -> str: :return: The str ID for the translation operation. :rtype: str """ - if self._polling_method._current_body: + if self._polling_method._current_body and self._polling_method._current_body.id: return self._polling_method._current_body.id return self._polling_method._get_id_from_headers() @@ -81,7 +83,7 @@ def details(self) -> TranslationStatus: """The details for the translation operation :return: The details for the translation operation. - :rtype: ~azure.ai.translation.document.TranslationStatus + :rtype: ~azure.ai.translation.document.models.TranslationStatus """ if self._polling_method._current_body: return TranslationStatus(self._polling_method._current_body) @@ -113,7 +115,12 @@ def __init__(self, *args, **kwargs): @property def _current_body(self) -> TranslationStatus: try: - return TranslationStatus(self._pipeline_response.http_response.json()) + response = self._pipeline_response.http_response + # Ignore non-success responses (e.g. a transient polling error) so they do not + # corrupt the operation status, id, or details reported by the poller. + if not 200 <= response.status_code < 300: + return TranslationStatus() # type: ignore[call-overload] + return TranslationStatus(response.json()) except Exception: # pylint: disable=broad-exception-caught return TranslationStatus() # type: ignore[call-overload] @@ -201,8 +208,13 @@ async def _begin_translation( # type: ignore[override] lro_delay = kwargs.pop("polling_interval", self._config.polling_interval) cont_token: Optional[str] = kwargs.pop("continuation_token", None) if cont_token is None: - raw_result = await self.__begin_translation_initial( # type: ignore[func-returns-value] - body=body, content_type=content_type, cls=lambda x, y, z: x, headers=_headers, params=_params, **kwargs + raw_result = await self._begin_translation_initial( # type: ignore[func-returns-value] + body=body, # type: ignore[arg-type] + content_type=content_type, + cls=lambda x, y, z: x, + headers=_headers, + params=_params, + **kwargs ) kwargs.pop("error_map", None) @@ -239,7 +251,10 @@ def get_long_running_output(pipeline_response): deserialization_callback=get_long_running_output, ) return AsyncDocumentTranslationLROPoller[_models.TranslationStatus]( - self._client, raw_result, get_long_running_output, polling_method # pylint: disable=possibly-used-before-assignment + self._client, + raw_result, + get_long_running_output, + polling_method, # pylint: disable=possibly-used-before-assignment ) @@ -247,7 +262,7 @@ class SingleDocumentTranslationClientOperationsMixin( GeneratedSingleDocumentTranslationClientOperationsMixin ): # pylint: disable=name-too-long - @overload + @overload # type: ignore[override] async def translate( self, body: _models.DocumentTranslateContent, @@ -255,7 +270,9 @@ async def translate( target_language: str, source_language: Optional[str] = None, category: Optional[str] = None, + deployment_name: Optional[str] = None, allow_fallback: Optional[bool] = None, + translate_text_within_image: Optional[bool] = None, **kwargs: Any ) -> AsyncIterator[bytes]: """Submit a single document translation request to the Document Translation service. @@ -282,10 +299,16 @@ async def translate( project details to this parameter to use your deployed customized system. Default value is: general. Default value is None. :paramtype category: str + :keyword deployment_name: Deployment name of the custom translation model for the translation + request. Default value is None. + :paramtype deployment_name: str :keyword allow_fallback: Specifies that the service is allowed to fall back to a general system when a custom system doesn't exist. Possible values are: true (default) or false. Default value is None. :paramtype allow_fallback: bool + :keyword translate_text_within_image: Optional boolean parameter to translate text within an + image in the document. Default value is None. + :paramtype translate_text_within_image: bool :return: AsyncIterator[bytes] :rtype: AsyncIterator[bytes] :raises ~azure.core.exceptions.HttpResponseError: @@ -308,7 +331,9 @@ async def translate( target_language: str, source_language: Optional[str] = None, category: Optional[str] = None, + deployment_name: Optional[str] = None, allow_fallback: Optional[bool] = None, + translate_text_within_image: Optional[bool] = None, **kwargs: Any ) -> AsyncIterator[bytes]: """Submit a single document translation request to the Document Translation service. @@ -335,16 +360,26 @@ async def translate( project details to this parameter to use your deployed customized system. Default value is: general. Default value is None. :paramtype category: str + :keyword deployment_name: Deployment name of the custom translation model for the translation + request. Default value is None. + :paramtype deployment_name: str :keyword allow_fallback: Specifies that the service is allowed to fall back to a general system when a custom system doesn't exist. Possible values are: true (default) or false. Default value is None. :paramtype allow_fallback: bool + :keyword translate_text_within_image: Optional boolean parameter to translate text within an + image in the document. Default value is None. + :paramtype translate_text_within_image: bool :return: AsyncIterator[bytes] :rtype: AsyncIterator[bytes] :raises ~azure.core.exceptions.HttpResponseError: """ @distributed_trace_async + @api_version_validation( + params_added_on={"2026-03-01": ["deployment_name"], "2024-11-01-preview": ["translate_text_within_image"]}, + api_versions_list=["2024-05-01", "2024-11-01-preview", "2025-12-01-preview", "2026-03-01"], + ) async def translate( self, body: Union[_models.DocumentTranslateContent, JSON], @@ -352,7 +387,9 @@ async def translate( target_language: str, source_language: Optional[str] = None, category: Optional[str] = None, + deployment_name: Optional[str] = None, allow_fallback: Optional[bool] = None, + translate_text_within_image: Optional[bool] = None, **kwargs: Any ) -> AsyncIterator[bytes]: """Submit a single document translation request to the Document Translation service. @@ -379,10 +416,16 @@ async def translate( project details to this parameter to use your deployed customized system. Default value is: general. Default value is None. :paramtype category: str + :keyword deployment_name: Deployment name of the custom translation model for the translation + request. Default value is None. + :paramtype deployment_name: str :keyword allow_fallback: Specifies that the service is allowed to fall back to a general system when a custom system doesn't exist. Possible values are: true (default) or false. Default value is None. :paramtype allow_fallback: bool + :keyword translate_text_within_image: Optional boolean parameter to translate text within an + image in the document. Default value is None. + :paramtype translate_text_within_image: bool :return: AsyncIterator[bytes] :rtype: AsyncIterator[bytes] :raises ~azure.core.exceptions.HttpResponseError: @@ -412,16 +455,17 @@ async def translate( _body = body.as_dict() if isinstance(body, _model_base.Model) else body _file_fields: List[str] = ["document", "glossary"] _data_fields: List[str] = [] - _files, _data = prepare_multipart_form_data(_body, _file_fields, _data_fields) + _files = prepare_multipart_form_data(_body, _file_fields, _data_fields) _request = build_single_document_translation_translate_request( target_language=target_language, source_language=source_language, category=category, + deployment_name=deployment_name, allow_fallback=allow_fallback, + translate_text_within_image=translate_text_within_image, api_version=self._config.api_version, files=_files, - data=_data, headers=_headers, params=_params, ) diff --git a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/aio/_patch.py b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/aio/_patch.py index e4d7ef70cc73..1523fc58d0f2 100644 --- a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/aio/_patch.py +++ b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/aio/_patch.py @@ -1,3 +1,4 @@ +# pylint: disable=line-too-long,useless-suppression # ------------------------------------ # Copyright (c) Microsoft Corporation. # Licensed under the MIT License. @@ -17,6 +18,9 @@ from ._operations._patch import AsyncDocumentTranslationLROPoller, AsyncDocumentTranslationLROPollingMethod from .._operations._patch import TranslationPolling from ._client import DocumentTranslationClient as GeneratedDocumentTranslationClient +from ._client import SingleDocumentTranslationClient as GeneratedSingleDocumentTranslationClient +from ._operations._patch import DocumentTranslationClientOperationsMixin +from ._operations._patch import SingleDocumentTranslationClientOperationsMixin from ..models import ( DocumentStatus, TranslationStatus, @@ -25,6 +29,7 @@ TranslationGlossary, DocumentTranslationInput, DocumentTranslationFileFormat, + FileFormatType, ) from ...document._patch import ( get_http_logging_policy, @@ -38,7 +43,7 @@ POLLING_INTERVAL = 1 -class DocumentTranslationClient(GeneratedDocumentTranslationClient): +class DocumentTranslationClient(DocumentTranslationClientOperationsMixin, GeneratedDocumentTranslationClient): """DocumentTranslationClient. :param endpoint: Supported document Translation endpoint, protocol and hostname, for example: @@ -48,7 +53,7 @@ class DocumentTranslationClient(GeneratedDocumentTranslationClient): AzureKeyCredential type or a TokenCredential type. Required. :type credential: ~azure.core.credentials.AzureKeyCredential or ~azure.core.credentials_async.AsyncTokenCredential - :keyword api_version: The API version to use for this operation. Default value is "2024-05-01". + :keyword api_version: The API version to use for this operation. Default value is "2026-03-01". Note that overriding this default value may result in unsupported behavior. :paramtype api_version: str :keyword int polling_interval: Default waiting time between two polls for LRO operations if no @@ -56,10 +61,7 @@ class DocumentTranslationClient(GeneratedDocumentTranslationClient): """ def __init__( - self, - endpoint: str, - credential: Union[AzureKeyCredential, AsyncTokenCredential], - **kwargs: Any + self, endpoint: str, credential: Union[AzureKeyCredential, AsyncTokenCredential], **kwargs: Any ) -> None: """DocumentTranslationClient is your interface to the Document Translation service. Use the client to translate whole documents while preserving source document @@ -119,7 +121,7 @@ async def close(self) -> None: """Close the :class:`~azure.ai.translation.document.aio.DocumentTranslationClient` session.""" await self._client.__aexit__() - @overload + @overload # type: ignore[override] async def begin_translation( self, source_url: str, @@ -132,6 +134,8 @@ async def begin_translation( storage_type: Optional[Union[str, StorageInputType]] = None, category_id: Optional[str] = None, glossaries: Optional[List[TranslationGlossary]] = None, + deployment_name: Optional[str] = None, + translate_text_within_image: Optional[bool] = None, **kwargs: Any ) -> AsyncDocumentTranslationLROPoller[AsyncItemPaged[DocumentStatus]]: """Begin translating the document(s) in your source container to your target container @@ -158,10 +162,14 @@ async def begin_translation( translation. This is most often use for file extensions. :keyword storage_type: Storage type of the input documents source string. Possible values include: "Folder", "File". - :paramtype storage_type: str or ~azure.ai.translation.document.StorageInputType + :paramtype storage_type: str or ~azure.ai.translation.document.models.StorageInputType :keyword str category_id: Category / custom model ID for using custom translation. :keyword glossaries: Glossaries to apply to translation. - :paramtype glossaries: list[~azure.ai.translation.document.TranslationGlossary] + :paramtype glossaries: list[~azure.ai.translation.document.models.TranslationGlossary] + :keyword str deployment_name: Deployment name of the custom translation model for the + translation request. + :keyword bool translate_text_within_image: Whether to translate text embedded within images + in the documents. :return: An instance of an AsyncDocumentTranslationLROPoller. Call `result()` on the poller object to return a pageable of DocumentStatus. A DocumentStatus will be returned for each translation on a document. @@ -170,7 +178,7 @@ async def begin_translation( """ @overload - async def begin_translation( + async def begin_translation( # pylint: disable=arguments-renamed self, inputs: StartTranslationDetails, **kwargs: Any ) -> AsyncDocumentTranslationLROPoller[AsyncItemPaged[DocumentStatus]]: """Begin translating the document(s) in your source container to your target container @@ -191,7 +199,7 @@ async def begin_translation( """ @overload - async def begin_translation( + async def begin_translation( # pylint: disable=arguments-renamed self, inputs: JSON, **kwargs: Any ) -> AsyncDocumentTranslationLROPoller[AsyncItemPaged[DocumentStatus]]: """Begin translating the document(s) in your source container to your target container @@ -249,7 +257,7 @@ async def begin_translation( """ @overload - async def begin_translation( + async def begin_translation( # pylint: disable=arguments-renamed self, inputs: IO[bytes], **kwargs: Any ) -> AsyncDocumentTranslationLROPoller[AsyncItemPaged[DocumentStatus]]: """Begin translating the document(s) in your source container to your target container @@ -270,7 +278,7 @@ async def begin_translation( """ @overload - async def begin_translation( + async def begin_translation( # pylint: disable=arguments-renamed self, inputs: List[DocumentTranslationInput], **kwargs: Any ) -> AsyncDocumentTranslationLROPoller[AsyncItemPaged[DocumentStatus]]: """Begin translating the document(s) in your source container to your target container @@ -282,7 +290,7 @@ async def begin_translation( :param inputs: A list of translation inputs. Each individual input has a single source URL to documents and can contain multiple TranslationTargets (one for each language) for the destination to write translated documents. - :type inputs: List[~azure.ai.translation.document.DocumentTranslationInput] + :type inputs: List[~azure.ai.translation.document.models.DocumentTranslationInput] :return: An instance of a AsyncDocumentTranslationLROPoller. Call `result()` on the poller object to return a pageable of DocumentStatus. A DocumentStatus will be returned for each translation on a document. @@ -303,7 +311,7 @@ async def begin_translation( # pylint: disable=docstring-missing-param,docstrin :param inputs: The translation inputs. Each individual input has a single source URL to documents and can contain multiple targets (one for each language) for the destination to write translated documents. - :type inputs: List[~azure.ai.translation.document.DocumentTranslationInput] or + :type inputs: List[~azure.ai.translation.document.models.DocumentTranslationInput] or IO[bytes] or JSON or ~azure.ai.translation.document.models.StartTranslationDetails :param str source_url: The source SAS URL to the Azure Blob container containing the documents to be translated. See the service documentation for the supported SAS permissions for accessing @@ -323,10 +331,10 @@ async def begin_translation( # pylint: disable=docstring-missing-param,docstrin translation. This is most often use for file extensions. :keyword storage_type: Storage type of the input documents source string. Possible values include: "Folder", "File". - :paramtype storage_type: str or ~azure.ai.translation.document.StorageInputType + :paramtype storage_type: str or ~azure.ai.translation.document.models.StorageInputType :keyword str category_id: Category / custom model ID for using custom translation. :keyword glossaries: Glossaries to apply to translation. - :paramtype glossaries: list[~azure.ai.translation.document.TranslationGlossary] + :paramtype glossaries: list[~azure.ai.translation.document.models.TranslationGlossary] :return: An instance of a DocumentTranslationLROPoller. Call `result()` on the poller object to return a pageable of DocumentStatus. A DocumentStatus will be returned for each translation on a document. @@ -520,7 +528,7 @@ async def get_supported_glossary_formats(self, **kwargs: Any) -> List[DocumentTr :raises ~azure.core.exceptions.HttpResponseError: """ - return (await super()._get_supported_formats(type="glossary", **kwargs)).value + return (await super()._get_supported_formats(type=FileFormatType.GLOSSARY, **kwargs)).value @distributed_trace_async async def get_supported_document_formats(self, **kwargs: Any) -> List[DocumentTranslationFileFormat]: @@ -531,11 +539,32 @@ async def get_supported_document_formats(self, **kwargs: Any) -> List[DocumentTr :raises ~azure.core.exceptions.HttpResponseError: """ - return (await super()._get_supported_formats(type="document", **kwargs)).value + return (await super()._get_supported_formats(type=FileFormatType.DOCUMENT, **kwargs)).value + + +class SingleDocumentTranslationClient( + SingleDocumentTranslationClientOperationsMixin, GeneratedSingleDocumentTranslationClient +): + """SingleDocumentTranslationClient is your interface to the Document Translation service to + translate a single document. + + :param endpoint: Supported document Translation endpoint, protocol and hostname, for example: + https://{TranslatorResourceName}.cognitiveservices.azure.com/translator. Required. + :type endpoint: str + :param credential: Credential used to authenticate requests to the service. Is either a key + credential type or a token credential type. Required. + :type credential: ~azure.core.credentials.AzureKeyCredential or + ~azure.core.credentials_async.AsyncTokenCredential + :keyword api_version: + The API version of the service to use for requests. It defaults to the latest service version. + Setting to an older version may result in reduced feature compatibility. + :paramtype api_version: str or ~azure.ai.translation.document.DocumentTranslationApiVersion + """ __all__: List[str] = [ "DocumentTranslationClient", + "SingleDocumentTranslationClient", "AsyncDocumentTranslationLROPoller", ] # Add all objects you want publicly available to users at this package level diff --git a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/aio/_vendor.py b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/aio/_vendor.py deleted file mode 100644 index d8c06c99fb96..000000000000 --- a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/aio/_vendor.py +++ /dev/null @@ -1,34 +0,0 @@ -# -------------------------------------------------------------------------- -# 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) Python Code Generator. -# Changes may cause incorrect behavior and will be lost if the code is regenerated. -# -------------------------------------------------------------------------- - -from abc import ABC -from typing import TYPE_CHECKING - -from ._configuration import DocumentTranslationClientConfiguration, SingleDocumentTranslationClientConfiguration - -if TYPE_CHECKING: - from azure.core import AsyncPipelineClient - - from .._serialization import Deserializer, Serializer - - -class DocumentTranslationClientMixinABC(ABC): - """DO NOT use this class. It is for internal typing use only.""" - - _client: "AsyncPipelineClient" - _config: DocumentTranslationClientConfiguration - _serialize: "Serializer" - _deserialize: "Deserializer" - - -class SingleDocumentTranslationClientMixinABC(ABC): - """DO NOT use this class. It is for internal typing use only.""" - - _client: "AsyncPipelineClient" - _config: SingleDocumentTranslationClientConfiguration - _serialize: "Serializer" - _deserialize: "Deserializer" diff --git a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/models/__init__.py b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/models/__init__.py index d14cd0756fdf..c70008c02424 100644 --- a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/models/__init__.py +++ b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/models/__init__.py @@ -5,50 +5,62 @@ # Code generated by Microsoft (R) Python Code Generator. # Changes may cause incorrect behavior and will be lost if the code is regenerated. # -------------------------------------------------------------------------- +# pylint: disable=wrong-import-position -from ._models import DocumentBatch -from ._models import DocumentFilter -from ._patch import DocumentStatus -from ._models import DocumentTranslateContent -from ._models import DocumentTranslationFileFormat -from ._patch import TranslationGlossary -from ._models import InnerTranslationError -from ._models import SourceInput -from ._models import StartTranslationDetails -from ._models import TranslationStatusSummary -from ._patch import TranslationTarget -from ._models import DocumentTranslationError -from ._patch import TranslationStatus -from ._patch import DocumentTranslationInput +from typing import TYPE_CHECKING -from ._enums import FileFormatType -from ._enums import Status -from ._enums import StorageInputType -from ._enums import TranslationStorageSource -from ._enums import TranslationErrorCode +if TYPE_CHECKING: + from ._patch import * # pylint: disable=unused-wildcard-import + +from ._models import ( # type: ignore + BatchOptions, + DocumentBatch, + DocumentFilter, + DocumentStatus, + DocumentTranslateContent, + DocumentTranslationError, + DocumentTranslationFileFormat, + InnerTranslationError, + SourceInput, + StartTranslationDetails, + TranslationGlossary, + TranslationStatus, + TranslationStatusSummary, + TranslationTarget, +) + +from ._enums import ( # type: ignore + FileFormatType, + Status, + StorageInputType, + TranslationErrorCode, + TranslationStorageSource, +) +from ._patch import __all__ as _patch_all +from ._patch import * from ._patch import patch_sdk as _patch_sdk __all__ = [ + "BatchOptions", "DocumentBatch", "DocumentFilter", "DocumentStatus", "DocumentTranslateContent", + "DocumentTranslationError", "DocumentTranslationFileFormat", - "TranslationGlossary", "InnerTranslationError", "SourceInput", "StartTranslationDetails", + "TranslationGlossary", + "TranslationStatus", "TranslationStatusSummary", "TranslationTarget", - "DocumentTranslationError", - "TranslationStatus", "FileFormatType", "Status", "StorageInputType", - "TranslationStorageSource", "TranslationErrorCode", - "DocumentTranslationInput", + "TranslationStorageSource", ] - +__all__.extend([p for p in _patch_all if p not in __all__]) # pyright: ignore _patch_sdk() diff --git a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/models/_enums.py b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/models/_enums.py index b3012b1998dc..5009fdd10af0 100644 --- a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/models/_enums.py +++ b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/models/_enums.py @@ -13,61 +13,61 @@ class FileFormatType(str, Enum, metaclass=CaseInsensitiveEnumMeta): """Format types.""" - DOCUMENT = "document" - """Document type file format""" - GLOSSARY = "glossary" - """Glossary type file format""" + DOCUMENT = "Document" + """Document type file format.""" + GLOSSARY = "Glossary" + """Glossary type file format.""" class Status(str, Enum, metaclass=CaseInsensitiveEnumMeta): """List of possible statuses for job or document.""" NOT_STARTED = "NotStarted" - """NotStarted""" + """NotStarted.""" RUNNING = "Running" - """Running""" + """Running.""" SUCCEEDED = "Succeeded" - """Succeeded""" + """Succeeded.""" FAILED = "Failed" - """Failed""" + """Failed.""" CANCELED = "Cancelled" - """Cancelled""" + """Cancelled.""" CANCELING = "Cancelling" - """Cancelling""" + """Cancelling.""" VALIDATION_FAILED = "ValidationFailed" - """ValidationFailed""" + """ValidationFailed.""" class StorageInputType(str, Enum, metaclass=CaseInsensitiveEnumMeta): """Storage type of the input documents source string.""" FOLDER = "Folder" - """Folder storage input type""" + """Folder storage input type.""" FILE = "File" - """File storage input type""" + """File storage input type.""" class TranslationErrorCode(str, Enum, metaclass=CaseInsensitiveEnumMeta): """Enums containing high level error codes.""" INVALID_REQUEST = "InvalidRequest" - """InvalidRequest""" + """InvalidRequest.""" INVALID_ARGUMENT = "InvalidArgument" - """InvalidArgument""" + """InvalidArgument.""" INTERNAL_SERVER_ERROR = "InternalServerError" - """InternalServerError""" + """InternalServerError.""" SERVICE_UNAVAILABLE = "ServiceUnavailable" - """ServiceUnavailable""" + """ServiceUnavailable.""" RESOURCE_NOT_FOUND = "ResourceNotFound" - """ResourceNotFound""" + """ResourceNotFound.""" UNAUTHORIZED = "Unauthorized" - """Unauthorized""" + """Unauthorized.""" REQUEST_RATE_TOO_HIGH = "RequestRateTooHigh" - """RequestRateTooHigh""" + """RequestRateTooHigh.""" class TranslationStorageSource(str, Enum, metaclass=CaseInsensitiveEnumMeta): """Storage Source.""" AZURE_BLOB = "AzureBlob" - """Azure blob storage source""" + """Azure blob storage source.""" diff --git a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/models/_models.py b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/models/_models.py index ab006704ffce..219764d11859 100644 --- a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/models/_models.py +++ b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/models/_models.py @@ -1,3 +1,4 @@ +# pylint: disable=line-too-long,useless-suppression # coding=utf-8 # -------------------------------------------------------------------------- # Copyright (c) Microsoft Corporation. All rights reserved. @@ -8,20 +9,47 @@ # pylint: disable=useless-super-delegation import datetime -from typing import Any, List, Mapping, Optional, TYPE_CHECKING, Union, overload +from typing import Any, Mapping, Optional, TYPE_CHECKING, Union, overload -from .. import _model_base -from .._model_base import rest_field -from .._vendor import FileType +from .._utils.model_base import Model as _Model, rest_field +from .._utils.utils import FileType if TYPE_CHECKING: from .. import models as _models -class DocumentBatch(_model_base.Model): - """Definition for the input batch translation request. +class BatchOptions(_Model): + """Translation batch request options. + + :ivar translate_text_within_image: Translation text within an image option. + :vartype translate_text_within_image: bool + """ + + translate_text_within_image: Optional[bool] = rest_field( + name="translateTextWithinImage", visibility=["read", "create", "update", "delete", "query"] + ) + """Translation text within an image option.""" + + @overload + def __init__( + self, + *, + translate_text_within_image: Optional[bool] = None, + ) -> None: ... + + @overload + def __init__(self, mapping: Mapping[str, Any]) -> None: + """ + :param mapping: raw JSON to initialize the model. + :type mapping: Mapping[str, Any] + """ + + def __init__(self, *args: Any, **kwargs: Any) -> None: + super().__init__(*args, **kwargs) - All required parameters must be populated in order to send to server. + +class DocumentBatch(_Model): + """Definition for the input batch translation request. :ivar source: Source of the input documents. Required. :vartype source: ~azure.ai.translation.document.models.SourceInput @@ -32,11 +60,13 @@ class DocumentBatch(_model_base.Model): :vartype storage_type: str or ~azure.ai.translation.document.models.StorageInputType """ - source: "_models.SourceInput" = rest_field() + source: "_models.SourceInput" = rest_field(visibility=["read", "create", "update", "delete", "query"]) """Source of the input documents. Required.""" - targets: List["_models.TranslationTarget"] = rest_field() + targets: list["_models.TranslationTarget"] = rest_field(visibility=["read", "create", "update", "delete", "query"]) """Location of the destination for the output. Required.""" - storage_type: Optional[Union[str, "_models.StorageInputType"]] = rest_field(name="storageType") + storage_type: Optional[Union[str, "_models.StorageInputType"]] = rest_field( + name="storageType", visibility=["read", "create", "update", "delete", "query"] + ) """Storage type of the input documents source string. Known values are: \"Folder\" and \"File\".""" @overload @@ -44,7 +74,7 @@ def __init__( self, *, source: "_models.SourceInput", - targets: List["_models.TranslationTarget"], + targets: list["_models.TranslationTarget"], storage_type: Optional[Union[str, "_models.StorageInputType"]] = None, ) -> None: ... @@ -59,29 +89,25 @@ def __init__(self, *args: Any, **kwargs: Any) -> None: super().__init__(*args, **kwargs) -class DocumentFilter(_model_base.Model): +class DocumentFilter(_Model): """Document filter. :ivar prefix: A case-sensitive prefix string to filter documents in the source path for - translation. - For example, when using a Azure storage blob Uri, use the prefix - to restrict sub folders for translation. + translation. For example, when using a Azure storage blob Uri, use the prefix to restrict sub + folders for translation. :vartype prefix: str :ivar suffix: A case-sensitive suffix string to filter documents in the source path for - translation. - This is most often use for file extensions. + translation. This is most often use for file extensions. :vartype suffix: str """ - prefix: Optional[str] = rest_field() - """A case-sensitive prefix string to filter documents in the source path for - translation. - For example, when using a Azure storage blob Uri, use the prefix - to restrict sub folders for translation.""" - suffix: Optional[str] = rest_field() - """A case-sensitive suffix string to filter documents in the source path for - translation. - This is most often use for file extensions.""" + prefix: Optional[str] = rest_field(visibility=["read", "create", "update", "delete", "query"]) + """A case-sensitive prefix string to filter documents in the source path for translation. For + example, when using a Azure storage blob Uri, use the prefix to restrict sub folders for + translation.""" + suffix: Optional[str] = rest_field(visibility=["read", "create", "update", "delete", "query"]) + """A case-sensitive suffix string to filter documents in the source path for translation. This is + most often use for file extensions.""" @overload def __init__( @@ -102,10 +128,9 @@ def __init__(self, *args: Any, **kwargs: Any) -> None: super().__init__(*args, **kwargs) -class DocumentStatus(_model_base.Model): +class DocumentStatus(_Model): """Document Status Response. - :ivar translated_document_url: Location of the document or folder. :vartype translated_document_url: str :ivar source_document_url: Location of the source document. Required. @@ -129,31 +154,74 @@ class DocumentStatus(_model_base.Model): :vartype id: str :ivar characters_charged: Character charged by the API. :vartype characters_charged: int + :ivar total_image_scans_succeeded: Total image scans charged by the API. + :vartype total_image_scans_succeeded: int + :ivar total_image_scans_failed: Total image scans failed. + :vartype total_image_scans_failed: int + :ivar images_charged: Images charged by the API. + :vartype images_charged: int + :ivar image_characters_detected: Characters detected within images. + :vartype image_characters_detected: int + :ivar deployment_name: Deployment name of the custom translation model used for the + translation. + :vartype deployment_name: str """ - translated_document_url: Optional[str] = rest_field(name="path") + translated_document_url: Optional[str] = rest_field( + name="path", visibility=["read", "create", "update", "delete", "query"] + ) """Location of the document or folder.""" - source_document_url: str = rest_field(name="sourcePath") + source_document_url: str = rest_field(name="sourcePath", visibility=["read", "create", "update", "delete", "query"]) """Location of the source document. Required.""" - created_on: datetime.datetime = rest_field(name="createdDateTimeUtc", format="rfc3339") + created_on: datetime.datetime = rest_field( + name="createdDateTimeUtc", visibility=["read", "create", "update", "delete", "query"], format="rfc3339" + ) """Operation created date time. Required.""" - last_updated_on: datetime.datetime = rest_field(name="lastActionDateTimeUtc", format="rfc3339") + last_updated_on: datetime.datetime = rest_field( + name="lastActionDateTimeUtc", visibility=["read", "create", "update", "delete", "query"], format="rfc3339" + ) """Date time in which the operation's status has been updated. Required.""" - status: Union[str, "_models.Status"] = rest_field() + status: Union[str, "_models.Status"] = rest_field(visibility=["read", "create", "update", "delete", "query"]) """List of possible statuses for job or document. Required. Known values are: \"NotStarted\", \"Running\", \"Succeeded\", \"Failed\", \"Cancelled\", \"Cancelling\", and \"ValidationFailed\".""" - translated_to: str = rest_field(name="to") + translated_to: str = rest_field(name="to", visibility=["read", "create", "update", "delete", "query"]) """To language. Required.""" - error: Optional["_models.DocumentTranslationError"] = rest_field() - """This contains an outer error with error code, message, details, target and an - inner error with more descriptive details.""" - translation_progress: float = rest_field(name="progress") + error: Optional["_models.DocumentTranslationError"] = rest_field( + visibility=["read", "create", "update", "delete", "query"] + ) + """This contains an outer error with error code, message, details, target and an inner error with + more descriptive details.""" + translation_progress: float = rest_field( + name="progress", visibility=["read", "create", "update", "delete", "query"] + ) """Progress of the translation if available. Required.""" - id: str = rest_field() + id: str = rest_field(visibility=["read", "create", "update", "delete", "query"]) """Document Id. Required.""" - characters_charged: Optional[int] = rest_field(name="characterCharged") + characters_charged: Optional[int] = rest_field( + name="characterCharged", visibility=["read", "create", "update", "delete", "query"] + ) """Character charged by the API.""" + total_image_scans_succeeded: Optional[int] = rest_field( + name="totalImageScansSucceeded", visibility=["read", "create", "update", "delete", "query"] + ) + """Total image scans charged by the API.""" + total_image_scans_failed: Optional[int] = rest_field( + name="totalImageScansFailed", visibility=["read", "create", "update", "delete", "query"] + ) + """Total image scans failed.""" + images_charged: Optional[int] = rest_field( + name="imageCharged", visibility=["read", "create", "update", "delete", "query"] + ) + """Images charged by the API.""" + image_characters_detected: Optional[int] = rest_field( + name="imageCharacterDetected", visibility=["read", "create", "update", "delete", "query"] + ) + """Characters detected within images.""" + deployment_name: Optional[str] = rest_field( + name="deploymentName", visibility=["read", "create", "update", "delete", "query"] + ) + """Deployment name of the custom translation model used for the translation.""" @overload def __init__( @@ -169,6 +237,11 @@ def __init__( translated_document_url: Optional[str] = None, error: Optional["_models.DocumentTranslationError"] = None, characters_charged: Optional[int] = None, + total_image_scans_succeeded: Optional[int] = None, + total_image_scans_failed: Optional[int] = None, + images_charged: Optional[int] = None, + image_characters_detected: Optional[int] = None, + deployment_name: Optional[str] = None, ) -> None: ... @overload @@ -182,20 +255,22 @@ def __init__(self, *args: Any, **kwargs: Any) -> None: super().__init__(*args, **kwargs) -class DocumentTranslateContent(_model_base.Model): +class DocumentTranslateContent(_Model): """Document Translate Request Content. - All required parameters must be populated in order to send to server. - :ivar document: Document to be translated in the form. Required. - :vartype document: ~azure.ai.translation.document._vendor.FileType + :vartype document: ~azure.ai.translation.document._utils.utils.FileType :ivar glossary: Glossary-translation memory will be used during translation in the form. - :vartype glossary: list[~azure.ai.translation.document._vendor.FileType] + :vartype glossary: list[~azure.ai.translation.document._utils.utils.FileType] """ - document: FileType = rest_field(is_multipart_file_input=True) + document: FileType = rest_field( + visibility=["read", "create", "update", "delete", "query"], is_multipart_file_input=True + ) """Document to be translated in the form. Required.""" - glossary: Optional[List[FileType]] = rest_field(is_multipart_file_input=True) + glossary: Optional[list[FileType]] = rest_field( + visibility=["read", "create", "update", "delete", "query"], is_multipart_file_input=True + ) """Glossary-translation memory will be used during translation in the form.""" @overload @@ -203,7 +278,7 @@ def __init__( self, *, document: FileType, - glossary: Optional[List[FileType]] = None, + glossary: Optional[list[FileType]] = None, ) -> None: ... @overload @@ -217,12 +292,9 @@ def __init__(self, *args: Any, **kwargs: Any) -> None: super().__init__(*args, **kwargs) -class DocumentTranslationError(_model_base.Model): - """This contains an outer error with error code, message, details, target and an - inner error with more descriptive details. - - Readonly variables are only populated by the server, and will be ignored when sending a request. - +class DocumentTranslationError(_Model): + """This contains an outer error with error code, message, details, target and an inner error with + more descriptive details. :ivar code: Enums containing high level error codes. Required. Known values are: "InvalidRequest", "InvalidArgument", "InternalServerError", "ServiceUnavailable", @@ -230,35 +302,37 @@ class DocumentTranslationError(_model_base.Model): :vartype code: str or ~azure.ai.translation.document.models.TranslationErrorCode :ivar message: Gets high level error message. Required. :vartype message: str - :ivar target: Gets the source of the error. - For example it would be "documents" or - "document id" in case of invalid document. + :ivar target: Gets the source of the error. For example it would be "documents" or "document + id" in case of invalid document. :vartype target: str :ivar inner_error: New Inner Error format which conforms to Cognitive Services API Guidelines which is available at - https://microsoft.sharepoint.com/%3Aw%3A/t/CognitiveServicesPMO/EUoytcrjuJdKpeOKIK_QRC8BPtUYQpKBi8JsWyeDMRsWlQ?e=CPq8ow. - This - contains required properties ErrorCode, message and optional properties target, + `https://microsoft.sharepoint.com/%3Aw%3A/t/CognitiveServicesPMO/EUoytcrjuJdKpeOKIK_QRC8BPtUYQpKBi8JsWyeDMRsWlQ?e=CPq8ow + `_. + This contains required properties ErrorCode, message and optional properties target, details(key value pair), inner error(this can be nested). :vartype inner_error: ~azure.ai.translation.document.models.InnerTranslationError """ - code: Union[str, "_models.TranslationErrorCode"] = rest_field() + code: Union[str, "_models.TranslationErrorCode"] = rest_field( + visibility=["read", "create", "update", "delete", "query"] + ) """Enums containing high level error codes. Required. Known values are: \"InvalidRequest\", \"InvalidArgument\", \"InternalServerError\", \"ServiceUnavailable\", \"ResourceNotFound\", \"Unauthorized\", and \"RequestRateTooHigh\".""" - message: str = rest_field() + message: str = rest_field(visibility=["read", "create", "update", "delete", "query"]) """Gets high level error message. Required.""" target: Optional[str] = rest_field(visibility=["read"]) - """Gets the source of the error. - For example it would be \"documents\" or - \"document id\" in case of invalid document.""" - inner_error: Optional["_models.InnerTranslationError"] = rest_field(name="innerError") - """New Inner Error format which conforms to Cognitive Services API Guidelines - which is available at - https://microsoft.sharepoint.com/%3Aw%3A/t/CognitiveServicesPMO/EUoytcrjuJdKpeOKIK_QRC8BPtUYQpKBi8JsWyeDMRsWlQ?e=CPq8ow. # pylint: disable=line-too-long - This - contains required properties ErrorCode, message and optional properties target, + """Gets the source of the error. For example it would be \"documents\" or \"document id\" in case + of invalid document.""" + inner_error: Optional["_models.InnerTranslationError"] = rest_field( + name="innerError", visibility=["read", "create", "update", "delete", "query"] + ) + """New Inner Error format which conforms to Cognitive Services API Guidelines which is available + at + `https://microsoft.sharepoint.com/%3Aw%3A/t/CognitiveServicesPMO/EUoytcrjuJdKpeOKIK_QRC8BPtUYQpKBi8JsWyeDMRsWlQ?e=CPq8ow + `_. + This contains required properties ErrorCode, message and optional properties target, details(key value pair), inner error(this can be nested).""" @overload @@ -281,10 +355,9 @@ def __init__(self, *args: Any, **kwargs: Any) -> None: super().__init__(*args, **kwargs) -class DocumentTranslationFileFormat(_model_base.Model): +class DocumentTranslationFileFormat(_Model): """File Format. - :ivar file_format: Name of the format. Required. :vartype file_format: str :ivar file_extensions: Supported file extension for this format. Required. @@ -295,32 +368,42 @@ class DocumentTranslationFileFormat(_model_base.Model): :vartype default_format_version: str :ivar format_versions: Supported Version. :vartype format_versions: list[str] - :ivar type: Supported Type for this format. Known values are: "document" and "glossary". + :ivar type: Supported Type for this format. Known values are: "Document" and "Glossary". :vartype type: str or ~azure.ai.translation.document.models.FileFormatType """ - file_format: str = rest_field(name="format") + file_format: str = rest_field(name="format", visibility=["read", "create", "update", "delete", "query"]) """Name of the format. Required.""" - file_extensions: List[str] = rest_field(name="fileExtensions") + file_extensions: list[str] = rest_field( + name="fileExtensions", visibility=["read", "create", "update", "delete", "query"] + ) """Supported file extension for this format. Required.""" - content_types: List[str] = rest_field(name="contentTypes") + content_types: list[str] = rest_field( + name="contentTypes", visibility=["read", "create", "update", "delete", "query"] + ) """Supported Content-Types for this format. Required.""" - default_format_version: Optional[str] = rest_field(name="defaultVersion") + default_format_version: Optional[str] = rest_field( + name="defaultVersion", visibility=["read", "create", "update", "delete", "query"] + ) """Default version if none is specified.""" - format_versions: Optional[List[str]] = rest_field(name="versions") + format_versions: Optional[list[str]] = rest_field( + name="versions", visibility=["read", "create", "update", "delete", "query"] + ) """Supported Version.""" - type: Optional[Union[str, "_models.FileFormatType"]] = rest_field() - """Supported Type for this format. Known values are: \"document\" and \"glossary\".""" + type: Optional[Union[str, "_models.FileFormatType"]] = rest_field( + visibility=["read", "create", "update", "delete", "query"] + ) + """Supported Type for this format. Known values are: \"Document\" and \"Glossary\".""" @overload def __init__( self, *, file_format: str, - file_extensions: List[str], - content_types: List[str], + file_extensions: list[str], + content_types: list[str], default_format_version: Optional[str] = None, - format_versions: Optional[List[str]] = None, + format_versions: Optional[list[str]] = None, type: Optional[Union[str, "_models.FileFormatType"]] = None, ) -> None: ... @@ -335,48 +418,45 @@ def __init__(self, *args: Any, **kwargs: Any) -> None: super().__init__(*args, **kwargs) -class InnerTranslationError(_model_base.Model): - """New Inner Error format which conforms to Cognitive Services API Guidelines - which is available at - https://microsoft.sharepoint.com/%3Aw%3A/t/CognitiveServicesPMO/EUoytcrjuJdKpeOKIK_QRC8BPtUYQpKBi8JsWyeDMRsWlQ?e=CPq8ow. - This - contains required properties ErrorCode, message and optional properties target, +class InnerTranslationError(_Model): + """New Inner Error format which conforms to Cognitive Services API Guidelines which is available + at + `https://microsoft.sharepoint.com/%3Aw%3A/t/CognitiveServicesPMO/EUoytcrjuJdKpeOKIK_QRC8BPtUYQpKBi8JsWyeDMRsWlQ?e=CPq8ow + `_. + This contains required properties ErrorCode, message and optional properties target, details(key value pair), inner error(this can be nested). - Readonly variables are only populated by the server, and will be ignored when sending a request. - - :ivar code: Gets code error string. Required. :vartype code: str :ivar message: Gets high level error message. Required. :vartype message: str - :ivar target: Gets the source of the error. - For example it would be "documents" or - "document id" in case of invalid document. + :ivar target: Gets the source of the error. For example it would be "documents" or "document + id" in case of invalid document. :vartype target: str :ivar inner_error: New Inner Error format which conforms to Cognitive Services API Guidelines which is available at - https://microsoft.sharepoint.com/%3Aw%3A/t/CognitiveServicesPMO/EUoytcrjuJdKpeOKIK_QRC8BPtUYQpKBi8JsWyeDMRsWlQ?e=CPq8ow. - This - contains required properties ErrorCode, message and optional properties target, + `https://microsoft.sharepoint.com/%3Aw%3A/t/CognitiveServicesPMO/EUoytcrjuJdKpeOKIK_QRC8BPtUYQpKBi8JsWyeDMRsWlQ?e=CPq8ow + `_. + This contains required properties ErrorCode, message and optional properties target, details(key value pair), inner error(this can be nested). :vartype inner_error: ~azure.ai.translation.document.models.InnerTranslationError """ - code: str = rest_field() + code: str = rest_field(visibility=["read", "create", "update", "delete", "query"]) """Gets code error string. Required.""" - message: str = rest_field() + message: str = rest_field(visibility=["read", "create", "update", "delete", "query"]) """Gets high level error message. Required.""" target: Optional[str] = rest_field(visibility=["read"]) - """Gets the source of the error. - For example it would be \"documents\" or - \"document id\" in case of invalid document.""" - inner_error: Optional["_models.InnerTranslationError"] = rest_field(name="innerError") - """New Inner Error format which conforms to Cognitive Services API Guidelines - which is available at - https://microsoft.sharepoint.com/%3Aw%3A/t/CognitiveServicesPMO/EUoytcrjuJdKpeOKIK_QRC8BPtUYQpKBi8JsWyeDMRsWlQ?e=CPq8ow. # pylint: disable=line-too-long - This - contains required properties ErrorCode, message and optional properties target, + """Gets the source of the error. For example it would be \"documents\" or \"document id\" in case + of invalid document.""" + inner_error: Optional["_models.InnerTranslationError"] = rest_field( + name="innerError", visibility=["read", "create", "update", "delete", "query"] + ) + """New Inner Error format which conforms to Cognitive Services API Guidelines which is available + at + `https://microsoft.sharepoint.com/%3Aw%3A/t/CognitiveServicesPMO/EUoytcrjuJdKpeOKIK_QRC8BPtUYQpKBi8JsWyeDMRsWlQ?e=CPq8ow + `_. + This contains required properties ErrorCode, message and optional properties target, details(key value pair), inner error(this can be nested).""" @overload @@ -399,31 +479,30 @@ def __init__(self, *args: Any, **kwargs: Any) -> None: super().__init__(*args, **kwargs) -class SourceInput(_model_base.Model): +class SourceInput(_Model): """Source of the input documents. - All required parameters must be populated in order to send to server. - :ivar source_url: Location of the folder / container or single file with your documents. Required. :vartype source_url: str :ivar filter: Document filter. :vartype filter: ~azure.ai.translation.document.models.DocumentFilter - :ivar language: Language code - If none is specified, we will perform auto detect on the document. + :ivar language: Language code If none is specified, we will perform auto detect on the + document. :vartype language: str :ivar storage_source: Storage Source. "AzureBlob" :vartype storage_source: str or ~azure.ai.translation.document.models.TranslationStorageSource """ - source_url: str = rest_field(name="sourceUrl") + source_url: str = rest_field(name="sourceUrl", visibility=["read", "create", "update", "delete", "query"]) """Location of the folder / container or single file with your documents. Required.""" - filter: Optional["_models.DocumentFilter"] = rest_field() + filter: Optional["_models.DocumentFilter"] = rest_field(visibility=["read", "create", "update", "delete", "query"]) """Document filter.""" - language: Optional[str] = rest_field() - """Language code - If none is specified, we will perform auto detect on the document.""" - storage_source: Optional[Union[str, "_models.TranslationStorageSource"]] = rest_field(name="storageSource") + language: Optional[str] = rest_field(visibility=["read", "create", "update", "delete", "query"]) + """Language code If none is specified, we will perform auto detect on the document.""" + storage_source: Optional[Union[str, "_models.TranslationStorageSource"]] = rest_field( + name="storageSource", visibility=["read", "create", "update", "delete", "query"] + ) """Storage Source. \"AzureBlob\"""" @overload @@ -447,23 +526,26 @@ def __init__(self, *args: Any, **kwargs: Any) -> None: super().__init__(*args, **kwargs) -class StartTranslationDetails(_model_base.Model): +class StartTranslationDetails(_Model): """Translation job submission batch request. - All required parameters must be populated in order to send to server. - :ivar inputs: The input list of documents or folders containing documents. Required. :vartype inputs: list[~azure.ai.translation.document.models.DocumentBatch] + :ivar options: The batch operation options. + :vartype options: ~azure.ai.translation.document.models.BatchOptions """ - inputs: List["_models.DocumentBatch"] = rest_field() + inputs: list["_models.DocumentBatch"] = rest_field(visibility=["read", "create", "update", "delete", "query"]) """The input list of documents or folders containing documents. Required.""" + options: Optional["_models.BatchOptions"] = rest_field(visibility=["read", "create", "update", "delete", "query"]) + """The batch operation options.""" @overload def __init__( self, *, - inputs: List["_models.DocumentBatch"], + inputs: list["_models.DocumentBatch"], + options: Optional["_models.BatchOptions"] = None, ) -> None: ... @overload @@ -477,40 +559,23 @@ def __init__(self, *args: Any, **kwargs: Any) -> None: super().__init__(*args, **kwargs) -class SupportedFileFormats(_model_base.Model): +class SupportedFileFormats(_Model): """List of supported file formats. - :ivar value: list of objects. Required. :vartype value: list[~azure.ai.translation.document.models.DocumentTranslationFileFormat] """ - value: List["_models.DocumentTranslationFileFormat"] = rest_field() + value: list["_models.DocumentTranslationFileFormat"] = rest_field( + visibility=["read", "create", "update", "delete", "query"] + ) """list of objects. Required.""" - -class TranslationErrorResponse(_model_base.Model): - """Contains unified error information used for HTTP responses across any Cognitive - Service. Instances - can be created either through - Microsoft.CloudAI.Containers.HttpStatusExceptionV2 or by returning it directly - from - a controller. - - :ivar error: This contains an outer error with error code, message, details, target and an - inner error with more descriptive details. - :vartype error: ~azure.ai.translation.document.models.DocumentTranslationError - """ - - error: Optional["_models.DocumentTranslationError"] = rest_field() - """This contains an outer error with error code, message, details, target and an - inner error with more descriptive details.""" - @overload def __init__( self, *, - error: Optional["_models.DocumentTranslationError"] = None, + value: list["_models.DocumentTranslationFileFormat"], ) -> None: ... @overload @@ -524,11 +589,9 @@ def __init__(self, *args: Any, **kwargs: Any) -> None: super().__init__(*args, **kwargs) -class TranslationGlossary(_model_base.Model): +class TranslationGlossary(_Model): """Glossary / translation memory for the request. - All required parameters must be populated in order to send to server. - :ivar glossary_url: Location of the glossary. We will use the file extension to extract the formatting if the format parameter is not supplied. @@ -544,18 +607,22 @@ class TranslationGlossary(_model_base.Model): :vartype storage_source: str or ~azure.ai.translation.document.models.TranslationStorageSource """ - glossary_url: str = rest_field(name="glossaryUrl") + glossary_url: str = rest_field(name="glossaryUrl", visibility=["read", "create", "update", "delete", "query"]) """Location of the glossary. We will use the file extension to extract the formatting if the format parameter is not supplied. If the translation language pair is not present in the glossary, it will not be applied. Required.""" - file_format: str = rest_field(name="format") + file_format: str = rest_field(name="format", visibility=["read", "create", "update", "delete", "query"]) """Format. Required.""" - format_version: Optional[str] = rest_field(name="version") + format_version: Optional[str] = rest_field( + name="version", visibility=["read", "create", "update", "delete", "query"] + ) """Optional Version. If not specified, default is used.""" - storage_source: Optional[Union[str, "_models.TranslationStorageSource"]] = rest_field(name="storageSource") + storage_source: Optional[Union[str, "_models.TranslationStorageSource"]] = rest_field( + name="storageSource", visibility=["read", "create", "update", "delete", "query"] + ) """Storage Source. \"AzureBlob\"""" @overload @@ -579,10 +646,9 @@ def __init__(self, *args: Any, **kwargs: Any) -> None: super().__init__(*args, **kwargs) -class TranslationStatus(_model_base.Model): +class TranslationStatus(_Model): """Translation job status response. - :ivar id: Id of the translation operation. Required. :vartype id: str :ivar created_on: Operation created date time. Required. @@ -600,20 +666,26 @@ class TranslationStatus(_model_base.Model): :vartype summary: ~azure.ai.translation.document.models.TranslationStatusSummary """ - id: str = rest_field() + id: str = rest_field(visibility=["read", "create", "update", "delete", "query"]) """Id of the translation operation. Required.""" - created_on: datetime.datetime = rest_field(name="createdDateTimeUtc", format="rfc3339") + created_on: datetime.datetime = rest_field( + name="createdDateTimeUtc", visibility=["read", "create", "update", "delete", "query"], format="rfc3339" + ) """Operation created date time. Required.""" - last_updated_on: datetime.datetime = rest_field(name="lastActionDateTimeUtc", format="rfc3339") + last_updated_on: datetime.datetime = rest_field( + name="lastActionDateTimeUtc", visibility=["read", "create", "update", "delete", "query"], format="rfc3339" + ) """Date time in which the operation's status has been updated. Required.""" - status: Union[str, "_models.Status"] = rest_field() + status: Union[str, "_models.Status"] = rest_field(visibility=["read", "create", "update", "delete", "query"]) """List of possible statuses for job or document. Required. Known values are: \"NotStarted\", \"Running\", \"Succeeded\", \"Failed\", \"Cancelled\", \"Cancelling\", and \"ValidationFailed\".""" - error: Optional["_models.DocumentTranslationError"] = rest_field() - """This contains an outer error with error code, message, details, target and an - inner error with more descriptive details.""" - summary: "_models.TranslationStatusSummary" = rest_field() + error: Optional["_models.DocumentTranslationError"] = rest_field( + visibility=["read", "create", "update", "delete", "query"] + ) + """This contains an outer error with error code, message, details, target and an inner error with + more descriptive details.""" + summary: "_models.TranslationStatusSummary" = rest_field(visibility=["read", "create", "update", "delete", "query"]) """Status Summary. Required.""" @overload @@ -639,10 +711,9 @@ def __init__(self, *args: Any, **kwargs: Any) -> None: super().__init__(*args, **kwargs) -class TranslationStatusSummary(_model_base.Model): +class TranslationStatusSummary(_Model): """Status Summary. - :ivar total: Total count. Required. :vartype total: int :ivar failed: Failed count. Required. @@ -657,22 +728,42 @@ class TranslationStatusSummary(_model_base.Model): :vartype canceled: int :ivar total_characters_charged: Total characters charged by the API. Required. :vartype total_characters_charged: int + :ivar total_image_scans_succeeded: Total image scans charged by the API. + :vartype total_image_scans_succeeded: int + :ivar total_image_scans_failed: Total image scans failed. + :vartype total_image_scans_failed: int + :ivar total_images_charged: Total images charged by the API. + :vartype total_images_charged: int """ - total: int = rest_field() + total: int = rest_field(visibility=["read", "create", "update", "delete", "query"]) """Total count. Required.""" - failed: int = rest_field() + failed: int = rest_field(visibility=["read", "create", "update", "delete", "query"]) """Failed count. Required.""" - success: int = rest_field() + success: int = rest_field(visibility=["read", "create", "update", "delete", "query"]) """Number of Success. Required.""" - in_progress: int = rest_field(name="inProgress") + in_progress: int = rest_field(name="inProgress", visibility=["read", "create", "update", "delete", "query"]) """Number of in progress. Required.""" - not_yet_started: int = rest_field(name="notYetStarted") + not_yet_started: int = rest_field(name="notYetStarted", visibility=["read", "create", "update", "delete", "query"]) """Count of not yet started. Required.""" - canceled: int = rest_field(name="cancelled") + canceled: int = rest_field(name="cancelled", visibility=["read", "create", "update", "delete", "query"]) """Number of cancelled. Required.""" - total_characters_charged: int = rest_field(name="totalCharacterCharged") + total_characters_charged: int = rest_field( + name="totalCharacterCharged", visibility=["read", "create", "update", "delete", "query"] + ) """Total characters charged by the API. Required.""" + total_image_scans_succeeded: Optional[int] = rest_field( + name="totalImageScansSucceeded", visibility=["read", "create", "update", "delete", "query"] + ) + """Total image scans charged by the API.""" + total_image_scans_failed: Optional[int] = rest_field( + name="totalImageScansFailed", visibility=["read", "create", "update", "delete", "query"] + ) + """Total image scans failed.""" + total_images_charged: Optional[int] = rest_field( + name="totalImageCharged", visibility=["read", "create", "update", "delete", "query"] + ) + """Total images charged by the API.""" @overload def __init__( @@ -685,6 +776,9 @@ def __init__( not_yet_started: int, canceled: int, total_characters_charged: int, + total_image_scans_succeeded: Optional[int] = None, + total_image_scans_failed: Optional[int] = None, + total_images_charged: Optional[int] = None, ) -> None: ... @overload @@ -698,15 +792,16 @@ def __init__(self, *args: Any, **kwargs: Any) -> None: super().__init__(*args, **kwargs) -class TranslationTarget(_model_base.Model): +class TranslationTarget(_Model): """Destination for the finished translated documents. - All required parameters must be populated in order to send to server. - :ivar target_url: Location of the folder / container with your documents. Required. :vartype target_url: str - :ivar category_id: Category / custom system for translation request. - :vartype category_id: str + :ivar category: Category / custom system for translation request. + :vartype category: str + :ivar deployment_name: Deployment name of the custom translation model for the translation + request. + :vartype deployment_name: str :ivar language: Target Language. Required. :vartype language: str :ivar glossaries: List of Glossary. @@ -715,15 +810,23 @@ class TranslationTarget(_model_base.Model): :vartype storage_source: str or ~azure.ai.translation.document.models.TranslationStorageSource """ - target_url: str = rest_field(name="targetUrl") + target_url: str = rest_field(name="targetUrl", visibility=["read", "create", "update", "delete", "query"]) """Location of the folder / container with your documents. Required.""" - category_id: Optional[str] = rest_field(name="category") + category: Optional[str] = rest_field(visibility=["read", "create", "update", "delete", "query"]) """Category / custom system for translation request.""" - language: str = rest_field() + deployment_name: Optional[str] = rest_field( + name="deploymentName", visibility=["read", "create", "update", "delete", "query"] + ) + """Deployment name of the custom translation model for the translation request.""" + language: str = rest_field(visibility=["read", "create", "update", "delete", "query"]) """Target Language. Required.""" - glossaries: Optional[List["_models.TranslationGlossary"]] = rest_field() + glossaries: Optional[list["_models.TranslationGlossary"]] = rest_field( + visibility=["read", "create", "update", "delete", "query"] + ) """List of Glossary.""" - storage_source: Optional[Union[str, "_models.TranslationStorageSource"]] = rest_field(name="storageSource") + storage_source: Optional[Union[str, "_models.TranslationStorageSource"]] = rest_field( + name="storageSource", visibility=["read", "create", "update", "delete", "query"] + ) """Storage Source. \"AzureBlob\"""" @overload @@ -732,8 +835,9 @@ def __init__( *, target_url: str, language: str, - category_id: Optional[str] = None, - glossaries: Optional[List["_models.TranslationGlossary"]] = None, + category: Optional[str] = None, + deployment_name: Optional[str] = None, + glossaries: Optional[list["_models.TranslationGlossary"]] = None, storage_source: Optional[Union[str, "_models.TranslationStorageSource"]] = None, ) -> None: ... diff --git a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/models/_patch.py b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/models/_patch.py index fc95f5ceb09d..487530ea078a 100644 --- a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/models/_patch.py +++ b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/models/_patch.py @@ -52,7 +52,7 @@ class DocumentTranslationInput: (see https://aka.ms/azsdk/documenttranslation/managed-identity). :param targets: Required. Location of the destination for the output. This is a list of TranslationTargets. Note that a TranslationTarget is required for each language code specified. - :type targets: list[~azure.ai.translation.document.TranslationTarget] + :type targets: list[~azure.ai.translation.document.models.TranslationTarget] :keyword Optional[str] source_language: Language code for the source documents. If none is specified, the source language will be auto-detected for each document. :keyword Optional[str] prefix: A case-sensitive prefix string to filter documents in the source path for @@ -62,7 +62,7 @@ class DocumentTranslationInput: translation. This is most often use for file extensions. :keyword storage_type: Storage type of the input documents source string. Possible values include: "Folder", "File". - :paramtype storage_type: Optional[str or ~azure.ai.translation.document.StorageInputType] + :paramtype storage_type: Optional[str or ~azure.ai.translation.document.models.StorageInputType] :keyword Optional[str] storage_source: Storage Source. Default value: "AzureBlob". Currently only "AzureBlob" is supported. """ @@ -149,6 +149,9 @@ class TranslationTarget(GeneratedTranslationTarget): :vartype target_url: str :ivar category_id: Category / custom system for translation request. :vartype category_id: str + :ivar deployment_name: Deployment name of the custom translation model for the translation + request. + :vartype deployment_name: str :ivar language: Target Language. Required. :vartype language: str :ivar glossaries: List of Glossary. @@ -159,8 +162,8 @@ class TranslationTarget(GeneratedTranslationTarget): target_url: str """Location of the folder / container with your documents. Required.""" - category_id: Optional[str] - """Category / custom system for translation request.""" + deployment_name: Optional[str] + """Deployment name of the custom translation model for the translation request.""" language: str """Target Language. Required.""" glossaries: Optional[List["TranslationGlossary"]] @@ -175,6 +178,7 @@ def __init__( language: str, *, category_id: Optional[str] = None, + deployment_name: Optional[str] = None, glossaries: Optional[List["TranslationGlossary"]] = None, storage_source: Optional[Union[str, "_models.TranslationStorageSource"]] = None, ): ... @@ -191,9 +195,24 @@ def __init__(self, *args: Any, **kwargs: Any) -> None: if not target and len(args) == 2: kwargs["target_url"] = args[0] kwargs["language"] = args[1] + args = () + if "category_id" in kwargs: + kwargs["category"] = kwargs.pop("category_id") super().__init__(*args, **kwargs) + @property + def category_id(self) -> Optional[str]: + """Category / custom system for translation request. + + :rtype: str or None + """ + return self.category + + @category_id.setter + def category_id(self, value: Optional[str]) -> None: + self.category = value + class TranslationGlossary(GeneratedTranslationGlossary): """Glossary / translation memory for the request. @@ -251,6 +270,7 @@ def __init__(self, *args: Any, **kwargs: Any) -> None: if not glossary and len(args) == 2: kwargs["glossary_url"] = args[0] kwargs["file_format"] = args[1] + args = () super().__init__(*args, **kwargs) @@ -281,6 +301,17 @@ class DocumentStatus(GeneratedDocumentStatus): :vartype id: str :ivar characters_charged: Character charged by the API. :vartype characters_charged: int + :ivar total_image_scans_succeeded: Total image scans succeeded. + :vartype total_image_scans_succeeded: int + :ivar total_image_scans_failed: Total image scans failed. + :vartype total_image_scans_failed: int + :ivar images_charged: Images charged by the API. + :vartype images_charged: int + :ivar image_characters_detected: Characters detected within images. + :vartype image_characters_detected: int + :ivar deployment_name: Deployment name of the custom translation model used for the + translation. + :vartype deployment_name: str """ translated_document_url: Optional[str] @@ -306,6 +337,16 @@ class DocumentStatus(GeneratedDocumentStatus): """Document Id. Required.""" characters_charged: Optional[int] """Character charged by the API.""" + total_image_scans_succeeded: Optional[int] + """Total image scans succeeded.""" + total_image_scans_failed: Optional[int] + """Total image scans failed.""" + images_charged: Optional[int] + """Images charged by the API.""" + image_characters_detected: Optional[int] + """Characters detected within images.""" + deployment_name: Optional[str] + """Deployment name of the custom translation model used for the translation.""" @overload def __init__( @@ -321,6 +362,11 @@ def __init__( translated_document_url: Optional[str] = None, error: Optional["_models.DocumentTranslationError"] = None, characters_charged: Optional[int] = None, + total_image_scans_succeeded: Optional[int] = None, + total_image_scans_failed: Optional[int] = None, + images_charged: Optional[int] = None, + image_characters_detected: Optional[int] = None, + deployment_name: Optional[str] = None, ): ... @overload diff --git a/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/types.py b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/types.py new file mode 100644 index 000000000000..87f2fa0112ca --- /dev/null +++ b/sdk/translation/azure-ai-translation-document/azure/ai/translation/document/types.py @@ -0,0 +1,187 @@ +# 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) Python Code Generator. +# Changes may cause incorrect behavior and will be lost if the code is regenerated. +# -------------------------------------------------------------------------- + +from typing import TYPE_CHECKING, Union +from typing_extensions import Required, TypedDict + +from ._utils.utils import FileType + +if TYPE_CHECKING: + from .models import StorageInputType, TranslationStorageSource + + +class BatchOptions(TypedDict, total=False): + """Translation batch request options. + + :ivar translate_text_within_image: Translation text within an image option. + :vartype translate_text_within_image: bool + """ + + translateTextWithinImage: bool + """Translation text within an image option.""" + + +class DocumentBatch(TypedDict, total=False): + """Definition for the input batch translation request. + + :ivar source: Source of the input documents. Required. + :vartype source: "SourceInput" + :ivar targets: Location of the destination for the output. Required. + :vartype targets: list["TranslationTarget"] + :ivar storage_type: Storage type of the input documents source string. Known values are: + "Folder" and "File". + :vartype storage_type: Union[str, "StorageInputType"] + """ + + source: Required["SourceInput"] + """Source of the input documents. Required.""" + targets: Required[list["TranslationTarget"]] + """Location of the destination for the output. Required.""" + storageType: Union[str, "StorageInputType"] + """Storage type of the input documents source string. Known values are: \"Folder\" and \"File\".""" + + +class DocumentFilter(TypedDict, total=False): + """Document filter. + + :ivar prefix: A case-sensitive prefix string to filter documents in the source path for + translation. For example, when using a Azure storage blob Uri, use the prefix to restrict sub + folders for translation. + :vartype prefix: str + :ivar suffix: A case-sensitive suffix string to filter documents in the source path for + translation. This is most often use for file extensions. + :vartype suffix: str + """ + + prefix: str + """A case-sensitive prefix string to filter documents in the source path for translation. For + example, when using a Azure storage blob Uri, use the prefix to restrict sub folders for + translation.""" + suffix: str + """A case-sensitive suffix string to filter documents in the source path for translation. This is + most often use for file extensions.""" + + +class DocumentTranslateContent(TypedDict, total=False): + """Document Translate Request Content. + + :ivar document: Document to be translated in the form. Required. + :vartype document: FileType + :ivar glossary: Glossary-translation memory will be used during translation in the form. + :vartype glossary: list[FileType] + """ + + document: Required[FileType] + """Document to be translated in the form. Required.""" + glossary: list[FileType] + """Glossary-translation memory will be used during translation in the form.""" + + +class SourceInput(TypedDict, total=False): + """Source of the input documents. + + :ivar source_url: Location of the folder / container or single file with your documents. + Required. + :vartype source_url: str + :ivar filter: Document filter. + :vartype filter: "DocumentFilter" + :ivar language: Language code If none is specified, we will perform auto detect on the + document. + :vartype language: str + :ivar storage_source: Storage Source. "AzureBlob" + :vartype storage_source: Union[str, "TranslationStorageSource"] + """ + + sourceUrl: Required[str] + """Location of the folder / container or single file with your documents. Required.""" + filter: "DocumentFilter" + """Document filter.""" + language: str + """Language code If none is specified, we will perform auto detect on the document.""" + storageSource: Union[str, "TranslationStorageSource"] + """Storage Source. \"AzureBlob\"""" + + +class StartTranslationDetails(TypedDict, total=False): + """Translation job submission batch request. + + :ivar inputs: The input list of documents or folders containing documents. Required. + :vartype inputs: list["DocumentBatch"] + :ivar options: The batch operation options. + :vartype options: "BatchOptions" + """ + + inputs: Required[list["DocumentBatch"]] + """The input list of documents or folders containing documents. Required.""" + options: "BatchOptions" + """The batch operation options.""" + + +class TranslationGlossary(TypedDict, total=False): + """Glossary / translation memory for the request. + + :ivar glossary_url: Location of the glossary. + We will use the file extension to extract the + formatting if the format parameter is not supplied. + + If the translation + language pair is not present in the glossary, it will not be applied. Required. + :vartype glossary_url: str + :ivar file_format: Format. Required. + :vartype file_format: str + :ivar format_version: Optional Version. If not specified, default is used. + :vartype format_version: str + :ivar storage_source: Storage Source. "AzureBlob" + :vartype storage_source: Union[str, "TranslationStorageSource"] + """ + + glossaryUrl: Required[str] + """Location of the glossary. + We will use the file extension to extract the + formatting if the format parameter is not supplied. + + If the translation + language pair is not present in the glossary, it will not be applied. Required.""" + format: Required[str] + """Format. Required.""" + version: str + """Optional Version. If not specified, default is used.""" + storageSource: Union[str, "TranslationStorageSource"] + """Storage Source. \"AzureBlob\"""" + + +class TranslationTarget(TypedDict, total=False): + """Destination for the finished translated documents. + + :ivar target_url: Location of the folder / container with your documents. Required. + :vartype target_url: str + :ivar category: Category / custom system for translation request. + :vartype category: str + :ivar deployment_name: Deployment name of the custom translation model for the translation + request. + :vartype deployment_name: str + :ivar language: Target Language. Required. + :vartype language: str + :ivar glossaries: List of Glossary. + :vartype glossaries: list["TranslationGlossary"] + :ivar storage_source: Storage Source. "AzureBlob" + :vartype storage_source: Union[str, "TranslationStorageSource"] + """ + + targetUrl: Required[str] + """Location of the folder / container with your documents. Required.""" + category: str + """Category / custom system for translation request.""" + deploymentName: str + """Deployment name of the custom translation model for the translation request.""" + language: Required[str] + """Target Language. Required.""" + glossaries: list["TranslationGlossary"] + """List of Glossary.""" + storageSource: Union[str, "TranslationStorageSource"] + """Storage Source. \"AzureBlob\"""" diff --git a/sdk/translation/azure-ai-translation-document/cspell.json b/sdk/translation/azure-ai-translation-document/cspell.json new file mode 100644 index 000000000000..077450317af6 --- /dev/null +++ b/sdk/translation/azure-ai-translation-document/cspell.json @@ -0,0 +1,7 @@ +{ + "version": "0.2", + "language": "en", + "words": [ + "deser" + ] +} diff --git a/sdk/translation/azure-ai-translation-document/samples/README.md b/sdk/translation/azure-ai-translation-document/samples/README.md index c778f3ca4380..88cae6d17d99 100644 --- a/sdk/translation/azure-ai-translation-document/samples/README.md +++ b/sdk/translation/azure-ai-translation-document/samples/README.md @@ -60,6 +60,8 @@ what you can do with the Azure Document Translation client library. |----------------|-------------| |[sample_translation_with_azure_blob.py][begin_translation_with_azure_blob] and [sample_translation_with_azure_blob_async.py][begin_translation_with_azure_blob_async]|Translate documents with upload/download help using Azure Blob Storage| |[sample_translation_with_custom_model.py][sample_translation_with_custom_model] and [sample_translation_with_custom_model_async.py][sample_translation_with_custom_model_async]|Translate documents using a custom model| +|[sample_translation_with_custom_model_deployment.py][sample_translation_with_custom_model_deployment] and [sample_translation_with_custom_model_deployment_async.py][sample_translation_with_custom_model_deployment_async]|Translate documents using a custom translation model deployment name| +|[sample_translation_with_image_translation.py][sample_translation_with_image_translation] and [sample_translation_with_image_translation_async.py][sample_translation_with_image_translation_async]|Translate text embedded within images in your documents| |[sample_begin_translation_with_filters.py][sample_begin_translation_with_filters] and [sample_begin_translation_with_filters_async.py][sample_begin_translation_with_filters_async]|Translate documents under a folder or translate only a specific document| |[sample_list_document_statuses_with_filters.py][sample_list_document_statuses_with_filters] and [sample_list_document_statuses_with_filters_async.py][sample_list_document_statuses_with_filters_async]|List document statuses using filters| |[sample_list_translations_with_filters.py][sample_list_translations_with_filters] and [sample_list_translations_with_filters_async.py][sample_list_translations_with_filters_async]|List translation operations using filters| @@ -83,6 +85,10 @@ what you can do with the Azure Document Translation client library. [list_translations_async]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/translation/azure-ai-translation-document/samples/async_samples/sample_list_translations_async.py [sample_translation_with_custom_model]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/translation/azure-ai-translation-document/samples/sample_translation_with_custom_model.py [sample_translation_with_custom_model_async]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/translation/azure-ai-translation-document/samples/async_samples/sample_translation_with_custom_model_async.py +[sample_translation_with_custom_model_deployment]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/translation/azure-ai-translation-document/samples/sample_translation_with_custom_model_deployment.py +[sample_translation_with_custom_model_deployment_async]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/translation/azure-ai-translation-document/samples/async_samples/sample_translation_with_custom_model_deployment_async.py +[sample_translation_with_image_translation]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/translation/azure-ai-translation-document/samples/sample_translation_with_image_translation.py +[sample_translation_with_image_translation_async]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/translation/azure-ai-translation-document/samples/async_samples/sample_translation_with_image_translation_async.py [sample_begin_translation_with_filters]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/translation/azure-ai-translation-document/samples/sample_begin_translation_with_filters.py [sample_begin_translation_with_filters_async]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/translation/azure-ai-translation-document/samples/async_samples/sample_begin_translation_with_filters_async.py [sample_list_document_statuses_with_filters]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/translation/azure-ai-translation-document/samples/sample_list_document_statuses_with_filters.py diff --git a/sdk/translation/azure-ai-translation-document/samples/async_samples/sample_begin_translation_async.py b/sdk/translation/azure-ai-translation-document/samples/async_samples/sample_begin_translation_async.py index 4dad31b85b77..960a7d336e2c 100644 --- a/sdk/translation/azure-ai-translation-document/samples/async_samples/sample_begin_translation_async.py +++ b/sdk/translation/azure-ai-translation-document/samples/async_samples/sample_begin_translation_async.py @@ -1,3 +1,4 @@ +# pylint: disable=line-too-long,useless-suppression # ------------------------------------ # Copyright (c) Microsoft Corporation. # Licensed under the MIT License. diff --git a/sdk/translation/azure-ai-translation-document/samples/async_samples/sample_begin_translation_with_filters_async.py b/sdk/translation/azure-ai-translation-document/samples/async_samples/sample_begin_translation_with_filters_async.py index 4fa3d844e478..43adaa2b7a51 100644 --- a/sdk/translation/azure-ai-translation-document/samples/async_samples/sample_begin_translation_with_filters_async.py +++ b/sdk/translation/azure-ai-translation-document/samples/async_samples/sample_begin_translation_with_filters_async.py @@ -1,3 +1,4 @@ +# pylint: disable=line-too-long,useless-suppression # coding=utf-8 # ------------------------------------ # Copyright (c) Microsoft Corporation. diff --git a/sdk/translation/azure-ai-translation-document/samples/async_samples/sample_translate_multiple_inputs_async.py b/sdk/translation/azure-ai-translation-document/samples/async_samples/sample_translate_multiple_inputs_async.py index 89867905621f..f56d912b6aa7 100644 --- a/sdk/translation/azure-ai-translation-document/samples/async_samples/sample_translate_multiple_inputs_async.py +++ b/sdk/translation/azure-ai-translation-document/samples/async_samples/sample_translate_multiple_inputs_async.py @@ -38,7 +38,7 @@ async def sample_multiple_translation_async(): import os from azure.core.credentials import AzureKeyCredential from azure.ai.translation.document.aio import DocumentTranslationClient - from azure.ai.translation.document import DocumentTranslationInput, TranslationTarget + from azure.ai.translation.document.models import DocumentTranslationInput, TranslationTarget endpoint = os.environ["AZURE_DOCUMENT_TRANSLATION_ENDPOINT"] key = os.environ["AZURE_DOCUMENT_TRANSLATION_KEY"] diff --git a/sdk/translation/azure-ai-translation-document/samples/async_samples/sample_translation_with_custom_model_deployment_async.py b/sdk/translation/azure-ai-translation-document/samples/async_samples/sample_translation_with_custom_model_deployment_async.py new file mode 100644 index 000000000000..18e0cd64ef78 --- /dev/null +++ b/sdk/translation/azure-ai-translation-document/samples/async_samples/sample_translation_with_custom_model_deployment_async.py @@ -0,0 +1,75 @@ +# ------------------------------------ +# Copyright (c) Microsoft Corporation. +# Licensed under the MIT License. +# ------------------------------------ + +""" +FILE: sample_translation_with_custom_model_deployment_async.py + +DESCRIPTION: + This sample demonstrates how to route a document translation request through a custom + translation model by specifying the model's deployment name. After the operation completes, + each document's status reports the deployment name that was used. + + 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_translation_with_custom_model_deployment_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) AZURE_SOURCE_CONTAINER_URL - the container SAS URL to your source container which has the documents + to be translated. + 4) AZURE_TARGET_CONTAINER_URL - the container SAS URL to your target container where the translated documents + will be written. + 5) AZURE_CUSTOM_MODEL_DEPLOYMENT_NAME - the deployment name of your custom translation model. +""" + +import asyncio + + +async def sample_translation_with_custom_model_deployment_async(): + import os + from azure.core.credentials import AzureKeyCredential + from azure.ai.translation.document.aio import DocumentTranslationClient + + endpoint = os.environ["AZURE_DOCUMENT_TRANSLATION_ENDPOINT"] + key = os.environ["AZURE_DOCUMENT_TRANSLATION_KEY"] + source_container_url = os.environ["AZURE_SOURCE_CONTAINER_URL"] + target_container_url = os.environ["AZURE_TARGET_CONTAINER_URL"] + deployment_name = os.environ["AZURE_CUSTOM_MODEL_DEPLOYMENT_NAME"] + + client = DocumentTranslationClient(endpoint, AzureKeyCredential(key)) + + async with client: + # Set the deployment name of your custom translation model on the request. + poller = await client.begin_translation( + source_container_url, + target_container_url, + "es", + deployment_name=deployment_name, + ) + result = await poller.result() + + print(f"Operation status: {poller.details.status}") + print(f"Total number of translations on documents: {poller.details.documents_total_count}") + + async for document in result: + print(f"Document ID: {document.id}") + print(f"Document status: {document.status}") + if document.status == "Succeeded": + print(f"Translated document location: {document.translated_document_url}") + print(f"Deployment name used: {document.deployment_name}") + print(f"Characters charged: {document.characters_charged}\n") + elif document.error: + print(f"Error Code: {document.error.code}, Message: {document.error.message}\n") + + +async def main(): + await sample_translation_with_custom_model_deployment_async() + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/sdk/translation/azure-ai-translation-document/samples/async_samples/sample_translation_with_glossaries_async.py b/sdk/translation/azure-ai-translation-document/samples/async_samples/sample_translation_with_glossaries_async.py index abc6983b1abf..6d954cc0226c 100644 --- a/sdk/translation/azure-ai-translation-document/samples/async_samples/sample_translation_with_glossaries_async.py +++ b/sdk/translation/azure-ai-translation-document/samples/async_samples/sample_translation_with_glossaries_async.py @@ -32,7 +32,7 @@ async def sample_translation_with_glossaries_async(): import os from azure.core.credentials import AzureKeyCredential from azure.ai.translation.document.aio import DocumentTranslationClient - from azure.ai.translation.document import TranslationGlossary + from azure.ai.translation.document.models import TranslationGlossary endpoint = os.environ["AZURE_DOCUMENT_TRANSLATION_ENDPOINT"] key = os.environ["AZURE_DOCUMENT_TRANSLATION_KEY"] diff --git a/sdk/translation/azure-ai-translation-document/samples/async_samples/sample_translation_with_image_translation_async.py b/sdk/translation/azure-ai-translation-document/samples/async_samples/sample_translation_with_image_translation_async.py new file mode 100644 index 000000000000..018848f5f571 --- /dev/null +++ b/sdk/translation/azure-ai-translation-document/samples/async_samples/sample_translation_with_image_translation_async.py @@ -0,0 +1,77 @@ +# ------------------------------------ +# Copyright (c) Microsoft Corporation. +# Licensed under the MIT License. +# ------------------------------------ + +""" +FILE: sample_translation_with_image_translation_async.py + +DESCRIPTION: + This sample demonstrates how to start a batch translation that also translates text + embedded within images in your documents by enabling `translate_text_within_image`. + When enabled, each document's status reports image scan usage details. + + 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_translation_with_image_translation_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) AZURE_SOURCE_CONTAINER_URL - the container SAS URL to your source container which has the documents + to be translated. + 4) AZURE_TARGET_CONTAINER_URL - the container SAS URL to your target container where the translated documents + will be written. +""" + +import asyncio + + +async def sample_translation_with_image_translation_async(): + import os + from azure.core.credentials import AzureKeyCredential + from azure.ai.translation.document.aio import DocumentTranslationClient + + endpoint = os.environ["AZURE_DOCUMENT_TRANSLATION_ENDPOINT"] + key = os.environ["AZURE_DOCUMENT_TRANSLATION_KEY"] + source_container_url = os.environ["AZURE_SOURCE_CONTAINER_URL"] + target_container_url = os.environ["AZURE_TARGET_CONTAINER_URL"] + + client = DocumentTranslationClient(endpoint, AzureKeyCredential(key)) + + async with client: + # Enable translation of text embedded within images for the batch. + poller = await client.begin_translation( + source_container_url, + target_container_url, + "es", + translate_text_within_image=True, + ) + result = await poller.result() + + print(f"Operation status: {poller.details.status}") + print(f"Total number of translations on documents: {poller.details.documents_total_count}") + + async for document in result: + print(f"Document ID: {document.id}") + print(f"Document status: {document.status}") + if document.status == "Succeeded": + print(f"Translated document location: {document.translated_document_url}") + print(f"Characters charged: {document.characters_charged}") + # Image scan usage is reported when image translation is enabled. + print(f"Total image scans succeeded: {document.total_image_scans_succeeded}") + print(f"Total image scans failed: {document.total_image_scans_failed}") + print(f"Images charged: {document.images_charged}") + print(f"Characters detected within images: {document.image_characters_detected}\n") + elif document.error: + print(f"Error Code: {document.error.code}, Message: {document.error.message}\n") + + +async def main(): + await sample_translation_with_image_translation_async() + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/sdk/translation/azure-ai-translation-document/samples/sample_begin_translation_with_filters.py b/sdk/translation/azure-ai-translation-document/samples/sample_begin_translation_with_filters.py index 5fca65452a8f..cae5f1852a67 100644 --- a/sdk/translation/azure-ai-translation-document/samples/sample_begin_translation_with_filters.py +++ b/sdk/translation/azure-ai-translation-document/samples/sample_begin_translation_with_filters.py @@ -1,3 +1,4 @@ +# pylint: disable=line-too-long,useless-suppression # coding=utf-8 # ------------------------------------ # Copyright (c) Microsoft Corporation. diff --git a/sdk/translation/azure-ai-translation-document/samples/sample_translate_multiple_inputs.py b/sdk/translation/azure-ai-translation-document/samples/sample_translate_multiple_inputs.py index efa28704d30e..32575b6fdf82 100644 --- a/sdk/translation/azure-ai-translation-document/samples/sample_translate_multiple_inputs.py +++ b/sdk/translation/azure-ai-translation-document/samples/sample_translate_multiple_inputs.py @@ -36,7 +36,8 @@ def sample_multiple_translation(): # [START multiple_translation] import os from azure.core.credentials import AzureKeyCredential - from azure.ai.translation.document import DocumentTranslationClient, DocumentTranslationInput, TranslationTarget + from azure.ai.translation.document import DocumentTranslationClient + from azure.ai.translation.document.models import DocumentTranslationInput, TranslationTarget endpoint = os.environ["AZURE_DOCUMENT_TRANSLATION_ENDPOINT"] key = os.environ["AZURE_DOCUMENT_TRANSLATION_KEY"] diff --git a/sdk/translation/azure-ai-translation-document/samples/sample_translation_with_custom_model_deployment.py b/sdk/translation/azure-ai-translation-document/samples/sample_translation_with_custom_model_deployment.py new file mode 100644 index 000000000000..4b9c97cf7660 --- /dev/null +++ b/sdk/translation/azure-ai-translation-document/samples/sample_translation_with_custom_model_deployment.py @@ -0,0 +1,69 @@ +# ------------------------------------ +# Copyright (c) Microsoft Corporation. +# Licensed under the MIT License. +# ------------------------------------ + +""" +FILE: sample_translation_with_custom_model_deployment.py + +DESCRIPTION: + This sample demonstrates how to route a document translation request through a custom + translation model by specifying the model's deployment name. The deployment name can be + supplied for both batch and single document translation. After the operation completes, + each document's status reports the deployment name that was used. + + 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_translation_with_custom_model_deployment.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) AZURE_SOURCE_CONTAINER_URL - the container SAS URL to your source container which has the documents + to be translated. + 4) AZURE_TARGET_CONTAINER_URL - the container SAS URL to your target container where the translated documents + will be written. + 5) AZURE_CUSTOM_MODEL_DEPLOYMENT_NAME - the deployment name of your custom translation model. +""" + + +def sample_translation_with_custom_model_deployment(): + import os + from azure.core.credentials import AzureKeyCredential + from azure.ai.translation.document import DocumentTranslationClient + + endpoint = os.environ["AZURE_DOCUMENT_TRANSLATION_ENDPOINT"] + key = os.environ["AZURE_DOCUMENT_TRANSLATION_KEY"] + source_container_url = os.environ["AZURE_SOURCE_CONTAINER_URL"] + target_container_url = os.environ["AZURE_TARGET_CONTAINER_URL"] + deployment_name = os.environ["AZURE_CUSTOM_MODEL_DEPLOYMENT_NAME"] + + client = DocumentTranslationClient(endpoint, AzureKeyCredential(key)) + + # Set the deployment name of your custom translation model on the request. + poller = client.begin_translation( + source_container_url, + target_container_url, + "es", + deployment_name=deployment_name, + ) + result = poller.result() + + print(f"Operation status: {poller.details.status}") + print(f"Total number of translations on documents: {poller.details.documents_total_count}") + + for document in result: + print(f"Document ID: {document.id}") + print(f"Document status: {document.status}") + if document.status == "Succeeded": + print(f"Translated document location: {document.translated_document_url}") + print(f"Deployment name used: {document.deployment_name}") + print(f"Characters charged: {document.characters_charged}\n") + elif document.error: + print(f"Error Code: {document.error.code}, Message: {document.error.message}\n") + + +if __name__ == "__main__": + sample_translation_with_custom_model_deployment() diff --git a/sdk/translation/azure-ai-translation-document/samples/sample_translation_with_glossaries.py b/sdk/translation/azure-ai-translation-document/samples/sample_translation_with_glossaries.py index 48ed264c9296..2a54f2a2ee70 100644 --- a/sdk/translation/azure-ai-translation-document/samples/sample_translation_with_glossaries.py +++ b/sdk/translation/azure-ai-translation-document/samples/sample_translation_with_glossaries.py @@ -29,7 +29,8 @@ def sample_translation_with_glossaries(): import os from azure.core.credentials import AzureKeyCredential - from azure.ai.translation.document import DocumentTranslationClient, TranslationGlossary + from azure.ai.translation.document import DocumentTranslationClient + from azure.ai.translation.document.models import TranslationGlossary endpoint = os.environ["AZURE_DOCUMENT_TRANSLATION_ENDPOINT"] key = os.environ["AZURE_DOCUMENT_TRANSLATION_KEY"] diff --git a/sdk/translation/azure-ai-translation-document/samples/sample_translation_with_image_translation.py b/sdk/translation/azure-ai-translation-document/samples/sample_translation_with_image_translation.py new file mode 100644 index 000000000000..0a2efecb255f --- /dev/null +++ b/sdk/translation/azure-ai-translation-document/samples/sample_translation_with_image_translation.py @@ -0,0 +1,70 @@ +# ------------------------------------ +# Copyright (c) Microsoft Corporation. +# Licensed under the MIT License. +# ------------------------------------ + +""" +FILE: sample_translation_with_image_translation.py + +DESCRIPTION: + This sample demonstrates how to start a batch translation that also translates text + embedded within images in your documents by enabling `translate_text_within_image`. + When enabled, each document's status reports image scan usage details. + + 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_translation_with_image_translation.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) AZURE_SOURCE_CONTAINER_URL - the container SAS URL to your source container which has the documents + to be translated. + 4) AZURE_TARGET_CONTAINER_URL - the container SAS URL to your target container where the translated documents + will be written. +""" + + +def sample_translation_with_image_translation(): + import os + from azure.core.credentials import AzureKeyCredential + from azure.ai.translation.document import DocumentTranslationClient + + endpoint = os.environ["AZURE_DOCUMENT_TRANSLATION_ENDPOINT"] + key = os.environ["AZURE_DOCUMENT_TRANSLATION_KEY"] + source_container_url = os.environ["AZURE_SOURCE_CONTAINER_URL"] + target_container_url = os.environ["AZURE_TARGET_CONTAINER_URL"] + + client = DocumentTranslationClient(endpoint, AzureKeyCredential(key)) + + # Enable translation of text embedded within images for the batch. + poller = client.begin_translation( + source_container_url, + target_container_url, + "es", + translate_text_within_image=True, + ) + result = poller.result() + + print(f"Operation status: {poller.details.status}") + print(f"Total number of translations on documents: {poller.details.documents_total_count}") + + for document in result: + print(f"Document ID: {document.id}") + print(f"Document status: {document.status}") + if document.status == "Succeeded": + print(f"Translated document location: {document.translated_document_url}") + print(f"Characters charged: {document.characters_charged}") + # Image scan usage is reported when image translation is enabled. + print(f"Total image scans succeeded: {document.total_image_scans_succeeded}") + print(f"Total image scans failed: {document.total_image_scans_failed}") + print(f"Images charged: {document.images_charged}") + print(f"Characters detected within images: {document.image_characters_detected}\n") + elif document.error: + print(f"Error Code: {document.error.code}, Message: {document.error.message}\n") + + +if __name__ == "__main__": + sample_translation_with_image_translation() diff --git a/sdk/translation/azure-ai-translation-document/setup.py b/sdk/translation/azure-ai-translation-document/setup.py index 8464b676cfe9..d404ba9554ef 100644 --- a/sdk/translation/azure-ai-translation-document/setup.py +++ b/sdk/translation/azure-ai-translation-document/setup.py @@ -42,7 +42,6 @@ "Programming Language :: Python", "Programming Language :: Python :: 3 :: Only", "Programming Language :: Python :: 3", - "Programming Language :: Python :: 3.8", "Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", @@ -69,5 +68,5 @@ "azure-core>=1.30.0", "typing-extensions>=4.6.0", ], - python_requires=">=3.8", + python_requires=">=3.9", ) diff --git a/sdk/translation/azure-ai-translation-document/tests/TestData/test-doc-image.docx b/sdk/translation/azure-ai-translation-document/tests/TestData/test-doc-image.docx new file mode 100644 index 000000000000..a5c220411ae7 Binary files /dev/null and b/sdk/translation/azure-ai-translation-document/tests/TestData/test-doc-image.docx differ diff --git a/sdk/translation/azure-ai-translation-document/tests/asynctestcase.py b/sdk/translation/azure-ai-translation-document/tests/asynctestcase.py index 70a2b169a88f..3c26e1f89d52 100644 --- a/sdk/translation/azure-ai-translation-document/tests/asynctestcase.py +++ b/sdk/translation/azure-ai-translation-document/tests/asynctestcase.py @@ -3,10 +3,15 @@ # Licensed under the MIT License. # ------------------------------------ -from azure.ai.translation.document.models import DocumentBatch, SourceInput, StartTranslationDetails +from azure.ai.translation.document.models import ( + DocumentBatch, + SourceInput, + StartTranslationDetails, + DocumentTranslationInput, + TranslationTarget, +) from devtools_testutils import AzureRecordedTestCase from testcase import DocumentTranslationTest, Document -from azure.ai.translation.document import DocumentTranslationInput, TranslationTarget class AsyncDocumentTranslationTest(DocumentTranslationTest, AzureRecordedTestCase): diff --git a/sdk/translation/azure-ai-translation-document/tests/preparer.py b/sdk/translation/azure-ai-translation-document/tests/preparer.py index e07fdf5fddae..75d204f30d4e 100644 --- a/sdk/translation/azure-ai-translation-document/tests/preparer.py +++ b/sdk/translation/azure-ai-translation-document/tests/preparer.py @@ -14,7 +14,6 @@ "translation", document_translation_endpoint="https://fakeendpoint.cognitiveservices.azure.com", document_translation_storage_name="fakeendpoint", - document_translation_storage_key="fakeZmFrZV9hY29jdW50X2tleQ==", ) diff --git a/sdk/translation/azure-ai-translation-document/tests/test_cancel_translation.py b/sdk/translation/azure-ai-translation-document/tests/test_cancel_translation.py index 44e1d2428308..35f2a90698f4 100644 --- a/sdk/translation/azure-ai-translation-document/tests/test_cancel_translation.py +++ b/sdk/translation/azure-ai-translation-document/tests/test_cancel_translation.py @@ -13,7 +13,8 @@ ) from devtools_testutils import recorded_by_proxy from azure.core.exceptions import HttpResponseError -from azure.ai.translation.document import DocumentTranslationClient, DocumentTranslationInput, TranslationTarget +from azure.ai.translation.document import DocumentTranslationClient +from azure.ai.translation.document.models import DocumentTranslationInput, TranslationTarget DocumentTranslationClientPreparer = functools.partial(_DocumentTranslationClientPreparer, DocumentTranslationClient) diff --git a/sdk/translation/azure-ai-translation-document/tests/test_cancel_translation_async.py b/sdk/translation/azure-ai-translation-document/tests/test_cancel_translation_async.py index 03416b541747..3577cfc1e9f1 100644 --- a/sdk/translation/azure-ai-translation-document/tests/test_cancel_translation_async.py +++ b/sdk/translation/azure-ai-translation-document/tests/test_cancel_translation_async.py @@ -12,7 +12,7 @@ DocumentTranslationClientPreparer as _DocumentTranslationClientPreparer, ) from devtools_testutils.aio import recorded_by_proxy_async -from azure.ai.translation.document import DocumentTranslationInput, TranslationTarget +from azure.ai.translation.document.models import DocumentTranslationInput, TranslationTarget from azure.ai.translation.document.aio import DocumentTranslationClient from azure.core.exceptions import HttpResponseError diff --git a/sdk/translation/azure-ai-translation-document/tests/test_document_status.py b/sdk/translation/azure-ai-translation-document/tests/test_document_status.py index 091c57bf6406..220373166c1e 100644 --- a/sdk/translation/azure-ai-translation-document/tests/test_document_status.py +++ b/sdk/translation/azure-ai-translation-document/tests/test_document_status.py @@ -10,7 +10,7 @@ DocumentTranslationClientPreparer as _DocumentTranslationClientPreparer, ) from devtools_testutils import recorded_by_proxy -from azure.ai.translation.document import DocumentTranslationInput, TranslationTarget +from azure.ai.translation.document.models import DocumentTranslationInput, TranslationTarget from azure.ai.translation.document import DocumentTranslationClient DocumentTranslationClientPreparer = functools.partial(_DocumentTranslationClientPreparer, DocumentTranslationClient) diff --git a/sdk/translation/azure-ai-translation-document/tests/test_document_status_async.py b/sdk/translation/azure-ai-translation-document/tests/test_document_status_async.py index 95ab5c62d06b..a5961a959ba6 100644 --- a/sdk/translation/azure-ai-translation-document/tests/test_document_status_async.py +++ b/sdk/translation/azure-ai-translation-document/tests/test_document_status_async.py @@ -11,7 +11,7 @@ DocumentTranslationClientPreparer as _DocumentTranslationClientPreparer, ) from devtools_testutils.aio import recorded_by_proxy_async -from azure.ai.translation.document import DocumentTranslationInput, TranslationTarget +from azure.ai.translation.document.models import DocumentTranslationInput, TranslationTarget from azure.ai.translation.document.aio import DocumentTranslationClient DocumentTranslationClientPreparer = functools.partial(_DocumentTranslationClientPreparer, DocumentTranslationClient) diff --git a/sdk/translation/azure-ai-translation-document/tests/test_list_document_statuses.py b/sdk/translation/azure-ai-translation-document/tests/test_list_document_statuses.py index 725e89a4a685..f7fd7fcab9df 100644 --- a/sdk/translation/azure-ai-translation-document/tests/test_list_document_statuses.py +++ b/sdk/translation/azure-ai-translation-document/tests/test_list_document_statuses.py @@ -46,7 +46,7 @@ def test_list_document_statuses(self, **kwargs): def test_list_document_statuses_with_skip(self, **kwargs): client = kwargs.pop("client") variables = kwargs.pop("variables", {}) - docs_count = 10 + docs_count = 5 skip = 2 target_language = "es" @@ -70,7 +70,7 @@ def test_list_document_statuses_with_skip(self, **kwargs): def test_list_document_statuses_filter_by_status(self, **kwargs): client = kwargs.pop("client") variables = kwargs.pop("variables", {}) - docs_count = 10 + docs_count = 5 target_language = "es" # submit and validate operation @@ -180,7 +180,7 @@ def test_list_document_statuses_order_by_creation_time_desc(self, **kwargs): def test_list_document_statuses_mixed_filters(self, **kwargs): client = kwargs.pop("client") variables = kwargs.pop("variables", {}) - docs_count = 10 + docs_count = 5 target_language = "es" skip = 1 statuses = ["Succeeded"] diff --git a/sdk/translation/azure-ai-translation-document/tests/test_list_document_statuses_async.py b/sdk/translation/azure-ai-translation-document/tests/test_list_document_statuses_async.py index 43ea2d9a5ae9..0df60334a319 100644 --- a/sdk/translation/azure-ai-translation-document/tests/test_list_document_statuses_async.py +++ b/sdk/translation/azure-ai-translation-document/tests/test_list_document_statuses_async.py @@ -76,7 +76,7 @@ async def test_list_document_statuses_with_skip(self, **kwargs): async def test_list_document_statuses_filter_by_status(self, **kwargs): client = kwargs.pop("client") variables = kwargs.pop("variables", {}) - docs_count = 10 + docs_count = 5 target_language = "es" # submit and validate operation @@ -113,7 +113,7 @@ async def test_list_document_statuses_filter_by_status(self, **kwargs): async def test_list_document_statuses_filter_by_ids(self, **kwargs): client = kwargs.pop("client") variables = kwargs.pop("variables", {}) - docs_count = 15 + docs_count = 5 target_language = "es" # submit and validate operation @@ -199,10 +199,10 @@ async def test_list_document_statuses_order_by_creation_time_desc(self, **kwargs async def test_list_document_statuses_mixed_filters(self, **kwargs): client = kwargs.pop("client") variables = kwargs.pop("variables", {}) - docs_count = 25 + docs_count = 5 target_language = "es" statuses = ["Succeeded"] - skip = 3 + skip = 1 # submit and validate operation poller = await self._begin_and_validate_translation_with_multiple_docs_async( diff --git a/sdk/translation/azure-ai-translation-document/tests/test_list_translations.py b/sdk/translation/azure-ai-translation-document/tests/test_list_translations.py index b8c8d3d3d388..ebad5f66cd96 100644 --- a/sdk/translation/azure-ai-translation-document/tests/test_list_translations.py +++ b/sdk/translation/azure-ai-translation-document/tests/test_list_translations.py @@ -26,8 +26,8 @@ def test_list_translations(self, **kwargs): client = kwargs.pop("client") variables = kwargs.pop("variables", {}) # create some translations - operations_count = 5 - docs_per_operation = 5 + operations_count = 2 + docs_per_operation = 1 self._begin_multiple_translations( client, operations_count, docs_per_operation=docs_per_operation, wait=False, variables=variables ) @@ -51,8 +51,8 @@ def test_list_translations_with_skip(self, **kwargs): client = kwargs.pop("client") variables = kwargs.pop("variables", {}) # prepare data - operations_count = 10 - docs_per_operation = 2 + operations_count = 2 + docs_per_operation = 1 skip = 5 # create some translations @@ -72,7 +72,7 @@ def test_list_translations_with_skip(self, **kwargs): def test_list_translations_filter_by_status(self, **kwargs): client = kwargs.pop("client") variables = kwargs.pop("variables", {}) - operations_count = 5 + operations_count = 2 docs_per_operation = 1 # create some translations with the status 'Succeeded' @@ -109,8 +109,8 @@ def test_list_translations_filter_by_status(self, **kwargs): def test_list_translations_filter_by_ids(self, **kwargs): client = kwargs.pop("client") variables = kwargs.pop("variables", {}) - operations_count = 3 - docs_per_operation = 2 + operations_count = 2 + docs_per_operation = 1 # create some translations translation_ids = self._begin_multiple_translations( @@ -132,8 +132,8 @@ def test_list_translations_filter_by_ids(self, **kwargs): def test_list_translations_filter_by_created_after(self, **kwargs): client = kwargs.pop("client") # create some translations - operations_count = 3 - docs_per_operation = 2 + operations_count = 2 + docs_per_operation = 1 # create some translations start = datetime.utcnow() @@ -159,7 +159,7 @@ def test_list_translations_filter_by_created_before(self, **kwargs): 'end' must be timezone-aware! """ client = kwargs.pop("client") - operations_count = 5 + operations_count = 2 docs_per_operation = 1 # create some translations @@ -184,8 +184,8 @@ def test_list_translations_filter_by_created_before(self, **kwargs): def test_list_translations_order_by_creation_time_asc(self, **kwargs): client = kwargs.pop("client") variables = kwargs.pop("variables", {}) - operations_count = 3 - docs_per_operation = 2 + operations_count = 2 + docs_per_operation = 1 # create some translations self._begin_multiple_translations( @@ -209,8 +209,8 @@ def test_list_translations_order_by_creation_time_asc(self, **kwargs): def test_list_translations_order_by_creation_time_desc(self, **kwargs): client = kwargs.pop("client") variables = kwargs.pop("variables", {}) - operations_count = 3 - docs_per_operation = 2 + operations_count = 2 + docs_per_operation = 1 # create some translations self._begin_multiple_translations( @@ -234,7 +234,7 @@ def test_list_translations_order_by_creation_time_desc(self, **kwargs): def test_list_translations_mixed_filters(self, **kwargs): client = kwargs.pop("client") # create some translations - operations_count = 4 + operations_count = 2 docs_per_operation = 1 statuses = ["Succeeded"] skip = 1 diff --git a/sdk/translation/azure-ai-translation-document/tests/test_list_translations_async.py b/sdk/translation/azure-ai-translation-document/tests/test_list_translations_async.py index ca99dbf5b226..7eb3c6626fdf 100644 --- a/sdk/translation/azure-ai-translation-document/tests/test_list_translations_async.py +++ b/sdk/translation/azure-ai-translation-document/tests/test_list_translations_async.py @@ -28,8 +28,8 @@ async def test_list_translations(self, **kwargs): client = kwargs.pop("client") variables = kwargs.pop("variables", {}) # create some translations - operations_count = 5 - docs_per_operation = 5 + operations_count = 2 + docs_per_operation = 1 await self._begin_multiple_translations_async( client, operations_count, docs_per_operation=docs_per_operation, wait=False, variables=variables ) @@ -53,8 +53,8 @@ async def test_list_translations_with_skip(self, **kwargs): client = kwargs.pop("client") variables = kwargs.pop("variables", {}) # prepare data - operations_count = 10 - docs_per_operation = 2 + operations_count = 2 + docs_per_operation = 1 skip = 5 # create some translations @@ -82,7 +82,7 @@ async def test_list_translations_with_skip(self, **kwargs): async def test_list_translations_filter_by_status(self, **kwargs): client = kwargs.pop("client") variables = kwargs.pop("variables", {}) - operations_count = 5 + operations_count = 2 docs_per_operation = 1 # create some translations with the status 'Succeeded' @@ -119,8 +119,8 @@ async def test_list_translations_filter_by_status(self, **kwargs): async def test_list_translations_filter_by_ids(self, **kwargs): client = kwargs.pop("client") variables = kwargs.pop("variables", {}) - operations_count = 3 - docs_per_operation = 2 + operations_count = 2 + docs_per_operation = 1 # create some translations translation_ids = await self._begin_multiple_translations_async( @@ -142,8 +142,8 @@ async def test_list_translations_filter_by_ids(self, **kwargs): async def test_list_translations_filter_by_created_after(self, **kwargs): client = kwargs.pop("client") # create some translations - operations_count = 3 - docs_per_operation = 2 + operations_count = 2 + docs_per_operation = 1 # create some translations start = datetime.utcnow() @@ -169,7 +169,7 @@ async def test_list_translations_filter_by_created_before(self, **kwargs): 'end' must be timezone-aware! """ client = kwargs.pop("client") - operations_count = 5 + operations_count = 2 docs_per_operation = 1 # create some translations @@ -196,8 +196,8 @@ async def test_list_translations_filter_by_created_before(self, **kwargs): async def test_list_translations_order_by_creation_time_asc(self, **kwargs): client = kwargs.pop("client") variables = kwargs.pop("variables", {}) - operations_count = 3 - docs_per_operation = 2 + operations_count = 2 + docs_per_operation = 1 # create some translations await self._begin_multiple_translations_async( @@ -221,8 +221,8 @@ async def test_list_translations_order_by_creation_time_asc(self, **kwargs): async def test_list_translations_order_by_creation_time_desc(self, **kwargs): client = kwargs.pop("client") variables = kwargs.pop("variables", {}) - operations_count = 3 - docs_per_operation = 2 + operations_count = 2 + docs_per_operation = 1 # create some translations await self._begin_multiple_translations_async( @@ -246,7 +246,7 @@ async def test_list_translations_order_by_creation_time_desc(self, **kwargs): async def test_list_translations_mixed_filters(self, **kwargs): client = kwargs.pop("client") # create some translations - operations_count = 4 + operations_count = 2 docs_per_operation = 1 statuses = ["Succeeded"] skip = 1 diff --git a/sdk/translation/azure-ai-translation-document/tests/test_model_updates.py b/sdk/translation/azure-ai-translation-document/tests/test_model_updates.py index 9d644964c52b..236a13e77640 100644 --- a/sdk/translation/azure-ai-translation-document/tests/test_model_updates.py +++ b/sdk/translation/azure-ai-translation-document/tests/test_model_updates.py @@ -11,6 +11,10 @@ TranslationStatusSummary, TranslationGlossary, TranslationStatus, + BatchOptions, + StartTranslationDetails, + DocumentTranslationInput, + TranslationTarget, ) from testcase import DocumentTranslationTest from preparer import ( @@ -18,7 +22,8 @@ DocumentTranslationClientPreparer as _DocumentTranslationClientPreparer, ) from devtools_testutils import recorded_by_proxy -from azure.ai.translation.document import DocumentTranslationClient, DocumentTranslationInput, TranslationTarget +from azure.ai.translation.document import DocumentTranslationClient +from azure.ai.translation.document._patch import get_translation_input DocumentTranslationClientPreparer = functools.partial(_DocumentTranslationClientPreparer, DocumentTranslationClient) @@ -208,6 +213,155 @@ def test_translation_status_args(self, **kwargs): translation_status_dict = TranslationStatus(**params) self.validate_translation_status(translation_status_dict) + def test_translation_target_deployment_name(self): + # deployment_name is exposed publicly and serialized to the wire property "deploymentName". + target = TranslationTarget( + target_url="https://t7d8641d8f25ec940prim.blob.core.windows.net/target-67890", + language="es", + deployment_name="my-deployment", + ) + assert target.deployment_name == "my-deployment" + + wire = target.as_dict() + assert wire["deploymentName"] == "my-deployment" + + def test_start_translation_details_translate_text_within_image(self): + # translate_text_within_image is carried on BatchOptions via StartTranslationDetails.options. + options = BatchOptions(translate_text_within_image=True) + assert options.translate_text_within_image is True + + details = StartTranslationDetails(inputs=[], options=options) + wire = details.as_dict() + assert wire["options"]["translateTextWithinImage"] is True + + def test_document_status_deserializes_new_fields(self): + # DocumentStatus exposes the deployment name and image scan usage returned by the service. + payload = { + "path": "https://target/doc.txt", + "sourcePath": "https://source/doc.txt", + "createdDateTimeUtc": "2026-03-01T00:00:00Z", + "lastActionDateTimeUtc": "2026-03-01T00:05:00Z", + "status": "Succeeded", + "to": "es", + "progress": 1.0, + "id": "doc-1", + "characterCharged": 100, + "deploymentName": "my-deployment", + "totalImageScansSucceeded": 6, + "totalImageScansFailed": 1, + "imageCharged": 3, + "imageCharacterDetected": 1257, + } + status = DocumentStatus(payload) + assert status.deployment_name == "my-deployment" + assert status.total_image_scans_succeeded == 6 + assert status.total_image_scans_failed == 1 + assert status.images_charged == 3 + assert status.image_characters_detected == 1257 + + def test_translation_status_summary_deserializes_image_totals(self): + # TranslationStatusSummary exposes the image scan totals returned by the service, + # mapping the wire names totalImageScansSucceeded / totalImageScansFailed / totalImageCharged. + payload = { + "total": 10, + "failed": 2, + "success": 5, + "inProgress": 3, + "notYetStarted": 0, + "cancelled": 0, + "totalCharacterCharged": 10000, + "totalImageScansSucceeded": 6, + "totalImageScansFailed": 1, + "totalImageCharged": 3, + } + summary = TranslationStatusSummary(payload) + assert summary.total_image_scans_succeeded == 6 + assert summary.total_image_scans_failed == 1 + assert summary.total_images_charged == 3 + + def test_begin_translation_overloaded_inputs_dispatch(self): + # begin_translation accepts a list of DocumentTranslationInput positionally or via the + # 'inputs=' keyword; both build the same StartTranslationDetails. This is SDK request + # dispatch (not service behavior), so it is validated without the live service. + inputs = [ + DocumentTranslationInput( + source_url="https://source", + targets=[TranslationTarget(target_url="https://target", language="es")], + ) + ] + + positional = get_translation_input((inputs,), {}, None) + keyword = get_translation_input((), {"inputs": inputs}, None) + + for request in (positional, keyword): + assert isinstance(request, StartTranslationDetails) + batch = request.inputs[0] + assert batch.source.source_url == "https://source" + assert batch.targets[0].target_url == "https://target" + assert batch.targets[0].language == "es" + + def test_begin_translation_list_inputs_translate_text_within_image(self): + # Regression: translate_text_within_image must be honored for the List[DocumentTranslationInput] + # batch form (it was previously read only on the single-URL form and silently dropped here). + inputs = [ + DocumentTranslationInput( + source_url="https://source", + targets=[TranslationTarget(target_url="https://target", language="es")], + ) + ] + + request = get_translation_input((inputs,), {"translate_text_within_image": True}, None) + assert isinstance(request, StartTranslationDetails) + assert request.options is not None + assert request.options.translate_text_within_image is True + + # When the option is not provided, no BatchOptions is attached. + request_without = get_translation_input((inputs,), {}, None) + assert request_without.options is None + + def test_begin_translation_single_input_dispatch(self): + # The single-input convenience form accepts source/target/language positionally or by + # keyword; both build an equivalent StartTranslationDetails. + positional = get_translation_input(("https://source", "https://target", "es"), {}, None) + keyword = get_translation_input( + (), {"source_url": "https://source", "target_url": "https://target", "target_language": "es"}, None + ) + + for request in (positional, keyword): + assert isinstance(request, StartTranslationDetails) + batch = request.inputs[0] + assert batch.source.source_url == "https://source" + assert batch.targets[0].target_url == "https://target" + assert batch.targets[0].language == "es" + + def test_begin_translation_single_input_serialization(self): + # The keyword options on the single-input begin_translation form serialize onto the + # request as expected (previously covered by a live raw_response_hook test). + request = get_translation_input( + ("https://source", "https://target", "es"), + { + "storage_type": "File", + "source_language": "en", + "prefix": "", + "suffix": ".txt", + "category_id": "fake", + "glossaries": [TranslationGlossary(glossary_url="https://glossaryfile.txt", file_format="txt")], + }, + None, + ) + + batch = request.inputs[0] + assert batch.source.source_url == "https://source" + assert batch.source.language == "en" + assert batch.source.filter.prefix == "" + assert batch.source.filter.suffix == ".txt" + assert batch.storage_type == "File" + assert batch.targets[0].category_id == "fake" + assert batch.targets[0].glossaries[0].file_format == "txt" + assert batch.targets[0].glossaries[0].glossary_url == "https://glossaryfile.txt" + assert batch.targets[0].language == "es" + assert batch.targets[0].target_url == "https://target" + def validate_translation_target(self, translation_target): assert translation_target is not None assert translation_target.target_url is not None diff --git a/sdk/translation/azure-ai-translation-document/tests/test_translation.py b/sdk/translation/azure-ai-translation-document/tests/test_translation.py index 3407d20ce0f8..c6d79f56b6ce 100644 --- a/sdk/translation/azure-ai-translation-document/tests/test_translation.py +++ b/sdk/translation/azure-ai-translation-document/tests/test_translation.py @@ -5,7 +5,6 @@ import functools import pytest -import json import os from azure.core.exceptions import HttpResponseError from testcase import DocumentTranslationTest, Document @@ -15,8 +14,7 @@ ) from devtools_testutils import recorded_by_proxy from azure.storage.blob import ContainerClient -from azure.ai.translation.document.models._models import StartTranslationDetails as _StartTranslationDetails -from azure.ai.translation.document import ( +from azure.ai.translation.document.models import ( DocumentTranslationInput, TranslationTarget, TranslationGlossary, @@ -26,6 +24,8 @@ DocumentTranslationClientPreparer = functools.partial(_DocumentTranslationClientPreparer, DocumentTranslationClient) GLOSSARY_FILE_NAME = os.path.abspath(os.path.join(os.path.abspath(__file__), "..", "./glossaries-valid.csv")) +# A document that embeds an image containing legible text, used to exercise image translation. +IMAGE_DOC_FILE_NAME = os.path.abspath(os.path.join(os.path.dirname(__file__), "TestData", "test-doc-image.docx")) class TestTranslation(DocumentTranslationTest): @@ -235,33 +235,6 @@ def test_bad_input_target(self, **kwargs): assert e.value.error.code == "InvalidTargetDocumentAccessLevel" return variables - @DocumentTranslationPreparer() - @DocumentTranslationClientPreparer() - @recorded_by_proxy - def test_use_supported_and_unsupported_files(self, **kwargs): - client = kwargs.pop("client") - variables = kwargs.pop("variables", {}) - # prepare containers and test data - source_container_sas_url = self.create_source_container( - data=[Document(suffix=".txt"), Document(suffix=".jpg")], variables=variables - ) - target_container_sas_url = self.create_target_container(variables=variables) - - # prepare translation inputs - translation_inputs = [ - DocumentTranslationInput( - source_url=source_container_sas_url, - targets=[TranslationTarget(target_url=target_container_sas_url, language="es")], - ) - ] - - poller = client.begin_translation(translation_inputs) - result = poller.result() - self._validate_translation_metadata(poller=poller, status="Succeeded", total=1, succeeded=1) - for document in result: - self._validate_doc_status(document, "es") - return variables - @pytest.mark.skip("Service now raises exception in this case. Need to follow-up") @DocumentTranslationPreparer() @DocumentTranslationClientPreparer() @@ -347,61 +320,6 @@ def test_empty_document(self, **kwargs): assert doc.error.code == "NoTranslatableText" return variables - @DocumentTranslationPreparer() - @DocumentTranslationClientPreparer() - @recorded_by_proxy - def test_overloaded_inputs(self, **kwargs): - client = kwargs.pop("client") - variables = kwargs.pop("variables", {}) - # prepare containers and test data - source_container_sas_url = self.create_source_container(data=Document(data=b"hello world"), variables=variables) - target_container_sas_url = self.create_target_container(variables=variables) - target_container_sas_url_2 = self.create_target_container(variables=variables, container_suffix="2") - - # prepare translation inputs - translation_inputs = [ - DocumentTranslationInput( - source_url=source_container_sas_url, - targets=[TranslationTarget(target_url=target_container_sas_url, language="es")], - ) - ] - - # positional - poller = client.begin_translation(translation_inputs) - result = poller.result() - self._validate_translation_metadata(poller, status="Succeeded", total=1, succeeded=1) - - # keyword - translation_inputs[0].targets[0].target_url = target_container_sas_url_2 - poller = client.begin_translation(inputs=translation_inputs) - result = poller.result() - self._validate_translation_metadata(poller, status="Succeeded", total=1, succeeded=1) - return variables - - @DocumentTranslationPreparer() - @DocumentTranslationClientPreparer() - @recorded_by_proxy - def test_overloaded_single_input(self, **kwargs): - client = kwargs.pop("client") - variables = kwargs.pop("variables", {}) - # prepare containers and test data - source_container_sas_url = self.create_source_container(data=Document(data=b"hello world"), variables=variables) - target_container_sas_url = self.create_target_container(variables=variables) - target_container_sas_url_2 = self.create_target_container(variables=variables, container_suffix="2") - - # positional - poller = client.begin_translation(source_container_sas_url, target_container_sas_url, "es") - result = poller.result() - self._validate_translation_metadata(poller, status="Succeeded", total=1, succeeded=1) - - # keyword - poller = client.begin_translation( - source_url=source_container_sas_url, target_url=target_container_sas_url_2, target_language="es" - ) - result = poller.result() - self._validate_translation_metadata(poller, status="Succeeded", total=1, succeeded=1) - return variables - @DocumentTranslationPreparer() @DocumentTranslationClientPreparer() def test_overloaded_bad_input(self, **kwargs): @@ -445,61 +363,74 @@ def test_translation_continuation_token(self, **kwargs): @DocumentTranslationPreparer() @DocumentTranslationClientPreparer() @recorded_by_proxy - def test_single_input_with_kwargs(self, **kwargs): + def test_single_input_with_kwarg_successful(self, **kwargs): client = kwargs.pop("client") variables = kwargs.pop("variables", {}) # prepare containers and test data - source_container_sas_url = self.create_source_container(data=Document(data=b"hello world"), variables=variables) + source_container_sas_url = self.create_source_container( + data=[Document(data=b"hello world", prefix="kwargs"), Document(data=b"hello world")], variables=variables + ) target_container_sas_url = self.create_target_container(variables=variables) - def callback(request): - req = _StartTranslationDetails._deserialize(json.loads(request.http_request.body), []) - input = req.inputs[0] - assert input.source.source_url == source_container_sas_url - assert input.source.language == "en" - assert input.source.filter.prefix == "" - assert input.source.filter.suffix == ".txt" - assert input.storage_type == "File" - assert input.targets[0].category_id == "fake" - assert input.targets[0].glossaries[0].file_format == "txt" - assert input.targets[0].glossaries[0].glossary_url == "https://glossaryfile.txt" - assert input.targets[0].language == "es" - assert input.targets[0].target_url == target_container_sas_url - - try: - poller = client.begin_translation( - source_container_sas_url, - target_container_sas_url, - "es", - storage_type="File", - source_language="en", - prefix="", - suffix=".txt", - category_id="fake", - glossaries=[TranslationGlossary(glossary_url="https://glossaryfile.txt", file_format="txt")], - raw_response_hook=callback, - ) - poller.result() - except HttpResponseError as e: - pass + poller = client.begin_translation(source_container_sas_url, target_container_sas_url, "fr", prefix="kwargs") + result = poller.result() + self._validate_translation_metadata(poller, status="Succeeded", total=1, succeeded=1) + for doc in result: + self._validate_doc_status(doc, target_language="fr") return variables @DocumentTranslationPreparer() @DocumentTranslationClientPreparer() @recorded_by_proxy - def test_single_input_with_kwarg_successful(self, **kwargs): + def test_single_source_single_target_with_deployment_name(self, **kwargs): client = kwargs.pop("client") variables = kwargs.pop("variables", {}) # prepare containers and test data + blob_data = b"This is some text" + source_container_sas_url = self.create_source_container(data=Document(data=blob_data), variables=variables) + target_container_sas_url = self.create_target_container(variables=variables) + + # "general" routes to the default NMT model, so no custom model deployment is required. + translation_inputs = [ + DocumentTranslationInput( + source_url=source_container_sas_url, + targets=[ + TranslationTarget(target_url=target_container_sas_url, language="fr", deployment_name="general") + ], + ) + ] + + # The service accepts the deployment name and translates successfully. The document status does + # not echo the deployment name back for the default ("general") model, so request-side + # serialization of deployment_name is verified separately in the model tests. + self._begin_and_validate_translation(client, translation_inputs, 1, "fr") + return variables + + @DocumentTranslationPreparer() + @DocumentTranslationClientPreparer() + @recorded_by_proxy + def test_single_source_single_target_with_image_translation(self, **kwargs): + client = kwargs.pop("client") + variables = kwargs.pop("variables", {}) + # The document must contain an image with legible text so image scanning has something to translate. + with open(IMAGE_DOC_FILE_NAME, "rb") as fd: + image_doc_data = fd.read() source_container_sas_url = self.create_source_container( - data=[Document(data=b"hello world", prefix="kwargs"), Document(data=b"hello world")], variables=variables + data=Document(name="test-doc-image", suffix=".docx", data=image_doc_data), variables=variables ) target_container_sas_url = self.create_target_container(variables=variables) - poller = client.begin_translation(source_container_sas_url, target_container_sas_url, "fr", prefix="kwargs") + # Enable translation of text embedded within images for the batch. + poller = client.begin_translation( + source_container_sas_url, target_container_sas_url, "fr", translate_text_within_image=True + ) result = poller.result() + self._validate_translation_metadata(poller, status="Succeeded", total=1, succeeded=1) for doc in result: + # The request enables image translation (verified on the wire) and the document translates + # successfully. Image scan usage is only reported by the service when images are actually + # scanned, so it is not asserted here. self._validate_doc_status(doc, target_language="fr") return variables @@ -513,12 +444,13 @@ def test_translation_with_glossary(self, **kwargs): source_container_sas_url = self.create_source_container(data=[doc]) target_container_sas_url = self.create_target_container() - container_client = ContainerClient(self.storage_endpoint, self.source_container_name, self.storage_key) + container_client = ContainerClient( + self.storage_endpoint, self.source_container_name, credential=self.get_storage_credential() + ) with open(GLOSSARY_FILE_NAME, "rb") as fd: container_client.upload_blob(name=GLOSSARY_FILE_NAME, data=fd.read()) - prefix, suffix = source_container_sas_url.split("?") - glossary_file_sas_url = prefix + "/" + GLOSSARY_FILE_NAME + "?" + suffix + glossary_file_sas_url = source_container_sas_url + "/" + GLOSSARY_FILE_NAME poller = client.begin_translation( source_container_sas_url, @@ -528,7 +460,9 @@ def test_translation_with_glossary(self, **kwargs): ) result = poller.result() - container_client = ContainerClient(self.storage_endpoint, self.target_container_name, self.storage_key) + container_client = ContainerClient( + self.storage_endpoint, self.target_container_name, credential=self.get_storage_credential() + ) # download translated file and assert that translation reflects glossary changes document = doc.name + doc.suffix diff --git a/sdk/translation/azure-ai-translation-document/tests/test_translation_async.py b/sdk/translation/azure-ai-translation-document/tests/test_translation_async.py index 30f2fe07adbe..650f78c44b2b 100644 --- a/sdk/translation/azure-ai-translation-document/tests/test_translation_async.py +++ b/sdk/translation/azure-ai-translation-document/tests/test_translation_async.py @@ -5,7 +5,6 @@ import functools import pytest -import json import os from testcase import Document from asynctestcase import AsyncDocumentTranslationTest @@ -16,13 +15,14 @@ from devtools_testutils.aio import recorded_by_proxy_async from azure.core.exceptions import HttpResponseError from azure.storage.blob import ContainerClient -from azure.ai.translation.document.models._models import StartTranslationDetails as _StartTranslationDetails -from azure.ai.translation.document import DocumentTranslationInput, TranslationTarget, TranslationGlossary +from azure.ai.translation.document.models import DocumentTranslationInput, TranslationTarget, TranslationGlossary from azure.ai.translation.document.aio import DocumentTranslationClient DocumentTranslationClientPreparer = functools.partial(_DocumentTranslationClientPreparer, DocumentTranslationClient) GLOSSARY_FILE_NAME = os.path.abspath(os.path.join(os.path.abspath(__file__), "..", "./glossaries-valid.csv")) +# A document that embeds an image containing legible text, used to exercise image translation. +IMAGE_DOC_FILE_NAME = os.path.abspath(os.path.join(os.path.dirname(__file__), "TestData", "test-doc-image.docx")) class TestTranslation(AsyncDocumentTranslationTest): @@ -233,33 +233,6 @@ async def test_bad_input_target(self, **kwargs): assert e.value.error.code == "InvalidTargetDocumentAccessLevel" return variables - @DocumentTranslationPreparer() - @DocumentTranslationClientPreparer() - @recorded_by_proxy_async - async def test_use_supported_and_unsupported_files(self, **kwargs): - client = kwargs.pop("client") - variables = kwargs.pop("variables", {}) - # prepare containers and test data - source_container_sas_url = self.create_source_container( - data=[Document(suffix=".txt"), Document(suffix=".jpg")], variables=variables - ) - target_container_sas_url = self.create_target_container(variables=variables) - - # prepare translation inputs - translation_inputs = [ - DocumentTranslationInput( - source_url=source_container_sas_url, - targets=[TranslationTarget(target_url=target_container_sas_url, language="es")], - ) - ] - async with client: - poller = await client.begin_translation(translation_inputs) - result = await poller.result() - self._validate_translation_metadata(poller, status="Succeeded", total=1, succeeded=1) - async for document in result: - self._validate_doc_status(document, "es") - return variables - @pytest.mark.skip("Service now raises exception in this case. Need to follow-up") @DocumentTranslationPreparer() @DocumentTranslationClientPreparer() @@ -346,63 +319,6 @@ async def test_empty_document(self, **kwargs): assert doc.error.code == "NoTranslatableText" return variables - @DocumentTranslationPreparer() - @DocumentTranslationClientPreparer() - @recorded_by_proxy_async - async def test_overloaded_inputs(self, **kwargs): - client = kwargs.pop("client") - variables = kwargs.pop("variables", {}) - # prepare containers and test data - source_container_sas_url = self.create_source_container(data=Document(data=b"hello world"), variables=variables) - target_container_sas_url = self.create_target_container(variables=variables) - target_container_sas_url_2 = self.create_target_container(variables=variables, container_suffix="2") - - # prepare translation inputs - translation_inputs = [ - DocumentTranslationInput( - source_url=source_container_sas_url, - targets=[TranslationTarget(target_url=target_container_sas_url, language="es")], - ) - ] - - # positional - async with client: - poller = await client.begin_translation(translation_inputs) - result = await poller.result() - self._validate_translation_metadata(poller, status="Succeeded", total=1, succeeded=1) - - # keyword - translation_inputs[0].targets[0].target_url = target_container_sas_url_2 - poller = await client.begin_translation(inputs=translation_inputs) - result = await poller.result() - self._validate_translation_metadata(poller, status="Succeeded", total=1, succeeded=1) - return variables - - @DocumentTranslationPreparer() - @DocumentTranslationClientPreparer() - @recorded_by_proxy_async - async def test_overloaded_single_input(self, **kwargs): - client = kwargs.pop("client") - variables = kwargs.pop("variables", {}) - # prepare containers and test data - source_container_sas_url = self.create_source_container(data=Document(data=b"hello world"), variables=variables) - target_container_sas_url = self.create_target_container(variables=variables) - target_container_sas_url_2 = self.create_target_container(variables=variables, container_suffix="2") - - # positional - async with client: - poller = await client.begin_translation(source_container_sas_url, target_container_sas_url, "es") - result = await poller.result() - self._validate_translation_metadata(poller, status="Succeeded", total=1, succeeded=1) - - # keyword - poller = await client.begin_translation( - source_url=source_container_sas_url, target_url=target_container_sas_url_2, target_language="es" - ) - result = await poller.result() - self._validate_translation_metadata(poller, status="Succeeded", total=1, succeeded=1) - return variables - @DocumentTranslationPreparer() @DocumentTranslationClientPreparer() async def test_overloaded_bad_input(self, **kwargs): @@ -448,65 +364,78 @@ async def test_translation_continuation_token(self, **kwargs): @DocumentTranslationPreparer() @DocumentTranslationClientPreparer() @recorded_by_proxy_async - async def test_single_input_with_kwargs(self, **kwargs): + async def test_single_input_with_kwarg_successful(self, **kwargs): client = kwargs.pop("client") variables = kwargs.pop("variables", {}) # prepare containers and test data - source_container_sas_url = self.create_source_container(data=Document(data=b"hello world"), variables=variables) + source_container_sas_url = self.create_source_container( + data=[Document(data=b"hello world", prefix="kwargs"), Document(data=b"hello world")], variables=variables + ) target_container_sas_url = self.create_target_container(variables=variables) - def callback(request): - req = _StartTranslationDetails._deserialize(json.loads(request.http_request.body), []) - input = req.inputs[0] - assert input.source.source_url == source_container_sas_url - assert input.source.language == "en" - assert input.source.filter.prefix == "" - assert input.source.filter.suffix == ".txt" - assert input.storage_type == "File" - assert input.targets[0].category_id == "fake" - assert input.targets[0].glossaries[0].file_format == "txt" - assert input.targets[0].glossaries[0].glossary_url == "https://glossaryfile.txt" - assert input.targets[0].language == "es" - assert input.targets[0].target_url == target_container_sas_url - async with client: - try: - poller = await client.begin_translation( - source_container_sas_url, - target_container_sas_url, - "es", - storage_type="File", - source_language="en", - prefix="", - suffix=".txt", - category_id="fake", - glossaries=[TranslationGlossary(glossary_url="https://glossaryfile.txt", file_format="txt")], - raw_response_hook=callback, - ) - await poller.result() - except HttpResponseError as e: - pass + poller = await client.begin_translation( + source_container_sas_url, target_container_sas_url, "fr", prefix="kwargs" + ) + result = await poller.result() + self._validate_translation_metadata(poller, status="Succeeded", total=1, succeeded=1) + async for doc in result: + self._validate_doc_status(doc, target_language="fr") return variables @DocumentTranslationPreparer() @DocumentTranslationClientPreparer() @recorded_by_proxy_async - async def test_single_input_with_kwarg_successful(self, **kwargs): + async def test_single_source_single_target_with_deployment_name(self, **kwargs): client = kwargs.pop("client") variables = kwargs.pop("variables", {}) # prepare containers and test data + blob_data = b"This is some text" + source_container_sas_url = self.create_source_container(data=Document(data=blob_data), variables=variables) + target_container_sas_url = self.create_target_container(variables=variables) + + # "general" routes to the default NMT model, so no custom model deployment is required. + translation_inputs = [ + DocumentTranslationInput( + source_url=source_container_sas_url, + targets=[ + TranslationTarget(target_url=target_container_sas_url, language="fr", deployment_name="general") + ], + ) + ] + + # The service accepts the deployment name and translates successfully. The document status does + # not echo the deployment name back for the default ("general") model, so request-side + # serialization of deployment_name is verified separately in the model tests. + await self._begin_and_validate_translation_async(client, translation_inputs, 1, "fr") + return variables + + @DocumentTranslationPreparer() + @DocumentTranslationClientPreparer() + @recorded_by_proxy_async + async def test_single_source_single_target_with_image_translation(self, **kwargs): + client = kwargs.pop("client") + variables = kwargs.pop("variables", {}) + # The document must contain an image with legible text so image scanning has something to translate. + with open(IMAGE_DOC_FILE_NAME, "rb") as fd: + image_doc_data = fd.read() source_container_sas_url = self.create_source_container( - data=[Document(data=b"hello world", prefix="kwargs"), Document(data=b"hello world")], variables=variables + data=Document(name="test-doc-image", suffix=".docx", data=image_doc_data), variables=variables ) target_container_sas_url = self.create_target_container(variables=variables) async with client: + # Enable translation of text embedded within images for the batch. poller = await client.begin_translation( - source_container_sas_url, target_container_sas_url, "fr", prefix="kwargs" + source_container_sas_url, target_container_sas_url, "fr", translate_text_within_image=True ) result = await poller.result() + self._validate_translation_metadata(poller, status="Succeeded", total=1, succeeded=1) async for doc in result: + # The request enables image translation (verified on the wire) and the document translates + # successfully. Image scan usage is only reported by the service when images are actually + # scanned, so it is not asserted here. self._validate_doc_status(doc, target_language="fr") return variables @@ -520,12 +449,13 @@ async def test_translation_with_glossary(self, **kwargs): source_container_sas_url = self.create_source_container(data=[doc]) target_container_sas_url = self.create_target_container() - container_client = ContainerClient(self.storage_endpoint, self.source_container_name, self.storage_key) + container_client = ContainerClient( + self.storage_endpoint, self.source_container_name, credential=self.get_storage_credential() + ) with open(GLOSSARY_FILE_NAME, "rb") as fd: container_client.upload_blob(name=GLOSSARY_FILE_NAME, data=fd.read()) - prefix, suffix = source_container_sas_url.split("?") - glossary_file_sas_url = prefix + "/" + GLOSSARY_FILE_NAME + "?" + suffix + glossary_file_sas_url = source_container_sas_url + "/" + GLOSSARY_FILE_NAME async with client: poller = await client.begin_translation( source_container_sas_url, @@ -535,7 +465,9 @@ async def test_translation_with_glossary(self, **kwargs): ) result = await poller.result() - container_client = ContainerClient(self.storage_endpoint, self.target_container_name, self.storage_key) + container_client = ContainerClient( + self.storage_endpoint, self.target_container_name, credential=self.get_storage_credential() + ) # download translated file and assert that translation reflects glossary changes document = doc.name + doc.suffix diff --git a/sdk/translation/azure-ai-translation-document/tests/testcase.py b/sdk/translation/azure-ai-translation-document/tests/testcase.py index 8d2abead3989..e317e0fac595 100644 --- a/sdk/translation/azure-ai-translation-document/tests/testcase.py +++ b/sdk/translation/azure-ai-translation-document/tests/testcase.py @@ -5,12 +5,17 @@ import os import time -import datetime import uuid -from azure.ai.translation.document.models import DocumentBatch, SourceInput, StartTranslationDetails +from azure.ai.translation.document.models import ( + DocumentBatch, + SourceInput, + StartTranslationDetails, + DocumentTranslationInput, + TranslationTarget, +) from devtools_testutils import AzureRecordedTestCase, set_custom_default_matcher -from azure.storage.blob import generate_container_sas, ContainerClient -from azure.ai.translation.document import DocumentTranslationInput, TranslationTarget +from azure.storage.blob import ContainerClient +from azure.identity import DefaultAzureCredential class Document: @@ -39,9 +44,11 @@ def storage_name(self): def storage_endpoint(self): return "https://" + self.storage_name + ".blob.core.windows.net/" - @property - def storage_key(self): - return os.getenv("DOCUMENT_TRANSLATION_STORAGE_KEY", "fakeZmFrZV9hY29jdW50X2tleQ==") + def get_storage_credential(self): + # Recorded tests authenticate to storage with Entra ID (RBAC) rather than an + # account key, so they work even when the storage account has shared-key access + # disabled. Only used in live/record mode; playback never touches storage. + return DefaultAzureCredential() def upload_documents(self, data, container_client): if isinstance(data, list): @@ -55,40 +62,41 @@ def create_source_container(self, data, variables={}, **kwargs): var_key = "source_container_name" + container_suffix if self.is_live: self.source_container_name = variables[var_key] = "src" + str(uuid.uuid4()) - container_client = ContainerClient(self.storage_endpoint, variables[var_key], self.storage_key) + container_client = ContainerClient( + self.storage_endpoint, variables[var_key], credential=self.get_storage_credential() + ) container_client.create_container() self.upload_documents(data, container_client) - return self.generate_sas_url(variables[var_key], "rl") + return self.container_url(variables[var_key]) def create_target_container(self, data=None, variables={}, **kwargs): container_suffix = kwargs.get("container_suffix", "") var_key = "target_container_name" + container_suffix if self.is_live: self.target_container_name = variables[var_key] = "target" + str(uuid.uuid4()) - container_client = ContainerClient(self.storage_endpoint, variables[var_key], self.storage_key) + container_client = ContainerClient( + self.storage_endpoint, variables[var_key], credential=self.get_storage_credential() + ) container_client.create_container() if data: self.upload_documents(data, container_client) - return self.generate_sas_url(variables[var_key], "wl") + return self.container_url(variables[var_key]) - def generate_sas_url(self, container_name, permission): - # this can be reverted to set_bodiless_matcher() after tests are re-recorded and don't contain these headers + def container_url(self, container_name): + # The Document Translation service reads/writes the containers using the Translator + # resource's managed identity, so a plain container URL (no SAS) is passed. This + # avoids any dependency on the storage account key / shared-key access. + # This can be reverted to set_bodiless_matcher() after tests are re-recorded. + # "Accept" is excluded because the generated begin_translation request no longer sends + # "Accept: application/json" (the 202 response has no body); excluding it keeps the + # existing recordings valid without re-recording every translation-flow test. set_custom_default_matcher( - compare_bodies=False, excluded_headers="Authorization,Content-Length,x-ms-client-request-id,x-ms-request-id" + compare_bodies=False, + excluded_headers="Accept,Authorization,Content-Length,x-ms-client-request-id,x-ms-request-id", ) - sas_token = self.generate_sas( - generate_container_sas, - account_name=self.storage_name, - container_name=container_name, - account_key=self.storage_key, - permission=permission, - expiry=datetime.datetime.utcnow() + datetime.timedelta(hours=2), - ) - - container_sas_url = self.storage_endpoint + container_name + "?" + sas_token - return container_sas_url + return self.storage_endpoint + container_name def wait(self, duration=30): if self.is_live: diff --git a/sdk/translation/azure-ai-translation-document/tsp-location.yaml b/sdk/translation/azure-ai-translation-document/tsp-location.yaml index bb4b6ef00eab..3902f6c74423 100644 --- a/sdk/translation/azure-ai-translation-document/tsp-location.yaml +++ b/sdk/translation/azure-ai-translation-document/tsp-location.yaml @@ -1,3 +1,3 @@ -commit: ccc08b40afbff1abe17c8250ed03a87e81fbf673 +commit: e7ef236186d1a72ce0f9cf41ce425d840568e477 repo: Azure/azure-rest-api-specs -directory: specification/translation/Azure.AI.DocumentTranslation +directory: specification/translation/data-plane/DocumentTranslation