🚧 Host-free Python environment API

[atifaziz]

This PR addresses #378 by proposing a new API for setting up the Python API that does not require a host builder.

It explores alternative APIs that don't require Microsoft's dependency injection hosting framework (IHost/IHostBuilder). The implementation demonstrates two potential approaches, each treating a different API as the "core" implementation, which requires a team decision on the long-term architecture direction.

Key Design Changes

New PythonEnvironmentConfiguration Class - Immutable Configuration Pattern

The centerpiece of this exploration is the new PythonEnvironmentConfiguration class (preferred), which uses non-destructive mutation through an immutable builder pattern. This class:

• Uses immutable data structures with ImmutableArray<T> collections
• Each configuration method returns a new instance rather than modifying existing state
• Implements IServiceProvider for internal service resolution while maintaining external immutability
• Provides a complete fluent API that somewhat mirrors the existing IPythonEnvironmentBuilder functionality
• Supports all existing Python locators (redistributable, NuGet, Windows Store, Conda, etc.)
• Handles package installers (pip, uv) and environment management (venv, Conda)

Two Approaches Under Consideration

This PR demonstrates two different approaches for integrating host-free functionality, each building on top of a different API being treated as the "core":

Approach 1: DI-First with Python.GetEnvironment Helper

The Python static class treats the existing service-based DI infrastructure as the core implementation and provides convenience methods for non-host scenarios:

// Simple static helper that internally uses DI services
var env = Python.GetEnvironment();
var env = Python.GetEnvironment(RedistributablePythonVersion.Python3_13, logLevel: LogLevel.Debug);

This approach maintains the current service-based architecture as the foundation while offering simplified entry points.

Approach 2: Configuration-First with AddPython Integration

The new AddPython(IServiceCollection, PythonEnvironmentConfiguration) extension assumes PythonEnvironmentConfiguration as the core API and adapts it for DI scenarios:

services.AddPython(
    PythonEnvironmentConfiguration.Default
        .SetHome(home)
        .FromRedistributable("3.12")
        .AddPipInstaller());

This approach treats the immutable configuration as the primary abstraction with DI as an integration layer.

Decision Required

The team needs to decide which approach should serve as the core implementation. Maintaining both approaches long-term would double the maintenance burden for all configuration options, even though one API could theoretically be implemented in terms of the other.

Benefits and Trade-offs

Potential Benefits

• Reduced Dependencies: Applications wouldn't need Microsoft hosting framework for simple Python usage
• Non-destructive Configuration: Immutable configuration objects provide better predictability and debugging
• Improved Performance: Eliminates service container overhead for simple scenarios
• Better Testability: Immutable configurations are easier to test and reason about
• Enhanced Flexibility: Works with any application architecture, not just Microsoft DI

Trade-offs and Concerns

• Maintenance Overhead: Two API surfaces means duplicate maintenance for every new feature or locator
• Complexity: Users now have multiple ways to achieve the same goal, potentially causing confusion
• Migration Burden: Even with backward compatibility, users may need guidance on which API to use when

Because of these concerns, there should be one core API (preferably PythonEnvironmentConfiguration) that has a simple bridge for host-based DI scenarios.

---

Pending work:

• API decision
• PR description
• Update Public API for analyzer
• Add unit tests PythonEnvironmentConfiguration