mypy-boto3-polly Type Stubs

Warnings

• breaking Support for Python 3.8 was removed in `mypy-boto3-builder` version 8.12.0. Users on Python 3.8 or older will need to upgrade their Python version.
  Fix: Upgrade your Python environment to 3.9 or newer.
• breaking TypeDef naming conventions changed in `mypy-boto3-builder` version 8.9.0. This led to shorter names for packed method arguments (e.g., `CreateDistributionRequestRequestTypeDef` became `CreateDistributionRequestTypeDef`) and reordered suffixes for conflicting TypeDefs. Code relying on exact TypeDef names may break.
  Fix: Review and update TypeDef imports and usage in your codebase to match the new naming conventions. Consult the `mypy-boto3-polly` documentation for the correct TypeDef names.
• gotcha `mypy-boto3-polly` is a stub-only package (PEP 561). It *must* be installed alongside the `boto3` library itself. Mypy and IDEs will automatically find these stubs, but if `boto3` is not present, the type stubs will have no implementation to apply to.
  Fix: Always ensure `boto3` is installed in the same environment as `mypy-boto3-polly` (e.g., `pip install boto3 mypy-boto3-polly`).
• gotcha For optimal autocomplete and type checking in some IDEs (especially older versions of PyCharm or VSCode without the Pylance extension), it is recommended to explicitly type your `boto3.client()` calls, even with stubs installed.
  Fix: When creating a client, explicitly add the type annotation: `client: PollyClient = boto3.client("polly")`.

Install

• pip install boto3 mypy-boto3-polly Install with pip

Imports

• PollyClient

  from mypy_boto3_polly.client import PollyClient

  While `boto3.client('polly')` returns a client object, directly importing `PollyClient` from `boto3.client` does not provide the specific type hints. The `mypy-boto3-polly` package provides the fully typed `PollyClient`.
• DescribeVoicesPaginator

  from mypy_boto3_polly.paginator import DescribeVoicesPaginator

• AudioEventTypeDef

  from mypy_boto3_polly.type_defs import AudioEventTypeDef

Quickstart

This quickstart demonstrates how to use the `mypy-boto3-polly` type stubs with a standard boto3 client. It explicitly types the Polly client and its response, allowing type checkers to validate usage and provide intelligent autocomplete.

import boto3
from mypy_boto3_polly.client import PollyClient
from mypy_boto3_polly.type_defs import SynthesizeSpeechOutputTypeDef
import os


def synthesize_and_save(text: str, output_path: str):
    # Ensure AWS credentials are available (e.g., via environment variables or ~/.aws/credentials)
    # For local testing, ensure AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION are set.

    # Explicitly type the client for full type-checking benefits
    client: PollyClient = boto3.client("polly", region_name=os.environ.get('AWS_REGION', 'us-east-1'))

    response: SynthesizeSpeechOutputTypeDef = client.synthesize_speech(
        Text=text,
        OutputFormat='mp3',
        VoiceId='Joanna'
    )

    # In a real application, handle the 'AudioStream' which is a StreamingBody
    # For this quickstart, we'll just demonstrate the typing of the response.
    if response['AudioStream']:
        print(f"Successfully received audio stream with content type: {response['ContentType']}")
        # Example: to save to a file (simplified, error handling omitted)
        # with open(output_path, 'wb') as f:
        #     f.write(response['AudioStream'].read())
        # print(f"Audio saved to {output_path}")
    else:
        print("No audio stream received.")

# Example usage (requires AWS setup for actual execution)
# synthesize_and_save("Hello, world! This is a typed Polly client example.", "output.mp3")
print("Quickstart code demonstrates type hinting for boto3 Polly client.")