Skip to content

Add WithUvEnvironment extension method to Aspire.Hosting.Python - #11937

Merged
David Fowler (davidfowl) merged 8 commits into
mainfrom
copilot/add-with-python-uv-environment
Oct 10, 2025
Merged

David Fowler (davidfowl) merged 8 commits into
mainfrom
copilot/add-with-python-uv-environment

Conversation

Copilot AI commented Oct 10, 2025 •

Copy link
Copy Markdown
Contributor

Implements the WithUvEnvironment extension method for Python applications in .NET Aspire, enabling automatic UV-managed virtual environment setup before application startup.

Overview

This PR adds support for UV (https://github.com/astral-sh/uv), a modern Python package manager, to ensure virtual environments and dependencies are properly configured before Python applications start.

Changes

New Resource Type: PythonUvEnvironmentResource

An internal sealed resource class that represents a UV environment setup task. It extends ExecutableResource to run the uv sync command. The resource establishes a parent-child relationship with the Python application through annotations and is excluded from manifest generation.

New Extension Method: WithUvEnvironment<T>()

The extension method can be chained on any Python app resource to automatically set up a UV-managed environment:

var builder = DistributedApplication.CreateBuilder(args);

var python = builder.AddPythonApp("my-python-app", "../python-app", "main.py")
    .WithUvEnvironment()
    .WithArgs("--verbose");

builder.Build().Run();

Behavior

  1. Creates a child resource named {pythonAppName}-uv-environment
  2. Executes uv sync in the Python app's working directory
  3. Establishes a parent-child relationship with the Python application through relationship annotations
  4. Adds a WaitForCompletion dependency ensuring the Python app waits for UV sync to complete successfully before starting
  5. If UV sync fails (non-zero exit code), the resource fails and the Python application won't start
  6. The UV environment resource is excluded from manifest generation

Playground Sample Updated

Updated the AspireWithPython playground sample to demonstrate the new WithUvEnvironment() method. The playground's AppHost project has been simplified by removing manual MSBuild targets for Python virtual environment setup, as this is now handled automatically by WithUvEnvironment().

Testing

Added comprehensive test coverage including:

  • Resource creation and naming validation
  • Command argument configuration (uv sync)
  • WaitForCompletion relationship validation
  • Null argument handling

All 39 tests in the Python hosting test suite pass successfully.

Fixes

Fixes #11934

Original prompt

This section details on the original issue you should resolve

<issue_title>Add WithPythonUvEnvironment to Python extension builder in Aspire.Hosting.Python</issue_title>
<issue_description>### Is there an existing issue for this?

  • I have searched the existing issues

Is your feature request related to a problem? Please describe the problem.

The Aspire.Hosting.Python package needs a way of adding a UV-managed virtual environment with dependencies to the PythonAppResource.

This can be done with an extension method to the builder patterns in PythonAppResourceBuilderExtensions called WithPythonUvEnvironment.

Describe the solution you'd like

The method should take any PythonAppResource and attach a child resource which runs the uv sync command in the working directory of the Python app to ensure that the virtual environment exists.

The API for this would be:

        public static IResourceBuilder<T> WithPythonUvEnvironment<T>(this IResourceBuilder<T> builder)
        where T : PythonAppResource

This new resource runs uv sync in the working directory of the Python App Resource for which it was attached. This uv sync command is done via the existing Executable Resource infrastructure.

Behaviours:

  1. The name of this new resource is the python app resource name with -uv-environment suffixed, i.e. $"{builder.Resource.Name}-uv-environment
  2. This new resource is a new standalone resource class, PythonUvEnvironmentResource
  3. This new UV resource adds the Python app resource as a parent and sets a WaitForCompletion relationship to the parent so that the uv sync command must complete successfully before the PythonAppResource can be started. This ensure that the virtual environment exists and the dependencies are installed before the Python app is started.
  4. If the uv sync command fails, it should fail the resource and the parent Python App resource will fail to start.

Additional context

No response</issue_description>

Comments on the Issue (you are Copilot in this section)

Fixes #11934


✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Copilot AI and others added 2 commits October 10, 2025 05:07
Co-authored-by: davidfowl <95136+davidfowl@users.noreply.github.com>
Co-authored-by: davidfowl <95136+davidfowl@users.noreply.github.com>
Copilot AI changed the title [WIP] Add WithPythonUvEnvironment to Python extension builder Add WithPythonUvEnvironment extension method to Aspire.Hosting.Python Oct 10, 2025
@davidfowl

Copy link
Copy Markdown
Collaborator

Copilot implement the PR feedback.

…ernal, remove IResourceWithParent

Co-authored-by: davidfowl <95136+davidfowl@users.noreply.github.com>
Copilot AI changed the title Add WithPythonUvEnvironment extension method to Aspire.Hosting.Python Add WithUvEnvironment extension method to Aspire.Hosting.Python Oct 10, 2025
@davidfowl

Copy link
Copy Markdown
Collaborator

Update the python playgroud sample to use the UseUvEnvironment method and remove https://github.com/dotnet/aspire/blob/main/playground/AspireWithPython/AspireWithPython.AppHost/AspireWithPython.AppHost.csproj

@davidfowl

Copy link
Copy Markdown
Collaborator

Copilot implement the review feedback.

Co-authored-by: davidfowl <95136+davidfowl@users.noreply.github.com>
…Environment

Co-authored-by: davidfowl <95136+davidfowl@users.noreply.github.com>

Copilot AI commented Oct 10, 2025

Copy link
Copy Markdown
Contributor Author

Update the python playgroud sample to use the UseUvEnvironment method and remove https://github.com/dotnet/aspire/blob/main/playground/AspireWithPython/AspireWithPython.AppHost/AspireWithPython.AppHos...

Updated AspireWithPython.AppHost/AppHost.cs to use WithUvEnvironment() and removed all MSBuild targets from the .csproj file that were manually setting up the Python virtual environment in commit 8fc0279.

@github-actions

github-actions Bot commented Oct 10, 2025 •

Copy link
Copy Markdown
Contributor

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 11937

Or

  • Run remotely in PowerShell:
iex "& { $(irm https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 11937"

@davidfowl
David Fowler (davidfowl) marked this pull request as ready for review October 10, 2025 07:17
Copilot AI review requested due to automatic review settings October 10, 2025 07:17

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR adds UV (modern Python package manager) support to the Aspire.Hosting.Python package by implementing a WithUvEnvironment extension method that automatically sets up UV-managed virtual environments before Python application startup.

  • Introduces PythonUvEnvironmentResource as an internal resource class that executes uv sync commands
  • Adds WithUvEnvironment<T>() extension method for configuring UV environment setup with proper dependency management
  • Updates the AspireWithPython playground sample to demonstrate the new functionality and removes manual MSBuild virtual environment setup

Reviewed Changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated no comments.

Show a summary per file
File Description
src/Aspire.Hosting.Python/PythonUvEnvironmentResource.cs New internal resource class that extends ExecutableResource to run UV sync commands
src/Aspire.Hosting.Python/PythonAppResourceBuilderExtensions.cs Implements the WithUvEnvironment extension method with proper resource relationships
src/Aspire.Hosting.Python/Aspire.Hosting.Python.csproj Adds InternalsVisibleTo attribute for test access
tests/Aspire.Hosting.Python.Tests/AddPythonAppTests.cs Comprehensive test coverage for the new UV environment functionality
playground/AspireWithPython/AspireWithPython.AppHost/AppHost.cs Updates playground to use WithUvEnvironment method
playground/AspireWithPython/AspireWithPython.AppHost/AspireWithPython.AppHost.csproj Removes manual MSBuild Python environment setup targets
playground/AspireWithPython/InstrumentedPythonProject/pyproject.toml Adds UV-compatible project configuration file
playground/AspireWithPython/InstrumentedPythonProject/requirements.txt Removes requirements.txt in favor of pyproject.toml dependencies
playground/AspireWithPython/InstrumentedPythonProject/.python-version Specifies Python 3.13 version for UV

@dotnet-policy-service dotnet-policy-service Bot added this to the 13.0 milestone Oct 10, 2025
@eerhardt
Eric Erhardt (eerhardt) deleted the copilot/add-with-python-uv-environment branch October 10, 2025 14:13
@@ -0,0 +1 @@
3.13

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For my learning - why does this need to go here and in the pyproject.toml file?

@davidfowl David Fowler (davidfowl) Oct 10, 2025 •

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is like global json, uv will install this python version if this file is here

https://docs.astral.sh/uv/concepts/python-versions/#python-version-files

though we don’t bootstrap python with uv (yet)

@github-actions github-actions Bot locked and limited conversation to collaborators Nov 10, 2025
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add WithPythonUvEnvironment to Python extension builder in Aspire.Hosting.Python

5 participants