[Cosmos] docs updates

sdk/cosmos/azure-cosmos/MANIFEST.in

@@ -1,5 +1,5 @@
 include README.md
-include changelog.md
+include HISTORY.md
 include LICENSE.txt
 include azure/__init__.py
 recursive-include doc *.bat

sdk/cosmos/azure-cosmos/README.md

@@ -79,7 +79,7 @@ Once you've initialized a [CosmosClient][ref_cosmosclient], you can interact wit
 
 * [Container][ref_container]: A container is a collection of JSON documents. You create (insert), read, update, and delete items in a container by using methods on the [ContainerProxy][ref_container] object.
 
-* [Item][ref_item]: An Item is the dictionary-like representation of a JSON document stored in a container. Each Item you add to a container must include an `id` key with a value that uniquely identifies the item within the container.
+* Item: An Item is the dictionary-like representation of a JSON document stored in a container. Each Item you add to a container must include an `id` key with a value that uniquely identifies the item within the container.
 
 For more information about these resources, see [Working with Azure Cosmos databases, containers and items][cosmos_resources].
 
@@ -271,20 +271,19 @@ 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]: http://cosmosproto.westus.azurecontainer.io/#azure.cosmos.Container.delete_item
-[ref_container_query_items]: http://cosmosproto.westus.azurecontainer.io/#azure.cosmos.Container.query_items
-[ref_container_upsert_item]: http://cosmosproto.westus.azurecontainer.io/#azure.cosmos.Container.upsert_item
-[ref_container]: http://cosmosproto.westus.azurecontainer.io/#azure.cosmos.Container
-[ref_cosmos_sdk]: http://cosmosproto.westus.azurecontainer.io
-[ref_cosmosclient_create_database]: http://cosmosproto.westus.azurecontainer.io/#azure.cosmos.CosmosClient.create_database
-[ref_cosmosclient]: http://cosmosproto.westus.azurecontainer.io/#azure.cosmos.CosmosClient
-[ref_database]: http://cosmosproto.westus.azurecontainer.io/#azure.cosmos.Database
-[ref_httpfailure]: https://docs.microsoft.com/python/api/azure-cosmos/azure.cosmos.errors.CosmosHttpResponseError
-[ref_item]: http://cosmosproto.westus.azurecontainer.io/#azure.cosmos.Item
-[sample_database_mgmt]: https://github.com/binderjoe/cosmos-python-prototype/blob/master/examples/databasemanagementsample.py
-[sample_document_mgmt]: https://github.com/binderjoe/cosmos-python-prototype/blob/master/examples/documentmanagementsample.py
-[sample_examples_misc]: https://github.com/binderjoe/cosmos-python-prototype/blob/master/examples/examples.py
-[source_code]: https://github.com/binderjoe/cosmos-python-prototype
+[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_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_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
+[sample_examples_misc]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/cosmos/azure-cosmos/samples/examples.py
+[source_code]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/cosmos/azure-cosmos
 [venv]: https://docs.python.org/3/library/venv.html
 [virtualenv]: https://virtualenv.pypa.io
 

sdk/cosmos/azure-cosmos/samples/examples.py

@@ -0,0 +1,145 @@
+# These examples are ingested by the documentation system, and are
+# displayed in the SDK reference documentation. When editing these
+# example snippets, take into consideration how this might affect
+# the readability and usability of the reference documentation.
+
+# All interaction with Cosmos DB starts with an instance of the CosmosClient
+# [START create_client]
+from azure.cosmos import errors, CosmosClient, PartitionKey
+
+import os
+
+url = os.environ["ACCOUNT_URI"]
+key = os.environ["ACCOUNT_KEY"]
+client = CosmosClient(url, key)
+# [END create_client]
+
+# Create a database in the account using the CosmosClient,
+# specifying that the operation shouldn't throw an exception
+# if a database with the given ID already exists.
+# [START create_database]
+database_name = "testDatabase"
+try:
+    database = client.create_database(id=database_name)
+except errors.CosmosResourceExistsError:
+    database = client.get_database_client(database=database_name)
+# [END create_database]
+
+# Create a container, handling the exception if a container with the
+# same ID (name) already exists in the database.
+# [START create_container]
+container_name = "products"
+try:
+    container = database.create_container(
+        id=container_name, partition_key=PartitionKey(path="/productName")
+    )
+except errors.CosmosResourceExistsError:
+    container = database.get_container_client(container_name)
+# [END create_container]
+
+# Create a container with custom settings. This example
+# creates a container with a custom partition key.
+# [START create_container_with_settings]
+customer_container_name = "customers"
+try:
+    customer_container = database.create_container(
+        id=customer_container_name,
+        partition_key=PartitionKey(path="/city"),
+        default_ttl=200,
+    )
+except errors.CosmosResourceExistsError:
+    customer_container = database.get_container_client(customer_container_name)
+# [END create_container_with_settings]
+
+# Retrieve a container by walking down the resource hierarchy
+# (client->database->container), handling the exception generated
+# if no container with the specified ID was found in the database.
+# [START get_container]
+database = client.get_database_client(database_name)
+container = database.get_container_client(container_name)
+# [END get_container]
+
+# [START list_containers]
+database = client.get_database_client(database_name)
+for container in database.list_containers():
+    print(f"Container ID: {container.id}")
+# [END list_containers]
+
+# Insert new items by defining a dict and calling Container.upsert_item
+# [START upsert_items]
+container = database.get_container_client(container_name)
+for i in range(1, 10):
+    container.upsert_item(
+        dict(id=f"item{i}", productName="Widget", productModel=f"Model {i}")
+    )
+# [END upsert_items]
+
+# Modify an existing item in the container
+# [START update_item]
+item = container.read_item("item2", partition_key="Widget")
+item["productModel"] = "DISCONTINUED"
+updated_item = container.upsert_item(item)
+# [END update_item]
+
+# Query the items in a container using SQL-like syntax. This example
+# gets all items whose product model hasn't been discontinued.
+# [START query_items]
+import json
+
+for item in container.query_items(
+    query='SELECT * FROM products p WHERE p.productModel <> "DISCONTINUED"',
+    enable_cross_partition_query=True,
+):
+    print(json.dumps(item, indent=True))
+# [END query_items]
+
+# Parameterized queries are also supported. This example
+# gets all items whose product model has been discontinued.
+# [START query_items_param]
+discontinued_items = container.query_items(
+    query='SELECT * FROM products p WHERE p.productModel = @model AND p.productName="Widget"',
+    parameters=[dict(name="@model", value="DISCONTINUED")],
+)
+for item in discontinued_items:
+    print(json.dumps(item, indent=True))
+# [END query_items_param]
+
+# Delete items from the container.
+# The Cosmos DB SQL API does not support 'DELETE' queries,
+# so deletes must be done with the delete_item method
+# on the container.
+# [START delete_items]
+for item in container.query_items(
+    query='SELECT * FROM products p WHERE p.productModel = "DISCONTINUED" AND p.productName="Widget"'
+):
+    container.delete_item(item, partition_key="Widget")
+# [END delete_items]
+
+# Retrieve the properties of a database
+# [START get_database_properties]
+properties = database.read()
+print(json.dumps(properties, indent=True))
+# [END get_database_properties]
+
+# Modify the properties of an existing container
+# This example sets the default time to live (TTL) for items in the
+# container to 3600 seconds (1 hour). An item in container is deleted
+# when the TTL has elapsed since it was last edited.
+# [START reset_container_properties]
+# Set the TTL on the container to 3600 seconds (one hour)
+database.replace_container(container, partition_key=PartitionKey(path='/productName'), default_ttl=3600)
+
+# Display the new TTL setting for the container
+container_props = database.get_container_client(container_name).read()
+print(f"New container TTL: {json.dumps(container_props['defaultTtl'])}")
+# [END reset_container_properties]
+
+# Create a user in the database.
+# [START create_user]
+try:
+    database.create_user(dict(id="Walter Harp"))
+except errors.CosmosResourceExistsError:
+    print("A user with that ID already exists.")
+except errors.CosmosHttpResponseError as failure:
+    print(f"Failed to create user. Status code:{failure.status_code}")
+# [END create_user]

sdk/cosmos/azure-cosmos/setup.py

@@ -27,7 +27,7 @@
 
 with open("README.md", encoding="utf-8") as f:
     README = f.read()
-with open("changelog.md", encoding="utf-8") as f:
+with open("HISTORY.md", encoding="utf-8") as f:
     HISTORY = f.read()
 
 setup(
@@ -73,6 +73,7 @@
       'azure-core<2.0.0,>=1.0.0b3'
     ],
     extras_require={
+      ":python_version<'3.4'": ['enum34>=1.0.4'],
       ":python_version<'3.0'": ["azure-nspkg"],
       ":python_version<'3.5'": ["typing"]
     },