Waiters are not clearly documented

[dwc0011]

Describe the issue

When viewing the docs for waiters the params and filters are unclear. For example, the wait_until_stopped method request syntax has filters listed for describe_instances. But the docs state

Waits until this Instance is stopped. This method calls EC2.Waiter.instance_stopped.wait() which polls. [EC2.Client.describe_instances()]

This is confusing because why would I pass the filters if I am calling it directly from an instance. Could I call it with another instance-id, that is a listed filter, would it then wait on that instance? Are the docs correct?

Example Doc

EC2.Instance.wait_until_stopped(**kwargs)
Waits until this Instance is stopped. This method calls EC2.Waiter.instance_stopped.wait() which polls. EC2.Client.describe_instances() every 15 seconds until a successful state is reached. An error is returned after 40 failed checks.

See also: AWS API Documentation

Request Syntax
instance.wait_until_stopped(
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
DryRun=True|False,
MaxResults=123,
NextToken='string'
)
PARAMETERS:
Filters (list) –

The filters.

affinity - The affinity setting for an instance running on a Dedicated Host ( default | host).
architecture - The instance architecture ( i386 | x86_64 | arm64).
availability-zone - The Availability Zone of the instance.
block-device-mapping.attach-time - The attach time for an EBS volume mapped to the instance, for example, 2022-09-15T17:15:20.000Z.
block-device-mapping.delete-on-termination - A Boolean that indicates whether the EBS volume is deleted on instance termination.
....

Links

https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2/instance/wait_until_stopped.html

https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2/instance/wait_until_exists.html

https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2/instance/wait_until_terminated.html

https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2/instance/wait_until_exists.html

[tim-finnigan]

Hi @dwc0011 thanks for reaching out. The parameters for waiters like wait_until_stopped automatically correspond to those of the command being polled (describe_instances). I can see how this would be confusing, because you already have a reference to the instance in your example and filters are not necessary.

The general documentation on Boto3 Resource waiters does not use filters: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/resources.html#waiters. (Boto3 Client waiters are implemented slightly different: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/clients.html#waiters.)

Passing a different instance ID in the filters would cause the waiter to not work as expected. You could find the waiter definitions here and add boto3.set_stream_logger('') to your script for a deeper look into the behavior.

I'll leave this issue open to track for now as the documentation could potentially be improved.