Port Azure Functions QuickStart from TypeScript to Python with v2 programming model (#2)

* Initial plan

* Complete Azure Functions Python port with infrastructure and documentation

Co-authored-by: nzthiago <[email protected]>

* Implement SDK type bindings for ContainerClient

Co-authored-by: nzthiago <[email protected]>

* Initial updates to work with SDK Types

* Updating SDK package with fix for user assigned identity to work

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: nzthiago <[email protected]>
Co-authored-by: Thiago Almeida <[email protected]>

Author: Copilot

.gitignore

@@ -6,6 +6,23 @@ __pycache__/
 # C extensions
 *.so
 
+# Azurite
+__azurite*
+AzuriteConfig
+__blobstorage__
+__queuestorage__
+__tablestorage__
+
+# VS Code
+.vscode/
+
+# Mac DS_Store files
+#  These files are created by macOS to store custom attributes of a folder such as the
+#  position of icons or the choice of background image. They are not needed in version control
+#  and can be safely ignored.
+#  For more information, see https://en.wikipedia.org/wiki/.DS_Store
+.DS_Store
+
 # Distribution / packaging
 .Python
 build/
@@ -205,3 +222,15 @@ cython_debug/
 marimo/_static/
 marimo/_lsp/
 __marimo__/
+
+# Azure Functions
+local.settings.json
+bin
+obj
+appsettings.json
+*.user
+*.userprefs
+*.zip
+
+# Azure Developer CLI
+.azure

README.md

@@ -1,57 +1,211 @@
-# Project Name
+---
+page_type: sample
+languages:
+- python
+- bicep
+- azdeveloper
+products:
+- azure
+- azure-functions
+- azure-blob-storage
+- azure-virtual-network
+- entra-id
+urlFragment: functions-quickstart-python-azd-eventgrid-blob
+name: Azure Functions Python Event Grid Blob Trigger using Azure Developer CLI
+description: This template repository contains an Azure Functions reference sample using the Blob trigger with Event Grid source type, written in Python (v2 programming model) and deployed to Azure using the Azure Developer CLI (azd). The sample uses managed identity and a virtual network to make sure deployment is secure by default.
+---
+<!-- YAML front-matter schema: https://review.learn.microsoft.com/en-us/help/contribute/samples/process/onboarding?branch=main#supported-metadata-fields-for-readmemd -->
 
-(short, 1-3 sentenced, description of the project)
+# Azure Functions Python Event Grid Blob Trigger using Azure Developer CLI
 
-## Features
+This template repository contains an Azure Functions reference sample using the Blob trigger with Event Grid source type, written in Python (v2 programming model) and deployed to Azure using the Azure Developer CLI (`azd`). When deployed to Azure the sample uses managed identity and a virtual network to make sure deployment is secure by default. You can control whether a VNet is used in the sample by setting `VNET_ENABLED` to true or false in the AZD parameters.
 
-This project framework provides the following features:
+This sample implements a simple function that copies PDF files from an `unprocessed-pdf` container to a `processed-pdf` container when new blobs are created. This straightforward example showcases how to use the Event Grid blob trigger to automatically respond to blob creation events in near real-time.
 
-* Feature 1
-* Feature 2
-* ...
+![Architecture diagram for Azure Functions Event Grid Blob Trigger](./img/architecture.png)
 
-## Getting Started
+## Benefits of Event Grid Blob Trigger
 
-### Prerequisites
+This sample uses the Event Grid source type for the Blob trigger, which provides significant advantages over the traditional scan-based approach:
 
-(ideally very short, if any)
+- **Near real-time processing**: Event Grid delivers blob events within milliseconds of creation, eliminating the delays associated with container scanning.
+- **Improved scalability**: Perfect for Flex Consumption plans where the traditional polling-based Blob trigger isn't available.
+- **Reduced costs**: Eliminates storage transaction costs from polling, which can be substantial with large numbers of blobs.
+- **Enhanced reliability**: Uses a robust pub/sub model that ensures blob events aren't missed, even during function downtime.
+- **Better performance**: No performance degradation with large numbers of blobs in a container, unlike the scan-based approach.
 
-- OS
-- Library version
-- ...
+The Event Grid approach is recommended for all new Blob trigger implementations, especially when using Flex Consumption plans where the traditional storage polling method isn't available.
 
-### Installation
+## Prerequisites
 
-(ideally very short)
++ [Azure Developer CLI](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd)
++ [Python 3.12+](https://www.python.org/downloads/)
++ [Azure Functions Core Tools](https://learn.microsoft.com/azure/azure-functions/functions-run-local?pivots=programming-language-python#install-the-azure-functions-core-tools)
++ To use Visual Studio Code to run and debug locally:
+  + [Visual Studio Code](https://code.visualstudio.com/)
+  + [Azure Storage extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azurestorage)
+  + [Azure Functions extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azurefunctions)
+  + [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
+  + [REST Client](https://marketplace.visualstudio.com/items?itemName=humao.rest-client)
++ [Azurite](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to emulate Azure Storage services when running locally
 
-- npm install [package name]
-- mvn install
-- ...
+Optional for uploading blobs:
 
-### Quickstart
-(Add steps to get up and running quickly)
++ [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) or
++ [Azure Storage Explorer](https://azure.microsoft.com/en-us/products/storage/storage-explorer/#Download-4)
 
-1. git clone [repository clone url]
-2. cd [repository name]
-3. ...
+## Initialize the local project
 
+To initialize a project from this `azd` template, clone the GitHub template repository locally using the `git clone` command:
 
-## Demo
+    ```bash
+    git clone https://github.com/Azure-Samples/functions-quickstart-python-azd-eventgrid-blob.git
+    cd functions-quickstart-python-azd-eventgrid-blob
+    ```
 
-A demo app is included to show how to use the project.
+    You can also clone the repository from your own fork in GitHub.
 
-To run the demo, follow these steps:
+# Start and prepare the local storage emulator
 
-(Add steps to start up the demo)
+Azure Functions uses Azurite to emulate Azure Storage services when running locally. If you haven't done so, [install Azurite](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite#install-azurite).
 
-1.
-2.
-3.
+Create two containers in the local storage emulator called `processed-pdf` and `unprocessed-pdf`. Follow these steps:
 
-## Resources
+1. Ensure Azurite is running. For more details see [Run Azurite](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite#run-azurite)
 
-(Any additional resources or related projects)
+2. Use Azure Storage Explorer, or the VS Code Storage Extension to create the containers.
 
-- Link to supporting information
-- Link to similar sample
-- ...
+   **Using Azure Storage Explorer:**
+   + Install [Azure Storage Explorer](https://azure.microsoft.com/en-us/products/storage/storage-explorer/#Download-4)
+   + Open Azure Storage Explorer.
+   + Connect to the local emulator by selecting `Attach to a local emulator.`
+   + Navigate to the `Blob Containers` section.
+   + Right-click and select `Create Blob Container.`
+   + Name the containers `processed-pdf` and `unprocessed-pdf`.
+
+   **Using VS Code Storage Extension:**
+   + Install the VS Code [Azure Storage extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azurestorage)
+   + Ensure Azurite is running
+   + Click on the Azure extension icon in VS Code
+   + Under `Workspace`, expand `Local Emulator`
+   + Right click on `Blob Containers` and select `Create Blob Container`
+   + Name the containers `processed-pdf` and `unprocessed-pdf`
+
+3. Upload the PDF files from the `data` folder to the `unprocessed-pdf` container.
+
+   **Using Azure Storage Explorer:**
+    + Open Azure Storage Explorer.
+    + Navigate to the `unprocessed-pdf` container.
+    + Click on "Upload" and select "Upload Folder" or "Upload Files."
+    + Choose the `data` folder or the specific PDF files to upload.
+    + Confirm the upload to the `unprocessed-pdf` container.
+
+   **Using VS Code Storage Extension:**
+   + Install the VS Code [Azure Storage extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azurestorage)
+   + Ensure Azurite is running
+   + Click on the Azure extension icon in VS Code
+   + Under `Workspace`, expand `Local Emulator`, expand `Blob Containers`
+   + Right click on `unprocessed-pdf` and select `Open in Explorer`
+   + Copy and paste all the pdf files from the `data` folder to it
+
+## Run your app
+
+  **Using the terminal**
+
++ Create and activate a Python virtual environment:
+
+    ```bash
+    python -m venv .venv
+    source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+    ```
+
++ Navigate to the `src` directory and install dependencies:
+
+    ```bash
+    cd src
+    pip install -r requirements.txt
+    ```
+
++ From the `src` folder, run this command to start the Functions host locally:
+
+    ```bash
+    func start
+    ```
+
+  **Using Visual Studio Code**
+
++ Open the project folder in a new terminal.
++ Run the `code .` command to open the project in Visual Studio Code.
++ Create and activate a Python virtual environment:
+  + Open Command Palette (F1) and run `Python: Create Environment`
+  + Select `Venv` and choose your Python 3.12+ interpreter
+  + Select the `src/requirements.txt` file to install dependencies
++ In the command palette (F1), type `Azurite: Start`, which enables debugging without warnings.
++ Open the `src` folder in VS Code and press **F5** to run in the debugger. Make a note of the `localhost` URL endpoints, including the port, which might not be `7071`.
+
+## Trigger the function
+
+Now that the storage emulator is running, has files on the `unprocessed-pdf` container, and our app is running, we can execute the `process_blob_upload` function to simulate a new blob event.
+
++ If you are using VS Code, Visual Studio, or other tooling that supports .http files, you can open the [`test.http`](./test.http) project file, update the port on the `localhost` URL (if needed), and then click on Send Request to call the locally running `process_blob_upload` function. This will trigger the function to process the `Benefit_Options.pdf` file. You can update the file name in the JSON to process other PDF files.
+
+## Source Code
+
+The function code for the `process_blob_upload` endpoint is defined in [`function_app.py`](./src/function_app.py). The function uses the Python v2 programming model and the `@app.blob_trigger()` decorator to register the blob trigger with Event Grid source.
+
+    ```python
+    @app.blob_trigger(arg_name="blob", 
+                      path="unprocessed-pdf/{name}",
+                      connection="PDFProcessorSTORAGE",
+                      source="EventGrid")
+    def process_blob_upload(blob: func.InputStream) -> None:
+        # Function implementation
+    ```
+
+The `copy_to_processed_container` method uses the Azure Storage Blob SDK to upload the processed file to the destination blob container.
+
+## Deploy to Azure
+
+Login to the Azure Developer CLI if you haven't already:
+
+```bash
+azd auth login
+```
+
+Run this command from the base folder to provision the function app and other required Azure Azure resources, and deploy your code:
+
+```bash
+azd up
+```
+
+If required you can opt-out of a VNet being used in the sample. To do so, use `azd env` to configure `VNET_ENABLED` to `false` before running `azd up`:
+
+```bash
+azd env set VNET_ENABLED false
+azd up
+```
+
+You're prompted to supply these required deployment parameters:
+
+| Parameter | Description |
+| ---- | ---- |
+| _Environment name_ | An environment that's used to maintain a unique deployment context for your app. You won't be prompted if you created the local project using `azd init`.|
+| _Azure subscription_ | Subscription in which your resources are created.|
+| _Azure location_ | Azure region in which to create the resource group that contains the new Azure resources. Only regions that currently support the Flex Consumption plan are shown.|
+
+After publish completes successfully, the new resource group will have a storage account and the `processed-pdf` and `unprocessed-pdf` containers. Upload PDF files from the data folder to the `unprocessed-pdf` folder and then check `processed-pdf` for the file.
+
+## Redeploy your code
+
+You can run the `azd up` command as many times as you need to both provision your Azure resources and deploy code updates to your function app.
+
+>[!NOTE]
+>Deployed code files are always overwritten by the latest deployment package.
+
+## Clean up resources
+
+When you're done working with your function app and related resources, you can use this command to delete the function app and its related resources from Azure and avoid incurring any further costs:
+
+```bash
+azd down
+```

azure.yaml

@@ -0,0 +1,22 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/main/schemas/v1.0/azure.yaml.json
+
+name: functions-quickstart-python-azd-eventgrid-blob
+metadata:
+    template: [email protected]
+hooks:
+    postdeploy:
+      windows:
+        shell: pwsh
+        run: ./scripts/post-up.ps1
+        interactive: true
+        continueOnError: false
+      posix:
+        shell: sh
+        run: ./scripts/post-up.sh
+        interactive: true
+        continueOnError: false
+services:
+  processor:
+    project: ./src
+    language: python
+    host: function