Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Cosmos] Clean up public surface area #40008

Merged
merged 15 commits into from
Mar 27, 2025
Merged

[Cosmos] Clean up public surface area #40008

merged 15 commits into from
Mar 27, 2025

Conversation

simorenoh
Copy link
Member

We have recently found that some of the arguments and options that we expose in our public surface area are not relevant to several methods even though they are listed in their typehints. This PR aims at cleaning that up so that customers can be aware of the exact options that are available to them in every single one of our methods. Most of these changes revolved around the session_token, etag, match_condition and response_hook arguments. Some notes on these:

Session tokens only apply to item-level operations. Control plane operations are strongly consistent so this option has no relevance for those operations.

Etags and their relevant match conditions only apply to item-level operations, and within those only apply to replace and delete operations that deal with single items. Their typehints have been removed from all other instances where they were referenced.

Response hooks in the Python SDK will always take in two things: the response headers (dictionary of string -> string) and the response (dictionary of string -> any). Typehints have been updated to reflect this, and some wrong uses of response hooks were removed from query-type methods since calling the response hook at that point is broken behavior that does not in any way reference the results of the query and were using the wrong last_response_headers that would come from other operations at that point in the code.

The following were cleaned up:

cosmos_client.py

  • Removed session_token option from the list_databases, query_databases methods as they are not relevant to them.
  • Removed session_token, etag, match_condition options from the create_database, create_database_if_not_exists, delete_database methods as they are not relevant to them.

database.py

  • Removed session_token option from the read, list_containers, query_containers methods as they are not relevant to them.
  • Removed session_token, etag, match_condition options from the create_container, create_container_if_not_exists, delete_container, replace_container methods as they are not relevant to them.

container.py

  • Removed session_token option from the read method as it is not relevant to this operation.
  • Removed etag and match_condition options from the upsert_item, create_item, execute_item_batch, delete_all_items_by_partition_key methods as they are not relevant to them.
  • Fixed the response_hook typehints to be more accurate and removed their direct use before the queries get executed for the read_all_items, query_items_change_feed, and query_items methods.

The same changes have been made to the async client's relevant files.

Also went ahead and fixed some tests I happened to see, as well as removing the mention of "Lazy" indexing since it has been unsupported for almost 5 years now.

@simorenoh simorenoh marked this pull request as ready for review March 10, 2025 23:47
@Copilot Copilot bot review requested due to automatic review settings March 10, 2025 23:47
@simorenoh simorenoh requested review from annatisch and a team as code owners March 10, 2025 23:47
Copy link
Contributor

@Copilot Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PR Overview

This PR cleans up the public API surface by removing unsupported parameters (such as session_token, etag, and match_condition) from various methods and by updating typehints and response hook usage. It also removes legacy functionality (e.g. lazy indexing) and converts synchronous test clean‐up calls to their asynchronous counterparts.

Reviewed Changes

File Description
sdk/cosmos/azure-cosmos/azure/cosmos/aio/_database.py Updates to remove session_token from method signatures and to add warnings for unsupported parameters in async methods.
sdk/cosmos/azure-cosmos/azure/cosmos/cosmos_client.py Removed unsupported parameters from database creation and query methods, replacing direct parameter usage with warnings.
sdk/cosmos/azure-cosmos/azure/cosmos/database.py Similar removal of unsupported parameters and updates to deprecation warnings in database and container creation methods.
sdk/cosmos/azure-cosmos/azure/cosmos/documents.py Removal of the Lazy indexing mode and improved docstring wording for indexing classes.
sdk/cosmos/azure-cosmos/test/test_computed_properties_async.py Updated container deletion calls to be asynchronous.

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

Copy link
Member

@tvaron3 tvaron3 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Left some minor comments, but LGTM

@azure-sdk
Copy link
Collaborator

API change check

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

azure-cosmos

@simorenoh simorenoh requested a review from annatisch March 17, 2025 15:44
Copy link
Member

@kushagraThapar kushagraThapar left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM @simorenoh thanks for the changes.

@simorenoh simorenoh merged commit 71ef1ea into main Mar 27, 2025
19 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
Status: Done
Development

Successfully merging this pull request may close these issues.

5 participants