{"id":2133,"library":"mypy-boto3-stepfunctions","title":"Type annotations for boto3 Step Functions","description":"mypy-boto3-stepfunctions provides comprehensive type annotations for the AWS Step Functions service within `boto3`. It enhances static analysis tools like Mypy, Pyright, and IDEs (VSCode, PyCharm) by adding precise type hints to client methods, paginators, waiters, and TypeDefs. The current version is 1.42.3, actively maintained with releases frequently following `boto3` updates.","status":"active","version":"1.42.3","language":"en","source_language":"en","source_url":"https://github.com/youtype/mypy_boto3_builder","tags":["mypy","boto3","aws","stepfunctions","type-hints","stubs","static-analysis"],"install":[{"cmd":"pip install mypy-boto3-stepfunctions","lang":"bash","label":"Install library"},{"cmd":"pip install boto3 mypy","lang":"bash","label":"Install runtime and type checker"}],"dependencies":[{"reason":"Provides the AWS SDK for Python that these type stubs annotate.","package":"boto3"},{"reason":"The primary static type checker for Python, which utilizes these stubs.","package":"mypy","optional":true}],"imports":[{"note":"Import the typed Step Functions client for explicit annotations.","symbol":"SFNClient","correct":"from mypy_boto3_stepfunctions.client import SFNClient"},{"note":"Import specific TypedDicts for explicit response type annotations.","symbol":"ListStateMachinesOutputTypeDef","correct":"from mypy_boto3_stepfunctions.type_defs import ListStateMachinesOutputTypeDef"},{"note":"Import literals for type-safe string arguments.","symbol":"EncryptionTypeType","correct":"from mypy_boto3_stepfunctions.literals import EncryptionTypeType"}],"quickstart":{"code":"import boto3\nimport os\nfrom typing import TYPE_CHECKING\n\n# These imports are only for type checking purposes.\nif TYPE_CHECKING:\n    from mypy_boto3_stepfunctions.client import SFNClient\n    from mypy_boto3_stepfunctions.type_defs import ListStateMachinesOutputTypeDef\n\n# boto3 automatically picks up AWS credentials from environment variables\n# (e.g., AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION) or ~/.aws/credentials.\n# Ensure these are configured for a live AWS connection.\n\ntry:\n    # Get the Step Functions client.\n    # During static analysis (TYPE_CHECKING is True), 'sfn_client' will be inferred as SFNClient.\n    # At runtime, it behaves like a standard boto3 client.\n    sfn_client: \"SFNClient\" = boto3.client(\"stepfunctions\", region_name=os.environ.get('AWS_REGION', 'us-east-1'))\n\n    # Use the typed client. Mypy will validate arguments and the return type.\n    response: ListStateMachinesOutputTypeDef = sfn_client.list_state_machines(maxResults=10)\n\n    print(\"Successfully listed Step Functions state machines:\")\n    for sm in response[\"stateMachines\"]:\n        print(f\"- {sm['name']} (ARN: {sm['stateMachineArn']})\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Please ensure your AWS credentials are configured and you have permissions for Step Functions (states:ListStateMachines).\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to version 3.9 or newer.","message":"Support for Python 3.8 has been removed across all `mypy-boto3` packages, including `mypy-boto3-stepfunctions`.","severity":"breaking","affected_versions":"8.12.0 and later"},{"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.","message":"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`).","severity":"breaking","affected_versions":"8.9.0 and later"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions (due to PyCharm issue)"},{"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`.","message":"When conditionally importing `mypy-boto3` types with `if TYPE_CHECKING:` to avoid runtime dependencies, Pylint may report 'undefined variable' errors.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}