diff --git a/sdk/cosmos/azure-cosmos/CHANGELOG.md b/sdk/cosmos/azure-cosmos/CHANGELOG.md index c488b4b63592..988e7ca7adb5 100644 --- a/sdk/cosmos/azure-cosmos/CHANGELOG.md +++ b/sdk/cosmos/azure-cosmos/CHANGELOG.md @@ -9,6 +9,7 @@ #### Bugs Fixed #### Other Changes +* Marked `computed_properties` keyword as provisional, un-marked `continuation_token_limit` as provisional. See [PR 34207](https://github.com/Azure/azure-sdk-for-python/pull/34207). ### 4.5.2b4 (2024-02-02) This version and all future versions will require Python 3.8+. diff --git a/sdk/cosmos/azure-cosmos/azure/cosmos/aio/_container.py b/sdk/cosmos/azure-cosmos/azure/cosmos/aio/_container.py index 79fb51e8ee1c..5fcd9e0d6ffc 100644 --- a/sdk/cosmos/azure-cosmos/azure/cosmos/aio/_container.py +++ b/sdk/cosmos/azure-cosmos/azure/cosmos/aio/_container.py @@ -297,7 +297,6 @@ async def read_item( request_options = _build_options(kwargs) request_options["partitionKey"] = await self._set_partition_key(partition_key) - max_integrated_cache_staleness_in_ms = kwargs.pop('max_integrated_cache_staleness_in_ms', None) if max_integrated_cache_staleness_in_ms is not None: validate_cache_staleness_value(max_integrated_cache_staleness_in_ms) request_options["maxIntegratedCacheStaleness"] = max_integrated_cache_staleness_in_ms @@ -369,6 +368,7 @@ def query_items( initial_headers: Optional[Dict[str, str]] = None, max_integrated_cache_staleness_in_ms: Optional[int] = None, priority_level: Optional[Literal["High", "Low"]] = None, + continuation_token_limit: Optional[int] = None, **kwargs: Any ) -> AsyncItemPaged[Dict[str, Any]]: """Return all results matching the given `query`. @@ -397,9 +397,9 @@ def query_items( :keyword dict[str, str] initial_headers: Initial headers to be sent as part of the request. :keyword response_hook: A callable invoked with the response metadata. :paramtype response_hook: Callable[[Dict[str, str], AsyncItemPaged[Dict[str, Any]]], None] - :keyword int continuation_token_limit: **provisional** The size limit in kb of the - response continuation token in the query response. Valid values are positive integers. - A value of 0 is the same as not passing a value (default no limit). + :keyword int continuation_token_limit: The size limit in kb of the response continuation token in the query + response. Valid values are positive integers. + A value of 0 is the same as not passing a value (default no limit). :keyword int max_integrated_cache_staleness_in_ms: The max cache staleness for the integrated cache in milliseconds. For accounts configured to use the integrated cache, using Session or Eventual consistency, responses are guaranteed to be no staler than this value. @@ -453,7 +453,6 @@ def query_items( feed_options["maxIntegratedCacheStaleness"] = max_integrated_cache_staleness_in_ms correlated_activity_id = GenerateGuidId() feed_options["correlatedActivityId"] = correlated_activity_id - continuation_token_limit = kwargs.pop("continuation_token_limit", None) if continuation_token_limit is not None: feed_options["responseContinuationTokenLimitInKb"] = continuation_token_limit if hasattr(response_hook, "clear"): diff --git a/sdk/cosmos/azure-cosmos/azure/cosmos/aio/_cosmos_client.py b/sdk/cosmos/azure-cosmos/azure/cosmos/aio/_cosmos_client.py index 512d087ee00b..201105953a0e 100644 --- a/sdk/cosmos/azure-cosmos/azure/cosmos/aio/_cosmos_client.py +++ b/sdk/cosmos/azure-cosmos/azure/cosmos/aio/_cosmos_client.py @@ -66,6 +66,7 @@ def _build_auth(credential: CredentialType) -> CredentialDict: "such as ClientSecretCredential).") return auth + def _build_connection_policy(kwargs: Dict[str, Any]) -> ConnectionPolicy: # pylint: disable=protected-access policy = kwargs.pop('connection_policy', None) or ConnectionPolicy() diff --git a/sdk/cosmos/azure-cosmos/azure/cosmos/aio/_database.py b/sdk/cosmos/azure-cosmos/azure/cosmos/aio/_database.py index 1f85944a409d..59165914cc3e 100644 --- a/sdk/cosmos/azure-cosmos/azure/cosmos/aio/_database.py +++ b/sdk/cosmos/azure-cosmos/azure/cosmos/aio/_database.py @@ -194,8 +194,8 @@ async def create_container( 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 List[Dict[str, str]] computed_properties: Sets The computed properties for this container in the Azure - Cosmos DB Service. For more Information on how to use computed properties visit + :keyword List[Dict[str, str]] computed_properties: **provisional** Sets The computed properties for this + container in the Azure Cosmos DB Service. For more Information on how to use computed properties visit `here: https://learn.microsoft.com/en-us/azure/cosmos-db/nosql/query/computed-properties?tabs=dotnet` :keyword response_hook: A callable invoked with the response metadata. :paramtype response_hook: Callable[[Dict[str, str], Dict[str, Any]], None] @@ -291,8 +291,8 @@ async def create_container_if_not_exists( 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 List[Dict[str, str]] computed_properties: Sets The computed properties for this container in the Azure - Cosmos DB Service. For more Information on how to use computed properties visit + :keyword List[Dict[str, str]] computed_properties: **provisional** Sets The computed properties for this + container in the Azure Cosmos DB Service. For more Information on how to use computed properties visit `here: https://learn.microsoft.com/en-us/azure/cosmos-db/nosql/query/computed-properties?tabs=dotnet` :keyword response_hook: A callable invoked with the response metadata. :paramtype response_hook: Callable[[Dict[str, str], Dict[str, Any]], None] @@ -479,14 +479,14 @@ async def replace_container( :keyword match_condition: The match condition to use upon the etag. :paramtype match_condition: ~azure.core.MatchConditions :keyword dict[str, str] initial_headers: Initial headers to be sent as part of the request. - :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: Raised if the container couldn't be replaced. - This includes if the container with given id does not exist. :keyword int analytical_storage_ttl: Analytical store time to live (TTL) for items in the container. A value of None leaves analytical storage off and a value of -1 turns analytical storage on with no TTL. Please note that analytical storage can only be enabled on Synapse Link enabled accounts. + :keyword response_hook: A callable invoked with the response metadata. + :paramtype response_hook: Callable[[Dict[str, str], Dict[str, Any]], None] :returns: A `ContainerProxy` instance representing the container after replace completed. + :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: Raised if the container couldn't be replaced. + This includes if the container with given id does not exist. :rtype: ~azure.cosmos.aio.ContainerProxy .. admonition:: Example: diff --git a/sdk/cosmos/azure-cosmos/azure/cosmos/aio/_scripts.py b/sdk/cosmos/azure-cosmos/azure/cosmos/aio/_scripts.py index b25f7de53fdd..85a82c82f0d0 100644 --- a/sdk/cosmos/azure-cosmos/azure/cosmos/aio/_scripts.py +++ b/sdk/cosmos/azure-cosmos/azure/cosmos/aio/_scripts.py @@ -50,10 +50,10 @@ class ScriptsProxy: """ def __init__( - self, - container: "ContainerProxy", - client_connection: _CosmosClientConnection, - container_link: str + self, + container: "ContainerProxy", + client_connection: _CosmosClientConnection, + container_link: str ) -> None: self.client_connection = client_connection self.container_link = container_link diff --git a/sdk/cosmos/azure-cosmos/azure/cosmos/container.py b/sdk/cosmos/azure-cosmos/azure/cosmos/container.py index 74905ca33c46..da1c6e3ef6ce 100644 --- a/sdk/cosmos/azure-cosmos/azure/cosmos/container.py +++ b/sdk/cosmos/azure-cosmos/azure/cosmos/container.py @@ -22,10 +22,11 @@ """Create, read, update and delete items in the Azure Cosmos DB SQL API service. """ - -from typing import Any, Dict, List, Optional, Sequence, Union, Tuple, Mapping, Type, cast import warnings +from typing import Any, Dict, List, Optional, Sequence, Union, Tuple, Mapping, Type, cast +from typing_extensions import Literal +from azure.core import MatchConditions from azure.core.tracing.decorator import distributed_trace from azure.core.paging import ItemPaged @@ -133,6 +134,10 @@ def read( # pylint:disable=docstring-missing-param populate_query_metrics: Optional[bool] = None, populate_partition_key_range_statistics: Optional[bool] = None, populate_quota_info: Optional[bool] = None, + *, + session_token: Optional[str] = None, + priority_level: Optional[Literal["High", "Low"]] = None, + initial_headers: Optional[Dict[str, str]] = None, **kwargs: Any ) -> Dict[str, Any]: """Read the container properties. @@ -141,7 +146,7 @@ def read( # pylint:disable=docstring-missing-param range statistics in response headers. :param bool populate_quota_info: Enable returning collection storage quota information in response headers. :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 dict[str, str] initial_headers: Initial headers to be sent as part of the request. :keyword Literal["High", "Low"] priority_level: Priority based execution allows users to set a priority for each request. Once the user has reached their provisioned throughput, low priority requests are throttled before high priority requests start getting throttled. Feature must first be enabled at the account level. @@ -152,6 +157,12 @@ def read( # pylint:disable=docstring-missing-param :returns: Dict representing the retrieved container. :rtype: dict[str, Any] """ + if session_token is not None: + kwargs['session_token'] = session_token + if priority_level is not None: + kwargs['priority_level'] = priority_level + if initial_headers is not None: + kwargs['initial_headers'] = initial_headers request_options = build_options(kwargs) if populate_query_metrics: warnings.warn( @@ -172,9 +183,14 @@ def read( # pylint:disable=docstring-missing-param def read_item( # pylint:disable=docstring-missing-param self, item: Union[str, Mapping[str, Any]], - partition_key: Optional[PartitionKeyType], + partition_key: PartitionKeyType, populate_query_metrics: Optional[bool] = None, post_trigger_include: Optional[str] = None, + *, + session_token: Optional[str] = None, + initial_headers: Optional[Dict[str, str]] = None, + max_integrated_cache_staleness_in_ms: Optional[int] = None, + priority_level: Optional[Literal["High", "Low"]] = None, **kwargs: Any ) -> Dict[str, Any]: """Get the item identified by `item`. @@ -207,20 +223,23 @@ def read_item( # pylint:disable=docstring-missing-param :name: update_item """ doc_link = self._get_document_link(item) + if session_token is not None: + kwargs['session_token'] = session_token + if initial_headers is not None: + kwargs['initial_headers'] = initial_headers + if priority_level is not None: + kwargs['priority_level'] = priority_level request_options = build_options(kwargs) - if partition_key is not None: - request_options["partitionKey"] = self._set_partition_key(partition_key) + request_options["partitionKey"] = self._set_partition_key(partition_key) if populate_query_metrics is not None: warnings.warn( "the populate_query_metrics flag does not apply to this method and will be removed in the future", UserWarning, ) request_options["populateQueryMetrics"] = populate_query_metrics - if post_trigger_include is not None: request_options["postTriggerInclude"] = post_trigger_include - max_integrated_cache_staleness_in_ms = kwargs.pop('max_integrated_cache_staleness_in_ms', None) if max_integrated_cache_staleness_in_ms is not None: validate_cache_staleness_value(max_integrated_cache_staleness_in_ms) request_options["maxIntegratedCacheStaleness"] = max_integrated_cache_staleness_in_ms @@ -232,6 +251,11 @@ def read_all_items( # pylint:disable=docstring-missing-param self, max_item_count: Optional[int] = None, populate_query_metrics: Optional[bool] = None, + *, + session_token: Optional[str] = None, + initial_headers: Optional[Dict[str, str]] = None, + max_integrated_cache_staleness_in_ms: Optional[int] = None, + priority_level: Optional[Literal["High", "Low"]] = None, **kwargs: Any ) -> ItemPaged[Dict[str, Any]]: """List all the items in the container. @@ -249,6 +273,12 @@ def read_all_items( # pylint:disable=docstring-missing-param :returns: An Iterable of items (dicts). :rtype: Iterable[Dict[str, Any]] """ + if session_token is not None: + kwargs['session_token'] = session_token + if initial_headers is not None: + kwargs['initial_headers'] = initial_headers + if priority_level is not None: + kwargs['priority_level'] = priority_level feed_options = build_options(kwargs) response_hook = kwargs.pop('response_hook', None) if max_item_count is not None: @@ -259,7 +289,6 @@ def read_all_items( # pylint:disable=docstring-missing-param UserWarning, ) feed_options["populateQueryMetrics"] = populate_query_metrics - max_integrated_cache_staleness_in_ms = kwargs.pop('max_integrated_cache_staleness_in_ms', None) if max_integrated_cache_staleness_in_ms: validate_cache_staleness_value(max_integrated_cache_staleness_in_ms) feed_options["maxIntegratedCacheStaleness"] = max_integrated_cache_staleness_in_ms @@ -280,6 +309,9 @@ def query_items_change_feed( is_start_from_beginning: bool = False, continuation: Optional[str] = None, max_item_count: Optional[int] = None, + *, + partition_key: Optional[PartitionKeyType] = None, + priority_level: Optional[Literal["High", "Low"]] = None, **kwargs: Any ) -> ItemPaged[Dict[str, Any]]: """Get a sorted list of items that were changed, in the order in which they were modified. @@ -300,11 +332,12 @@ def query_items_change_feed( :returns: An Iterable of items (dicts). :rtype: Iterable[dict[str, Any]] """ + if priority_level is not None: + kwargs['priority_level'] = priority_level feed_options = build_options(kwargs) response_hook = kwargs.pop('response_hook', None) if partition_key_range_id is not None: feed_options["partitionKeyRangeId"] = partition_key_range_id - partition_key = kwargs.pop("partitionKey", kwargs.pop("partition_key", None)) if partition_key is not None: feed_options["partitionKey"] = self._set_partition_key(partition_key) if is_start_from_beginning is not None: @@ -334,6 +367,13 @@ def query_items( # pylint:disable=docstring-missing-param max_item_count: Optional[int] = None, enable_scan_in_query: Optional[bool] = None, populate_query_metrics: Optional[bool] = None, + *, + populate_index_metrics: Optional[bool] = None, + session_token: Optional[str] = None, + initial_headers: Optional[Dict[str, str]] = None, + max_integrated_cache_staleness_in_ms: Optional[int] = None, + priority_level: Optional[Literal["High", "Low"]] = None, + continuation_token_limit: Optional[int] = None, **kwargs: Any ) -> ItemPaged[Dict[str, Any]]: """Return all results matching the given `query`. @@ -360,9 +400,9 @@ def query_items( # pylint:disable=docstring-missing-param :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 Callable response_hook: A callable invoked with the response metadata. - :keyword int continuation_token_limit: **provisional** The size limit in kb of the - response continuation token in the query response. Valid values are positive integers. - A value of 0 is the same as not passing a value (default no limit). + :keyword int continuation_token_limit: The size limit in kb of the response continuation token in the query + response. Valid values are positive integers. + A value of 0 is the same as not passing a value (default no limit). :keyword int max_integrated_cache_staleness_in_ms: The max cache staleness for the integrated cache in milliseconds. For accounts configured to use the integrated cache, using Session or Eventual consistency, responses are guaranteed to be no staler than this value. @@ -393,6 +433,12 @@ def query_items( # pylint:disable=docstring-missing-param :caption: Parameterized query to get all products that have been discontinued: :name: query_items_param """ + if session_token is not None: + kwargs['session_token'] = session_token + if initial_headers is not None: + kwargs['initial_headers'] = initial_headers + if priority_level is not None: + kwargs['priority_level'] = priority_level feed_options = build_options(kwargs) response_hook = kwargs.pop('response_hook', None) if enable_cross_partition_query is not None: @@ -401,7 +447,6 @@ def query_items( # pylint:disable=docstring-missing-param feed_options["maxItemCount"] = max_item_count if populate_query_metrics is not None: feed_options["populateQueryMetrics"] = populate_query_metrics - populate_index_metrics = kwargs.pop("populate_index_metrics", None) if populate_index_metrics is not None: feed_options["populateIndexMetrics"] = populate_index_metrics if partition_key is not None: @@ -414,13 +459,11 @@ def query_items( # pylint:disable=docstring-missing-param feed_options["partitionKey"] = self._set_partition_key(partition_key) if enable_scan_in_query is not None: feed_options["enableScanInQuery"] = enable_scan_in_query - max_integrated_cache_staleness_in_ms = kwargs.pop('max_integrated_cache_staleness_in_ms', None) if max_integrated_cache_staleness_in_ms: validate_cache_staleness_value(max_integrated_cache_staleness_in_ms) feed_options["maxIntegratedCacheStaleness"] = max_integrated_cache_staleness_in_ms correlated_activity_id = GenerateGuidId() feed_options["correlatedActivityId"] = correlated_activity_id - continuation_token_limit = kwargs.pop("continuation_token_limit", None) if continuation_token_limit is not None: feed_options["responseContinuationTokenLimitInKb"] = continuation_token_limit if hasattr(response_hook, "clear"): @@ -458,6 +501,12 @@ def replace_item( # pylint:disable=docstring-missing-param populate_query_metrics: Optional[bool] = None, pre_trigger_include: Optional[str] = None, post_trigger_include: Optional[str] = None, + *, + session_token: Optional[str] = None, + initial_headers: Optional[Dict[str, str]] = None, + etag: Optional[str] = None, + match_condition: Optional[MatchConditions] = None, + priority_level: Optional[Literal["High", "Low"]] = None, **kwargs: Any ) -> Dict[str, Any]: """Replaces the specified item if it exists in the container. @@ -485,6 +534,20 @@ def replace_item( # pylint:disable=docstring-missing-param :rtype: Dict[str, Any] """ item_link = self._get_document_link(item) + if pre_trigger_include is not None: + kwargs['pre_trigger_include'] = pre_trigger_include + if post_trigger_include is not None: + kwargs['post_trigger_include'] = post_trigger_include + if session_token is not None: + kwargs['session_token'] = session_token + if initial_headers is not None: + kwargs['initial_headers'] = initial_headers + if priority_level is not None: + kwargs['priority_level'] = priority_level + if etag is not None: + kwargs['etag'] = etag + if match_condition is not None: + kwargs['match_condition'] = match_condition request_options = build_options(kwargs) request_options["disableAutomaticIdGeneration"] = True if populate_query_metrics is not None: @@ -493,10 +556,6 @@ def replace_item( # pylint:disable=docstring-missing-param UserWarning, ) request_options["populateQueryMetrics"] = populate_query_metrics - if pre_trigger_include is not None: - request_options["preTriggerInclude"] = pre_trigger_include - if post_trigger_include is not None: - request_options["postTriggerInclude"] = post_trigger_include return self.client_connection.ReplaceItem( document_link=item_link, new_document=body, options=request_options, **kwargs @@ -509,6 +568,12 @@ def upsert_item( # pylint:disable=docstring-missing-param populate_query_metrics: Optional[bool]=None, pre_trigger_include: Optional[str] = None, post_trigger_include: Optional[str] = None, + *, + session_token: Optional[str] = None, + initial_headers: Optional[Dict[str, str]] = None, + etag: Optional[str] = None, + match_condition: Optional[MatchConditions] = None, + priority_level: Optional[Literal["High", "Low"]] = None, **kwargs: Any ) -> Dict[str, Any]: """Insert or update the specified item. @@ -533,6 +598,20 @@ def upsert_item( # pylint:disable=docstring-missing-param :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: The given item could not be upserted. :rtype: Dict[str, Any] """ + if pre_trigger_include is not None: + kwargs['pre_trigger_include'] = pre_trigger_include + if post_trigger_include is not None: + kwargs['post_trigger_include'] = post_trigger_include + if session_token is not None: + kwargs['session_token'] = session_token + if initial_headers is not None: + kwargs['initial_headers'] = initial_headers + if priority_level is not None: + kwargs['priority_level'] = priority_level + if etag is not None: + kwargs['etag'] = etag + if match_condition is not None: + kwargs['match_condition'] = match_condition request_options = build_options(kwargs) request_options["disableAutomaticIdGeneration"] = True if populate_query_metrics is not None: @@ -541,10 +620,6 @@ def upsert_item( # pylint:disable=docstring-missing-param UserWarning, ) request_options["populateQueryMetrics"] = populate_query_metrics - if pre_trigger_include is not None: - request_options["preTriggerInclude"] = pre_trigger_include - if post_trigger_include is not None: - request_options["postTriggerInclude"] = post_trigger_include return self.client_connection.UpsertItem( database_or_container_link=self.container_link, @@ -561,6 +636,13 @@ def create_item( # pylint:disable=docstring-missing-param pre_trigger_include: Optional[str] = None, post_trigger_include: Optional[str] = None, indexing_directive: Optional[int] = None, + *, + enable_automatic_id_generation: bool = False, + session_token: Optional[str] = None, + initial_headers: Optional[Dict[str, str]] = None, + etag: Optional[str] = None, + match_condition: Optional[MatchConditions] = None, + priority_level: Optional[Literal["High", "Low"]] = None, **kwargs: Any ) -> Dict[str, Any]: """Create an item in the container. @@ -589,19 +671,28 @@ def create_item( # pylint:disable=docstring-missing-param :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: Item with the given ID already exists. :rtype: Dict[str, Any] """ + if pre_trigger_include is not None: + kwargs['pre_trigger_include'] = pre_trigger_include + if post_trigger_include is not None: + kwargs['post_trigger_include'] = post_trigger_include + if session_token is not None: + kwargs['session_token'] = session_token + if initial_headers is not None: + kwargs['initial_headers'] = initial_headers + if priority_level is not None: + kwargs['priority_level'] = priority_level + if etag is not None: + kwargs['etag'] = etag + if match_condition is not None: + kwargs['match_condition'] = match_condition request_options = build_options(kwargs) - - request_options["disableAutomaticIdGeneration"] = not kwargs.pop('enable_automatic_id_generation', False) + request_options["disableAutomaticIdGeneration"] = not enable_automatic_id_generation if populate_query_metrics: warnings.warn( "the populate_query_metrics flag does not apply to this method and will be removed in the future", UserWarning, ) request_options["populateQueryMetrics"] = populate_query_metrics - if pre_trigger_include is not None: - request_options["preTriggerInclude"] = pre_trigger_include - if post_trigger_include is not None: - request_options["postTriggerInclude"] = post_trigger_include if indexing_directive is not None: request_options["indexingDirective"] = indexing_directive @@ -614,6 +705,14 @@ def patch_item( item: Union[str, Dict[str, Any]], partition_key: PartitionKeyType, patch_operations: List[Dict[str, Any]], + *, + filter_predicate: Optional[str] = None, + pre_trigger_include: Optional[str] = None, + post_trigger_include: Optional[str] = None, + session_token: Optional[str] = None, + etag: Optional[str] = None, + match_condition: Optional[MatchConditions] = None, + priority_level: Optional[Literal["High", "Low"]] = None, **kwargs: Any ) -> Dict[str, Any]: """ Patches the specified item with the provided operations if it @@ -635,15 +734,29 @@ def patch_item( has changed, and act according to the condition specified by the `match_condition` parameter. :keyword ~azure.core.MatchConditions match_condition: The match condition to use upon the etag. :keyword Callable response_hook: A callable invoked with the response metadata. + :keyword Literal["High", "Low"] priority_level: Priority based execution allows users to set a priority for each + request. Once the user has reached their provisioned throughput, low priority requests are throttled + before high priority requests start getting throttled. Feature must first be enabled at the account level. :returns: A dict representing the item after the patch operations went through. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: The patch operations failed or the item with given id does not exist. :rtype: dict[str, Any] """ + if pre_trigger_include is not None: + kwargs['pre_trigger_include'] = pre_trigger_include + if post_trigger_include is not None: + kwargs['post_trigger_include'] = post_trigger_include + if session_token is not None: + kwargs['session_token'] = session_token + if priority_level is not None: + kwargs['priority_level'] = priority_level + if etag is not None: + kwargs['etag'] = etag + if match_condition is not None: + kwargs['match_condition'] = match_condition request_options = build_options(kwargs) request_options["disableAutomaticIdGeneration"] = True request_options["partitionKey"] = self._set_partition_key(partition_key) - filter_predicate = kwargs.pop("filter_predicate", None) if filter_predicate is not None: request_options["filterPredicate"] = filter_predicate @@ -656,6 +769,12 @@ def execute_item_batch( self, batch_operations: Sequence[Union[Tuple[str, Tuple[Any, ...]], Tuple[str, Tuple[Any, ...], Dict[str, Any]]]], partition_key: PartitionKeyType, + *, + pre_trigger_include: Optional[str] = None, + post_trigger_include: Optional[str] = None, + session_token: Optional[str] = None, + etag: Optional[str] = None, + match_condition: Optional[MatchConditions] = None, **kwargs: Any ) -> List[Dict[str, Any]]: """ Executes the transactional batch for the specified partition key. @@ -676,6 +795,16 @@ def execute_item_batch( :raises ~azure.cosmos.exceptions.CosmosBatchOperationError: A transactional batch operation failed in the batch. :rtype: List[Dict[str, Any]] """ + if pre_trigger_include is not None: + kwargs['pre_trigger_include'] = pre_trigger_include + if post_trigger_include is not None: + kwargs['post_trigger_include'] = post_trigger_include + if session_token is not None: + kwargs['session_token'] = session_token + if etag is not None: + kwargs['etag'] = etag + if match_condition is not None: + kwargs['match_condition'] = match_condition request_options = build_options(kwargs) request_options["partitionKey"] = self._set_partition_key(partition_key) request_options["disableAutomaticIdGeneration"] = True @@ -691,6 +820,11 @@ def delete_item( # pylint:disable=docstring-missing-param populate_query_metrics: Optional[bool] = None, pre_trigger_include: Optional[str] = None, post_trigger_include: Optional[str] = None, + *, + session_token: Optional[str] = None, + initial_headers: Optional[Dict[str, str]] = None, + etag: Optional[str] = None, + match_condition: Optional[MatchConditions] = None, **kwargs: Any ) -> None: """Delete the specified item from the container. @@ -713,6 +847,14 @@ def delete_item( # pylint:disable=docstring-missing-param :raises ~azure.cosmos.exceptions.CosmosResourceNotFoundError: The item does not exist in the container. :rtype: None """ + if session_token is not None: + kwargs['session_token'] = session_token + if initial_headers is not None: + kwargs['initial_headers'] = initial_headers + if etag is not None: + kwargs['etag'] = etag + if match_condition is not None: + kwargs['match_condition'] = match_condition request_options = build_options(kwargs) if partition_key is not None: request_options["partitionKey"] = self._set_partition_key(partition_key) @@ -940,6 +1082,12 @@ def delete_conflict( def delete_all_items_by_partition_key( self, partition_key: PartitionKeyType, + *, + pre_trigger_include: Optional[str] = None, + post_trigger_include: Optional[str] = None, + session_token: Optional[str] = None, + etag: Optional[str] = None, + match_condition: Optional[MatchConditions] = None, **kwargs: Any ) -> None: """The delete by partition key feature is an asynchronous, background operation that allows you to delete all @@ -959,6 +1107,16 @@ def delete_all_items_by_partition_key( :keyword Callable response_hook: A callable invoked with the response metadata. :rtype: None """ + if pre_trigger_include is not None: + kwargs['pre_trigger_include'] = pre_trigger_include + if post_trigger_include is not None: + kwargs['post_trigger_include'] = post_trigger_include + if session_token is not None: + kwargs['session_token'] = session_token + if etag is not None: + kwargs['etag'] = etag + if match_condition is not None: + kwargs['match_condition'] = match_condition request_options = build_options(kwargs) # regardless if partition key is valid we set it as invalid partition keys are set to a default empty value request_options["partitionKey"] = self._set_partition_key(partition_key) diff --git a/sdk/cosmos/azure-cosmos/azure/cosmos/cosmos_client.py b/sdk/cosmos/azure-cosmos/azure/cosmos/cosmos_client.py index 209e9882a47e..5f14c9fda3f8 100644 --- a/sdk/cosmos/azure-cosmos/azure/cosmos/cosmos_client.py +++ b/sdk/cosmos/azure-cosmos/azure/cosmos/cosmos_client.py @@ -25,6 +25,7 @@ from typing import Any, Dict, Iterable, List, Mapping, Optional, Union, cast import warnings +from azure.core import MatchConditions from azure.core.tracing.decorator import distributed_trace from azure.core.paging import ItemPaged from azure.core.credentials import TokenCredential @@ -250,6 +251,11 @@ def create_database( # pylint:disable=docstring-missing-param id: str, populate_query_metrics: Optional[bool] = None, 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: """ @@ -277,8 +283,16 @@ def create_database( # pylint:disable=docstring-missing-param :caption: Create a database in the Cosmos DB account: :name: create_database """ - request_options = build_options(kwargs) response_hook = kwargs.pop('response_hook', None) + if session_token is not None: + kwargs["session_token"] = session_token + if initial_headers is not None: + kwargs["initial_headers"] = initial_headers + if etag is not None: + kwargs["etag"] = etag + if match_condition is not None: + kwargs["match_condition"] = match_condition + request_options = build_options(kwargs) if populate_query_metrics is not None: warnings.warn( "the populate_query_metrics flag does not apply to this method and will be removed in the future", @@ -298,6 +312,11 @@ def create_database_if_not_exists( # pylint:disable=docstring-missing-param id: str, populate_query_metrics: Optional[bool] = None, 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: """ @@ -321,6 +340,14 @@ def create_database_if_not_exists( # pylint:disable=docstring-missing-param :rtype: ~azure.cosmos.DatabaseProxy :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: The database read or creation failed. """ + if session_token is not None: + kwargs["session_token"] = session_token + if initial_headers is not None: + kwargs["initial_headers"] = initial_headers + if etag is not None: + kwargs["etag"] = etag + if match_condition is not None: + kwargs["match_condition"] = match_condition try: database_proxy = self.get_database_client(id) database_proxy.read( @@ -358,6 +385,9 @@ def list_databases( # pylint:disable=docstring-missing-param self, max_item_count: Optional[int] = None, populate_query_metrics: Optional[bool] = None, + *, + session_token: Optional[str] = None, + initial_headers: Optional[Dict[str, str]] = None, **kwargs: Any ) -> ItemPaged[Dict[str, Any]]: """List the databases in a Cosmos DB SQL database account. @@ -369,8 +399,12 @@ def list_databases( # pylint:disable=docstring-missing-param :returns: An Iterable of database properties (dicts). :rtype: Iterable[Dict[str, str]] """ - feed_options = build_options(kwargs) response_hook = kwargs.pop('response_hook', None) + if session_token is not None: + kwargs["session_token"] = session_token + if initial_headers is not None: + kwargs["initial_headers"] = initial_headers + feed_options = build_options(kwargs) if max_item_count is not None: feed_options["maxItemCount"] = max_item_count if populate_query_metrics is not None: @@ -393,6 +427,9 @@ def query_databases( # pylint:disable=docstring-missing-param enable_cross_partition_query: Optional[bool] = None, max_item_count: Optional[int] = None, populate_query_metrics: Optional[bool] = None, + *, + session_token: Optional[str] = None, + initial_headers: Optional[Dict[str, str]] = None, **kwargs: Any ) -> ItemPaged[Dict[str, Any]]: """Query the databases in a Cosmos DB SQL database account. @@ -409,8 +446,12 @@ def query_databases( # pylint:disable=docstring-missing-param :returns: An Iterable of database properties (dicts). :rtype: Iterable[Dict[str, str]] """ - feed_options = build_options(kwargs) response_hook = kwargs.pop('response_hook', None) + if session_token is not None: + kwargs["session_token"] = session_token + if initial_headers is not None: + kwargs["initial_headers"] = initial_headers + feed_options = build_options(kwargs) if enable_cross_partition_query is not None: feed_options["enableCrossPartitionQuery"] = enable_cross_partition_query if max_item_count is not None: @@ -444,6 +485,11 @@ def delete_database( # pylint:disable=docstring-missing-param self, database: Union[str, DatabaseProxy, Mapping[str, Any]], populate_query_metrics: Optional[bool] = None, + *, + session_token: Optional[str] = None, + initial_headers: Optional[Dict[str, str]] = None, + etag: Optional[str] = None, + match_condition: Optional[MatchConditions] = None, **kwargs: Any ) -> None: """Delete the database with the given ID (name). @@ -460,8 +506,16 @@ def delete_database( # pylint:disable=docstring-missing-param :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: If the database couldn't be deleted. :rtype: None """ - request_options = build_options(kwargs) response_hook = kwargs.pop('response_hook', None) + if session_token is not None: + kwargs["session_token"] = session_token + if initial_headers is not None: + kwargs["initial_headers"] = initial_headers + if etag is not None: + kwargs["etag"] = etag + if match_condition is not None: + kwargs["match_condition"] = match_condition + request_options = build_options(kwargs) if populate_query_metrics is not None: warnings.warn( "the populate_query_metrics flag does not apply to this method and will be removed in the future", diff --git a/sdk/cosmos/azure-cosmos/azure/cosmos/database.py b/sdk/cosmos/azure-cosmos/azure/cosmos/database.py index ccae48cd3f17..b923864aa20f 100644 --- a/sdk/cosmos/azure-cosmos/azure/cosmos/database.py +++ b/sdk/cosmos/azure-cosmos/azure/cosmos/database.py @@ -25,6 +25,7 @@ from typing import Any, Dict, List, Union, Optional, Mapping import warnings +from azure.core import MatchConditions from azure.core.tracing.decorator import distributed_trace from azure.core.paging import ItemPaged from azure.cosmos.partition_key import PartitionKey @@ -123,6 +124,9 @@ def _get_properties(self) -> Dict[str, Any]: def read( # pylint:disable=docstring-missing-param self, populate_query_metrics: Optional[bool] = None, + *, + session_token: Optional[str] = None, + initial_headers: Optional[Dict[str, str]] = None, **kwargs: Any ) -> Dict[str, Any]: """Read the database properties. @@ -135,6 +139,10 @@ def read( # pylint:disable=docstring-missing-param :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: If the given database couldn't be retrieved. """ database_link = _get_database_link(self) + if session_token is not None: + kwargs['session_token'] = session_token + if initial_headers is not None: + kwargs['initial_headers'] = initial_headers request_options = build_options(kwargs) if populate_query_metrics is not None: warnings.warn( @@ -159,6 +167,12 @@ def create_container( # pylint:disable=docstring-missing-param offer_throughput: Optional[Union[int, ThroughputProperties]] = None, unique_key_policy: Optional[Dict[str, Any]] = None, conflict_resolution_policy: Optional[Dict[str, Any]] = None, + *, + session_token: Optional[str] = None, + initial_headers: Optional[Dict[str, str]] = None, + etag: Optional[str] = None, + match_condition: Optional[MatchConditions] = None, + analytical_storage_ttl: Optional[int] = None, **kwargs: Any ) -> ContainerProxy: """Create a new container with the given ID (name). @@ -182,8 +196,8 @@ def create_container( # pylint:disable=docstring-missing-param :keyword int analytical_storage_ttl: Analytical store time to live (TTL) for items in the container. A value of None leaves analytical storage off and a value of -1 turns analytical storage on with no TTL. Please note that analytical storage can only be enabled on Synapse Link enabled accounts. - :keyword List[Dict[str, str]] computed_properties: Sets The computed properties for this container in the Azure - Cosmos DB Service. For more Information on how to use computed properties visit + :keyword List[Dict[str, str]] computed_properties: **provisional** Sets The computed properties for this + container in the Azure Cosmos DB Service. For more Information on how to use computed properties visit `here: https://learn.microsoft.com/en-us/azure/cosmos-db/nosql/query/computed-properties?tabs=dotnet` :returns: A `ContainerProxy` instance representing the new container. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: The container creation failed. @@ -222,12 +236,20 @@ def create_container( # pylint:disable=docstring-missing-param definition["uniqueKeyPolicy"] = unique_key_policy if conflict_resolution_policy is not None: definition["conflictResolutionPolicy"] = conflict_resolution_policy - analytical_storage_ttl = kwargs.pop("analytical_storage_ttl", None) if analytical_storage_ttl is not None: definition["analyticalStorageTtl"] = analytical_storage_ttl computed_properties = kwargs.pop('computed_properties', None) if computed_properties: definition["computedProperties"] = computed_properties + + if session_token is not None: + kwargs['session_token'] = session_token + if initial_headers is not None: + kwargs['initial_headers'] = initial_headers + if etag is not None: + kwargs['etag'] = etag + if match_condition is not None: + kwargs['match_condition'] = match_condition request_options = build_options(kwargs) if populate_query_metrics is not None: warnings.warn( @@ -278,8 +300,8 @@ def create_container_if_not_exists( # pylint:disable=docstring-missing-param :keyword int analytical_storage_ttl: Analytical store time to live (TTL) for items in the container. A value of None leaves analytical storage off and a value of -1 turns analytical storage on with no TTL. Please note that analytical storage can only be enabled on Synapse Link enabled accounts. - :keyword List[Dict[str, str]] computed_properties: Sets The computed properties for this container in the Azure - Cosmos DB Service. For more Information on how to use computed properties visit + :keyword List[Dict[str, str]] computed_properties: **provisional** Sets The computed properties for this + container in the Azure Cosmos DB Service. For more Information on how to use computed properties visit `here: https://learn.microsoft.com/en-us/azure/cosmos-db/nosql/query/computed-properties?tabs=dotnet` :returns: A `ContainerProxy` instance representing the container. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: The container read or creation failed. @@ -313,6 +335,11 @@ def delete_container( # pylint:disable=docstring-missing-param self, container: Union[str, ContainerProxy, Mapping[str, Any]], populate_query_metrics: Optional[bool] = None, + *, + session_token: Optional[str] = None, + initial_headers: Optional[Dict[str, str]] = None, + etag: Optional[str] = None, + match_condition: Optional[MatchConditions] = None, **kwargs: Any ) -> None: """Delete a container. @@ -330,6 +357,14 @@ def delete_container( # pylint:disable=docstring-missing-param :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: If the container couldn't be deleted. :rtype: None """ + if session_token is not None: + kwargs['session_token'] = session_token + if initial_headers is not None: + kwargs['initial_headers'] = initial_headers + if etag is not None: + kwargs['etag'] = etag + if match_condition is not None: + kwargs['match_condition'] = match_condition request_options = build_options(kwargs) if populate_query_metrics is not None: warnings.warn( @@ -373,6 +408,9 @@ def list_containers( # pylint:disable=docstring-missing-param self, max_item_count: Optional[int] = None, populate_query_metrics: Optional[bool] = None, + *, + session_token: Optional[str] = None, + initial_headers: Optional[Dict[str, str]] = None, **kwargs: Any ) -> ItemPaged[Dict[str, Any]]: """List the containers in the database. @@ -394,6 +432,10 @@ def list_containers( # pylint:disable=docstring-missing-param :caption: List all containers in the database: :name: list_containers """ + if session_token is not None: + kwargs['session_token'] = session_token + if initial_headers is not None: + kwargs['initial_headers'] = initial_headers feed_options = build_options(kwargs) response_hook = kwargs.pop('response_hook', None) if max_item_count is not None: @@ -419,6 +461,9 @@ def query_containers( # pylint:disable=docstring-missing-param parameters: Optional[List[Dict[str, Any]]] = None, max_item_count: Optional[int] = None, populate_query_metrics: Optional[bool] = None, + *, + session_token: Optional[str] = None, + initial_headers: Optional[Dict[str, str]] = None, **kwargs: Any ) -> ItemPaged[Dict[str, Any]]: """List the properties for containers in the current database. @@ -433,6 +478,10 @@ def query_containers( # pylint:disable=docstring-missing-param :returns: An Iterable of container properties (dicts). :rtype: Iterable[Dict[str, Any]] """ + if session_token is not None: + kwargs['session_token'] = session_token + if initial_headers is not None: + kwargs['initial_headers'] = initial_headers feed_options = build_options(kwargs) response_hook = kwargs.pop('response_hook', None) if max_item_count is not None: @@ -463,6 +512,12 @@ def replace_container( # pylint:disable=docstring-missing-param default_ttl: Optional[int] = None, conflict_resolution_policy: Optional[Dict[str, Any]] = None, populate_query_metrics: Optional[bool] = None, + *, + session_token: Optional[str] = None, + initial_headers: Optional[Dict[str, str]] = None, + etag: Optional[str] = None, + match_condition: Optional[MatchConditions] = None, + analytical_storage_ttl: Optional[int] = None, **kwargs: Any ) -> ContainerProxy: """Reset the properties of the container. @@ -483,13 +538,13 @@ def replace_container( # pylint:disable=docstring-missing-param has changed, and act according to the condition specified by the `match_condition` parameter. :keyword ~azure.core.MatchConditions match_condition: The match condition to use upon the etag. :keyword Dict[str, str] initial_headers: Initial headers to be sent as part of the request. - :keyword Callable response_hook: A callable invoked with the response metadata. - :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: Raised if the container couldn't be replaced. - This includes if the container with given id does not exist. :keyword int analytical_storage_ttl: Analytical store time to live (TTL) for items in the container. A value of None leaves analytical storage off and a value of -1 turns analytical storage on with no TTL. Please note that analytical storage can only be enabled on Synapse Link enabled accounts. + :keyword Callable response_hook: A callable invoked with the response metadata. :returns: A `ContainerProxy` instance representing the container after replace completed. + :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: Raised if the container couldn't be replaced. + This includes if the container with given id does not exist. :rtype: ~azure.cosmos.ContainerProxy .. admonition:: Example: @@ -501,8 +556,15 @@ def replace_container( # pylint:disable=docstring-missing-param :caption: Reset the TTL property on a container, and display the updated properties: :name: reset_container_properties """ + if session_token is not None: + kwargs['session_token'] = session_token + if initial_headers is not None: + kwargs['initial_headers'] = initial_headers + if etag is not None: + kwargs['etag'] = etag + if match_condition is not None: + kwargs['match_condition'] = match_condition request_options = build_options(kwargs) - analytical_storage_ttl = kwargs.pop("analytical_storage_ttl", None) if populate_query_metrics is not None: warnings.warn( "the populate_query_metrics flag does not apply to this method and will be removed in the future",