expose feedRange as a class type

Author: annie-mac

sdk/cosmos/azure-cosmos/azure/cosmos/__init__.py

@@ -42,6 +42,7 @@
 )
 from .partition_key import PartitionKey
 from .permission import Permission
+from ._feed_range import FeedRange
 
 __all__ = (
     "CosmosClient",
@@ -64,5 +65,6 @@
     "TriggerType",
     "ConnectionRetryPolicy",
     "ThroughputProperties",
+    "FeedRange"
 )
 __version__ = VERSION

sdk/cosmos/azure-cosmos/azure/cosmos/_change_feed/change_feed_state.py

@@ -34,7 +34,7 @@
 from azure.cosmos._change_feed.change_feed_start_from import ChangeFeedStartFromInternal, \
     ChangeFeedStartFromETagAndFeedRange
 from azure.cosmos._change_feed.composite_continuation_token import CompositeContinuationToken
-from azure.cosmos._change_feed.feed_range import FeedRange, FeedRangeEpk, FeedRangePartitionKey
+from azure.cosmos._change_feed.feed_range_internal import FeedRangeInternal, FeedRangeInternalEpk, FeedRangeInternalPartitionKey
 from azure.cosmos._change_feed.feed_range_composite_continuation_token import FeedRangeCompositeContinuation
 from azure.cosmos._routing.aio.routing_map_provider import SmartRoutingMapProvider as AsyncSmartRoutingMapProvider
 from azure.cosmos._routing.routing_map_provider import SmartRoutingMapProvider
@@ -79,7 +79,7 @@ def apply_server_response_continuation(self, continuation: str, has_modified_res
     def from_json(
             container_link: str,
             container_rid: str,
-            change_feed_state_context: Dict[str, Any]):
+            change_feed_state_context: Dict[str, Any]) -> 'ChangeFeedState':
 
         if (change_feed_state_context.get("partitionKeyRangeId")
                 or change_feed_state_context.get("continuationPkRangeId")):
@@ -184,7 +184,7 @@ def __init__(
             self,
             container_link: str,
             container_rid: str,
-            feed_range: FeedRange,
+            feed_range: FeedRangeInternal,
             change_feed_start_from: ChangeFeedStartFromInternal,
             continuation: Optional[FeedRangeCompositeContinuation]
     ) -> None:
@@ -380,22 +380,20 @@ def from_initial_state(
             collection_rid: str,
             change_feed_state_context: Dict[str, Any]) -> 'ChangeFeedStateV2':
 
-        feed_range: Optional[FeedRange] = None
+        feed_range: Optional[FeedRangeInternal] = None
         if change_feed_state_context.get("feedRange"):
-            feed_range_str = base64.b64decode(change_feed_state_context["feedRange"]).decode('utf-8')
-            feed_range_json = json.loads(feed_range_str)
-            feed_range = FeedRangeEpk(Range.ParseFromDict(feed_range_json))
+            feed_range = change_feed_state_context.get("feedRange")
         elif change_feed_state_context.get("partitionKey"):
             if change_feed_state_context.get("partitionKeyFeedRange"):
                 feed_range =\
-                    FeedRangePartitionKey(
+                    FeedRangeInternalPartitionKey(
                         change_feed_state_context["partitionKey"],
                         change_feed_state_context["partitionKeyFeedRange"])
             else:
                 raise ValueError("partitionKey is in the changeFeedStateContext, but missing partitionKeyFeedRange")
         else:
             # default to full range
-            feed_range = FeedRangeEpk(
+            feed_range = FeedRangeInternalEpk(
                 Range(
                 "",
                 "FF",

sdk/cosmos/azure-cosmos/azure/cosmos/_change_feed/feed_range_composite_continuation_token.py

@@ -26,7 +26,7 @@
 from typing import Any, Deque, Dict, Optional
 
 from azure.cosmos._change_feed.composite_continuation_token import CompositeContinuationToken
-from azure.cosmos._change_feed.feed_range import FeedRange, FeedRangeEpk, FeedRangePartitionKey
+from azure.cosmos._change_feed.feed_range_internal import FeedRangeInternal, FeedRangeInternalEpk, FeedRangeInternalPartitionKey
 from azure.cosmos._routing.routing_map_provider import SmartRoutingMapProvider
 from azure.cosmos._routing.aio.routing_map_provider import SmartRoutingMapProvider as AsyncSmartRoutingMapProvider
 from azure.cosmos._routing.routing_range import Range
@@ -39,7 +39,7 @@ class FeedRangeCompositeContinuation:
     def __init__(
             self,
             container_rid: str,
-            feed_range: FeedRange,
+            feed_range: FeedRangeInternal,
             continuation: Deque[CompositeContinuationToken]) -> None:
         if container_rid is None:
             raise ValueError("container_rid is missing")
@@ -87,11 +87,11 @@ def from_json(cls, data) -> 'FeedRangeCompositeContinuation':
                         for child_range_continuation_token in continuation_data]
 
         # parsing feed range
-        feed_range: Optional[FeedRange] = None
-        if data.get(FeedRangeEpk.type_property_name):
-            feed_range = FeedRangeEpk.from_json(data)
-        elif data.get(FeedRangePartitionKey.type_property_name):
-            feed_range = FeedRangePartitionKey.from_json(data, continuation[0].feed_range)
+        feed_range: Optional[FeedRangeInternal] = None
+        if data.get(FeedRangeInternalEpk.type_property_name):
+            feed_range = FeedRangeInternalEpk.from_json(data)
+        elif data.get(FeedRangeInternalPartitionKey.type_property_name):
+            feed_range = FeedRangeInternalPartitionKey.from_json(data, continuation[0].feed_range)
         else:
             raise ValueError("Invalid feed range composite continuation token [Missing feed range scope]")
 
@@ -171,5 +171,5 @@ def apply_not_modified_response(self) -> None:
             self._initial_no_result_range = self._current_token.feed_range
 
     @property
-    def feed_range(self) -> FeedRange:
+    def feed_range(self) -> FeedRangeInternal:
         return self._feed_range

sdk/cosmos/azure-cosmos/azure/cosmos/_change_feed/feed_range.py renamed to sdk/cosmos/azure-cosmos/azure/cosmos/_change_feed/feed_range_internal.py

@@ -29,7 +29,7 @@
 from azure.cosmos.partition_key import _Undefined, _Empty
 
 
-class FeedRange(ABC):
+class FeedRangeInternal(ABC):
 
     @abstractmethod
     def get_normalized_range(self) -> Range:
@@ -39,7 +39,7 @@ def get_normalized_range(self) -> Range:
     def to_dict(self) -> Dict[str, Any]:
         pass
 
-class FeedRangePartitionKey(FeedRange):
+class FeedRangeInternalPartitionKey(FeedRangeInternal):
     type_property_name = "PK"
 
     def __init__(
@@ -69,7 +69,7 @@ def to_dict(self) -> Dict[str, Any]:
         return { self.type_property_name: self._pk_value }
 
     @classmethod
-    def from_json(cls, data: Dict[str, Any], feed_range: Range) -> 'FeedRangePartitionKey':
+    def from_json(cls, data: Dict[str, Any], feed_range: Range) -> 'FeedRangeInternalPartitionKey':
         if data.get(cls.type_property_name):
             pk_value = data.get(cls.type_property_name)
             if not pk_value:
@@ -80,11 +80,11 @@ def from_json(cls, data: Dict[str, Any], feed_range: Range) -> 'FeedRangePartiti
                 return cls(list(pk_value), feed_range)
             return cls(data[cls.type_property_name], feed_range)
 
-        raise ValueError(f"Can not parse FeedRangePartitionKey from the json,"
+        raise ValueError(f"Can not parse FeedRangeInternalPartitionKey from the json,"
                          f" there is no property {cls.type_property_name}")
 
 
-class FeedRangeEpk(FeedRange):
+class FeedRangeInternalEpk(FeedRangeInternal):
     type_property_name = "Range"
 
     def __init__(self, feed_range: Range) -> None:
@@ -102,8 +102,9 @@ def to_dict(self) -> Dict[str, Any]:
         }
 
     @classmethod
-    def from_json(cls, data: Dict[str, Any]) -> 'FeedRangeEpk':
+    def from_json(cls, data: Dict[str, Any]) -> 'FeedRangeInternalEpk':
         if data.get(cls.type_property_name):
             feed_range = Range.ParseFromDict(data.get(cls.type_property_name))
             return cls(feed_range)
-        raise ValueError(f"Can not parse FeedRangeEPK from the json, there is no property {cls.type_property_name}")
+        raise ValueError(f"Can not parse FeedRangeInternalEPK from the json,"
+                         f" there is no property {cls.type_property_name}")

sdk/cosmos/azure-cosmos/azure/cosmos/_feed_range.py

@@ -0,0 +1,97 @@
+
+# The MIT License (MIT)
+# Copyright (c) 2014 Microsoft Corporation
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+import base64
+import json
+from abc import ABC, abstractmethod
+from typing import Any, Dict
+
+from azure.cosmos._change_feed.feed_range_internal import FeedRangeInternal, FeedRangeInternalEpk
+from azure.cosmos._routing.routing_range import Range
+
+
+class FeedRange(ABC):
+    """Represents a single feed range in an Azure Cosmos DB SQL API container. """
+
+    def to_string(self) -> str:
+        """Get a json representation of the feed range.
+           The returned json string can be used to create a new feed range from it.
+        :return: A json representation of the feed range.
+        :rtype: str
+        """
+        return self._to_base64_encoded_string()
+
+    @staticmethod
+    def from_string(json_str: str) -> 'FeedRange':
+        """
+        Create a feed range from previously obtained string representation.
+
+        :param json_str: A string representation of a feed range.
+        :return: A feed range.
+        :rtype: ~azure.cosmos.FeedRange
+        """
+        feed_range_json_str = base64.b64decode(json_str).decode('utf-8')
+        feed_range_json = json.loads(feed_range_json_str)
+        if feed_range_json.get(FeedRangeEpk.type_property_name):
+            return FeedRangeEpk._from_json(feed_range_json)
+        else:
+            raise ValueError("Invalid feed range base64 encoded string [Wrong feed range type]")
+
+    @abstractmethod
+    def _to_dict(self) -> Dict[str, Any]:
+        pass
+
+    @abstractmethod
+    def _to_feed_range_internal(self) -> 'FeedRangeInternal':
+        pass
+
+    def _to_base64_encoded_string(self) -> str:
+        data_json = json.dumps(self._to_dict())
+        json_bytes = data_json.encode('utf-8')
+        # Encode the bytes to a Base64 string
+        base64_bytes = base64.b64encode(json_bytes)
+        # Convert the Base64 bytes to a string
+        return base64_bytes.decode('utf-8')
+
+class FeedRangeEpk (FeedRange):
+    type_property_name = "Range"
+
+    def __init__(self, feed_range: Range) -> None:
+        if feed_range is None:
+            raise ValueError("feed_range cannot be None")
+
+        self._feed_range = feed_range
+
+    def _to_dict(self) -> Dict[str, Any]:
+        return {
+            self.type_property_name: self._feed_range.to_dict()
+        }
+
+    def _to_feed_range_internal(self) -> 'FeedRangeInternal':
+        return FeedRangeInternalEpk(self._feed_range)
+
+    @classmethod
+    def _from_json(cls, data: Dict[str, Any]) -> 'FeedRange':
+        if data.get(cls.type_property_name):
+            feed_range = Range.ParseFromDict(data.get(cls.type_property_name))
+            return cls(feed_range)
+        raise ValueError(f"Can not parse FeedRangeEPK from the json, there is no property {cls.type_property_name}")

sdk/cosmos/azure-cosmos/azure/cosmos/_routing/routing_range.py

@@ -25,12 +25,8 @@
 import base64
 import binascii
 import json
-from typing import Dict, Any
 
 
-def partition_key_range_to_range_string(partition_key_range: Dict[str, Any]) -> str:
-    return Range.PartitionKeyRangeToRange(partition_key_range).to_base64_encoded_string()
-
 class PartitionKeyRange(object):
     """Partition Key Range Constants"""
 

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

@@ -41,7 +41,8 @@
     GenerateGuidId,
     _set_properties_cache
 )
-from .._routing.routing_range import Range, partition_key_range_to_range_string
+from .._feed_range import FeedRange, FeedRangeEpk
+from .._routing.routing_range import Range
 from ..offer import ThroughputProperties
 from ..partition_key import (
     NonePartitionKeyValue,
@@ -526,15 +527,16 @@ def query_items_change_feed(
     def query_items_change_feed(
             self,
             *,
-            feed_range: str,
+            feed_range: FeedRange,
             max_item_count: Optional[int] = None,
             start_time: Optional[Union[datetime, Literal["Now", "Beginning"]]] = None,
             priority: Optional[Literal["High", "Low"]] = None,
             **kwargs: Any
     ) -> AsyncItemPaged[Dict[str, Any]]:
         """Get a sorted list of items that were changed, in the order in which they were modified.
 
-        :keyword str feed_range: The feed range that is used to define the scope.
+        :keyword feed_range: The feed range that is used to define the scope.
+        :type feed_range: ~azure.cosmos.FeedRange
         :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.
@@ -659,7 +661,8 @@ def query_items_change_feed( # pylint: disable=unused-argument
                 self._get_epk_range_for_partition_key(kwargs.pop('partition_key'))
 
         if kwargs.get("feed_range") is not None:
-            change_feed_state_context["feedRange"] = kwargs.pop('feed_range')
+            feed_range: FeedRange = kwargs.pop('feed_range')
+            change_feed_state_context["feedRange"] = feed_range._to_feed_range_internal()
 
         feed_options["containerProperties"] = self._get_properties()
         feed_options["changeFeedStateContext"] = change_feed_state_context
@@ -1243,7 +1246,7 @@ async def read_feed_ranges(
             *,
             force_refresh: Optional[bool] = False,
             **kwargs: Any
-    ) -> List[str]:
+    ) -> List[FeedRange]:
         """ Obtains a list of feed ranges that can be used to parallelize feed operations.
 
         :keyword bool force_refresh:
@@ -1262,4 +1265,4 @@ async def read_feed_ranges(
                 [Range("", "FF", True, False)],
                 **kwargs)
 
-        return [partition_key_range_to_range_string(partitionKeyRange) for partitionKeyRange in partition_key_ranges]
+        return [FeedRangeEpk(Range.PartitionKeyRangeToRange(partitionKeyRange)) for partitionKeyRange in partition_key_ranges]

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

@@ -39,7 +39,8 @@
     _set_properties_cache
 )
 from ._cosmos_client_connection import CosmosClientConnection
-from ._routing.routing_range import Range, partition_key_range_to_range_string
+from ._feed_range import FeedRange, FeedRangeEpk
+from ._routing.routing_range import Range
 from .offer import Offer, ThroughputProperties
 from .partition_key import (
     NonePartitionKeyValue,
@@ -352,7 +353,7 @@ def query_items_change_feed(
     def query_items_change_feed(
             self,
             *,
-            feed_range: str,
+            feed_range: FeedRange,
             max_item_count: Optional[int] = None,
             start_time: Optional[Union[datetime, Literal["Now", "Beginning"]]] = None,
             priority: Optional[Literal["High", "Low"]] = None,
@@ -361,7 +362,8 @@ def query_items_change_feed(
 
         """Get a sorted list of items that were changed, in the order in which they were modified.
 
-        :keyword str feed_range: The feed range that is used to define the scope.
+        :keyword feed_range: The feed range that is used to define the scope.
+        :type feed_range: ~azure.cosmos.FeedRange
         :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.
@@ -500,7 +502,8 @@ def query_items_change_feed(
                 self._get_epk_range_for_partition_key(kwargs.pop('partition_key'))
 
         if kwargs.get("feed_range") is not None:
-            change_feed_state_context["feedRange"] = kwargs.pop('feed_range')
+            feed_range: FeedRange = kwargs.pop('feed_range')
+            change_feed_state_context["feedRange"] = feed_range._to_feed_range_internal()
 
         container_properties = self._get_properties()
         feed_options["changeFeedStateContext"] = change_feed_state_context
@@ -1310,7 +1313,7 @@ def read_feed_ranges(
             self,
             *,
             force_refresh: Optional[bool] = False,
-            **kwargs: Any) -> List[str]:
+            **kwargs: Any) -> List[FeedRange]:
 
         """ Obtains a list of feed ranges that can be used to parallelize feed operations.
 
@@ -1329,4 +1332,4 @@ def read_feed_ranges(
                 [Range("", "FF", True, False)], # default to full range
                 **kwargs)
 
-        return [partition_key_range_to_range_string(partitionKeyRange) for partitionKeyRange in partition_key_ranges]
+        return [FeedRangeEpk(Range.PartitionKeyRangeToRange(partitionKeyRange)) for partitionKeyRange in partition_key_ranges]