Type Annotations for boto3 CloudTrail

Warnings

• breaking Support for Python 3.8 and older was removed in `mypy-boto3-builder` version 8.12.0. All generated `mypy-boto3-*` packages, including `mypy-boto3-cloudtrail`, now require Python >= 3.9.
  Fix: Upgrade your Python environment to 3.9 or newer.
• breaking In `mypy-boto3-builder` 8.9.0, there were changes to how TypeDef names are generated, specifically for packed method arguments (e.g., `CreateDistributionRequestRequestTypeDef` became `CreateDistributionRequestTypeDef`) and conflicting `Extra` postfixes (`CreateDistributionExtraRequestTypeDef` to `CreateDistributionRequestExtraTypeDef`). While `cloudtrail` specific types might not match these exact examples, similar renamings could apply to other service `TypeDef`s.
  Fix: Review your `TypeDef` imports and usage after upgrading, as some names might have been shortened or reordered. Consult the `mypy-boto3` documentation for specific services.
• gotcha PyCharm users might experience slow performance with Literal overloads (issue PY-40997). The recommendation is to use `boto3-stubs-lite` (e.g., `pip install 'boto3-stubs-lite[cloudtrail]'`) or disable PyCharm's internal type checker and rely on `mypy` or `pyright`.
  Fix: Install `boto3-stubs-lite[cloudtrail]` instead of `boto3-stubs[cloudtrail]` or `mypy-boto3-cloudtrail` if performance is an issue in PyCharm, or configure your IDE to use an external type checker.
• gotcha When using `TYPE_CHECKING` blocks for conditional imports to avoid runtime dependencies (common for stub packages), Pylint might complain about undefined variables. To fix this, set variables inside the `TYPE_CHECKING` block to `object` in the `else` branch.
  Fix: Wrap your type-hinted variable declarations with an `if TYPE_CHECKING:` block and assign `object` in the `else` branch, as shown in the quickstart example (e.g., `if TYPE_CHECKING: from mypy_boto3_cloudtrail.client import CloudTrailClient else: CloudTrailClient = object`).
• breaking The `mypy-boto3-builder` migrated to PEP 561 compliant packages in version 8.12.0. While designed to be backward compatible for standard usage, this fundamental change in packaging type information might affect highly customized build systems or older `mypy`/`pip` versions that relied on pre-PEP 561 behavior.
  Fix: Ensure your `pip` and `mypy` versions are up-to-date. If encountering issues with type discovery in complex environments, verify the `py.typed` marker file is correctly recognized by your tooling.

Install

• pip install mypy-boto3-cloudtrail Standalone package
• pip install 'boto3-stubs[cloudtrail]' Part of boto3-stubs (recommended for multiple services)

Imports

• CloudTrailClient

  from mypy_boto3_cloudtrail.client import CloudTrailClient

• LookupEventsPaginator

  from mypy_boto3_cloudtrail.paginator import LookupEventsPaginator

• LookupEventsResponseTypeDef

  from mypy_boto3_cloudtrail.type_defs import LookupEventsResponseTypeDef

  Importing directly from boto3's internal client module does not provide mypy-boto3 type hints. The `CloudTrailClient` from `mypy_boto3_cloudtrail.client` is the correctly typed version to use with boto3.client().

Quickstart

This quickstart demonstrates how to instantiate a boto3 CloudTrail client and use the `mypy-boto3-cloudtrail` type hints for methods and response structures. It includes an example of looking up events and iterating through the typed response. The `TYPE_CHECKING` block ensures that these stub imports are only used by type checkers and not during runtime, making it safe for production.

import boto3
from typing import TYPE_CHECKING, List, Dict, Any

if TYPE_CHECKING:
    from mypy_boto3_cloudtrail.client import CloudTrailClient
    from mypy_boto3_cloudtrail.type_defs import EventTypeDef, LookupEventsResponseTypeDef


def list_cloudtrail_events(client: 'CloudTrailClient') -> List['EventTypeDef']:
    """Lists recent CloudTrail events with type hints."""
    # Example of a typed client call
    response: 'LookupEventsResponseTypeDef' = client.lookup_events(MaxResults=5)
    events: List['EventTypeDef'] = response.get('Events', [])
    for event in events:
        print(f"Event Name: {event.get('EventName')}, Event ID: {event.get('EventId')}")
    return events


if __name__ == "__main__":
    # In a real application, credentials would be configured via environment variables, ~/.aws/credentials, etc.
    # For this example, we assume default configuration.
    boto_session = boto3.Session()
    
    # The type hint here ensures static analysis tools understand the client's methods and return types
    cloudtrail_client: 'CloudTrailClient' = boto_session.client('cloudtrail')
    
    print("Listing CloudTrail events (first 5):")
    try:
        listed_events = list_cloudtrail_events(cloudtrail_client)
        if not listed_events:
            print("No events found.")
    except Exception as e:
        print(f"Error listing events: {e}")