diff --git a/src/frontend/src/content/docs/integrations/frameworks/python.mdx b/src/frontend/src/content/docs/integrations/frameworks/python.mdx index 97822dd2..56fea5f3 100644 --- a/src/frontend/src/content/docs/integrations/frameworks/python.mdx +++ b/src/frontend/src/content/docs/integrations/frameworks/python.mdx @@ -1,15 +1,13 @@ --- title: Python integration +description: Learn how to use the Aspire Python Hosting integration to orchestrate Python applications in an Aspire solution. --- -import { Badge } from '@astrojs/starlight/components'; import { Aside } from '@astrojs/starlight/components'; -import InstallPackage from "@components/InstallPackage.astro"; +import InstallPackage from '@components/InstallPackage.astro'; import { Image } from 'astro:assets'; import pythonIcon from '@assets/icons/python.svg'; - - Python logo -The Aspire Python hosting integration enables you to run Python applications alongside your Aspire projects in the Aspire app host. This integration supports both [Uvicorn](https://www.uvicorn.org/) applications and [uv](https://docs.astral.sh/uv/) package manager applications. +The Aspire Python hosting integration enables you to run Python applications alongside your Aspire projects in the Aspire app host. This integration provides first-class support for Python apps, scripts, modules, executables, and web frameworks like FastAPI. + +:::tip[First-class Python support] +As of Aspire 13, Python is a first-class workload with the `Aspire.Hosting.Python` package. The previous `CommunityToolkit.Aspire.Hosting.Python.Extensions` package is deprecated, and its functionality has been integrated into the official package with full support for debugging, service discovery, and deployment alongside .NET and JavaScript applications. +::: -## Hosting integration +## Installation -To get started with the Aspire Python hosting integration, install the [CommunityToolkit.Aspire.Hosting.Python.Extensions](https://www.nuget.org/packages/CommunityToolkit.Aspire.Hosting.Python.Extensions) NuGet package in the app host project. +To access these types and APIs for expressing Python resources in your [`AppHost`](/get-started/app-host/) project, install the [📦 Aspire.Hosting.Python](https://www.nuget.org/packages/Aspire.Hosting.Python) NuGet package: - + -### Add Uvicorn app +## Add Python app -To add a Uvicorn application to your app host, use the `AddUvicornApp` extension method: +To add a Python application to your app host, use the `AddPythonApp` extension method to run a Python script: ```csharp title="C# — AppHost.cs" var builder = DistributedApplication.CreateBuilder(args); -var python = builder.AddUvicornApp( +var python = builder.AddPythonApp( name: "python-api", projectDirectory: "../python-app", - appName: "main:app") + scriptPath: "main.py") .WithHttpEndpoint(port: 8000, env: "PORT"); builder.AddProject() @@ -46,28 +48,59 @@ builder.AddProject() // After adding all resources, run the app... ``` -The `AddUvicornApp` method requires: +The `AddPythonApp` method requires: - **name**: The name of the resource in the Aspire dashboard - **projectDirectory**: The path to the directory containing your Python application -- **appName**: The Python module and ASGI application instance (e.g., `main:app` for an `app` instance in `main.py`) +- **scriptPath**: The path to the Python script to run (relative to the project directory) - +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var python = builder.AddPythonModule( + name: "python-module", + projectDirectory: "../python-app", + moduleName: "mymodule") + .WithHttpEndpoint(port: 8000, env: "PORT"); + +// After adding all resources, run the app... +``` + +The `AddPythonModule` method requires: +- **name**: The name of the resource in the Aspire dashboard +- **projectDirectory**: The path to the directory containing your Python application +- **moduleName**: The name of the Python module to run -### Add uv app +## Add Python executable -To add an application using the [uv package manager](https://docs.astral.sh/uv/), use the `AddUvApp` extension method: +To run a Python executable or CLI tool from a virtual environment, use the `AddPythonExecutable` extension method: ```csharp title="C# — AppHost.cs" var builder = DistributedApplication.CreateBuilder(args); -var python = builder.AddUvApp( +var python = builder.AddPythonExecutable( + name: "python-tool", + projectDirectory: "../python-app", + executable: "uvicorn", + args: ["main:app", "--host", "0.0.0.0", "--port", "8000"]); + +// After adding all resources, run the app... +``` + +## Add Uvicorn app + +For ASGI web frameworks like FastAPI, Starlette, and Quart, use the `AddUvicornApp` extension method which provides built-in support for Uvicorn: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var python = builder.AddUvicornApp( name: "python-api", projectDirectory: "../python-app", - scriptPath: "main.py") + appName: "main:app") .WithHttpEndpoint(port: 8000, env: "PORT"); builder.AddProject() @@ -76,12 +109,116 @@ builder.AddProject() // After adding all resources, run the app... ``` -The `AddUvApp` method requires: +The `AddUvicornApp` method requires: - **name**: The name of the resource in the Aspire dashboard - **projectDirectory**: The path to the directory containing your Python application -- **scriptPath**: The path to the Python script to run (relative to the project directory) +- **appName**: The Python module and ASGI application instance (e.g., `main:app` for an `app` instance in `main.py`) + +### Uvicorn configuration + +The `AddUvicornApp` method supports additional configuration options: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var python = builder.AddUvicornApp("python-api", "../python-app", "main:app") + .WithHttpEndpoint(port: 8000, env: "PORT") + .WithEnvironment("UVICORN_WORKERS", "4") + .WithEnvironment("UVICORN_LOG_LEVEL", "info"); + +// After adding all resources, run the app... +``` + +Common Uvicorn environment variables: +- **UVICORN_PORT**: The port to listen on +- **UVICORN_HOST**: The host to bind to (default: `127.0.0.1`) +- **UVICORN_WORKERS**: Number of worker processes +- **UVICORN_LOG_LEVEL**: Logging level (e.g., `debug`, `info`, `warning`, `error`) + +## Virtual environment management + +The Python hosting integration automatically detects and manages Python virtual environments: + +### Automatic virtual environment + +By default, the integration looks for a virtual environment in the project directory. If a `requirements.txt` or `pyproject.toml` file is found, it will automatically create and activate a virtual environment. + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +// Automatically detects and uses virtual environment +var python = builder.AddPythonApp("python-api", "../python-app", "main.py"); + +// After adding all resources, run the app... +``` + +### Custom virtual environment + +To specify a custom virtual environment location, use the `WithVirtualEnvironment` method: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var python = builder.AddPythonApp("python-api", "../python-app", "main.py") + .WithVirtualEnvironment("../python-app/.venv"); + +// After adding all resources, run the app... +``` + +### Disable virtual environment + +To disable automatic virtual environment creation, use the `WithoutVirtualEnvironment` method: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var python = builder.AddPythonApp("python-api", "../python-app", "main.py") + .WithoutVirtualEnvironment(); + +// After adding all resources, run the app... +``` + +## Package management + +The Python hosting integration supports multiple package managers and allows you to choose which one to use: + +### Using uv package manager + +Use the `WithUv()` method to explicitly use the [uv package manager](https://docs.astral.sh/uv/) for faster dependency installation: -### Configure endpoints +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var python = builder.AddUvicornApp("python-api", "../python-app", "main:app") + .WithUv() + .WithHttpEndpoint(port: 8000, env: "PORT"); + +// After adding all resources, run the app... +``` + +The `WithUv()` method configures the Python app to use uv for package management, which is significantly faster than pip and recommended for new projects. + +### Using pip package manager + +Use the `WithPip()` method to explicitly use pip for package management: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var python = builder.AddPythonApp("python-api", "../python-app", "main.py") + .WithPip() + .WithHttpEndpoint(port: 8000, env: "PORT"); + +// After adding all resources, run the app... +``` + + + +## Configure endpoints Python applications typically use environment variables to configure the port they listen on. Use `WithHttpEndpoint` to configure the port and set the environment variable: @@ -89,23 +226,114 @@ Python applications typically use environment variables to configure the port th var builder = DistributedApplication.CreateBuilder(args); var python = builder.AddUvicornApp("python-api", "../python-app", "main:app") - .WithHttpEndpoint(port: 8000, env: "UVICORN_PORT"); + .WithHttpEndpoint(port: 8000, env: "PORT"); + +// After adding all resources, run the app... +``` + +### Multiple endpoints + +You can configure multiple endpoints for a Python application: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var python = builder.AddPythonApp("python-api", "../python-app", "main.py") + .WithHttpEndpoint(port: 8000, env: "HTTP_PORT", name: "http") + .WithHttpEndpoint(port: 8443, env: "HTTPS_PORT", name: "https"); // After adding all resources, run the app... ``` -Common environment variables for Python web frameworks: -- **UVICORN_PORT**: For Uvicorn applications -- **PORT**: Generic port configuration used by many frameworks +## Health checks + +The Python hosting integration supports health checks for monitoring service health: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); -### Working directory +var python = builder.AddUvicornApp("python-api", "../python-app", "main:app") + .WithHttpEndpoint(port: 8000, env: "PORT") + .WithHttpHealthCheck("/health"); -By default, the working directory is set to the `projectDirectory` specified when adding the Python app. The integration will look for the Python virtual environment and dependencies in this directory. +// After adding all resources, run the app... +``` + +## Environment variables + +Pass environment variables to your Python application using the `WithEnvironment` method: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var python = builder.AddPythonApp("python-api", "../python-app", "main.py") + .WithEnvironment("DEBUG", "true") + .WithEnvironment("LOG_LEVEL", "debug"); + +// After adding all resources, run the app... +``` + +## Service discovery + +Python applications can reference other services in the Aspire app host using service discovery: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var postgres = builder.AddPostgres("postgres") + .AddDatabase("mydb"); + +var python = builder.AddPythonApp("python-api", "../python-app", "main.py") + .WithReference(postgres); + +// After adding all resources, run the app... +``` + +The connection string will be available as an environment variable in the Python application. + +## Debugging + +The Python hosting integration provides full debugging support in Visual Studio Code: + +1. Install the [Aspire VS Code extension](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.dotnet-aspire) +2. Set breakpoints in your Python code +3. Run the Aspire app host +4. The debugger will automatically attach to your Python application + + + +## Deployment + +When deploying your Aspire application, the Python hosting integration automatically generates production-ready Dockerfiles for your Python services: + +```dockerfile +# Auto-generated Dockerfile +FROM python:3.12-slim + +WORKDIR /app +COPY requirements.txt . +RUN pip install -r requirements.txt + +COPY . . +CMD ["python", "main.py"] +``` + + ## See also -- [Uvicorn documentation](https://www.uvicorn.org/) -- [uv documentation](https://docs.astral.sh/uv/) -- [Aspire Community Toolkit](https://github.com/CommunityToolkit/Aspire) +- [Build your first Aspire app](/get-started/first-app/) +- [Deploy your first Aspire app](/get-started/deploy-first-app/) - [Aspire integrations overview](/integrations/overview/) +- [Aspire.Hosting.Python NuGet package](https://www.nuget.org/packages/Aspire.Hosting.Python) +- [Uvicorn documentation](https://www.uvicorn.org/) +- [uv package manager documentation](https://docs.astral.sh/uv/) - [Aspire GitHub repo](https://github.com/dotnet/aspire)