[Cosmos] Etag handling bugfix and documentation rollback

[simorenoh]

The etag handling that was changed as part of PR 40008 missed the fact that there was improper handling for this argument in the _base.py class that would now take care of this logic. This PR aims at improving that logic based on these new changes. Specifically, an exception would be raised when manually providing 'None' for an etag value as an argument.

This PR also reverts changes to the etag and match_conditions documentation for the upsert_item methods in their respective clients, since upsert, replace and delete are all valid for these options.

[Copilot]

Pull Request Overview

This PR addresses a bug in etag handling by reworking how etag and match_condition are propagated in the SDK and updating corresponding tests, while reverting documentation changes for the upsert_item methods.

• Updated tests to now pass etag as None instead of a random string.
• Enhanced the upsert_item API in both synchronous and asynchronous container implementations to correctly accept etag and match_condition parameters.
• Modified _base.py to raise a ValueError when an etag is provided without a corresponding match_condition, ensuring proper error handling.

Reviewed Changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
sdk/cosmos/azure-cosmos/tests/test_backwards_compatibility_async.py	Updated test scenarios for asynchronous etag handling by passing etag as None.
sdk/cosmos/azure-cosmos/tests/test_backwards_compatibility.py	Updated test scenarios for synchronous etag handling by passing etag as None.
sdk/cosmos/azure-cosmos/azure/cosmos/container.py	Modified upsert_item to accept and forward etag and match_condition parameters.
sdk/cosmos/azure-cosmos/azure/cosmos/aio/_container.py	Modified async upsert_item to accept and forward etag and match_condition parameters.
sdk/cosmos/azure-cosmos/azure/cosmos/_base.py	Changed error handling to raise an exception if etag is provided without match_condition.
sdk/cosmos/azure-cosmos/CHANGELOG.md	Documented the etag bug fix in the changelog.

[azure-sdk]

API change check

APIView has identified API level changes in this PR and created following API reviews.

azure-cosmos

[tvaron3]

LGTM

[kushagraThapar]

Changes look good, though I am curious, are there any more test cases that we need to think about? Or does this cover everything related to _etag and match_condition?

[simorenoh]

Changes look good, though I am curious, are there any more test cases that we need to think about? Or does this cover everything related to _etag and match_condition? @kushagraThapar

It's the one case we didn't cover for the relevant code paths - unfortunately our logic in _base.py was only checking for etag to be present in the kwargs, but not checking if it was set to None. For all the other cases with match_conditions we have tests in the relevant item crud files.