[Cosmos] deprecate offer-named methods in favor of new throughput-named methods

sdk/cosmos/azure-cosmos/CHANGELOG.md

@@ -3,6 +3,7 @@
 ### 4.3.0b5 (Unreleased)
 
 #### Other Changes
+- Deprecated offer-named methods in favor of their new throughput-named counterparts (`read_offer` -> `get_throughput`).
 - Marked the GetAuthorizationMethod for deprecation since it will no longer be public in a future release.
 - Added samples showing how to configure retry options for both the sync and async clients.
 - Deprecated the `connection_retry_policy` and `retry_options` options in the sync client.
@@ -31,7 +32,7 @@
 - Added new **provisional** `max_integrated_cache_staleness_in_ms` parameter to read item and query items APIs in order
   to make use of the **preview** CosmosDB integrated cache functionality.
   Please see [Azure Cosmos DB integrated cache](https://docs.microsoft.com/azure/cosmos-db/integrated-cache) for more details.
-- Added support for split-proof queries for the async client
+- Added support for split-proof queries for the async client.
 
 ### Bugs fixed
 - Default consistency level for the sync and async clients is no longer `Session` and will instead be set to the 

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

@@ -32,7 +32,7 @@
 from .._base import build_options as _build_options, validate_cache_staleness_value
 from ..exceptions import CosmosResourceNotFoundError
 from ..http_constants import StatusCodes
-from ..offer import Offer
+from ..offer import ThroughputProperties
 from .scripts import ScriptsProxy
 from ..partition_key import NonePartitionKeyValue
 
@@ -114,10 +114,10 @@ def _set_partition_key(self, partition_key) -> Union[str, Awaitable]:
 
     @distributed_trace_async
     async def read(
-            self,
-            populate_partition_key_range_statistics=None,  # type: Optional[bool]
-            populate_quota_info=None,  # type: Optional[bool]
-            **kwargs  # type: Any
+        self,
+        populate_partition_key_range_statistics=None,  # type: Optional[bool]
+        populate_quota_info=None,  # type: Optional[bool]
+        **kwargs  # type: Any
     ) -> Dict[str, Any]:
         """Read the container properties.
 
@@ -151,9 +151,9 @@ async def read(
 
     @distributed_trace_async
     async def create_item(
-            self,
-            body,  # type: Dict[str, Any]
-            **kwargs  # type: Any
+        self,
+        body,  # type: Dict[str, Any]
+        **kwargs  # type: Any
     ) -> Dict[str, Any]:
         """Create an item in the container.
 
@@ -198,10 +198,10 @@ async def create_item(
 
     @distributed_trace_async
     async def read_item(
-            self,
-            item,  # type: Union[str, Dict[str, Any]]
-            partition_key,  # type: Any
-            **kwargs  # type: Any
+        self,
+        item,  # type: Union[str, Dict[str, Any]]
+        partition_key,  # type: Any
+        **kwargs  # type: Any
     ) -> Dict[str, Any]:
         """Get the item identified by `item`.
 
@@ -245,9 +245,9 @@ async def read_item(
 
     @distributed_trace
     def read_all_items(
-            self,
-            max_item_count=None,  # type: Optional[int]
-            **kwargs  # type: Any
+        self,
+        max_item_count=None,  # type: Optional[int]
+        **kwargs  # type: Any
     ) -> AsyncItemPaged[Dict[str, Any]]:
         """List all the items in the container.
 
@@ -284,14 +284,14 @@ def read_all_items(
 
     @distributed_trace
     def query_items(
-            self,
-            query,  # type: str
-            parameters=None,  # type: Optional[List[Dict[str, Any]]]
-            partition_key=None,  # type: Optional[Any]
-            max_item_count=None,  # type: Optional[int]
-            enable_scan_in_query=None,  # type: Optional[bool]
-            populate_query_metrics=None,  # type: Optional[bool]
-            **kwargs  # type: Any
+        self,
+        query,  # type: str
+        parameters=None,  # type: Optional[List[Dict[str, Any]]]
+        partition_key=None,  # type: Optional[Any]
+        max_item_count=None,  # type: Optional[int]
+        enable_scan_in_query=None,  # type: Optional[bool]
+        populate_query_metrics=None,  # type: Optional[bool]
+        **kwargs  # type: Any
     ) -> AsyncItemPaged[Dict[str, Any]]:
         """Return all results matching the given `query`.
 
@@ -373,12 +373,12 @@ def query_items(
 
     @distributed_trace
     def query_items_change_feed(
-            self,
-            partition_key_range_id=None,  # type: Optional[str]
-            is_start_from_beginning=False,  # type: bool
-            continuation=None,  # type: Optional[str]
-            max_item_count=None,  # type: Optional[int]
-            **kwargs  # type: Any
+        self,
+        partition_key_range_id=None,  # type: Optional[str]
+        is_start_from_beginning=False,  # type: bool
+        continuation=None,  # type: Optional[str]
+        max_item_count=None,  # type: Optional[int]
+        **kwargs  # type: Any
     ) -> AsyncItemPaged[Dict[str, Any]]:
         """Get a sorted list of items that were changed, in the order in which they were modified.
 
@@ -419,11 +419,11 @@ def query_items_change_feed(
 
     @distributed_trace_async
     async def upsert_item(
-            self,
-            body,  # type: Dict[str, Any]
-            pre_trigger_include=None,  # type: Optional[str]
-            post_trigger_include=None,  # type: Optional[str]
-            **kwargs  # type: Any
+        self,
+        body,  # type: Dict[str, Any]
+        pre_trigger_include=None,  # type: Optional[str]
+        post_trigger_include=None,  # type: Optional[str]
+        **kwargs  # type: Any
     ) -> Dict[str, Any]:
         """Insert or update the specified item.
 
@@ -463,12 +463,12 @@ async def upsert_item(
 
     @distributed_trace_async
     async def replace_item(
-            self,
-            item,  # type: Union[str, Dict[str, Any]]
-            body,  # type: Dict[str, Any]
-            pre_trigger_include=None,  # type: Optional[str]
-            post_trigger_include=None,  # type: Optional[str]
-            **kwargs  # type: Any
+        self,
+        item,  # type: Union[str, Dict[str, Any]]
+        body,  # type: Dict[str, Any]
+        pre_trigger_include=None,  # type: Optional[str]
+        post_trigger_include=None,  # type: Optional[str]
+        **kwargs  # type: Any
     ) -> Dict[str, Any]:
         """Replaces the specified item if it exists in the container.
 
@@ -507,12 +507,12 @@ async def replace_item(
 
     @distributed_trace_async
     async def delete_item(
-            self,
-            item,  # type: Union[str, Dict[str, Any]]
-            partition_key,  # type: Any
-            pre_trigger_include=None,  # type: Optional[str]
-            post_trigger_include=None,  # type: Optional[str]
-            **kwargs  # type: Any
+        self,
+        item,  # type: Union[str, Dict[str, Any]]
+        partition_key,  # type: Any
+        pre_trigger_include=None,  # type: Optional[str]
+        post_trigger_include=None,  # type: Optional[str]
+        **kwargs  # type: Any
     ) -> None:
         """Delete the specified item from the container.
 
@@ -546,17 +546,17 @@ async def delete_item(
             response_hook(self.client_connection.last_response_headers, result)
 
     @distributed_trace_async
-    async def read_offer(self, **kwargs):
-        # type: (Any) -> Offer
-        """Read the Offer object for this container.
+    async def get_throughput(self, **kwargs):
+        # type: (Any) -> ThroughputProperties
+        """Get the ThroughputProperties object for this container.
 
-        If no Offer already exists for the container, an exception is raised.
+        If no ThroughputProperties already exist for the container, an exception is raised.
 
         :keyword Callable response_hook: A callable invoked with the response metadata.
-        :returns: Offer for the container.
-        :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: No offer exists for the container or
-            the offer could not be retrieved.
-        :rtype: ~azure.cosmos.Offer
+        :returns: ThroughputProperties for the container.
+        :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: No throughput properties exists for the container or
+            the throughput properties could not be retrieved.
+        :rtype: ~azure.cosmos.ThroughputProperties
         """
         response_hook = kwargs.pop('response_hook', None)
         properties = await self._get_properties()
@@ -565,30 +565,33 @@ async def read_offer(self, **kwargs):
             "query": "SELECT * FROM root r WHERE r.resource=@link",
             "parameters": [{"name": "@link", "value": link}],
         }
-        offers = [offer async for offer in self.client_connection.QueryOffers(query_spec, **kwargs)]
-        if len(offers) == 0:
+        throughput_properties = [throughput async for throughput in
+                                 self.client_connection.QueryOffers(query_spec, **kwargs)]
+        if len(throughput_properties) == 0:
             raise CosmosResourceNotFoundError(
                 status_code=StatusCodes.NOT_FOUND,
-                message="Could not find Offer for database " + self.database_link)
+                message="Could not find ThroughputProperties for container " + self.container_link)
 
         if response_hook:
-            response_hook(self.client_connection.last_response_headers, offers)
+            response_hook(self.client_connection.last_response_headers, throughput_properties)
 
-        return Offer(offer_throughput=offers[0]["content"]["offerThroughput"], properties=offers[0])
+        return ThroughputProperties(
+            offer_throughput=throughput_properties[0]["content"]["offerThroughput"],
+            properties=throughput_properties[0])
 
     @distributed_trace_async
     async def replace_throughput(self, throughput, **kwargs):
-        # type: (int, Any) -> Offer
+        # type: (int, Any) -> ThroughputProperties
         """Replace the container's throughput.
 
-        If no Offer already exists for the container, an exception is raised.
+        If no ThroughputProperties already exist for the container, an exception is raised.
 
         :param throughput: The throughput to be set (an integer).
         :keyword Callable response_hook: A callable invoked with the response metadata.
-        :returns: Offer for the container, updated with new throughput.
-        :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: No offer exists for the container
-            or the offer could not be updated.
-        :rtype: ~azure.cosmos.Offer
+        :returns: ThroughputProperties for the container, updated with new throughput.
+        :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: No throughput properties exist for the container
+            or the throughput properties could not be updated.
+        :rtype: ~azure.cosmos.ThroughputProperties
         """
         response_hook = kwargs.pop('response_hook', None)
         properties = await self._get_properties()
@@ -597,19 +600,21 @@ async def replace_throughput(self, throughput, **kwargs):
             "query": "SELECT * FROM root r WHERE r.resource=@link",
             "parameters": [{"name": "@link", "value": link}],
         }
-        offers = [offer async for offer in self.client_connection.QueryOffers(query_spec, **kwargs)]
-        if len(offers) == 0:
+        throughput_properties = [throughput async for throughput in
+                                 self.client_connection.QueryOffers(query_spec, **kwargs)]
+        if len(throughput_properties) == 0:
             raise CosmosResourceNotFoundError(
                 status_code=StatusCodes.NOT_FOUND,
-                message="Could not find Offer for database " + self.database_link)
+                message="Could not find ThroughputProperties for container " + self.container_link)
 
-        new_offer = offers[0].copy()
-        new_offer["content"]["offerThroughput"] = throughput
-        data = await self.client_connection.ReplaceOffer(offer_link=offers[0]["_self"], offer=offers[0], **kwargs)
+        new_throughput_properties = throughput_properties[0].copy()
+        new_throughput_properties["content"]["offerThroughput"] = throughput
+        data = await self.client_connection.ReplaceOffer(offer_link=throughput_properties[0]["_self"],
+                                                         offer=throughput_properties[0], **kwargs)
         if response_hook:
             response_hook(self.client_connection.last_response_headers, data)
 
-        return Offer(offer_throughput=data["content"]["offerThroughput"], properties=data)
+        return ThroughputProperties(offer_throughput=data["content"]["offerThroughput"], properties=data)
 
     @distributed_trace
     def list_conflicts(self, max_item_count=None, **kwargs):
@@ -635,12 +640,12 @@ def list_conflicts(self, max_item_count=None, **kwargs):
 
     @distributed_trace
     def query_conflicts(
-            self,
-            query,  # type: str
-            parameters=None,  # type: Optional[List[Dict[str, Any]]]
-            partition_key=None,  # type: Optional[Any]
-            max_item_count=None,  # type: Optional[int]
-            **kwargs  # type: Any
+        self,
+        query,  # type: str
+        parameters=None,  # type: Optional[List[Dict[str, Any]]]
+        partition_key=None,  # type: Optional[Any]
+        max_item_count=None,  # type: Optional[int]
+        **kwargs  # type: Any
     ) -> AsyncItemPaged[Dict[str, Any]]:
         """Return all conflicts matching a given `query`.
 
@@ -673,11 +678,11 @@ def query_conflicts(
         return result
 
     @distributed_trace_async
-    async def read_conflict(
-            self,
-            conflict,  # type: Union[str, Dict[str, Any]]
-            partition_key,  # type: Any
-            **kwargs  # type: Any
+    async def get_conflict(
+        self,
+        conflict,  # type: Union[str, Dict[str, Any]]
+        partition_key,  # type: Any
+        **kwargs  # type: Any
     ) -> Dict[str, Any]:
         """Get the conflict identified by `conflict`.
 
@@ -700,10 +705,10 @@ async def read_conflict(
 
     @distributed_trace_async
     async def delete_conflict(
-            self,
-            conflict,  # type: Union[str, Dict[str, Any]]
-            partition_key,  # type: Any
-            **kwargs  # type: Any
+        self,
+        conflict,  # type: Union[str, Dict[str, Any]]
+        partition_key,  # type: Any
+        **kwargs  # type: Any
     ) -> None:
         """Delete a specified conflict from the container.