wmeints / aspire-python

.NET Aspire hosting extensions for Python projects

Aspire hosting extensions for Python projects

---

IMPORTANT I merged most of the code here into the .NET Aspire code base. If you want to use Python projects with Aspire, make sure to check out the docs here: https://learn.microsoft.com/en-us/dotnet/aspire/get-started/build-aspire-apps-with-python?tabs=bash

---

This project adds additional support for running Python projects as smoothly as C# projects.

System requirements

• Python
• .NET SDK 8 or higher
• .NET Aspire workload preview 7

Getting started

Before using this extension you should know how to set up an Aspire project. There's an excellent guide in the documentation.

Once you've set up a basic Aspire project, follow the instructions below to get started.

Before you start building

These extensions make a few assumptions about your project:

• You have a virtual environment in the .venv directory in your Python project. You can set up a virtual environment with venv, rye or poetry.
• You have a Dockerfile in the root directory of your Python project. A sample Dockerfile can be found here

Note: I haven't added support for Anaconda because I don't use it myself. Feel free to open a PR to add support for Anaconda.

Setting up a Python project

Basic Python projects can be configured using the following code:

using FizzyLogic.Aspire.Python.Hosting;

var builder = DistributedApplication.CreateBuilder(args);

builder.AddPythonProjectWithVirtualEnvironment("batch", "apps/batch");

builder.Build().Run();

By adding a Python project resource, you'll automatically get tracing, logging, and metrics configured. Note that you need to add extra HTTP and HTTPS endpoints yourself by calling .WithHttpEndpoint or WithHttpsEndpoint.

The Python project is deployed as a container when you publish the Aspire application. You'll need a Dockerfile in the Python project directory for the publication to work properly.

Telemetry data is automatically gathered when you have the following package available in your virtual environment:

• opentelemetry-distro (Make sure you install opentelemetry-distro[otlp])

Setting up a Flask project

Flask applications differ from regular Python projects in that we'll automatically expose an HTTP endpoint for the project. You can configure a new Flask project using the following code:

using FizzyLogic.Aspire.Python.Hosting;

var builder = DistributedApplication.CreateBuilder(args);

builder.AddFlaskProjectWithVirtualEnvironment("flask-service", "apps/flask-service");

builder.Build().Run();

As with regular Python projects, the Flask project is published as a container. You'll need a Dockerfile in the Python project directory for the publication to work properly.

Telemetry data is automatically gathered when you have the following two packages available in your virtual environment:

• opentelemetry-distro (Make sure you install opentelemetry-distro[otlp])
• opentelemetry-instrumentation-flask

Developing

Setting up your environment

Before you can work on the code, make sure you have .NET 8, Python, and Rye configured. After install .NET 8, run the following commands to get the correct workload setup:

dotnet workload update
dotnet workload install aspire

Running the sample in the repository

The repository contains a sample application which demonstrates various scenarios that are supported by this extension. Before running the sample, make sure you've synced the environments:

pushd sample/apps/batch && rye sync && popd
pushd sample/apps/flask-service && rye sync && popd

Syncing the environments for the various components shouldn't take too long to complete. After completing the sync step, you can run the host like so:

cd sample/host/FizzyLogic.Aspire.Python.AppHost
dotnet run

aspire-python's Issues

Add unit-tests for various scenarios

Bad, bad, bad, I didn't add any unit-tests. I have a few things in mind for testing:

• Test detection of virtual environments
• Test detection of OTEL support
• Test validation of various properties

Add samples for FastAPI

This is in the same area as #2 . I'll need to add a sample for FastAPI and verify that everything is working as intended.
Maybe it's fun to automatically detect the correct ports and set them up for the developer.

Add samples for Flask

This is in the same area as #2 . I'll need to add a sample for Flask and verify that everything is working as intended.
Maybe it's fun to automatically detect the correct ports and set them up for the developer.

Check Windows compatibility

Windows is untested but should work. I'm going to verify this and fix issues.

Add samples for Django

I suspect that running Django projects is a little more complicated than a regular Python project. So I'm going to have to add a sample and maybe modify a few things to get that working correctly. Maybe it's fun to automatically detect the correct ports and set them up for the developer.