[Cosmos] use python3 typehints and move options to kwargs on async client

sdk/cosmos/azure-cosmos/CHANGELOG.md

@@ -2,15 +2,13 @@
 
 ### 4.3.0b5 (Unreleased)
 
-#### Features Added
-
 #### Breaking Changes
-
-#### Bugs Fixed
+- Method signatures have been updated to use keyword arguments instead of positional arguments for most method options in the async client.
 
 #### Other Changes
  - 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.
+
 ### 4.3.0b4 (2022-04-07)
 
 #### Features Added

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

@@ -32,7 +32,7 @@
 
 from ._cosmos_client_connection_async import CosmosClientConnection
 from .._base import build_options
-from ..permission import Permission as _permission
+from ..permission import Permission
 
 
 class UserProxy(object):
@@ -42,19 +42,22 @@ class UserProxy(object):
     :func:`DatabaseProxy.get_user_client` method.
     """
 
-    def __init__(self, client_connection, id, database_link, properties=None):  # pylint: disable=redefined-builtin
-        # type: (CosmosClientConnection, str, str, Dict[str, Any]) -> None
+    def __init__(
+            self,
+            client_connection: CosmosClientConnection,
+            id: str,  # pylint: disable=redefined-builtin
+            database_link: str,
+            properties: Dict[str, Any] = None
+    ) -> None:
         self.client_connection = client_connection
         self.id = id
         self.user_link = u"{}/users/{}".format(database_link, id)
         self._properties = properties
 
-    def __repr__(self):
-        # type () -> str
+    def __repr__(self) -> str:
         return "<UserProxy [{}]>".format(self.user_link)[:1024]
 
-    def _get_permission_link(self, permission_or_id):
-        # type: (Union[Permission, str, Dict[str, Any]]) -> str
+    def _get_permission_link(self, permission_or_id: Union[Permission, str, Dict[str, Any]]) -> str:
         if isinstance(permission_or_id, str):
             return u"{}/permissions/{}".format(self.user_link, permission_or_id)
         try:
@@ -63,21 +66,20 @@ def _get_permission_link(self, permission_or_id):
             pass
         return u"{}/permissions/{}".format(self.user_link, cast("Dict[str, str]", permission_or_id)["id"])
 
-    async def _get_properties(self):
-        # type: () -> Dict[str, Any]
+    async def _get_properties(self) -> Dict[str, Any]:
         if self._properties is None:
             self._properties = await self.read()
         return self._properties
 
     @distributed_trace_async
-    async def read(self, **kwargs):
-        # type: (Any) -> Dict[str, Any]
-        """Read user propertes.
+    async def read(self, **kwargs: Any) -> Dict[str, Any]:
+        """Read user properties.
 
-        :keyword Callable response_hook: A callable invoked with the response metadata.
-        :returns: A dictionary of the retrieved user properties.
+        :keyword response_hook: A callable invoked with the response metadata.
+        :paramtype response_hook: Callable[[Dict[str, str], Dict[str, Any]], Any]
         :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: If the given user couldn't be retrieved.
-        :rtype: dict[str, Any]
+        :returns: A dictionary of the retrieved user properties.
+        :rtype: Dict[str, Any]
         """
         request_options = build_options(kwargs)
         response_hook = kwargs.pop('response_hook', None)
@@ -91,17 +93,18 @@ async def read(self, **kwargs):
         return cast('Dict[str, Any]', self._properties)
 
     @distributed_trace
-    def list_permissions(self, max_item_count=None, **kwargs):
-        # type: (Optional[int], Any) -> AsyncItemPaged[Dict[str, Any]]
+    def list_permissions(self, **kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]:
         """List all permission for the user.
 
-        :param max_item_count: Max number of permissions to be returned in the enumeration operation.
-        :keyword Callable response_hook: A callable invoked with the response metadata.
+        :keyword int max_item_count: Max number of permissions 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]], Any]
         :returns: An AsyncItemPaged of permissions (dicts).
-        :rtype: AsyncItemPaged[dict[str, Any]]
+        :rtype: AsyncItemPaged[Dict[str, Any]]
         """
         feed_options = build_options(kwargs)
         response_hook = kwargs.pop('response_hook', None)
+        max_item_count = kwargs.pop('max_item_count', None)
         if max_item_count is not None:
             feed_options["maxItemCount"] = max_item_count
 
@@ -115,23 +118,24 @@ def list_permissions(self, max_item_count=None, **kwargs):
     @distributed_trace
     def query_permissions(
         self,
-        query,
-        parameters=None,
-        max_item_count=None,
-        **kwargs
-    ):
-        # type: (str, Optional[List[str]], Optional[int], Any) -> AsyncItemPaged[Dict[str, Any]]
+        query: str,
+        parameters: Optional[List[Dict[str, Any]]] = None,
+        **kwargs: Any
+    ) -> AsyncItemPaged[Dict[str, Any]]:
         """Return all permissions matching the given `query`.
 
-        :param query: The Azure Cosmos DB SQL query to execute.
+        :param str query: The Azure Cosmos DB SQL query to execute.
         :param parameters: Optional array of parameters to the query. Ignored if no query is provided.
-        :param max_item_count: Max number of permissions to be returned in the enumeration operation.
-        :keyword Callable response_hook: A callable invoked with the response metadata.
+        :type parameters: Optional[List[Dict[str, Any]]]
+        :keyword int max_item_count: Max number of permissions 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]]], Any]
         :returns: An AsyncItemPaged of permissions (dicts).
-        :rtype: AsyncItemPaged[dict[str, Any]]
+        :rtype: AsyncItemPaged[Dict[str, Any]]
         """
         feed_options = build_options(kwargs)
         response_hook = kwargs.pop('response_hook', None)
+        max_item_count = kwargs.pop('max_item_count', None)
         if max_item_count is not None:
             feed_options["maxItemCount"] = max_item_count
 
@@ -148,16 +152,21 @@ def query_permissions(
         return result
 
     @distributed_trace_async
-    async def get_permission(self, permission, **kwargs):
-        # type: (Union[str, Dict[str, Any], Permission], Any) -> Permission
+    async def get_permission(
+            self,
+            permission: Union[str, Dict[str, Any], Permission],
+            **kwargs: Any
+    ) -> Permission:
         """Get the permission identified by `id`.
 
         :param permission: The ID (name), dict representing the properties or :class:`Permission`
             instance of the permission to be retrieved.
-        :keyword Callable response_hook: A callable invoked with the response metadata.
-        :returns: A dict representing the retrieved permission.
+        :type permission: Union[str, Dict[str, Any], ~azure.cosmos.Permission]
+        :keyword response_hook: A callable invoked with the response metadata.
+        :paramtype response_hook: Callable[[Dict[str, str], Dict[str, Any]], Any]
         :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: If the given permission couldn't be retrieved.
-        :rtype: dict[str, Any]
+        :returns: The retrieved permission object.
+        :rtype: ~azure.cosmos.Permission
         """
         request_options = build_options(kwargs)
         response_hook = kwargs.pop('response_hook', None)
@@ -169,7 +178,7 @@ async def get_permission(self, permission, **kwargs):
         if response_hook:
             response_hook(self.client_connection.last_response_headers, permission_resp)
 
-        return _permission(
+        return Permission(
             id=permission_resp["id"],
             user_link=self.user_link,
             permission_mode=permission_resp["permissionMode"],
@@ -178,17 +187,18 @@ async def get_permission(self, permission, **kwargs):
         )
 
     @distributed_trace_async
-    async def create_permission(self, body, **kwargs):
-        # type: (Dict[str, Any], Any) -> Permission
+    async def create_permission(self, body: Dict[str, Any], **kwargs: Any) -> Permission:
         """Create a permission for the user.
 
-        To update or replace an existing permision, use the :func:`UserProxy.upsert_permission` method.
+        To update or replace an existing permission, use the :func:`UserProxy.upsert_permission` method.
 
         :param body: A dict-like object representing the permission to create.
-        :keyword Callable response_hook: A callable invoked with the response metadata.
-        :returns: A dict representing the new permission.
+        :type body: Dict[str, Any]
+        :keyword response_hook: A callable invoked with the response metadata.
+        :paramtype response_hook: Callable[[Dict[str, str], Dict[str, Any]], Any]
         :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: If the given permission couldn't be created.
-        :rtype: dict[str, Any]
+        :returns: A permission object representing the new permission.
+        :rtype: ~azure.cosmos.Permission
         """
         request_options = build_options(kwargs)
         response_hook = kwargs.pop('response_hook', None)
@@ -200,7 +210,7 @@ async def create_permission(self, body, **kwargs):
         if response_hook:
             response_hook(self.client_connection.last_response_headers, permission)
 
-        return _permission(
+        return Permission(
             id=permission["id"],
             user_link=self.user_link,
             permission_mode=permission["permissionMode"],
@@ -209,18 +219,19 @@ async def create_permission(self, body, **kwargs):
         )
 
     @distributed_trace_async
-    async def upsert_permission(self, body, **kwargs):
-        # type: (Dict[str, Any], Any) -> Permission
+    async def upsert_permission(self, body: Dict[str, Any], **kwargs: Any) -> Permission:
         """Insert or update the specified permission.
 
         If the permission already exists in the container, it is replaced. If
         the permission does not exist, it is inserted.
 
         :param body: A dict-like object representing the permission to update or insert.
-        :param Callable response_hook: A callable invoked with the response metadata.
-        :returns: A dict representing the upserted permission.
+        :type body: Dict[str, Any]
+        :keyword response_hook: A callable invoked with the response metadata.
+        :paramtype response_hook: Callable[[Dict[str, str], Dict[str, Any]], Any]
         :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: If the given permission could not be upserted.
-        :rtype: dict[str, Any]
+        :returns: A dict representing the upserted permission.
+        :rtype: ~azure.cosmos.Permission
         """
         request_options = build_options(kwargs)
         response_hook = kwargs.pop('response_hook', None)
@@ -232,7 +243,7 @@ async def upsert_permission(self, body, **kwargs):
         if response_hook:
             response_hook(self.client_connection.last_response_headers, permission)
 
-        return _permission(
+        return Permission(
             id=permission["id"],
             user_link=self.user_link,
             permission_mode=permission["permissionMode"],
@@ -241,20 +252,27 @@ async def upsert_permission(self, body, **kwargs):
         )
 
     @distributed_trace_async
-    async def replace_permission(self, permission, body, **kwargs):
-        # type: (str, Union[str, Dict[str, Any], Permission], Any) -> Permission
+    async def replace_permission(
+            self,
+            permission: Union[str, Dict[str, Any], Permission],
+            body: Dict[str, Any],
+            **kwargs: Any
+    ) -> Permission:
         """Replaces the specified permission if it exists for the user.
 
         If the permission does not already exist, an exception is raised.
 
         :param permission: The ID (name), dict representing the properties or :class:`Permission`
             instance of the permission to be replaced.
+        :type permission: Union[str, Dict[str, Any], ~azure.cosmos.Permission]
         :param body: A dict-like object representing the permission to replace.
-        :keyword Callable response_hook: A callable invoked with the response metadata.
-        :returns: A dict representing the permission after replace went through.
+        :type body: Dict[str, Any]
+        :keyword response_hook: A callable invoked with the response metadata.
+        :paramtype response_hook: Callable[[Dict[str, str], Dict[str, Any]], Any]
         :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: If the replace failed or the permission
             with given id does not exist.
-        :rtype: dict[str, Any]
+        :returns: A permission object representing the permission after the replace went through.
+        :rtype: ~azure.cosmos.Permission
         """
         request_options = build_options(kwargs)
         response_hook = kwargs.pop('response_hook', None)
@@ -266,7 +284,7 @@ async def replace_permission(self, permission, body, **kwargs):
         if response_hook:
             response_hook(self.client_connection.last_response_headers, permission_resp)
 
-        return _permission(
+        return Permission(
             id=permission_resp["id"],
             user_link=self.user_link,
             permission_mode=permission_resp["permissionMode"],
@@ -275,15 +293,16 @@ async def replace_permission(self, permission, body, **kwargs):
         )
 
     @distributed_trace_async
-    async def delete_permission(self, permission, **kwargs):
-        # type: (Union[str, Dict[str, Any], Permission], Any) -> None
+    async def delete_permission(self, permission: Union[str, Dict[str, Any], Permission], **kwargs: Any) -> None:
         """Delete the specified permission from the user.
 
         If the permission does not already exist, an exception is raised.
 
         :param permission: The ID (name), dict representing the properties or :class:`Permission`
             instance of the permission to be deleted.
-        :keyword Callable response_hook: A callable invoked with the response metadata.
+        :type permission: Union[str, Dict[str, Any], ~azure.cosmos.Permission]
+        :keyword response_hook: A callable invoked with the response metadata.
+        :paramtype response_hook: Callable[[Dict[str, str], None], Any]
         :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: The permission wasn't deleted successfully.
         :raises ~azure.cosmos.exceptions.CosmosResourceNotFoundError: The permission does not exist for the user.
         :rtype: None

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

@@ -340,7 +340,7 @@ def query_items(
             For accounts configured to use the integrated cache, using Session or Eventual consistency,
             responses are guaranteed to be no staler than this value.
         :returns: An Iterable of items (dicts).
-        :rtype: Iterable[dict[str, Any]]
+        :rtype: ItemPaged[dict[str, Any]]
 
         .. admonition:: Example:
 

sdk/cosmos/azure-cosmos/azure/cosmos/cosmos_client.py

@@ -136,7 +136,7 @@ class CosmosClient(object):
 
     :param str url: The URL of the Cosmos DB account.
     :param credential: Can be the account key, or a dictionary of resource tokens.
-    :type credential: str or dict[str, str]
+    :type credential: Union[str, Dict[str, str], ~azure.core.credentials.TokenCredential]
     :param str consistency_level: Consistency level to use for the session. The default value is None (Account level).
     :keyword int timeout: An absolute timeout in seconds, for the combined HTTP request and response processing.
     :keyword int request_timeout: The HTTP request timeout in milliseconds.