Merge pull request #300425 from hallvictoria/hallvictoria/python-updates

Adding Azure Functions Python samples

Author: JamesJBarnett

articles/azure-functions/functions-bindings-azure-sql-input.md

@@ -44,7 +44,7 @@ The examples refer to a `ToDoItem` class and a corresponding database table:
 
 :::code language="sql" source="~/functions-sql-todo-sample/sql/create.sql" range="1-7":::
 
-To return [multiple output bindings](./dotnet-isolated-process-guide.md#multiple-output-bindings) in our samples, we'll create a custom return type:
+To return [multiple output bindings](./dotnet-isolated-process-guide.md#multiple-output-bindings) in our samples, we create a custom return type:
 
 ```cs
 public static class OutputType
@@ -59,7 +59,7 @@ public static class OutputType
 
 ### HTTP trigger, write one record
 
-The following example shows a [C# function](functions-dotnet-class-library.md) that adds a record to a database, using data provided in an HTTP POST request as a JSON body.  The return object is the `OutputType` class we created to handle both an HTTP response and the SQL output binding.
+The following example shows a [C# function](functions-dotnet-class-library.md) that adds a record to a database, using data provided in an HTTP POST request as a JSON body. The return object is the `OutputType` class we created to handle both an HTTP response and the SQL output binding.
 
 ```cs
 using System;
@@ -133,7 +133,7 @@ CREATE TABLE dbo.RequestLog (
 )
 ```
 
-To use an additional output binding, we add a class for `RequestLog` and  modify our `OutputType` class:
+To use an extra output binding, we add a class for `RequestLog` and  modify our `OutputType` class:
 
 ```cs
 using System;
@@ -378,7 +378,7 @@ public class ToDoItem {
 <a id="http-trigger-write-record-to-table-java"></a>
 ### HTTP trigger, write a record to a table
 
-The following example shows a SQL output binding in a Java function that adds a record to a table, using data provided in an HTTP POST request as a JSON body.  The function takes an additional dependency on the [com.google.code.gson](https://github.com/google/gson) library to parse the JSON body.
+The following example shows a SQL output binding in a Java function that adds a record to a table, using data provided in an HTTP POST request as a JSON body. The function takes another dependency on the [com.google.code.gson](https://github.com/google/gson) library to parse the JSON body.
 
 ```xml
 <dependency>
@@ -423,7 +423,7 @@ public class PostToDo {
 <a id="http-trigger-write-to-two-tables-java"></a>
 ### HTTP trigger, write to two tables
 
-The following example shows a SQL output binding in a JavaS function that adds records to a database in two different tables (`dbo.ToDo` and `dbo.RequestLog`), using data provided in an HTTP POST request as a JSON body and multiple output bindings.  The function takes an additional dependency on the [com.google.code.gson](https://github.com/google/gson) library to parse the JSON body.
+The following example shows a SQL output binding in a JavaS function that adds records to a database in two different tables (`dbo.ToDo` and `dbo.RequestLog`), using data provided in an HTTP POST request as a JSON body and multiple output bindings. The function takes another dependency on the [com.google.code.gson](https://github.com/google/gson) library to parse the JSON body.
 
 ```xml
 <dependency>
@@ -868,7 +868,6 @@ The following is sample python code for the function_app.py file:
 import json
 import logging
 import azure.functions as func
-from azure.functions.decorators.core import DataType
 
 app = func.FunctionApp()
 
@@ -1099,7 +1098,7 @@ The [C# library](functions-dotnet-class-library.md) uses the [SqlAttribute](http
 | Attribute property |Description|
 |---------|---------|
 | **CommandText** | Required. The name of the table being written to by the binding.  |
-| **ConnectionStringSetting** | Required. The name of an app setting that contains the connection string for the database to which data is being written. This isn't the actual connection string and must instead resolve to an environment variable. | 
+| **ConnectionStringSetting** | Required. The name of an app setting that contains the connection string for the database to which data is being written. This value isn't the actual connection string and must instead resolve to an environment variable. | 
 
 
 ::: zone-end  
@@ -1111,8 +1110,8 @@ In the [Java functions runtime library](/java/api/overview/azure/functions/runti
 
 | Element |Description|
 |---------|---------|
-| **commandText** | Required.  The name of the table being written to by the binding.  |
-| **connectionStringSetting** | Required. The name of an app setting that contains the connection string for the database to which data is being written. This isn't the actual connection string and must instead resolve to an environment variable.| 
+| **commandText** | Required. The name of the table being written to by the binding.  |
+| **connectionStringSetting** | Required. The name of an app setting that contains the connection string for the database to which data is being written. This value isn't the actual connection string and must instead resolve to an environment variable.| 
 |**name** |  Required. The unique name of the function binding. | 
 
 ::: zone-end  
@@ -1127,7 +1126,7 @@ The following table explains the properties that you can set on the `options` ob
 | Property | Description |
 |---------|----------------------|
 | **commandText** | Required. The name of the table being written to by the binding.  |
-| **connectionStringSetting** | Required. The name of an app setting that contains the connection string for the database to which data is being written. This isn't the actual connection string and must instead resolve to an environment variable. Optional keywords in the connection string value are [available to refine SQL bindings connectivity](./functions-bindings-azure-sql.md#sql-connection-string). |
+| **connectionStringSetting** | Required. The name of an app setting that contains the connection string for the database to which data is being written. This value isn't the actual connection string and must instead resolve to an environment variable. Optional keywords in the connection string value are [available to refine SQL bindings connectivity](./functions-bindings-azure-sql.md#sql-connection-string). |
 
 # [Model v3](#tab/nodejs-v3)
 
@@ -1139,7 +1138,7 @@ The following table explains the binding configuration properties that you set i
 |**direction** | Required. Must be set to `out`. |
 |**name** | Required. The name of the variable that represents the entity in function code. | 
 | **commandText** | Required. The name of the table being written to by the binding.  |
-| **connectionStringSetting** | Required. The name of an app setting that contains the connection string for the database to which data is being written. This isn't the actual connection string and must instead resolve to an environment variable. Optional keywords in the connection string value are [available to refine SQL bindings connectivity](./functions-bindings-azure-sql.md#sql-connection-string). |
+| **connectionStringSetting** | Required. The name of an app setting that contains the connection string for the database to which data is being written. This value isn't the actual connection string and must instead resolve to an environment variable. Optional keywords in the connection string value are [available to refine SQL bindings connectivity](./functions-bindings-azure-sql.md#sql-connection-string). |
 
 ---
 
@@ -1155,7 +1154,7 @@ The following table explains the binding configuration properties that you set i
 |**direction** | Required. Must be set to `out`. |
 |**name** | Required. The name of the variable that represents the entity in function code. | 
 | **commandText** | Required. The name of the table being written to by the binding.  |
-| **connectionStringSetting** | Required. The name of an app setting that contains the connection string for the database to which data is being written. This isn't the actual connection string and must instead resolve to an environment variable. Optional keywords in the connection string value are [available to refine SQL bindings connectivity](./functions-bindings-azure-sql.md#sql-connection-string). |
+| **connectionStringSetting** | Required. The name of an app setting that contains the connection string for the database to which data is being written. This value isn't the actual connection string and must instead resolve to an environment variable. Optional keywords in the connection string value are [available to refine SQL bindings connectivity](./functions-bindings-azure-sql.md#sql-connection-string). |
 
 ::: zone-end  
 
@@ -1169,7 +1168,7 @@ The `CommandText` property is the name of the table where the data is to be stor
 
 The output bindings use the T-SQL [MERGE](/sql/t-sql/statements/merge-transact-sql) statement which requires [SELECT](/sql/t-sql/statements/merge-transact-sql#permissions) permissions on the target database.
 
-If an exception occurs when a SQL output binding is executed then the function code stop executing.  This may result in an error code being returned, such as an HTTP trigger returning a 500 error code.  If the `IAsyncCollector` is used in a .NET function then the function code can handle exceptions throw by the call to `FlushAsync()`.
+If an exception occurs when a SQL output binding is executed, then the function code stops executing. This behavior may result in an error code being returned, such as an HTTP trigger returning a 500 error code. If the `IAsyncCollector` is used in a .NET function, then the function code can handle exceptions throw by the call to `FlushAsync()`.
 
 ## Next steps
 

articles/azure-functions/functions-bindings-azure-sql-output.md

@@ -444,7 +444,6 @@ The following is sample python code for the function_app.py file:
 import json
 import logging
 import azure.functions as func
-from azure.functions.decorators.core import DataType
 
 app = func.FunctionApp()
 

articles/azure-functions/functions-bindings-azure-sql-trigger.md

@@ -102,7 +102,7 @@ namespace CosmosDBSamplesV2
 
 ### Queue trigger, write one doc (v4 extension)
 
-Apps using [Azure Cosmos DB extension version 4.x](./functions-bindings-cosmosdb-v2.md?tabs=extensionv4) or higher will have different attribute properties which are shown below. The following example shows a [C# function](functions-dotnet-class-library.md) that adds a document to a database, using data provided in message from Queue storage.
+Apps using [Azure Cosmos DB extension version 4.x](./functions-bindings-cosmosdb-v2.md?tabs=extensionv4) or higher have different attribute properties which are shown below. The following example shows a [C# function](functions-dotnet-class-library.md) that adds a document to a database, using data provided in message from Queue storage.
 
 ```cs
 using Microsoft.Azure.WebJobs;
@@ -206,7 +206,7 @@ public String cosmosDbQueryById(
 
 #### HTTP trigger, save one document to database via return value
 
-The following example shows a Java function whose signature is annotated with `@CosmosDBOutput` and has return value of type `String`. The JSON document returned by the function will be automatically written to the corresponding Azure Cosmos DB collection.
+The following example shows a Java function whose signature is annotated with `@CosmosDBOutput` and has return value of type `String`. The JSON document returned by the function is automatically written to the corresponding Azure Cosmos DB collection.
 
 ```java
     @FunctionName("WriteOneDoc")
@@ -338,7 +338,7 @@ The following example shows a Java function that writes multiple documents to Az
     }
 ```
 
-In the [Java functions runtime library](/java/api/overview/azure/functions/runtime), use the `@CosmosDBOutput` annotation on parameters that will be written to Azure Cosmos DB.  The annotation parameter type should be `OutputBinding<T>`, where `T` is either a native Java type or a POJO.
+In the [Java functions runtime library](/java/api/overview/azure/functions/runtime), use the `@CosmosDBOutput` annotation on parameters that is written to Azure Cosmos DB. The annotation parameter type should be `OutputBinding<T>`, where `T` is either a native Java type or a POJO.
 
 ::: zone-end  
 ::: zone pivot="programming-language-typescript"  
@@ -467,7 +467,7 @@ Here's the JavaScript code:
     };
 ```
 
-For bulk insert form the objects first and then run the stringify function. Here's the JavaScript code:
+For bulk insert form the objects first and then, run the stringify function. Here's the JavaScript code:
 
 ```javascript
     module.exports = async function (context) {
@@ -705,6 +705,12 @@ By default, when you write to the output parameter in your function, a document
 > [!NOTE]  
 > When you specify the ID of an existing document, it gets overwritten by the new output document.
 
+::: zone pivot="programming-language-python" 
+
+The output function parameter must be defined as `func.Out[func.Document]`. Refer to the [output example](#example) for details.
+
+::: zone-end
+
 ::: zone pivot="programming-language-csharp"  
 
 The parameter type supported by the Cosmos DB output binding depends on the Functions runtime version, the extension package version, and the C# modality used.

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

@@ -693,6 +693,9 @@ There are two options for outputting an Event Grid message from a function:
 - **Return value**: Set the `name` property in *function.json* to `$return`. With this configuration, the function's return value is persisted as an Event Grid message.
 - **Imperative**: Pass a value to the [set](/python/api/azure-functions/azure.functions.out#set-val--t-----none) method of the parameter declared as an [Out](/python/api/azure-functions/azure.functions.out) type. The value passed to `set` is persisted as an Event Grid message.
 
+
+The output function parameter must be defined as `func.Out[str]`, `func.Out[bytes]`, `func.Out[func.EventGridOutputEvent]`, or `func.Out[List[func.EventGridOutputEvent]]`. Refer to the [output example](#example) for details.
+
 ::: zone-end
 
 ## Connections

articles/azure-functions/functions-bindings-event-grid-output.md

@@ -458,6 +458,8 @@ There are two options for outputting an Event Hubs message from a function:
 
 - **Imperative**: Pass a value to the [set](/python/api/azure-functions/azure.functions.out#set-val--t-----none) method of the parameter declared as an [Out](/python/api/azure-functions/azure.functions.out) type. The value passed to `set` is persisted as an Event Hubs message.
 
+The output function parameter must be defined as `func.Out[func.EventHubEvent]` or `func.Out[List[func.EventHubEvent]]`. Refer to the [output example](#example) for details.
+
 ::: zone-end
 
 [!INCLUDE [functions-event-hubs-connections](../../includes/functions-event-hubs-connections.md)]

articles/azure-functions/functions-bindings-event-hubs-output.md

@@ -269,9 +269,10 @@ Push-OutputBinding -Name outputSbMsg -Value @{
 ::: zone-end  
 ::: zone pivot="programming-language-python"  
 
-The following example demonstrates how to write out to a Service Bus queue in Python. The example depends on whether you use the [v1 or v2 Python programming model](functions-reference-python.md).
+The following example demonstrates how to write out to a Service Bus topics and Service Bus queues in Python. The example depends on whether you use the [v1 or v2 Python programming model](functions-reference-python.md).
 
 # [v2](#tab/python-v2)
+This example shows how to write out to a Service Bus topic.
 
 ```python
 import logging
@@ -281,17 +282,33 @@ app = func.FunctionApp()
 
 @app.route(route="put_message")
 @app.service_bus_topic_output(arg_name="message",
-                              connection="<CONNECTION_SETTING>",
-                              topic_name="<TOPIC_NAME>")
+                              connection="AzureServiceBusConnectionString",
+                              topic_name="outTopic")
 def main(req: func.HttpRequest, message: func.Out[str]) -> func.HttpResponse:
     input_msg = req.params.get('message')
     message.set(input_msg)
     return 'OK'
 ```
 
-# [v1](#tab/python-v1)
+This example shows how to write out to a Service Bus queue.
+
+```python
+import azure.functions as func
+
+app = func.FunctionApp()
+
+@app.route(route="put_message")
+@app.service_bus_queue_output(
+    arg_name="msg",
+    connection="AzureServiceBusConnectionString",
+    queue_name="outqueue")
+def put_message(req: func.HttpRequest, msg: func.Out[str]):
+    msg.set(req.get_body().decode('utf-8'))
+    return 'OK'
+```
 
-A Service Bus binding definition is defined in *function.json* where *type* is set to `serviceBus`.
+# [v1](#tab/python-v1)
+A Service Bus binding definition is defined in *function.json* where *type* is set to `serviceBus`. This example shows how to write out to a Service Bus topic.
 
 ```json
 {
@@ -317,7 +334,7 @@ A Service Bus binding definition is defined in *function.json* where *type* is s
       "direction": "out",
       "connection": "AzureServiceBusConnectionString",
       "name": "msg",
-      "queueName": "outqueue"
+      "topicName": "outTopic"
     }
   ]
 }
@@ -328,6 +345,47 @@ In *_\_init_\_.py*, you can write out a message to the queue by passing a value
 ```python
 import azure.functions as func
 
+def main(req: azf.HttpRequest, msg: azf.Out[str]):
+    msg.set(req.get_body().decode('utf-8'))
+
+    return 'OK'
+```
+
+This example shows how to write out to a Service Bus queue.
+
+```json
+{
+  "scriptFile": "__init__.py",
+  "bindings": [
+    {
+      "authLevel": "function",
+      "type": "httpTrigger",
+      "direction": "in",
+      "name": "req",
+      "methods": [
+        "get",
+        "post"
+      ]
+    },
+    {
+      "type": "http",
+      "direction": "out",
+      "name": "$return"
+    },
+    {
+      "type": "serviceBus",
+      "direction": "out",
+      "connection": "AzureServiceBusConnectionString",
+      "name": "msg",
+      "queueName": "outqueue"
+    }
+  ]
+}
+```
+
+```python
+import azure.functions as func
+
 def main(req: func.HttpRequest, msg: func.Out[str]) -> func.HttpResponse:
 
     input_msg = req.params.get('message')
@@ -564,8 +622,9 @@ Access the output message by using `context.bindings.<name>` where `<name>` is t
 ::: zone pivot="programming-language-powershell"  
 Output to the Service Bus is available via the `Push-OutputBinding` cmdlet where you pass arguments that match the name designated by binding's name parameter in the *function.json* file.
 ::: zone-end   
-::: zone pivot="programming-language-python"  
-Use the [Azure Service Bus SDK](../service-bus-messaging/index.yml) rather than the built-in output binding.
+::: zone pivot="programming-language-python" 
+The output function parameter must be defined as `func.Out[str]` or `func.Out[bytes]`. Refer to the [output example](#example) for details. 
+Alternatively, you can use the [Azure Service Bus SDK](../service-bus-messaging/index.yml) rather than the built-in output binding.
 ::: zone-end  
 For a complete example, see [the examples section](#example).