Python hosting: Support .venv lookup by walking up parent directories

[Copilot]

Implementation Complete: .venv Lookup by Walking Up Parent Directories

Successfully implemented virtual environment lookup that walks up parent directories from the Python app directory, stopping at the AppHost's parent directory. This allows finding shared .venv in common parent folders while avoiding unrelated venvs.

Changes Summary

Refactored Architecture

Before: Multi-location lookup logic was in WithVirtualEnvironment, affecting all calls
After: Logic moved to AddPythonAppCore, only applies to default .venv during initial creation

Core Changes (PythonAppResourceBuilderExtensions.cs)

1. AddPythonAppCore Enhancement

   • Added logic to detect when using default .venv path
   • Calls new ResolveDefaultVirtualEnvironmentPath helper for smart lookup
   • Passes resolved path to WithVirtualEnvironment
   • Uses appDirectory parameter for resolution (not WorkingDirectory)

2. New Helper Method: ResolveDefaultVirtualEnvironmentPath

   • First checks if the app directory is under the AppHost's parent directory tree
   • If not under AppHost's parent, only looks in the app directory itself (no walking up)
   • If under AppHost's parent, walks up parent directories from Python app directory
   • Checks each parent directory for .venv
   • Stops at the AppHost's parent directory (doesn't go beyond)
   • Uses platform-aware path comparison (case-insensitive on Windows, case-sensitive on Unix)
   • Returns first found .venv or defaults to app directory
   • Only called for default .venv during AddPythonScript/Module/Executable

3. Simplified WithVirtualEnvironment

   • Now uses paths verbatim (no multi-location lookup)
   • Resolves relative paths against app working directory only
   • Honors explicit developer intent

Test Improvements (AddPythonAppTests.cs)

• Added AssertPythonCommandPath helper to eliminate duplicate OS-specific path assertions
• Simplified directory naming (removed random file names where not needed)
• Consistently use TempDirectory for temporary directories
• All 72 tests passing ✅

Supported Scenarios

Scenario 1: .venv in parent folder of Python app (happy path)

pythonapp/.venv          ← Found here
pythonapp/myapp.py
apphost.cs

Scenario 2: .venv in common parent, AppHost in sibling folder

.venv                    ← Found here (common parent)
.aspire/apphost.cs
pythonapp/myapp.py

Scenario 3: Avoid unrelated .venv

.venv                    ← NOT used (beyond AppHost's parent)
app2/.venv
app2/apphost.cs
app1/.aspire/apphost.cs
app1/pythonapp/myapp.py  ← Starts here, walks up to app1's parent, stops

Scenario 4: App not under AppHost's parent tree

.venv                    ← NOT used (different tree)
apphostparent/apphost.cs
someotherparent/pythonapp/.venv  ← Only checks here
someotherparent/pythonapp/myapp.py

Behavior Matrix

Scenario	Lookup Behavior
AddPythonScript("name", "dir", "script.py")	Walk up from app dir, stop at AppHost's parent (if in same tree)
AddPythonModule("name", "dir", "module")	Walk up from app dir, stop at AppHost's parent (if in same tree)
AddPythonExecutable("name", "dir", "exe")	Walk up from app dir, stop at AppHost's parent (if in same tree)
.WithVirtualEnvironment(".venv")	Uses .venv in app directory verbatim
.WithVirtualEnvironment("custom")	Uses custom in app directory verbatim
.WithVirtualEnvironment("/abs/path")	Uses absolute path verbatim

Key Benefits

1. Explicit is Explicit: When developers specify a path via WithVirtualEnvironment, it's used exactly as provided
2. Smart Defaults: Walks up parent directories to find shared virtual environments
3. Safe Boundaries: Stops at AppHost's parent to avoid unrelated venvs
4. Separate Trees: Only looks in app directory when app is not under AppHost's parent tree
5. Predictable: Clear separation between automatic (walk-up lookup) and explicit (verbatim) behavior
6. Backward Compatible: Existing code works unchanged
7. Clean Tests: Reduced duplication with helper methods
8. Cross-Platform: Uses platform-aware path comparison (case-insensitive on Windows, case-sensitive on Unix)

Original prompt

Lets make the default python resource support looking for the .venv in the python app directory and in the apphost directory. If we dont find any we default to the one in the python app directory.

---

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

[davidfowl]

@copilot Fix the duplicate logic in tests around asserting the path to python with a helper:

if (OperatingSystem.IsWindows())
{
Assert.Equal(Path.Join(appVenvPath, "Scripts", "python.exe"), pythonProjectResource.Command);
}
else
{
Assert.Equal(Path.Join(appVenvPath, "bin", "python"), pythonProjectResource.Command);
}

Also there's a TempDirectory helper in the project that can be used here.

[Copilot]

@copilot Fix the duplicate logic in tests around asserting the path to python with a helper:

if (OperatingSystem.IsWindows())...

Done! Added AssertPythonCommandPath helper method to eliminate the duplicate OS-specific assertions and simplified directory naming in tests. Commit: 7c32cb4

[github-actions]

🚀 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 -- 12616

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 12616"

[davidfowl]

@copilot After some research this seems to be a reasonable pattern:

💡 Design takeaway

For your ResolveDefaultVirtualEnvironmentPath helper, a good pragmatic default is:

• If VIRTUAL_ENV is set, use it.
• If .venv exists in the app directory, use it.
• Else if .venv exists in the AppHost directory, use it.
• Else return /.venv as the future creation path.

[Copilot]

@copilot After some research this seems to be a reasonable pattern:

💡 Design takeaway...

Implemented the recommended priority pattern. The helper now checks:

1. VIRTUAL_ENV from configuration (if set and exists)
2. .venv in app directory (if exists)
3. .venv in AppHost directory (if app is nearby and exists)
4. Defaults to app directory path

Using builder.Configuration["VIRTUAL_ENV"] instead of environment variables. Commit: af30659

[davidfowl]

@copilot remove the VIRTUAL_ENV from configuration (if set and exists) check as it may yield unexpected results when you aspire run

[Copilot]

@copilot remove the VIRTUAL_ENV from configuration (if set and exists) check as it may yield unexpected results when you aspire run

Removed the VIRTUAL_ENV configuration check. The lookup now uses a simpler three-tier system:

1. .venv in app directory (if exists)
2. .venv in AppHost directory (if app is nearby and exists)
3. Defaults to app directory path

Commit: a78085f

[davidfowl]

@copilot Add a comment to the code that shows what (if app is nearby and exists) means.

[Copilot]

@copilot Address the PR feedback. We don't want to intelligently find the vdir, lets look up parent folders but not beyond the apphost's direct parent. Also lets not confuse appDirectory from the work...

Addressed the feedback:

• Removed "intelligently" from comments
• Changed to use appDirectory parameter instead of resource.WorkingDirectory
• Removed redundant Path.IsPathRooted check (GetRelativePath always returns a relative path)
• Simplified condition to just check for default .venv folder
• Updated logic to only look within the AppHost's directory tree (checks that relative path doesn't start with "..")
• Clarified comments to explain the check prevents going beyond the AppHost directory

Commit: c866034

[davidfowl]

@copilot > Change logic to only look up to the AppHost's direct parent, not siblings

We want to start at the python app directory and walk up parents but not go outside of the apphost's parent folder. Scenarios:

• The venv is in the parent folder of the python app (happy path)

pythonapp/.venv
pythonapp/myapp.py
apphost.cs

• The venv is in the parent folder of the python app but the apphost is in a sibling folder.

.venv
.aspire/apphost.cs
pythonapp/myapp.py

In this case, we dont want to go any higher than the common parent of these 2 folders.

• The case we want to avoid is an unrelated venv

.venv
app2/.venv
app2/apphost.cs
app1/.aspire/apphost.cs
app1/pythonapp/myapp.py

app1 should not detect the .vnev in the root folder

[Copilot]

@copilot > Change logic to only look up to the AppHost's direct parent, not siblings

We want to start at the python app directory and walk up parents but not go outside of the apphost's parent folder...

Implemented the walk-up logic. The code now:

• Starts at the Python app directory
• Walks up parent directories looking for .venv
• Stops when reaching the AppHost's parent directory
• Returns the first found .venv or defaults to app directory

This handles all three scenarios:

1. ✅ .venv in parent folder of Python app (finds it)
2. ✅ .venv in common parent with AppHost in sibling (finds it, stops at common parent)
3. ✅ Avoids unrelated .venv (stops at AppHost's parent, doesn't go to root)

Commit: 7881363

[eerhardt]

@copilot is this the correct way to compare directory paths?

[Copilot]

Good catch! Updated to use platform-aware comparison: StringComparison.OrdinalIgnoreCase on Windows (case-insensitive file system) and StringComparison.Ordinal on Unix (case-sensitive file system). This ensures correct path matching across platforms. Commit: 26930ab

[eerhardt]

@copilot - this should also handle the case where the appDirectory isn't parented under the appHostParentDirectory. For example:

.venv
apphostparent/apphost.cs
someotherparent/pythonapp/myapp.py

When that happens, it should only look in the appDirectory.

[Copilot]

@copilot - this should also handle the case where the appDirectory isn't parented under the appHostParentDirectory. For example:

...

Added check for this scenario. The code now:

1. First checks if the app directory is under the AppHost's parent tree
2. If not (different directory trees), only looks in the app directory itself - no walking up
3. If yes (same tree), performs the walk-up logic stopping at AppHost's parent

This prevents walking up the entire directory structure when the app and AppHost are in separate trees. Commit: bf13f27

[eerhardt]

Just one more suggestion. Then the changes look good to me.

I didn't test this though, so @davidfowl you might want to give it a whirl.

[davidfowl]

/backport to release/13.0

[github-actions]

Started backporting to release/13.0: https://github.com/dotnet/aspire/actions/runs/19060887411