Merge pull request #210085 from ggailey777/pystein

[Functions] Python v2 examples and decorators in binding refs

Author: JamesJBarnett

.openpublishing.redirection.json

@@ -7548,6 +7548,11 @@
             "redirect_url": "/azure/reliability/reliability-functions",
             "redirect_document_id": false
         },
+        {
+            "source_path_from_root": "/articles/azure-functions/functions-bindings-triggers-python.md",
+            "redirect_url": "/azure/azure-functions/functions-reference-python?pivots=python-mode-decorators#triggers-and-inputs",
+            "redirect_document_id": false
+        },
         {
             "source_path_from_root": "/articles/azure-government/documentation-government-k8.md",
             "redirect_url": "/azure/azure-government",

articles/azure-functions/durable/durable-functions-bindings.md

@@ -2,7 +2,7 @@
 title: Azure Cosmos DB input binding for Functions 2.x and higher
 description: Learn to use the Azure Cosmos DB input binding in Azure Functions.
 ms.topic: reference
-ms.date: 03/04/2022
+ms.date: 03/02/2023
 ms.devlang: csharp, java, javascript, powershell, python
 ms.custom: devx-track-csharp, devx-track-python, ignite-2022
 zone_pivot_groups: programming-languages-set-functions-lang-workers
@@ -18,6 +18,23 @@ For information on setup and configuration details, see the [overview](./functio
 > When the collection is [partitioned](../cosmos-db/partitioning-overview.md#logical-partitions), lookup operations must also specify the partition key value.
 >
 
+::: zone pivot="programming-language-python"
+Azure Functions supports two programming models for Python. The way that you define your bindings depends on your chosen programming model.
+
+# [v2](#tab/python-v2)
+The Python v2 programming model lets you define bindings using decorators directly in your Python function code. For more information, see the [Python developer guide](functions-reference-python.md?pivots=python-mode-decorators#programming-model).
+
+# [v1](#tab/python-v1)
+The Python v1 programming model requires you to define bindings in a separate *function.json* file in the function folder. For more information, see the [Python developer guide](functions-reference-python.md?pivots=python-mode-configuration#programming-model).
+
+---
+
+This article supports both programming models.
+
+> [!IMPORTANT]
+> The Python v2 programming model is currently in preview.
+::: zone-end
+
 ## Example
 
 Unless otherwise noted, examples in this article target version 3.x of the [Azure Cosmos DB extension](functions-bindings-cosmosdb-v2.md). For use with extension version 4.x, you need to replace the string `collection` in property and attribute names with `container`. 
@@ -1505,9 +1522,45 @@ This section contains the following examples that read a single document by spec
 
 <a id="queue-trigger-look-up-id-from-json-python"></a>
 
+The examples depend on whether you use the [v1 or v2 Python programming model](functions-reference-python.md).
+
 ### Queue trigger, look up ID from JSON
 
-The following example shows an Azure Cosmos DB input binding in a *function.json* file and a [Python function](functions-reference-python.md) that uses the binding. The function reads a single document and updates the document's text value.
+The following example shows an Azure Cosmos DB input binding. The function reads a single document and updates the document's text value. 
+
+# [v2](#tab/python-v2)
+
+```python
+import logging
+import azure.functions as func
+
+app = func.FunctionApp()
+
+@app.queue_trigger(arg_name="msg", 
+                   queue_name="outqueue", 
+                   connection="AzureWebJobsStorage")
+@app.cosmos_db_input(arg_name="documents", 
+                     database_name="MyDatabase",
+                     collection_name="MyCollection",
+                     id="{msg.payload_property}",
+                     partition_key="{msg.payload_property}",
+                     connection_string_setting="MyAccount_COSMOSDB")
+@app.cosmos_db_output(arg_name="outputDocument", 
+                      database_name="MyDatabase",
+                      collection_name="MyCollection",
+                      connection_string_setting="MyAccount_COSMOSDB")
+def test_function(msg: func.QueueMessage,
+                  inputDocument: func.DocumentList, 
+                  outputDocument: func.Out[func.Document]):
+     document = documents[id]
+     document["text"] = "This was updated!"
+     doc = inputDocument[0]
+     doc["text"] = "This was updated!"
+     outputDocument.set(doc)
+     print(f"Updated document.")
+```
+
+# [v1](#tab/python-v1)
 
 Here's the binding data in the *function.json* file:
 
@@ -1548,11 +1601,20 @@ def main(queuemsg: func.QueueMessage, documents: func.DocumentList) -> func.Docu
         return document
 ```
 
+---
+
 <a id="http-trigger-look-up-id-from-query-string-python"></a>
 
 ### HTTP trigger, look up ID from query string
 
-The following example shows a [Python function](functions-reference-python.md) that retrieves a single document. The function is triggered by an HTTP request that uses a query string to specify the ID and partition key value to look up. That ID and partition key value are used to retrieve a `ToDoItem` document from the specified database and collection.
+The following example shows a function that retrieves a single document. The function is triggered by an HTTP request that uses a query string to specify the ID and partition key value to look up. That ID and partition key value are used to retrieve a `ToDoItem` document from the specified database and collection.
+
+# [v2](#tab/python-v2)
+
+No equivalent sample for v2 at this time.
+
+# [v1](#tab/python-v1)
+
 
 Here's the *function.json* file:
 
@@ -1605,11 +1667,19 @@ def main(req: func.HttpRequest, todoitems: func.DocumentList) -> str:
     return 'OK'
 ```
 
+---
+
 <a id="http-trigger-look-up-id-from-route-data-python"></a>
 
 ### HTTP trigger, look up ID from route data
 
-The following example shows a [Python function](functions-reference-python.md) that retrieves a single document. The function is triggered by an HTTP request that uses route data to specify the ID and partition key value to look up. That ID and partition key value are used to retrieve a `ToDoItem` document from the specified database and collection.
+The following example shows a function that retrieves a single document. The function is triggered by an HTTP request that uses route data to specify the ID and partition key value to look up. That ID and partition key value are used to retrieve a `ToDoItem` document from the specified database and collection.
+
+# [v2](#tab/python-v2)
+
+No equivalent sample for v2 at this time.
+
+# [v1](#tab/python-v1)
 
 Here's the *function.json* file:
 
@@ -1663,14 +1733,22 @@ def main(req: func.HttpRequest, todoitems: func.DocumentList) -> str:
     return 'OK'
 ```
 
+---
+
 <a id="queue-trigger-get-multiple-docs-using-sqlquery-python"></a>
 
 ### Queue trigger, get multiple docs, using SqlQuery
 
-The following example shows an Azure Cosmos DB input binding in a *function.json* file and a [Python function](functions-reference-python.md) that uses the binding. The function retrieves multiple documents specified by a SQL query, using a queue trigger to customize the query parameters.
+The following example shows an Azure Cosmos DB input binding Python function that uses the binding. The function retrieves multiple documents specified by a SQL query, using a queue trigger to customize the query parameters.
 
 The queue trigger provides a parameter `departmentId`. A queue message of `{ "departmentId" : "Finance" }` would return all records for the finance department.
 
+# [v2](#tab/python-v2)
+
+No equivalent sample for v2 at this time.
+
+# [v1](#tab/python-v1)
+
 Here's the binding data in the *function.json* file:
 
 ```json
@@ -1685,6 +1763,8 @@ Here's the binding data in the *function.json* file:
 }
 ```
 
+---
+
 ::: zone-end  
 ::: zone pivot="programming-language-csharp"
 ## Attributes
@@ -1718,6 +1798,26 @@ Both [in-process](functions-dotnet-class-library.md) and [isolated worker proces
 ---
 
 ::: zone-end  
+
+::: zone pivot="programming-language-python"
+## Decorators
+
+_Applies only to the Python v2 programming model._
+
+For Python v2 functions defined using a decorator, the following properties on the `cosmos_db_input`:
+
+| Property    | Description |
+|-------------|-----------------------------|
+|`arg_name` | The variable name used in function code that represents the list of documents with changes. |
+|`database_name`  | The name of the Azure Cosmos DB database with the collection being monitored. |
+|`collection_name`  | The name of the Azure CosmosDB collection being monitored. |
+|`connection_string_setting` | The connection string of the Azure Cosmos DB being monitored. |
+|`partition_key` | The partition key of the Azure Cosmos DB being monitored. |
+|`id` | The ID of the document to retrieve. |
+
+For Python functions defined by using *function.json*, see the [Configuration](#configuration) section.
+::: zone-end
+
 ::: zone pivot="programming-language-java"  
 ## Annotations
 
@@ -1735,6 +1835,13 @@ From the [Java functions runtime library](/java/api/overview/azure/functions/run
 ::: zone-end  
 ::: zone pivot="programming-language-javascript,programming-language-powershell,programming-language-python"  
 ## Configuration
+::: zone-end
+
+::: zone pivot="programming-language-python" 
+_Applies only to the Python v1 programming model._
+
+::: zone-end
+::: zone pivot="programming-language-javascript,programming-language-powershell,programming-language-python"  
 
 The following table explains the binding configuration properties that you set in the *function.json* file, where properties differ by extension version:  
 

articles/azure-functions/functions-bindings-cosmosdb-v2-input.md

@@ -2,7 +2,7 @@
 title: Azure Cosmos DB output binding for Functions 2.x and higher
 description: Learn to use the Azure Cosmos DB output binding in Azure Functions.
 ms.topic: reference
-ms.date: 03/04/2022
+ms.date: 03/02/2023
 ms.devlang: csharp, java, javascript, powershell, python
 ms.custom: devx-track-csharp, devx-track-python, ignite-2022
 zone_pivot_groups: programming-languages-set-functions-lang-workers
@@ -14,6 +14,23 @@ The Azure Cosmos DB output binding lets you write a new document to an Azure Cos
 
 For information on setup and configuration details, see the [overview](./functions-bindings-cosmosdb-v2.md).
 
+::: zone pivot="programming-language-python"
+Azure Functions supports two programming models for Python. The way that you define your bindings depends on your chosen programming model.
+
+# [v2](#tab/python-v2)
+The Python v2 programming model lets you define bindings using decorators directly in your Python function code. For more information, see the [Python developer guide](functions-reference-python.md?pivots=python-mode-decorators#programming-model).
+
+# [v1](#tab/python-v1)
+The Python v1 programming model requires you to define bindings in a separate *function.json* file in the function folder. For more information, see the [Python developer guide](functions-reference-python.md?pivots=python-mode-configuration#programming-model).
+
+---
+
+This article supports both programming models.
+
+> [!IMPORTANT]
+> The Python v2 programming model is currently in preview.
+::: zone-end
+
 ## Example
 
 Unless otherwise noted, examples in this article target version 3.x of the [Azure Cosmos DB extension](functions-bindings-cosmosdb-v2.md). For use with extension version 4.x, you need to replace the string `collection` in property and attribute names with `container`.
@@ -542,7 +559,7 @@ For bulk insert form the objects first and then run the stringify function. Here
 ::: zone-end  
 ::: zone pivot="programming-language-powershell"  
 
-The following example show how to write data to Azure Cosmos DB using an output binding. The binding is declared in the function's configuration file (_functions.json_), and take data from a queue message and writes out to an Azure Cosmos DB document.
+The following example shows how to write data to Azure Cosmos DB using an output binding. The binding is declared in the function's configuration file (_functions.json_), and takes data from a queue message and writes out to an Azure Cosmos DB document.
 
 ```json
 { 
@@ -572,7 +589,29 @@ Push-OutputBinding -Name EmployeeDocument -Value @{
 ::: zone-end  
 ::: zone pivot="programming-language-python"  
 
-The following example demonstrates how to write a document to an Azure Cosmos DB database as the output of a function.
+The following example demonstrates how to write a document to an Azure Cosmos DB database as the output of a function. The example depends on whether you use the [v1 or v2 Python programming model](functions-reference-python.md).
+
+# [v2](#tab/python-v2)
+
+```python
+import logging
+import azure.functions as func
+
+app = func.FunctionApp()
+
+@app.route()
+@app.cosmos_db_output(arg_name="documents", 
+                      database_name="DB_NAME",
+                      collection_name="COLLECTION_NAME",
+                      create_if_not_exists=True,
+                      connection_string_setting="CONNECTION_SETTING")
+def main(req: func.HttpRequest, documents: func.Out[func.Document]) -> func.HttpResponse:
+    request_body = req.get_body()
+    documents.set(func.Document.from_json(request_body))
+    return 'OK'
+```
+
+# [v1](#tab/python-v1)
 
 The binding definition is defined in *function.json* where *type* is set to `cosmosDB`.
 
@@ -622,6 +661,8 @@ def main(req: func.HttpRequest, doc: func.Out[func.Document]) -> func.HttpRespon
     return 'OK'
 ```
 
+---
+
 ::: zone-end 
 ::: zone pivot="programming-language-csharp" 
 ## Attributes
@@ -654,6 +695,25 @@ Both [in-process](functions-dotnet-class-library.md) and [isolated worker proces
 
 ---
 ::: zone-end  
+
+::: zone pivot="programming-language-python"
+## Decorators
+
+_Applies only to the Python v2 programming model._
+
+For Python v2 functions defined using a decorator, the following properties on the `cosmos_db_output`:
+
+| Property    | Description |
+|-------------|-----------------------------|
+|`arg_name` | The variable name used in function code that represents the list of documents with changes. |
+|`database_name`  | The name of the Azure Cosmos DB database with the collection being monitored. |
+|`collection_name`  | The name of the Azure CosmosDB collection being monitored. |
+|`create_if_not_exists`  | A Boolean value that indicates whether the database and collection should be created if they do not exist. |
+|`connection_string_setting` | The connection string of the Azure Cosmos DB being monitored. |
+
+For Python functions defined by using *function.json*, see the [Configuration](#configuration) section.
+::: zone-end
+
 ::: zone pivot="programming-language-java"  
 ## Annotations
 
@@ -672,6 +732,13 @@ From the [Java functions runtime library](/java/api/overview/azure/functions/run
 ::: zone-end  
 ::: zone pivot="programming-language-javascript,programming-language-powershell,programming-language-python"  
 ## Configuration
+::: zone-end
+
+::: zone pivot="programming-language-python" 
+_Applies only to the Python v1 programming model._
+
+::: zone-end
+::: zone pivot="programming-language-javascript,programming-language-powershell,programming-language-python"  
 
 The following table explains the binding configuration properties that you set in the *function.json* file, where properties differ by extension version: