Add support for condition failure return values

[Tomas Neme (Lacrymology)]

Contains

• DB migrations
• Features
• Test cases
• Bugfix
• Documentation
• Release

Issue

DynamoDB supports ReturnValuesOnConditionCheckFailure for conditional writes so callers can request the old item image when a write condition fails. PynamoDB already had part of the low-level request-construction seam, but model writes did not expose it for ordinary save, update, and delete calls, and transactional delete did not support it. The existing validation also accepted normal ReturnValues values that DynamoDB does not allow for ReturnValuesOnConditionCheckFailure.

Solution

Expose condition-failure return values through model write APIs and table/low-level connection write APIs, while preserving the existing PutError, UpdateError, DeleteError, and TransactWriteError behavior. Returned old item data remains available through the wrapped botocore error response when DynamoDB includes it.

Details

• Add return_values_on_condition_failure to Model.save().
• Add return_values_on_condition_failure to Model.update() while preserving the existing ReturnValues=ALL_NEW request behavior.
• Add return_values_on_condition_failure to Model.delete().
• Thread return_values_on_condition_failure through model save argument construction and table-scoped write methods.
• Thread return_values_on_condition_failure through low-level Connection.put_item, Connection.update_item, and Connection.delete_item.
• Update TransactWrite.delete() to accept return_values and pass it as ReturnValuesOnConditionCheckFailure.
• Tighten ReturnValuesOnConditionCheckFailure validation to DynamoDB’s allowed values: NONE and ALL_OLD.
• Preserve DynamoDB’s returned Item in the wrapped botocore error response for conditional write failures.
• Add unit coverage for model, table connection, low-level connection, transaction delete, validation, and wrapped error response behavior.
• Document model write support and how to inspect old item data from the wrapped botocore error response.

Screenshots

N/A

Related Issues

N/A

Additional Notes

Verification completed with:

• uv run pytest tests/test_model.py tests/test_table_connection.py tests/test_base_connection.py tests/test_transaction.py -k "return_values or condition or update or save or delete or preserves_error_response_item"
• uv run pytest tests/ -k "not ddblocal"
• uv run sphinx-build -W docs /tmp/docs-build
• uv run mypy .