Type annotations for boto3 Step Functions

Warnings

• breaking Support for Python 3.8 has been removed across all `mypy-boto3` packages, including `mypy-boto3-stepfunctions`.
  Fix: Upgrade your Python environment to version 3.9 or newer.
• breaking TypeDef naming conventions changed in version 8.9.0. Packed method arguments may now use shorter names (e.g., `CreateDistributionRequestRequestTypeDef` -> `CreateDistributionRequestTypeDef`), and conflicting `Extra` postfixes are moved to the end (e.g., `CreateDistributionExtraRequestTypeDef` -> `CreateDistributionRequestExtraTypeDef`).
  Fix: Review and update explicit `TypeDef` import names in your codebase if you were referencing them directly. IDEs and type checkers should highlight any breaking changes.
• gotcha PyCharm users may experience slow performance or high CPU usage due to an issue with Literal overloads (PY-40997) when using `boto3-stubs` or individual `mypy-boto3-*` packages.
  Fix: Consider using `boto3-stubs-lite` instead of the full package, or disable PyCharm's internal type checker and rely solely on `mypy` or `pyright`.
• gotcha When conditionally importing `mypy-boto3` types with `if TYPE_CHECKING:` to avoid runtime dependencies, Pylint may report 'undefined variable' errors.
  Fix: To resolve Pylint complaints, you can define dummy `object` types for the imported symbols in the `else` block of your `TYPE_CHECKING` condition, for example: `else: SFNClient = object`.

Install

• pip install mypy-boto3-stepfunctions Install library
• pip install boto3 mypy Install runtime and type checker

Imports

• SFNClient

  from mypy_boto3_stepfunctions.client import SFNClient

  Import the typed Step Functions client for explicit annotations.
• ListStateMachinesOutputTypeDef

  from mypy_boto3_stepfunctions.type_defs import ListStateMachinesOutputTypeDef

  Import specific TypedDicts for explicit response type annotations.
• EncryptionTypeType

  from mypy_boto3_stepfunctions.literals import EncryptionTypeType

  Import literals for type-safe string arguments.

Quickstart

Demonstrates how to obtain a type-hinted Step Functions client and use it to list state machines. The `TYPE_CHECKING` block ensures type hints are available for static analysis without adding runtime dependencies if not desired. The `region_name` is explicitly set using an environment variable for clarity.

import boto3
import os
from typing import TYPE_CHECKING

# These imports are only for type checking purposes.
if TYPE_CHECKING:
    from mypy_boto3_stepfunctions.client import SFNClient
    from mypy_boto3_stepfunctions.type_defs import ListStateMachinesOutputTypeDef

# boto3 automatically picks up AWS credentials from environment variables
# (e.g., AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION) or ~/.aws/credentials.
# Ensure these are configured for a live AWS connection.

try:
    # Get the Step Functions client.
    # During static analysis (TYPE_CHECKING is True), 'sfn_client' will be inferred as SFNClient.
    # At runtime, it behaves like a standard boto3 client.
    sfn_client: "SFNClient" = boto3.client("stepfunctions", region_name=os.environ.get('AWS_REGION', 'us-east-1'))

    # Use the typed client. Mypy will validate arguments and the return type.
    response: ListStateMachinesOutputTypeDef = sfn_client.list_state_machines(maxResults=10)

    print("Successfully listed Step Functions state machines:")
    for sm in response["stateMachines"]:
        print(f"- {sm['name']} (ARN: {sm['stateMachineArn']})")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Please ensure your AWS credentials are configured and you have permissions for Step Functions (states:ListStateMachines).")