[mutianf]

Table.mutate_rows documents that rows which fail keep their mutations so they
can be applied again, and rows that succeed are cleaned up, but the reroute to
the data client dropped the clearing entirely — so the retry idiom the docstring
describes resent mutations that had already committed. DirectRow.commit kept
its own documented behaviour of clearing after every returned status, but it
reported the synthetic DeadlineExceeded on timeout instead of the real error
from the wire, and the migration's finally had started discarding the mutations
even when the call raised and left the caller nothing to act on. Also documents
MutationsBatcher.mutate, which keeps no reference to the rows it batches and so
cannot clear them.

[gemini-code-assist]

Code Review

This pull request improves mutation handling and error reporting in the Bigtable client. It updates mutate_rows to clear mutations only for successfully applied rows, documents mutation lifecycle behaviors, and introduces _get_status_from_operation_error to unwrap synthetic DeadlineExceeded exceptions and expose the underlying terminal wire errors. Additionally, feedback was provided to use exc.details or [] in _get_status to prevent a potential TypeError in protobuf when exc.details is None.

[daniel-sanche]

nit: this comment is a bit long, and it currently reads more like a commit message referencing past states ("before the reroute"). It could be confusing in the future, reviewing the code in isolation

[mutianf]

Good call — reworded so it describes the behaviour rather than the history:

# Clear once a status is produced, success or failure. An error that
# cannot be turned into a status propagates instead, and the mutations
# stay on the row so the caller can retry them.

Fixed in 1d27cbb.