Type annotations for aiobotocore IAM

Common errors

• ModuleNotFoundError: No module named 'types_aiobotocore_iam.client'

  cause The `types-aiobotocore-iam` package is not installed, or there's a typo in the import path.
  fix Ensure the package is installed via `pip install types-aiobotocore-iam` or `pip install 'types-aiobotocore[iam]'`. Double-check the import statement for correct spelling.

• mypy: error: Missing attribute '__iter__' for 'IAMClient'

  cause This error or similar type-checking errors (e.g., 'no attribute', 'unexpected keyword argument') often indicate a mismatch between the installed `aiobotocore` version and `types-aiobotocore-iam` version, or the use of an older type checker.
  fix Ensure `aiobotocore` and `types-aiobotocore-iam` are compatible versions (preferably the same major.minor version). Upgrade your type checker (MyPy, Pyright) to the latest stable version. [7]

• An error occurred (AccessDeniedException) when calling the ListUsers operation: User: arn:aws:iam::123456789012:user/MyUser is not authorized to perform: iam:ListUsers on resource: arn:aws:iam::123456789012:user/*

  cause This is an AWS permissions error, not an issue with the type stubs. The IAM user or role executing the code lacks the necessary permissions to perform the requested AWS API call.
  fix Update the IAM policy attached to your AWS credentials to grant `iam:ListUsers` permission (or whatever specific permission is missing). [21, 24]

Warnings

• breaking Support for Python 3.8 has been removed in `mypy-boto3-builder` version 8.12.0 and subsequent `types-aiobotocore-*` packages. Projects targeting Python 3.8 will no longer receive updates or new type stubs.
  Fix: Upgrade your project's Python version to 3.9 or newer. Ensure your `requires_python` is set appropriately. [2]
• breaking Starting with `mypy-boto3-builder` 8.9.0, there were breaking changes to `TypeDef` naming conventions. Specifically, `TypeDefs` for packed method arguments use shorter names (e.g., `CreateDistributionRequestRequestTypeDef` -> `CreateDistributionRequestTypeDef`), and conflicting `TypeDef` 'Extra' postfixes were moved to the end (e.g., `CreateDistributionExtraRequestTypeDef` -> `CreateDistributionRequestExtraTypeDef`).
  Fix: Update your code to use the new `TypeDef` names. Consult the `types-aiobotocore` documentation or regenerate stubs if using `mypy-boto3-builder` directly. [14]
• gotcha To prevent `types-aiobotocore-*` packages from becoming runtime dependencies, it is best practice to wrap all imports of types from these libraries within a `if typing.TYPE_CHECKING:` block.
  Fix: Enclose type stub imports like `from types_aiobotocore_iam.client import IAMClient` within `if TYPE_CHECKING:` conditional blocks. [2, 6]
• gotcha PyCharm's built-in type checker may experience slow performance and high CPU usage, especially with `Literal` overloads present in these stubs. This is a known issue (PY-40997).
  Fix: It is recommended to use an external type checker like MyPy or Pyright instead of PyCharm's built-in one. Alternatively, consider using `types-aiobotocore-lite` or disable PyCharm's type checker for these libraries. [7, 20]

Install

• pip install types-aiobotocore-iam Install standalone IAM stubs
• pip install 'types-aiobotocore[iam]' Install IAM stubs as part of types-aiobotocore

Imports

• IAMClient
  wrong:

  from types_aiobotocore.iam import IAMClient

  correct:

  from types_aiobotocore_iam.client import IAMClient

  When using standalone service packages, the import path is directly from the service package. The `types-aiobotocore` package uses extras and internal paths for its bundled stubs.
• ListUsersResponseTypeDef

  from types_aiobotocore_iam.type_defs import ListUsersResponseTypeDef

  TypedDicts for API responses and request parameters are found in the `type_defs` submodule.

Quickstart

This quickstart demonstrates how to use `types-aiobotocore-iam` to provide type hints for an `aiobotocore` IAM client. It shows importing the `IAMClient` and a response `TypeDef` within a `TYPE_CHECKING` block for static analysis, then uses it to list IAM users.

import asyncio
from typing import TYPE_CHECKING

from aiobotocore.session import get_session

# Import type stubs only during type checking to avoid runtime dependencies
if TYPE_CHECKING:
    from types_aiobotocore_iam.client import IAMClient
    from types_aiobotocore_iam.type_defs import ListUsersResponseTypeDef

async def list_iam_users():
    session = get_session()
    async with session.create_client("iam") as client:
        # Explicitly hint the client type for better IDE support
        client: IAMClient = client

        print("Listing IAM users...")
        try:
            # Type-hint the response for static analysis and auto-completion
            response: ListUsersResponseTypeDef = await client.list_users()
            for user in response.get("Users", []):
                print(f"  User: {user.get('UserName')} (ARN: {user.get('Arn')})")
        except Exception as e:
            print(f"Error listing users: {e}")

if __name__ == "__main__":
    # This example requires valid AWS credentials configured in the environment
    # or ~/.aws/credentials. Ensure your IAM user has 'iam:ListUsers' permission.
    asyncio.run(list_iam_users())