/aws-sdk-python-usage

Waiters Reference

Using Waiters

Waiters poll an AWS operation until a resource reaches a desired state or the waiter times out:

import boto3

ec2 = boto3.client("ec2")

# Start an instance
ec2.start_instances(InstanceIds=["i-1234567890abcdef0"])

# Wait until it's running
waiter = ec2.get_waiter("instance_running")
waiter.wait(
    InstanceIds=["i-1234567890abcdef0"],
    WaiterConfig={
        "Delay": 15,        # seconds between polls (default varies by waiter)
        "MaxAttempts": 40,   # max poll attempts (default varies by waiter)
    },
)

WaiterConfig

Both are optional and override the waiter's built-in defaults.

Common Waiters

List available waiters for a client:

client.waiter_names  # ["bucket_exists", "bucket_not_exists", ...]

Waiter Errors

from botocore.exceptions import WaiterError

try:
    waiter = s3.get_waiter("object_exists")
    waiter.wait(Bucket="bucket", Key="key")
except WaiterError as e:
    print(f"Waiter failed: {e}")
    # e.last_response contains the last polling response

A WaiterError is raised when:

• MaxAttempts is exceeded without reaching the desired state
• The waiter enters a terminal failure state (e.g., the resource entered an unrecoverable state)

Custom Waiters

For operations without built-in waiters, define a custom waiter model:

import boto3
from botocore.waiter import WaiterModel, create_waiter_with_client

waiter_config = {
    "version": 2,
    "waiters": {
        "FunctionActive": {
            "operation": "GetFunction",
            "delay": 5,
            "maxAttempts": 20,
            "acceptors": [
                {
                    "matcher": "path",
                    "expected": "Active",
                    "argument": "Configuration.State",
                    "state": "success",
                },
                {
                    "matcher": "path",
                    "expected": "Failed",
                    "argument": "Configuration.State",
                    "state": "failure",
                },
            ],
        }
    },
}

client = boto3.client("lambda")
waiter_model = WaiterModel(waiter_config)
waiter = create_waiter_with_client("FunctionActive", waiter_model, client)
waiter.wait(FunctionName="my-function")

Acceptor matchers