This looks confusing. If I want to add e.g. a 2-second delay in the request, I would expect a delay => 2 option in the request() method.

But, modifying the response object instead of the request, and using a getter method instead of a setter looks very very counter-intuitive 😐

Maybe I'm missing something here?

To give some more context, here's how others do:

wget defines these options:

wget --wait=seconds
wget --random-wait

See https://man7.org/linux/man-pages/man1/wget.1.html

curl defines several options to define rate limiting:

# limit rate in bytes per second
curl https://example.com/ --limit-rate 200K

# limit by number of requests per second, hour, etc.
curl --rate 2/s -O https://example.com/[1-100].jpg
curl --rate 3/h -O https://example.com/[1-10].jpg

See https://everything.curl.dev/usingcurl/transfers/rate-limiting

I understand the confusion, here is the explanation from the pull request:

Returning the handler as an info item saves adding a new method and thus plays well with decorators, without requiring a new dedicated interface.

Thus, I'm not sure how to introduce this feature. Maybe this should be done in a different section? 🤔

This pauses the response, not only the request. Pausing is how you implement throttling for example, which is about inserting many many small delays when you read the body of the response.

OK, thanks for additional insights. Let's merge this then.