fix: revise and rename is_etag_in_json(data)

[cojenco]

This PR revises and renames retry.is_etag_in_json(data) to ensure that eTags are correctly captured and validated from the request body.

• Rename conditional retry predicate retry.is_etag_in_json(data) to retry.is_etag_in_data(data). It returns a boolean whether or not an etag is contained in the request body.
• Revise retry.is_etag_in_data(data) to reflect library use cases in which data is dict or None
• Update tests and docs

Fixes#481 🦕

[tritone]

Looks much cleaner, thank you!

[tritone]

Nit: I think we could be clearer that the dict represents the JSON body rather than containing it. Also, this is specifically intended for calls where metadata is sent in the request body.

It seems like it'd be better to actually just rename this function to is_etag_in_data but I guess technically this is part of the public surface of the library (even if we don't expect external callers to use it directly)?

[tseaver]

We could rename it and leave is_etag_in_json around as a backward-compatibility alias.

[cojenco]

Would it be something like this:

def is_etag_in_data(data):
"""Return True if an etag is contained in the request body.
:type data: dict or None
:param data: A dict representing the request JSON body. If not passed, returns False.
"""
return data is not None and "etag" in data
def is_etag_in_json(data):
"""
``is_etag_in_json`` is supported for backwards-compatibility reasons only;
please use ``is_etag_in_data`` instead.
"""
return is_etag_in_data(data)

[tseaver]

LGTM