[Cosmos] Clean up public surface area (Azure#40008)

* sync client changes

* Update test_computed_properties_async.py

* async changes

* great catches by Tomas

* added missing warnings

* address comments

* merge conflict on GH, reverting for now

* Update documents.py

* changelog and new messages

* mypy + pylint

* Update _container.py

* Update CHANGELOG.md

Author: simorenoh

sdk/cosmos/azure-cosmos/CHANGELOG.md

@@ -10,6 +10,8 @@
 * Fixed too many health checks happening when skipping the recommended client startup. See [PR 40203](https://github.com/Azure/azure-sdk-for-python/pull/40203).
 
 #### Other Changes
+* Removed excess keyword arguments from methods that did not use them. See [PR 40008](https://github.com/Azure/azure-sdk-for-python/pull/40008).
+* Removed first `response_hook` call for query methods that would utilize wrong response headers. See [PR 40008](https://github.com/Azure/azure-sdk-for-python/pull/40008).
 
 ### 4.10.0b2 (2025-04-08)
 

sdk/cosmos/azure-cosmos/azure/cosmos/aio/_container.py

@@ -23,10 +23,10 @@
 """
 
 from typing import Any, Dict, List, Optional, Union, cast, Mapping, Iterable, Callable
+import warnings
 from azure.core.async_paging import AsyncItemPaged
 from azure.core.credentials import TokenCredential
 from azure.core.credentials_async import AsyncTokenCredential
-from azure.core import MatchConditions
 from azure.core.pipeline.policies import RetryMode
 
 from azure.core.tracing.decorator_async import distributed_trace_async
@@ -250,10 +250,7 @@ async def create_database(
         id: str,
         *,
         offer_throughput: Optional[Union[int, ThroughputProperties]] = None,
-        session_token: Optional[str] = None,
         initial_headers: Optional[Dict[str, str]] = None,
-        etag: Optional[str] = None,
-        match_condition: Optional[MatchConditions] = None,
         **kwargs: Any
     ) -> DatabaseProxy:
         """
@@ -262,12 +259,7 @@ async def create_database(
         :param str id: ID (name) of the database to create.
         :keyword offer_throughput: The provisioned throughput for this offer.
         :paramtype offer_throughput: Union[int, ~azure.cosmos.ThroughputProperties]
-        :keyword str session_token: Token for use with Session consistency.
         :keyword dict[str, str] initial_headers: Initial headers to be sent as part of the request.
-        :keyword str etag: An ETag value, or the wildcard character (*). Used to check if the resource
-            has changed, and act according to the condition specified by the `match_condition` parameter.
-        :keyword match_condition: The match condition to use upon the etag.
-        :paramtype match_condition: ~azure.core.MatchConditions
         :keyword response_hook: A callable invoked with the response metadata.
         :paramtype response_hook: Callable[[Dict[str, str], Dict[str, Any]], None]
         :raises ~azure.cosmos.exceptions.CosmosResourceExistsError: Database with the given ID already exists.
@@ -284,14 +276,26 @@ async def create_database(
                 :caption: Create a database in the Cosmos DB account:
                 :name: create_database
         """
+        session_token = kwargs.get('session_token')
         if session_token is not None:
-            kwargs["session_token"] = session_token
-        if initial_headers is not None:
-            kwargs["initial_headers"] = initial_headers
+            warnings.warn(
+                "The 'session_token' flag does not apply to this method and is always ignored even if passed."
+                " It will now be removed in the future.",
+                DeprecationWarning)
+        etag = kwargs.get('etag')
         if etag is not None:
-            kwargs["etag"] = etag
+            warnings.warn(
+                "The 'etag' flag does not apply to this method and is always ignored even if passed."
+                " It will now be removed in the future.",
+                DeprecationWarning)
+        match_condition = kwargs.get('match_condition')
         if match_condition is not None:
-            kwargs["match_condition"] = match_condition
+            warnings.warn(
+                "The 'match_condition' flag does not apply to this method and is always ignored even if passed."
+                " It will now be removed in the future.",
+                DeprecationWarning)
+        if initial_headers is not None:
+            kwargs["initial_headers"] = initial_headers
         request_options = _build_options(kwargs)
         _set_throughput_options(offer=offer_throughput, request_options=request_options)
 
@@ -304,10 +308,7 @@ async def create_database_if_not_exists(  # pylint: disable=redefined-builtin
         id: str,
         *,
         offer_throughput: Optional[Union[int, ThroughputProperties]] = None,
-        session_token: Optional[str] = None,
         initial_headers: Optional[Dict[str, str]] = None,
-        etag: Optional[str] = None,
-        match_condition: Optional[MatchConditions] = None,
         **kwargs: Any
     ) -> DatabaseProxy:
         """
@@ -322,26 +323,33 @@ async def create_database_if_not_exists(  # pylint: disable=redefined-builtin
         :param str id: ID (name) of the database to read or create.
         :keyword offer_throughput: The provisioned throughput for this offer.
         :paramtype offer_throughput: Union[int, ~azure.cosmos.ThroughputProperties]
-        :keyword str session_token: Token for use with Session consistency.
         :keyword dict[str, str] initial_headers: Initial headers to be sent as part of the request.
-        :keyword str etag: An ETag value, or the wildcard character (*). Used to check if the resource
-            has changed, and act according to the condition specified by the `match_condition` parameter.
-        :keyword match_condition: The match condition to use upon the etag.
-        :paramtype match_condition: ~azure.core.MatchConditions
         :keyword response_hook: A callable invoked with the response metadata.
         :paramtype response_hook: Callable[[Dict[str, str], Dict[str, Any]], None]
         :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: The database read or creation failed.
         :returns: A DatabaseProxy instance representing the database.
         :rtype: ~azure.cosmos.DatabaseProxy
         """
+        session_token = kwargs.get('session_token')
         if session_token is not None:
-            kwargs["session_token"] = session_token
-        if initial_headers is not None:
-            kwargs["initial_headers"] = initial_headers
+            warnings.warn(
+                "The 'session_token' flag does not apply to this method and is always ignored even if passed."
+                " It will now be removed in the future.",
+                DeprecationWarning)
+        etag = kwargs.get('etag')
         if etag is not None:
-            kwargs["etag"] = etag
+            warnings.warn(
+                "The 'etag' flag does not apply to this method and is always ignored even if passed."
+                " It will now be removed in the future.",
+                DeprecationWarning)
+        match_condition = kwargs.get('match_condition')
         if match_condition is not None:
-            kwargs["match_condition"] = match_condition
+            warnings.warn(
+                "The 'match_condition' flag does not apply to this method and is always ignored even if passed."
+                " It will now be removed in the future.",
+                DeprecationWarning)
+        if initial_headers is not None:
+            kwargs["initial_headers"] = initial_headers
         try:
             database_proxy = self.get_database_client(id)
             await database_proxy.read(**kwargs)
@@ -375,7 +383,6 @@ def list_databases(
         self,
         *,
         max_item_count: Optional[int] = None,
-        session_token: Optional[str] = None,
         initial_headers: Optional[Dict[str, str]] = None,
         response_hook: Optional[Callable[[Mapping[str, Any]], None]] = None,
         **kwargs: Any
@@ -390,8 +397,12 @@ def list_databases(
         :returns: An AsyncItemPaged of database properties (dicts).
         :rtype: AsyncItemPaged[Dict[str, str]]
         """
+        session_token = kwargs.pop('session_token', None)
         if session_token is not None:
-            kwargs["session_token"] = session_token
+            warnings.warn(
+                "The 'session_token' flag does not apply to this method and is always ignored even if passed."
+                " It will now be removed in the future.",
+                DeprecationWarning)
         if initial_headers is not None:
             kwargs["initial_headers"] = initial_headers
         feed_options = _build_options(kwargs)
@@ -410,7 +421,6 @@ def query_databases(
         *,
         parameters: Optional[List[Dict[str, Any]]] = None,
         max_item_count: Optional[int] = None,
-        session_token: Optional[str] = None,
         initial_headers: Optional[Dict[str, str]] = None,
         response_hook: Optional[Callable[[Mapping[str, Any]], None]] = None,
         **kwargs: Any
@@ -429,8 +439,12 @@ def query_databases(
         :returns: An AsyncItemPaged of database properties (dicts).
         :rtype: AsyncItemPaged[Dict[str, str]]
         """
+        session_token = kwargs.get('session_token')
         if session_token is not None:
-            kwargs["session_token"] = session_token
+            warnings.warn(
+                "The 'session_token' flag does not apply to this method and is always ignored even if passed."
+                " It will now be removed in the future.",
+                DeprecationWarning)
         if initial_headers is not None:
             kwargs["initial_headers"] = initial_headers
         feed_options = _build_options(kwargs)
@@ -450,10 +464,7 @@ async def delete_database(
         self,
         database: Union[str, DatabaseProxy, Dict[str, Any]],
         *,
-        session_token: Optional[str] = None,
         initial_headers: Optional[Dict[str, str]] = None,
-        etag: Optional[str] = None,
-        match_condition: Optional[MatchConditions] = None,
         response_hook: Optional[Callable[[Mapping[str, Any]], None]] = None,
         **kwargs: Any
     ) -> None:
@@ -462,27 +473,34 @@ async def delete_database(
         :param database: The ID (name), dict representing the properties, or :class:`DatabaseProxy`
             instance of the database to delete.
         :type database: Union[str, ~azure.cosmos.DatabaseProxy, Dict[str, Any]]
-        :keyword str session_token: Token for use with Session consistency.
         :keyword dict[str, str] initial_headers: Initial headers to be sent as part of the request.
-        :keyword str etag: An ETag value, or the wildcard character (*). Used to check if the resource
-            has changed, and act according to the condition specified by the `match_condition` parameter.
-        :keyword match_condition: The match condition to use upon the etag.
-        :paramtype match_condition: ~azure.core.MatchConditions
         :keyword response_hook: A callable invoked with the response metadata.
         :paramtype response_hook: Callable[[Mapping[str, Any]], None]
         :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: If the database couldn't be deleted.
         :rtype: None
         """
+        session_token = kwargs.get('session_token')
         if session_token is not None:
-            kwargs["session_token"] = session_token
-        if initial_headers is not None:
-            kwargs["initial_headers"] = initial_headers
+            warnings.warn(
+                "The 'session_token' flag does not apply to this method and is always ignored even if passed."
+                " It will now be removed in the future.",
+                DeprecationWarning)
+        etag = kwargs.get('etag')
         if etag is not None:
-            kwargs["etag"] = etag
+            warnings.warn(
+                "The 'etag' flag does not apply to this method and is always ignored even if passed."
+                " It will now be removed in the future.",
+                DeprecationWarning)
+        match_condition = kwargs.get('match_condition')
         if match_condition is not None:
-            kwargs["match_condition"] = match_condition
-        request_options = _build_options(kwargs)
+            warnings.warn(
+                "The 'match_condition' flag does not apply to this method and is always ignored even if passed."
+                " It will now be removed in the future.",
+                DeprecationWarning)
 
+        if initial_headers is not None:
+            kwargs["initial_headers"] = initial_headers
+        request_options = _build_options(kwargs)
         database_link = _get_database_link(database)
         await self.client_connection.DeleteDatabase(database_link, options=request_options, **kwargs)
         if response_hook: