[Cosmos] More docs cleanup

doc/sphinx/ref/azure.cosmos.rst

@@ -6,19 +6,9 @@ Submodules
 
 .. toctree::
 
-   azure.cosmos.auth
-   azure.cosmos.container
-   azure.cosmos.cosmos_client
-   azure.cosmos.database
    azure.cosmos.diagnostics
-   azure.cosmos.documents
    azure.cosmos.errors
    azure.cosmos.http_constants
-   azure.cosmos.offer
-   azure.cosmos.partition_key
-   azure.cosmos.permission
-   azure.cosmos.scripts
-   azure.cosmos.user
 
 Module contents
 ---------------

sdk/cosmos/azure-cosmos/MANIFEST.in

@@ -2,8 +2,5 @@ include README.md
 include HISTORY.md
 include LICENSE.txt
 include azure/__init__.py
-recursive-include doc *.bat
-recursive-include doc *.py
-recursive-include doc *.rst
-recursive-include doc Makefile
+include samples/examples.py
 recursive-include test *.py

sdk/cosmos/azure-cosmos/README.md

@@ -63,7 +63,7 @@ export ACCOUNT_KEY=$(az cosmosdb list-keys --resource-group $RES_GROUP --name $A
 Once you've populated the `ACCOUNT_URI` and `ACCOUNT_KEY` environment variables, you can create the [CosmosClient][ref_cosmosclient].
 
 ```Python
-from azure.cosmos import CosmosClient, Container, Database, PartitionKey, errors
+from azure.cosmos import CosmosClient, PartitionKey, errors
 
 import os
 url = os.environ['ACCOUNT_URI']
@@ -271,14 +271,14 @@ For more extensive documentation on the Cosmos DB service, see the [Azure Cosmos
 [cosmos_sql_queries]: https://docs.microsoft.com/azure/cosmos-db/how-to-sql-query
 [cosmos_ttl]: https://docs.microsoft.com/azure/cosmos-db/time-to-live
 [python]: https://www.python.org/downloads/
-[ref_container_delete_item]: https://azure.github.io/azure-sdk-for-python/ref/azure.cosmos.container.html#azure.cosmos.container.ContainerProxy.delete_item
-[ref_container_query_items]: https://azure.github.io/azure-sdk-for-python/ref/azure.cosmos.container.html#azure.cosmos.container.ContainerProxy.query_items
-[ref_container_upsert_item]: https://azure.github.io/azure-sdk-for-python/ref/azure.cosmos.container.html#azure.cosmos.container.ContainerProxy.upsert_item
-[ref_container]: https://azure.github.io/azure-sdk-for-python/ref/azure.cosmos.container.html
+[ref_container_delete_item]: https://azure.github.io/azure-sdk-for-python/ref/azure.cosmos.html#azure.cosmos.ContainerProxy.delete_item
+[ref_container_query_items]: https://azure.github.io/azure-sdk-for-python/ref/azure.cosmos.html#azure.cosmos.ContainerProxy.query_items
+[ref_container_upsert_item]: https://azure.github.io/azure-sdk-for-python/ref/azure.cosmos.html#azure.cosmos.ContainerProxy.upsert_item
+[ref_container]: https://azure.github.io/azure-sdk-for-python/ref/azure.cosmos.html#azure.cosmos.ContainerProxy
 [ref_cosmos_sdk]: https://azure.github.io/azure-sdk-for-python/ref/azure.cosmos.html
-[ref_cosmosclient_create_database]: https://azure.github.io/azure-sdk-for-python/ref/azure.cosmos.cosmos_client.html#azure.cosmos.cosmos_client.CosmosClient.create_database
-[ref_cosmosclient]: https://azure.github.io/azure-sdk-for-python/ref/azure.cosmos.cosmos_client.html
-[ref_database]: https://azure.github.io/azure-sdk-for-python/ref/azure.cosmos.database.html
+[ref_cosmosclient_create_database]: https://azure.github.io/azure-sdk-for-python/ref/azure.cosmos.html#azure.cosmos.CosmosClient.create_database
+[ref_cosmosclient]: https://azure.github.io/azure-sdk-for-python/ref/azure.cosmos.html#azure.cosmos.CosmosClient
+[ref_database]: https://azure.github.io/azure-sdk-for-python/ref/azure.cosmos.html#azure.cosmos.DatabaseProxy
 [ref_httpfailure]: https://azure.github.io/azure-sdk-for-python/ref/azure.cosmos.errors.html#azure.cosmos.errors.CosmosHttpResponseError
 [sample_database_mgmt]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/cosmos/azure-cosmos/samples/DatabaseManagement
 [sample_document_mgmt]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/cosmos/azure-cosmos/samples/DocumentManagement

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

@@ -25,6 +25,7 @@
 from .database import DatabaseProxy
 from .user import UserProxy
 from .scripts import ScriptsProxy
+from .offer import Offer
 from .documents import (
     ConsistencyLevel,
     DataType,
@@ -35,6 +36,7 @@
     SSLConfiguration,
     TriggerOperation,
     TriggerType,
+    DatabaseAccount,
 )
 from .partition_key import PartitionKey
 from .permission import Permission
@@ -48,6 +50,8 @@
     "Permission",
     "ScriptsProxy",
     "UserProxy",
+    "Offer",
+    "DatabaseAccount",
     "ConsistencyLevel",
     "DataType",
     "IndexKind",

sdk/cosmos/azure-cosmos/azure/cosmos/_cosmos_client_connection.py

@@ -36,8 +36,8 @@
     UserAgentPolicy,
     NetworkTraceLoggingPolicy,
     CustomHookPolicy,
+    DistributedTracingPolicy,
     ProxyPolicy)
-from azure.core.pipeline.policies.distributed_tracing import DistributedTracingPolicy  # type: ignore
 
 from . import _base as base
 from . import documents

sdk/cosmos/azure-cosmos/azure/cosmos/_retry_utility.py

@@ -160,9 +160,9 @@ def send(self, request):
         :type request: ~azure.core.pipeline.PipelineRequest
         :return: Returns the PipelineResponse or raises error if maximum retries exceeded.
         :rtype: ~azure.core.pipeline.PipelineResponse
-        :raises: ~azure.core.exceptions.AzureError if maximum retries exceeded.
-        :raises: ~azure.cosmos.CosmosClientTimeoutError if specified timeout exceeded.
-        :raises: ~azure.core.exceptions.ClientAuthenticationError if authentication
+        :raises ~azure.core.exceptions.AzureError: Maximum retries exceeded.
+        :raises ~azure.cosmos.errors.CosmosClientTimeoutError: Specified timeout exceeded.
+        :raises ~azure.core.exceptions.ClientAuthenticationError: Authentication failed.
         """
         absolute_timeout = request.context.options.pop('timeout', None)
         per_request_timeout = request.context.options.pop('connection_timeout', 0)

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

@@ -127,8 +127,8 @@ def read(
         :param populate_quota_info: Enable returning collection storage quota information in response headers.
         :param request_options: Dictionary of additional properties to be used for the request.
         :param response_hook: a callable invoked with the response metadata
-        :raise `CosmosHttpResponseError`: Raised if the container couldn't be retrieved. This includes
-            if the container does not exist.
+        :raises ~azure.cosmos.errors.CosmosHttpResponseError: Raised if the container couldn't be retrieved.
+            This includes if the container does not exist.
         :returns: Dict representing the retrieved container.
         :rtype: dict[str, Any]
         """
@@ -173,12 +173,12 @@ def read_item(
         :param request_options: Dictionary of additional properties to be used for the request.
         :param response_hook: a callable invoked with the response metadata
         :returns: Dict representing the item to be retrieved.
-        :raise `CosmosHttpResponseError`: If the given item couldn't be retrieved.
+        :raises ~azure.cosmos.errors.CosmosHttpResponseError: The given item couldn't be retrieved.
         :rtype: dict[str, Any]
 
         .. admonition:: Example:
 
-            .. literalinclude:: ../../samples/examples.py
+            .. literalinclude:: ../samples/examples.py
                 :start-after: [START update_item]
                 :end-before: [END update_item]
                 :language: python
@@ -323,15 +323,15 @@ def query_items(
 
         .. admonition:: Example:
 
-            .. literalinclude:: ../../samples/examples.py
+            .. literalinclude:: ../samples/examples.py
                 :start-after: [START query_items]
                 :end-before: [END query_items]
                 :language: python
                 :dedent: 0
                 :caption: Get all products that have not been discontinued:
                 :name: query_items
 
-            .. literalinclude:: ../../samples/examples.py
+            .. literalinclude:: ../samples/examples.py
                 :start-after: [START query_items_param]
                 :end-before: [END query_items_param]
                 :language: python
@@ -392,7 +392,8 @@ def replace_item(
         :param request_options: Dictionary of additional properties to be used for the request.
         :param response_hook: a callable invoked with the response metadata
         :returns: A dict representing the item after replace went through.
-        :raise `CosmosHttpResponseError`: If the replace failed or the item with given id does not exist.
+        :raises ~azure.cosmos.errors.CosmosHttpResponseError: The replace failed or the item with
+            given id does not exist.
         :rtype: dict[str, Any]
         """
         item_link = self._get_document_link(item)
@@ -437,7 +438,7 @@ def upsert_item(
         :param request_options: Dictionary of additional properties to be used for the request.
         :param response_hook: a callable invoked with the response metadata
         :returns: A dict representing the upserted item.
-        :raise `CosmosHttpResponseError`: If the given item could not be upserted.
+        :raises ~azure.cosmos.errors.CosmosHttpResponseError: The given item could not be upserted.
         :rtype: dict[str, Any]
         """
         request_options = build_options(kwargs)
@@ -482,7 +483,7 @@ def create_item(
         :param request_options: Dictionary of additional properties to be used for the request.
         :param response_hook: a callable invoked with the response metadata
         :returns: A dict representing the new item.
-        :raises `CosmosHttpResponseError`: If item with the given ID already exists.
+        :raises ~azure.cosmos.errors.CosmosHttpResponseError: Item with the given ID already exists.
         :rtype: dict[str, Any]
         """
         request_options = build_options(kwargs)
@@ -529,8 +530,8 @@ def delete_item(
         :param post_trigger_include: trigger id to be used as post operation trigger.
         :param request_options: Dictionary of additional properties to be used for the request.
         :param response_hook: a callable invoked with the response metadata
-        :raises `CosmosHttpResponseError`: The item wasn't deleted successfully. If the item does not
-            exist in the container, a `404` error is returned.
+        :raises ~azure.cosmos.errors.CosmosHttpResponseError: The item wasn't deleted successfully.
+        :raises ~azure.cosmos.errors.CosmosResourceNotFoundError: The item does not exist in the container.
         :rtype: None
         """
         request_options = build_options(kwargs)
@@ -557,8 +558,9 @@ def read_offer(self, **kwargs):
 
         :param response_hook: a callable invoked with the response metadata
         :returns: Offer for the container.
-        :raise CosmosHttpResponseError: If no offer exists for the container or if the offer could not be retrieved.
-        :rtype: ~azure.cosmos.offer.Offer
+        :raises ~azure.cosmos.errors.CosmosHttpResponseError: No offer exists for the container or
+            the offer could not be retrieved.
+        :rtype: ~azure.cosmos.Offer
         """
         response_hook = kwargs.pop('response_hook', None)
         properties = self._get_properties()
@@ -587,8 +589,9 @@ def replace_throughput(self, throughput, **kwargs):
         :param throughput: The throughput to be set (an integer).
         :param response_hook: a callable invoked with the response metadata
         :returns: Offer for the container, updated with new throughput.
-        :raise CosmosHttpResponseError: If no offer exists for the container or if the offer could not be updated.
-        :rtype: ~azure.cosmos.offer.Offer
+        :raises ~azure.cosmos.errors.CosmosHttpResponseError: No offer exists for the container
+            or the offer could not be updated.
+        :rtype: ~azure.cosmos.Offer
         """
         response_hook = kwargs.pop('response_hook', None)
         properties = self._get_properties()
@@ -691,7 +694,7 @@ def get_conflict(self, conflict, partition_key, **kwargs):
         :param request_options: Dictionary of additional properties to be used for the request.
         :param response_hook: a callable invoked with the response metadata
         :returns: A dict representing the retrieved conflict.
-        :raise `CosmosHttpResponseError`: If the given conflict couldn't be retrieved.
+        :raises ~azure.cosmos.errors.CosmosHttpResponseError: The given conflict couldn't be retrieved.
         :rtype: dict[str, Any]
         """
         request_options = build_options(kwargs)
@@ -716,8 +719,8 @@ def delete_conflict(self, conflict, partition_key, **kwargs):
         :param partition_key: Partition key for the conflict to delete.
         :param request_options: Dictionary of additional properties to be used for the request.
         :param response_hook: a callable invoked with the response metadata
-        :raises `CosmosHttpResponseError`: The conflict wasn't deleted successfully. If the conflict
-            does not exist in the container, a `404` error is returned.
+        :raises ~azure.cosmos.errors.CosmosHttpResponseError: The conflict wasn't deleted successfully.
+        :raises ~azure.cosmos.errors.CosmosResourceNotFoundError: The conflict does not exist in the container.
         :rtype: None
         """
         request_options = build_options(kwargs)