Fix: Allow tuples to be used for hierarchical partition key values. (Azure#38136)

* Fix support for allowing tuples to be used for subapartition

Allows the usage of tuples alongside lists to be used for hierarchical partition key values. Both get serialized to json arrays. Previous behaviour would give an error that a prefix query was attempted which is incorrect behaviour.

* update docstrings

* Update CHANGELOG.md

* Update partition_key.py

* Update partition_key.py

optimization

* Update partition_key.py

* Update partition_key.py

* Update partition_key.py

* Update type hint of partition key

Changes the type hint of partition key to be sequence instead of explicitly tuple and list.

* update version

update version to 4.8.0

Author: bambriz

sdk/cosmos/azure-cosmos/CHANGELOG.md

@@ -1,6 +1,6 @@
 ## Release History
 
-### 4.7.1 (Unreleased)
+### 4.8.0 (2024-11-12)
 This version and all future versions will support Python 3.13.
 
 #### Features Added
@@ -24,6 +24,7 @@ For more information on this, see our README section [here](https://github.com/A
 * Added retry handling logic for DatabaseAccountNotFound exceptions. See [PR 36514](https://github.com/Azure/azure-sdk-for-python/pull/36514).
 * Fixed SDK regex validation that would not allow for item ids to be longer than 255 characters. See [PR 36569](https://github.com/Azure/azure-sdk-for-python/pull/36569).
 * Fixed issue where 'NoneType' object has no attribute error was raised when a session retry happened during a query. See [PR 37578](https://github.com/Azure/azure-sdk-for-python/pull/37578).
+* Fixed issue where passing subpartition partition key values as a tuple in a query would raise an error. See [PR 38136](https://github.com/Azure/azure-sdk-for-python/pull/38136)
 * Batch requests will now be properly considered as Write operation. See [PR 38365](https://github.com/Azure/azure-sdk-for-python/pull/38365).
 
 #### Other Changes

sdk/cosmos/azure-cosmos/azure/cosmos/_base.py

@@ -227,8 +227,11 @@ def GetHeaders(  # pylint: disable=too-many-statements,too-many-branches
         # else serialize using json dumps method which apart from regular values will serialize None into null
         else:
             # single partitioning uses a string and needs to be turned into a list
-            if isinstance(options["partitionKey"], list) and options["partitionKey"]:
-                pk_val = json.dumps(options["partitionKey"], separators=(',', ':'))
+            is_sequence_not_string = (isinstance(options["partitionKey"], Sequence) and
+                                      not isinstance(options["partitionKey"], str))
+
+            if is_sequence_not_string and options["partitionKey"]:
+                pk_val = json.dumps(list(options["partitionKey"]), separators=(',', ':'))
             else:
                 pk_val = json.dumps([options["partitionKey"]])
             headers[http_constants.HttpHeaders.PartitionKey] = pk_val

sdk/cosmos/azure-cosmos/azure/cosmos/_version.py

@@ -19,4 +19,4 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
-VERSION = "4.7.1"
+VERSION = "4.8.0"

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

@@ -283,7 +283,7 @@ async def read_item(
         :param item: The ID (name) or dict representing item to retrieve.
         :type item: Union[str, Dict[str, Any]]
         :param partition_key: Partition key for the item to retrieve.
-        :type partition_key: Union[str, int, float, bool, List[Union[str, int, float, bool]]]
+        :type partition_key: Union[str, int, float, bool, Sequence[Union[str, int, float, bool, None]]]
         :keyword str post_trigger_include: trigger id to be used as post operation trigger.
         :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.
@@ -413,7 +413,7 @@ def query_items(
         :paramtype parameters: List[Dict[str, Any]]
         :keyword partition_key: Specifies the partition key value for the item. If none is provided,
             a cross-partition query will be executed.
-        :paramtype partition_key: Union[str, int, float, bool, List[Union[str, int, float, bool]]]
+        :paramtype partition_key: Union[str, int, float, bool, Sequence[Union[str, int, float, bool, None]]]
         :keyword int max_item_count: Max number of items to be returned in the enumeration operation.
         :keyword bool enable_scan_in_query: Allow scan on the queries which couldn't be served as
             indexing was opted out on the requested paths.
@@ -521,7 +521,7 @@ def query_items_change_feed(
         :type start_time: Union[~datetime.datetime, Literal["Now", "Beginning"]]
         :keyword partition_key: The partition key that is used to define the scope
             (logical partition or a subset of a container)
-        :type partition_key: Union[str, int, float, bool, List[Union[str, int, float, bool]]]
+        :type partition_key: Union[str, int, float, bool, Sequence[Union[str, int, float, bool, None]]]
         :keyword Literal["High", "Low"] priority: 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.
@@ -623,7 +623,7 @@ def query_items_change_feed( # pylint: disable=unused-argument
         :keyword Dict[str, Any] feed_range: The feed range that is used to define the scope.
         :keyword partition_key: The partition key that is used to define the scope
             (logical partition or a subset of a container)
-        :type partition_key: Union[str, int, float, bool, List[Union[str, int, float, bool]]]
+        :type partition_key: Union[str, int, float, bool, Sequence[Union[str, int, float, bool, None]]]
         :keyword int max_item_count: Max number of items to be returned in the enumeration operation.
         :keyword start_time: The start time to start processing chang feed items.
             Beginning: Processing the change feed items from the beginning of the change feed.
@@ -877,7 +877,7 @@ async def patch_item(
         :param item: The ID (name) or dict representing item to be patched.
         :type item: Union[str, Dict[str, Any]]
         :param partition_key: The partition key of the object to patch.
-        :type partition_key: Union[str, int, float, bool, List[Union[str, int, float, bool]]]
+        :type partition_key: Union[str, int, float, bool, Sequence[Union[str, int, float, bool, None]]]
         :param patch_operations: The list of patch operations to apply to the item.
         :type patch_operations: List[Dict[str, Any]]
         :keyword str filter_predicate: conditional filter to apply to Patch operations.
@@ -949,7 +949,7 @@ async def delete_item(
         :param item: The ID (name) or dict representing item to be deleted.
         :type item: Union[str, Dict[str, Any]]
         :param partition_key: Specifies the partition key value for the item.
-        :type partition_key: Union[str, int, float, bool]
+        :type partition_key: Union[str, int, float, bool, Sequence[Union[str, int, float, bool, None]]]
         :keyword str pre_trigger_include: trigger id to be used as pre operation trigger.
         :keyword str post_trigger_include: trigger id to be used as post operation trigger.
         :keyword str session_token: Token for use with Session consistency.
@@ -1102,7 +1102,7 @@ def query_conflicts(
         :paramtype parameters: List[Dict[str, Any]]
         :keyword partition_key: Specifies the partition key value for the item. If none is passed in, a
             cross partition query will be executed.
-        :paramtype partition_key: Union[str, int, float, bool, List[Union[str, int, float, bool]]]
+        :paramtype partition_key: Union[str, int, float, bool, Sequence[Union[str, int, float, bool, None]]]
         :keyword int max_item_count: Max number of items to be returned in the enumeration operation.
         :keyword response_hook: A callable invoked with the response metadata.
         :paramtype response_hook: Callable[[Dict[str, str], AsyncItemPaged[Dict[str, Any]]], None]
@@ -1142,7 +1142,7 @@ async def get_conflict(
         :param conflict: The ID (name) or dict representing the conflict to retrieve.
         :type conflict: Union[str, Dict[str, Any]]
         :param partition_key: Partition key for the conflict to retrieve.
-        :type partition_key: Union[str, int, float, bool]
+        :type partition_key: Union[str, int, float, bool, Sequence[Union[str, int, float, bool, None]]]
         :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 given conflict couldn't be retrieved.
@@ -1172,7 +1172,7 @@ async def delete_conflict(
         :param conflict: The ID (name) or dict representing the conflict to retrieve.
         :type conflict: Union[str, Dict[str, Any]]
         :param partition_key: Partition key for the conflict to retrieve.
-        :type partition_key: Union[str, int, float, bool, List[Union[str, int, float, bool]]]
+        :type partition_key: Union[str, int, float, bool, Sequence[Union[str, int, float, bool, None]]]
         :keyword response_hook: A callable invoked with the response metadata.
         :paramtype response_hook: Callable[[Dict[str, str], None], None]
         :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: The conflict wasn't deleted successfully.
@@ -1205,7 +1205,7 @@ async def delete_all_items_by_partition_key(
         this background task.
 
         :param partition_key: Partition key for the items to be deleted.
-        :type partition_key: Any
+        :type partition_key: Union[str, int, float, bool, Sequence[Union[str, int, float, bool, None]]]
         :keyword str pre_trigger_include: trigger id to be used as pre operation trigger.
         :keyword str post_trigger_include: trigger id to be used as post operation trigger.
         :keyword str session_token: Token for use with Session consistency.
@@ -1253,7 +1253,7 @@ async def execute_item_batch(
         :param batch_operations: The batch of operations to be executed.
         :type batch_operations: List[Tuple[Any]]
         :param partition_key: The partition key value of the batch operations.
-        :type partition_key: Union[str, int, float, bool, List[Union[str, int, float, bool]]]
+        :type partition_key: Union[str, int, float, bool, Sequence[Union[str, int, float, bool, None]]]
         :keyword str pre_trigger_include: trigger id to be used as pre operation trigger.
         :keyword str post_trigger_include: trigger id to be used as post operation trigger.
         :keyword str session_token: Token for use with Session consistency.

sdk/cosmos/azure-cosmos/azure/cosmos/container.py

@@ -212,7 +212,7 @@ def read_item(  # pylint:disable=docstring-missing-param
         :param item: The ID (name) or dict representing item to retrieve.
         :type item: Union[str, Dict[str, Any]]
         :param partition_key: Partition key for the item to retrieve.
-        :type partition_key: Union[str, int, float, bool, List[Union[str, int, float, bool]]]
+        :type partition_key: Union[str, int, float, bool, Sequence[Union[str, int, float, bool, None]]]
         :param str post_trigger_include: trigger id to be used as post operation trigger.
         :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.
@@ -341,7 +341,7 @@ def query_items_change_feed(
         :type start_time: Union[~datetime.datetime, Literal["Now", "Beginning"]]
         :keyword partition_key: The partition key that is used to define the scope
             (logical partition or a subset of a container)
-        :type partition_key: Union[str, int, float, bool, List[Union[str, int, float, bool]]]
+        :type partition_key: Union[str, int, float, bool, Sequence[Union[str, int, float, bool, None]]]
         :keyword Literal["High", "Low"] priority: 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.
@@ -444,7 +444,7 @@ def query_items_change_feed(
         :keyword Dict[str, Any] feed_range: The feed range that is used to define the scope.
         :keyword partition_key: The partition key that is used to define the scope
             (logical partition or a subset of a container)
-        :type partition_key: Union[str, int, float, bool, List[Union[str, int, float, bool]]]
+        :type partition_key: Union[str, int, float, bool, Sequence[Union[str, int, float, bool, None]]]
         :keyword int max_item_count: Max number of items to be returned in the enumeration operation.
         :keyword start_time: The start time to start processing chang feed items.
             Beginning: Processing the change feed items from the beginning of the change feed.
@@ -576,7 +576,7 @@ def query_items(  # pylint:disable=docstring-missing-param
             Ignored if no query is provided.
         :type parameters: [List[Dict[str, object]]]
         :param partition_key: partition key at which the query request is targeted.
-        :type partition_key: Union[str, int, float, bool, List[Union[str, int, float, bool]]]
+        :type partition_key: Union[str, int, float, bool, Sequence[Union[str, int, float, bool, None]]]
         :param bool enable_cross_partition_query: Allows sending of more than one request to
             execute the query in the Azure Cosmos DB service.
             More than one request is necessary if the query is not scoped to single partition key value.
@@ -933,7 +933,7 @@ def patch_item(
         :param item: The ID (name) or dict representing item to be patched.
         :type item: Union[str, Dict[str, Any]]
         :param partition_key: The partition key of the object to patch.
-        :type partition_key: Union[str, int, float, bool, List[Union[str, int, float, bool]]]
+        :type partition_key: Union[str, int, float, bool, Sequence[Union[str, int, float, bool, None]]]
         :param patch_operations: The list of patch operations to apply to the item.
         :type patch_operations: List[Dict[str, Any]]
         :keyword str filter_predicate: conditional filter to apply to Patch operations.
@@ -1002,7 +1002,7 @@ def execute_item_batch(
         :param batch_operations: The batch of operations to be executed.
         :type batch_operations: List[Tuple[Any]]
         :param partition_key: The partition key value of the batch operations.
-        :type partition_key: Union[str, int, float, bool, List[Union[str, int, float, bool]]]
+        :type partition_key: Union[str, int, float, bool, Sequence[Union[str, int, float, bool, None]]]
         :keyword str pre_trigger_include: trigger id to be used as pre operation trigger.
         :keyword str post_trigger_include: trigger id to be used as post operation trigger.
         :keyword str session_token: Token for use with Session consistency.
@@ -1060,7 +1060,7 @@ def delete_item(  # pylint:disable=docstring-missing-param
         :param item: The ID (name) or dict representing item to be deleted.
         :type item: Union[str, Dict[str, Any]]
         :param partition_key: Specifies the partition key value for the item.
-        :type partition_key: Union[str, int, float, bool, List[Union[str, int, float, bool]]]
+        :type partition_key: Union[str, int, float, bool, Sequence[Union[str, int, float, bool, None]]]
         :param str pre_trigger_include: trigger id to be used as pre operation trigger.
         :param str post_trigger_include: trigger id to be used as post operation trigger.
         :keyword str session_token: Token for use with Session consistency.
@@ -1229,7 +1229,7 @@ def query_conflicts(
             the query in the Azure Cosmos DB service.
             More than one request is necessary if the query is not scoped to single partition key value.
         :param partition_key: Specifies the partition key value for the item.
-        :type partition_key: Union[str, int, float, bool, List[Union[str, int, float, bool]]]
+        :type partition_key: Union[str, int, float, bool, Sequence[Union[str, int, float, bool, None]]]
         :param int max_item_count: Max number of items to be returned in the enumeration operation.
         :keyword Callable response_hook: A callable invoked with the response metadata.
         :returns: An Iterable of conflicts (dicts).
@@ -1268,7 +1268,7 @@ def get_conflict(
         :param conflict: The ID (name) or dict representing the conflict to retrieve.
         :type conflict: Union[str, Dict[str, Any]]
         :param partition_key: Partition key for the conflict to retrieve.
-        :type partition_key: Union[str, int, float, bool, List[Union[str, int, float, bool]]]
+        :type partition_key: Union[str, int, float, bool, Sequence[Union[str, int, float, bool, None]]]
         :keyword Callable response_hook: A callable invoked with the response metadata.
         :returns: A dict representing the retrieved conflict.
         :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: The given conflict couldn't be retrieved.
@@ -1298,7 +1298,7 @@ def delete_conflict(
         :param conflict: The ID (name) or dict representing the conflict to be deleted.
         :type conflict: Union[str, Dict[str, Any]]
         :param partition_key: Partition key for the conflict to delete.
-        :type partition_key: Union[str, int, float, bool, List[Union[str, int, float, bool]]]
+        :type partition_key: Union[str, int, float, bool, Sequence[Union[str, int, float, bool, None]]]
         :keyword Callable response_hook: A callable invoked with the response metadata.
         :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: The conflict wasn't deleted successfully.
         :raises ~azure.cosmos.exceptions.CosmosResourceNotFoundError: The conflict does not exist in the container.
@@ -1333,7 +1333,7 @@ def delete_all_items_by_partition_key(
         this background task.
 
         :param partition_key: Partition key for the items to be deleted.
-        :type partition_key: Union[str, int, float, bool, List[Union[str, int, float, bool]]]
+        :type partition_key: Union[str, int, float, bool, Sequence[Union[str, int, float, bool, None]]]
         :keyword str pre_trigger_include: trigger id to be used as pre operation trigger.
         :keyword str post_trigger_include: trigger id to be used as post operation trigger.
         :keyword str session_token: Token for use with Session consistency.

sdk/cosmos/azure-cosmos/azure/cosmos/partition_key.py

@@ -281,12 +281,12 @@ def _get_effective_partition_key_for_multi_hash_partitioning_v2(
 
     def _is_prefix_partition_key(
             self,
-            partition_key: Union[str, int, float, bool, Sequence[Union[str, int, float, bool, None]], Type[NonePartitionKeyValue]]) -> bool: # pylint: disable=line-too-long
-        if self.kind!= "MultiHash":
-            return False
-        if isinstance(partition_key, list) and len(self['paths']) == len(partition_key):
+            partition_key: Union[str, int, float, bool, Sequence[Union[str, int, float, bool, None]], Type[NonePartitionKeyValue]]) -> bool:  # pylint: disable=line-too-long
+        if self.kind != "MultiHash":
             return False
-        return True
+        ret = ((isinstance(partition_key, Sequence) and
+                not isinstance(partition_key, str)) and len(self['paths']) != len(partition_key))
+        return ret
 
 
 def _return_undefined_or_empty_partition_key(is_system_key: bool) -> Union[_Empty, _Undefined]: