Add excluded locations on client and request levels

[allenkim0129]

Changes

This change will add excluded locations on client and request levels.

Design doc: https://microsoft-my.sharepoint.com/:w:/p/allekim/EWf4tc65_f9GiOv9aD2XkLMBD9h2ZAAXCcFTKghjutvqcg?e=AlD8w1

On Client level:

def excluded_locations_client_level_sample():
    preferred_locations = ['West US 3', 'West US', 'East US 2']
    excluded_locations = ['West US 3', 'West US']
    client = CosmosClient(
                HOST,
                MASTER_KEY,
                preferred_locations=preferred_locations,
                excluded_locations=excluded_locations
    )

    db = client.create_database(DATABASE_ID)
    container = db.create_container(id=CONTAINER_ID, partition_key=PARTITION_KEY)

    # For write operations with single master account, write endpoint will be the default endpoint,
    # since preferred_locations or excluded_locations are ignored and used
    container.create_item(get_test_item(0))

    # For read operations, read endpoints will be 'preferred_locations' - 'excluded_locations'.
    # In our sample, ['West US 3', 'West US', 'East US 2'] - ['West US 3', 'West US'] => ['East US 2'],
    # therefore 'East US 2' will be the read endpoint, and items will be read from 'East US 2' location
    item = container.read_item(item='Item_0', partition_key='Item_0')

• Note: During client creation, excluded locations can be set by using the excluded_locations parameter. This set will filter any existing preferred locations. If excluded locations filtered all preferred locations, Cosmos DB will use the default endpoints.

On Request level:

def excluded_locations_request_level_sample():
    preferred_locations = ['West US 3', 'West US', 'East US 2']
    excluded_locations_on_client = ['West US 3', 'West US']
    excluded_locations_on_request = ['West US 3']
    client = CosmosClient(
                HOST,
                MASTER_KEY,
                preferred_locations=preferred_locations,
                excluded_locations=excluded_locations_on_client
    )

    db = client.create_database(DATABASE_ID)
    container = db.create_container(id=CONTAINER_ID, partition_key=PARTITION_KEY)

    # For write operations with single master account, write endpoint will be the default endpoint,
    # since preferred_locations or excluded_locations are ignored and used
    container.create_item(get_test_item(0))

    # For read operations, read endpoints will be 'preferred_locations' - 'excluded_locations'.
    # However, in our sample, since the excluded_locations` were passed with the read request, the `excluded_location`
    # will be replaced with the locations from request, ['West US 3']. The `excluded_locations` on request always takes
    # the highest priority!
    # With the excluded_locations on request, the read endpoints will be ['West US', 'East US 2']
    #   ['West US 3', 'West US', 'East US 2'] - ['West US 3'] => ['West US', 'East US 2']
    # Therefore, items will be read from 'West US' or 'East US 2' location
    item = container.read_item(item='Item_0', partition_key='Item_0', excluded_locations=excluded_locations_on_request)

• Note: The excluded locations on requests level can be used by passing excluded_locations parameters along with any other parameters for Container level APIs. This excluded_location parameter will override the existing exlcuded locations on client level. This means also means that if a user can manupilate the client level excluded locations for the specific request. Moreover, if a user wants to skip all client level excluded locations, the user can simply pass an empty list [] of excluded locations to skip all excluded location filters.

Client level API works with excluded_location(11 APIs):

• read_item
• read_all_items
• query_items_change_feed
• query_items
• replace_item
• upsert_item
• create_item
• patch_item
• execute_item_batch
• delete_item
• delete_all_items_by_partition_key

Other Changes:

Bug Fix

• Fixed can_use_multiple_write_locations_for_request check method, because PartitionKey resource type was not included during the check.

All SDK Contribution checklist:

• The pull request does not introduce [breaking changes]
• CHANGELOG is updated for new features, bug fixes or other significant changes.
• I have read the contribution guidelines.

General Guidelines and Best Practices

• Title of the pull request is clear and informative.
• There are a small number of commits, each of which have an informative message. This means that previously merged commits do not appear in the history of the PR. For more information on cleaning up the commits in your PR, see this page.

Testing Guidelines

• Pull request includes test coverage for the included changes.

[azure-sdk]

API change check

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

azure-cosmos

[allenkim0129]

/azp run python - cosmos - tests

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[allenkim0129]

/azp run python - cosmos - tests

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[allenkim0129]

/azp run python - cosmos - tests

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[allenkim0129]

/azp run python - cosmos - tests

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[allenkim0129]

I created a new PR since there were some conflict with branch merges which ended up including more reviewer than required.

Previous PR with comments: #40298

[allenkim0129]

/azp run python - cosmos - tests

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[allenkim0129]

/azp run python - cosmos - tests

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[Copilot]

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

Comments suppressed due to low confidence (2)

sdk/cosmos/azure-cosmos/azure/cosmos/_request_object.py:80

• [nitpick] Consider adding type validation in set_excluded_location_from_options to ensure that options['excludedLocations'] is actually a list of strings.

def set_excluded_location_from_options(self, options: Mapping[str, Any]) -> None:

sdk/cosmos/azure-cosmos/azure/cosmos/_location_cache.py:168

• [nitpick] Although returning a fallback endpoint keeps the service available, consider logging a warning to highlight that all regional endpoints were excluded and the fallback is being used.

if not applicable_endpoints:

[allenkim0129]

This PR was created to remove unnecesary commits from the last PR. #40022

The previous PR will have all related comments from previous commits.

[allenkim0129]

/azp run python - cosmos - tests

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[simorenoh]

This looks great overall, thanks Allen! Just had a couple of comments/ questions 👍

[kushagraThapar]

Amazing work @allenkim0129
Great development + test coverage. Thanks for the efforts on this.
One thing though, we should add a section in the readme.md as well, noting this feature and pointing to the sample from the readme.md

[tvaron3]

LGTM

[allenkim0129]

/azp run python - cosmos - tests

[azure-pipelines]

Azure Pipelines will not run the associated pipelines, because the pull request was updated after the run command was issued. Review the pull request again and issue a new run command.

[allenkim0129]

/azp run python - cosmos - tests

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[allenkim0129]

/azp run python - cosmos - tests

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).