Type annotations for boto3 IoT service

Warnings

• breaking Support for Python 3.8 was removed starting with `mypy-boto3-builder` version 8.12.0 (which generates `mypy-boto3-iot` 1.42.14). Projects using Python 3.8 or older will need to upgrade to Python 3.9+.
  Fix: Upgrade your Python environment to 3.9 or newer.
• breaking The `mypy-boto3-builder` (and consequently `mypy-boto3-iot`) migrated to PEP 561 packages in version 8.12.0. This might change how type checkers discover packages, potentially requiring updates to `mypy` configurations or build systems that explicitly manage stubs.
  Fix: Ensure your type checker (e.g., Mypy, Pyright) is up-to-date and correctly configured to find PEP 561-compliant stub packages.
• breaking Version 8.9.0 of `mypy-boto3-builder` introduced breaking changes to `TypeDef` naming conventions, specifically for packed method arguments (shorter names) and conflicting `Extra` postfixes (moved to the end). If you rely on specific `TypeDef` names in your type hints, they may have changed.
  Fix: Review your code for `TypeDef` imports and usage, and update names according to the new conventions (e.g., `CreateDistributionRequestRequestTypeDef` to `CreateDistributionRequestTypeDef`).
• gotcha While `boto3-stubs` often provides implicit type annotations, explicit type annotations for client, resource, waiter, and paginator calls (e.g., `client: IoTClient = boto3.client('iot')`) are highly recommended for optimal IDE autocompletion and type checking, especially with tools like PyCharm or when using `boto3-stubs-lite`.
  Fix: Always use explicit type annotations when defining `boto3` client or resource objects to leverage full type-checking capabilities.
• gotcha When using `typing.TYPE_CHECKING` guards to avoid runtime dependency on `mypy-boto3-iot`, Pylint may complain about undefined variables. A common workaround is to assign `object` to the type-hinted variables outside the `TYPE_CHECKING` block.
  Fix: Implement a fallback for type-hinted variables: `if TYPE_CHECKING: from mypy_boto3_iot import IoTClient else: IoTClient = object`.

Install

• pip install mypy-boto3-iot boto3 Install standalone package
• pip install 'boto3-stubs[iot]' boto3 Install via boto3-stubs extras

Imports

• IoTClient

  from mypy_boto3_iot import IoTClient

  The `IoTClient` type should be imported from `mypy_boto3_iot` for type checking, not directly from `boto3` which doesn't export the typed client.
• ListThingsPaginator

  from mypy_boto3_iot.paginator import ListThingsPaginator

  Specific paginator types are located in the `paginator` submodule.
• AbortCriteriaTypeDef

  from mypy_boto3_iot.type_defs import AbortCriteriaTypeDef

  Type definitions for request/response bodies and other structures are in the `type_defs` submodule.

Quickstart

This quickstart demonstrates how to initialize an IoT client with type annotations and perform a basic operation like listing IoT things. It uses `TYPE_CHECKING` for conditional imports, ensuring the type stubs are only used during type checking.

import boto3
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from mypy_boto3_iot import IoTClient
    from mypy_boto3_iot.type_defs import ListThingsResponseTypeDef

def list_iot_things(region_name: str = 'us-east-1') -> ListThingsResponseTypeDef:
    # Initialize the boto3 client (type-checked by mypy-boto3-iot)
    client: IoTClient = boto3.client('iot', region_name=region_name)
    
    # Example operation: List IoT Things
    response = client.list_things(maxResults=10)
    
    print(f"Found {len(response.get('things', []))} IoT things.")
    for thing in response.get('things', []):
        print(f" - {thing['thingName']}")
        
    return response

if __name__ == '__main__':
    # This assumes AWS credentials are set up (e.g., via environment variables or ~/.aws/credentials)
    try:
        list_iot_things()
    except Exception as e:
        print(f"Error listing IoT things: {e}")