microsoft / microsoft/aspire.dev

[What's New Analysis] Create first-party Python hosting documentation

Open
#336 0 comments 0 reactions 1 assignee View on GitHub

@maddymontaquila is already working on this.

Since Feb 9, 2026.

external feedback
Dominant language
MDX
Stars
193
Forks
87
Avg merge
1d 22h
Merged PRs (30d)
73

Description

Summary

The first-party Aspire.Hosting.Python package introduced in Aspire 13.0 has no standalone documentation. The existing python-integration doc covers the Community Toolkit package (CommunityToolkit.Aspire.Hosting.Python.Extensions), not the first-party package.

What's Missing

The following APIs are documented only in what's-new-in-aspire-13:

// These are in Aspire.Hosting.Python - NOT the Community Toolkit
builder.AddPythonApp("etl-job", "../etl", "process_data.py");
builder.AddPythonModule("celery-worker", "../worker", "celery");
builder.AddPythonExecutable("api", "../api", "gunicorn");
builder.AddUvicornApp("api", "./api", "main:app");

// Package management
.WithUv()   // uv package manager
.WithPip()  // pip package manager
.WithVirtualEnvironment(".venv", createIfNotExists: true)

Suggested Content

  1. Hosting integration section with all 4 app types
  2. Package management - WithUv vs WithPip, auto-detection behavior
  3. Virtual environment configuration - paths, auto-creation
  4. Dockerfile generation - automatic multi-stage builds
  5. Python version detection - .python-version, pyproject.toml, fallback
  6. VS Code debugging - breakpoints work automatically
  7. Examples - FastAPI, Flask, Celery worker patterns

Why It Matters

Python is now a "first-class citizen" in Aspire 13 - this is a major selling point. Users searching for "Aspire Python" find the Community Toolkit doc which uses different APIs.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.