# feat: Add local python SDK replacement option via pip

## Summary

Implements local Python SDK replacement functionality for testing Pulumi providers and programs with unpublished Python SDK builds. This feature enables developers to test against local Python SDKs using `pip install -e` (editable mode), following the same pattern as existing YarnLink (Node.js) and GoModReplacement (Go) features.

## Implementation Details

### Changes Made

1. **pulumitest/opttest/opttest.go**:
   - Added `PythonLinks []string` field to `Options` struct to store local Python package paths
   - Created `PythonLink()` function to accept one or more local Python package paths
   - Updated `Defaults()` function to initialize `PythonLinks` slice

2. **pulumitest/newStack.go**:
   - Implemented pip install logic to execute `python -m pip install -e <path>` for each Python package
   - Uses absolute paths (consistent with GoModReplacement pattern)
   - Executes after YarnLink and before GoModReplacement for logical ordering
   - Includes proper error handling and logging

3. **pulumitest/opttest/opttest_test.go** (new file):
   - `TestPythonLinkOption`: Verifies single package path is appended
   - `TestPythonLinkMultiplePackages`: Verifies multiple package paths can be specified
   - `TestPythonLinkAccumulates`: Verifies packages accumulate across multiple calls
   - `TestDefaultsResetsPythonLinks`: Verifies Defaults() resets PythonLinks

4. **pulumitest/README.md**:
   - Added "Python - Local Package Installation" section
   - Documented PythonLink usage with examples
   - Followed same documentation pattern as YarnLink and GoModReplacement sections

### Key Features

- **Editable Mode**: Uses `pip install -e` for symlinked/editable installation (same behavior as yarn link)
- **Multiple Packages**: Supports installing multiple local Python packages in a single test
- **Absolute Paths**: Converts relative paths to absolute paths for reliability
- **Error Handling**: Clear error messages if pip install fails or paths don't exist
- **Environment Aware**: Uses `python -m pip` for better virtual environment compatibility

## Test Plan

- ✅ All unit tests for PythonLink option pass (4/4 tests)
- ✅ Code formatting passes (go fmt)
- ✅ Code vetting passes (go vet)
- ✅ Linting passes
- ✅ Implementation follows existing architectural patterns for YarnLink and GoModReplacement

## Usage Example

```go
import (
	"filepath"
	"testing"
	"github.com/pulumi/providertest/pulumitest"
	"github.com/pulumi/providertest/pulumitest/opttest"
)

func TestWithLocalPythonSDK(t *testing.T) {
	// Use local Python SDK build
	test := pulumitest.NewPulumiTest(t, "test_dir",
		opttest.PythonLink("../sdk/python"))

	// Or multiple packages
	test2 := pulumitest.NewPulumiTest(t, "test_dir",
		opttest.PythonLink("../sdk/python", "../other-sdk/python"))

	test.Up(t)
}
```

## Fixes #39

Author: rshade

pulumitest/README.md

@@ -131,6 +131,23 @@ NewPulumiTest(t, "test_dir",
   opttest.GoModReplacement("github.com/pulumi/pulumi-my-provider/sdk/v3", "..", "sdk"))
 ```
 
+### Python - Local Package Installation
+
+For Python, we support installing local packages in editable mode via `pip install -e`. This allows using a local build of the Python SDK during testing. Before running your test, ensure your Python environment is properly configured (typically within a virtual environment).
+
+The local package installation can be specified using the `PythonLink` test option:
+
+```go
+NewPulumiTest(t, "test_dir", opttest.PythonLink("../sdk/python"))
+```
+
+Multiple packages can be specified:
+
+```go
+NewPulumiTest(t, "test_dir",
+  opttest.PythonLink("../sdk/python", "../other-sdk/python"))
+```
+
 ## Additional Operations
 
 ### Update Source

pulumitest/newStack.go

@@ -83,6 +83,10 @@ func (pt *PulumiTest) NewStack(t PT, stackName string, opts ...optnewstack.NewSt
 
 	ptLogF(t, "creating stack %s", stackName)
 	stack, err := auto.NewStackLocalSource(pt.ctx, stackName, pt.workingDir, stackOpts...)
+	if err != nil {
+		ptFatalF(t, "failed to create stack: %s", err)
+		return nil
+	}
 
 	providerPluginPaths := options.ProviderPluginPaths()
 	if len(providerPluginPaths) > 0 {
@@ -148,6 +152,22 @@ func (pt *PulumiTest) NewStack(t PT, stackName string, opts ...optnewstack.NewSt
 		}
 	}
 
+	if options.PythonLinks != nil && len(options.PythonLinks) > 0 {
+		for _, pkgPath := range options.PythonLinks {
+			absPath, err := filepath.Abs(pkgPath)
+			if err != nil {
+				ptFatalF(t, "failed to get absolute path for %s: %s", pkgPath, err)
+			}
+			cmd := exec.Command("python", "-m", "pip", "install", "-e", absPath)
+			cmd.Dir = pt.workingDir
+			ptLogF(t, "installing python package: %s", cmd)
+			out, err := cmd.CombinedOutput()
+			if err != nil {
+				ptFatalF(t, "failed to install python package %s: %s\n%s", pkgPath, err, out)
+			}
+		}
+	}
+
 	if options.GoModReplacements != nil && len(options.GoModReplacements) > 0 {
 		orderedReplacements := make([]string, 0, len(options.GoModReplacements))
 		for old := range options.GoModReplacements {
@@ -170,11 +190,6 @@ func (pt *PulumiTest) NewStack(t PT, stackName string, opts ...optnewstack.NewSt
 			}
 		}
 	}
-
-	if err != nil {
-		ptFatalF(t, "failed to create stack: %s", err)
-		return nil
-	}
 	if !stackOptions.SkipDestroy {
 		t.Cleanup(func() {
 			t.Helper()

pulumitest/opttest/opttest.go

@@ -105,6 +105,14 @@ func YarnLink(packages ...string) Option {
 	})
 }
 
+// PythonLink specifies packages which should be installed from a local path via `pip install -e` (editable mode).
+// Each package path is installed with `pip install -e <path>` on stack creation.
+func PythonLink(packagePaths ...string) Option {
+	return optionFunc(func(o *Options) {
+		o.PythonLinks = append(o.PythonLinks, packagePaths...)
+	})
+}
+
 // GoModReplacement specifies replacements to be add to the go.mod file when running the program under test.
 // Each replacement is added to the go.mod file with `go mod edit -replace <replacement>` on stack creation.
 func GoModReplacement(packageSpecifier string, replacementPathElem ...string) Option {
@@ -166,6 +174,7 @@ type Options struct {
 	Providers             map[providers.ProviderName]ProviderConfigUnion
 	UseAmbientBackend     bool
 	YarnLinks             []string
+	PythonLinks           []string
 	GoModReplacements     map[string]string
 	CustomEnv             map[string]string
 	ExtraWorkspaceOptions []auto.LocalWorkspaceOption
@@ -200,6 +209,7 @@ func Defaults() Option {
 		o.Providers = make(map[providers.ProviderName]ProviderConfigUnion)
 		o.UseAmbientBackend = false
 		o.YarnLinks = []string{}
+		o.PythonLinks = []string{}
 		o.GoModReplacements = make(map[string]string)
 		o.CustomEnv = make(map[string]string)
 		o.ExtraWorkspaceOptions = []auto.LocalWorkspaceOption{}

pulumitest/opttest/opttest_test.go

@@ -0,0 +1,63 @@
+package opttest_test
+
+import (
+	"testing"
+
+	"github.com/pulumi/providertest/pulumitest/opttest"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestPythonLinkOption(t *testing.T) {
+	t.Parallel()
+
+	opts := opttest.DefaultOptions()
+	assert.Empty(t, opts.PythonLinks, "expected PythonLinks to be empty by default")
+
+	pythonLink := opttest.PythonLink("path/to/sdk")
+	pythonLink.Apply(opts)
+
+	assert.Equal(t, []string{"path/to/sdk"}, opts.PythonLinks, "expected PythonLink to append path")
+}
+
+func TestPythonLinkMultiplePackages(t *testing.T) {
+	t.Parallel()
+
+	opts := opttest.DefaultOptions()
+
+	pythonLink := opttest.PythonLink("path/to/sdk1", "path/to/sdk2")
+	pythonLink.Apply(opts)
+
+	assert.Equal(t, []string{"path/to/sdk1", "path/to/sdk2"}, opts.PythonLinks,
+		"expected PythonLink to append multiple paths")
+}
+
+func TestPythonLinkAccumulates(t *testing.T) {
+	t.Parallel()
+
+	opts := opttest.DefaultOptions()
+
+	pythonLink1 := opttest.PythonLink("path/to/sdk1")
+	pythonLink1.Apply(opts)
+
+	pythonLink2 := opttest.PythonLink("path/to/sdk2")
+	pythonLink2.Apply(opts)
+
+	assert.Equal(t, []string{"path/to/sdk1", "path/to/sdk2"}, opts.PythonLinks,
+		"expected PythonLinks to accumulate across multiple calls")
+}
+
+func TestDefaultsResetsPythonLinks(t *testing.T) {
+	t.Parallel()
+
+	opts := opttest.DefaultOptions()
+
+	pythonLink := opttest.PythonLink("path/to/sdk")
+	pythonLink.Apply(opts)
+
+	assert.NotEmpty(t, opts.PythonLinks, "expected PythonLinks to be populated")
+
+	defaults := opttest.Defaults()
+	defaults.Apply(opts)
+
+	assert.Empty(t, opts.PythonLinks, "expected Defaults to reset PythonLinks")
+}