diff --git a/CLI-IMPLEMENTATION.md b/CLI-IMPLEMENTATION.md index 1761a3b..94a0034 100644 --- a/CLI-IMPLEMENTATION.md +++ b/CLI-IMPLEMENTATION.md @@ -2,7 +2,7 @@ Status: implementation sequence, updated 2026-11-11. Native Go profiling and binding commands are implemented, with CI coverage for the relocated CLI and shared YAML resources. -The TypeScript and Java add-ons run from PATH (`rc profile typescript`, `rc profile java`, `rc plugins list`). Add-on descriptors, `rc doctor`, +The TypeScript, Java, and Python add-ons run from PATH (`rc profile typescript`, `rc profile java`, `rc profile python`, `rc plugins list`). Add-on descriptors, `rc doctor`, other languages, system-package distribution, and upstream workflow migration remain planned. Repository: github.com/runtimeconditions/rc-cli; executable and command name: `rc`. System package and Homebrew formula name: `rc-cli`; releases use independent `vMAJOR.MINOR.PATCH` tags. @@ -62,6 +62,7 @@ rc profile go generate --dir ./service --out profile.yaml rc profile go validate-extensions --dir ./service rc profile typescript generate --project ./service --name orders --workload-uri https://example.com/orders rc profile java generate --project ./service --classpath bindings.jar --name orders --workload-uri https://example.com/orders +rc profile python generate --project ./service --name orders --workload-uri https://example.com/orders rc profile python profile generate --project ./service rc plugins list [--output yaml] rc doctor [--language go|python|java|...] [--output yaml] diff --git a/README.md b/README.md index beceecf..1fb1ad0 100644 --- a/README.md +++ b/README.md @@ -102,25 +102,33 @@ TypeScript profiler is on npm for developers who want it in their npm scripts: `npm install --global @runtimeconditions/typescript-profiler`. The Java profiler is a jar that its launcher, `rc-profiler-java`, runs; download it from the [releases](https://github.com/runtimeconditions/java-rc-profiler/releases) of -`runtimeconditions/java-rc-profiler` and put the launcher on `PATH`. System packages for Homebrew, +`runtimeconditions/java-rc-profiler` and put the launcher on `PATH`. The Python profiler is on PyPI as +`runtimeconditions-profiler`; install it with `pip` into the workload's own virtual environment, because it finds +binding packages through that environment's metadata, and put the environment's `bin` directory on `PATH`. System packages for Homebrew, apt, and yum, so that `rc` and its add-ons install the same way on a build server, are planned. | Command | Purpose | | --- | --- | | `rc profile typescript [flags]` | Run the installed TypeScript profiler. | | `rc profile java [flags]` | Run the installed Java profiler. | +| `rc profile python [flags]` | Run the installed Python profiler. | | `rc plugins list [--output yaml]` | Show the Go profiler and each add-on's status, version, and path. | -Everything after `typescript` or `java` goes to the add-on unchanged, so it keeps its own flags +Everything after `typescript`, `java`, or `python` goes to the add-on unchanged, so it keeps its own flags (for example `--project` instead of `--dir`, and `--classpath` for Java). `rc` looks for -`rc-profiler-typescript`, then `runtimeconditions-typescript-profiler`, or `rc-profiler-java`, on `PATH`; -`RC_TYPESCRIPT_PROFILER` or `RC_JAVA_PROFILER` can name an absolute path instead. It runs the add-on only +`rc-profiler-typescript`, then `runtimeconditions-typescript-profiler`, or `rc-profiler-java`, or +`runtimeconditions-python-profiler`, on `PATH`; `RC_TYPESCRIPT_PROFILER`, `RC_JAVA_PROFILER`, or +`RC_PYTHON_PROFILER` can name an absolute path instead. It runs the add-on only if `--version --json` lists the core profile schema `rc` targets (0.4.0). The add-on's output and exit status pass through. The Java launcher chooses the JDK, not `rc`: `RC_JAVA_HOME`, then `JAVA_HOME`, then the runtime bundled in its system package, then `java` on `PATH`. It needs JDK 17 or newer and says so when none is found. +The Python profiler runs on the interpreter of the environment it is installed in (Python 3.11 or newer), and +sees the binding packages installed there. Install the profiler next to the bindings the workload imports, not +with `pipx`, which would give it an environment of its own. + ## Binding commands ```sh diff --git a/internal/cli/plugins_test.go b/internal/cli/plugins_test.go index ac50a9e..495e554 100644 --- a/internal/cli/plugins_test.go +++ b/internal/cli/plugins_test.go @@ -36,6 +36,8 @@ const readyVersion = `{"name":"@runtimeconditions/typescript-profiler","version" const javaVersion = `{"name":"runtimeconditions-java-profiler","version":"0.1.0","coreSchemas":["0.4.0"]}` +const pythonVersion = `{"name":"runtimeconditions-python-profiler","version":"0.5.0","coreSchemas":["0.4.0"]}` + func deps(runner process.Runner, installed ...string) Dependencies { present := map[string]bool{} for _, name := range installed { @@ -161,10 +163,11 @@ func TestPluginsListReportsEveryStatus(t *testing.T) { t.Fatalf("an add-on with its own runtime is ready without node: %+v", packaged[1]) } ready := read(deps(&fakeRunner{version: readyVersion}, "rc-profiler-typescript", "node")) - if len(ready) != 3 || ready[0].Language != "go" || ready[0].Status != "built-in" || + if len(ready) != 4 || ready[0].Language != "go" || ready[0].Status != "built-in" || ready[1].Language != "typescript" || ready[1].Status != "ready" || ready[1].Version != "0.2.0" || ready[1].Path != "/usr/bin/rc-profiler-typescript" || ready[1].Origin != "path" || - ready[2].Language != "java" || ready[2].Status != "missing" { + ready[2].Language != "java" || ready[2].Status != "missing" || + ready[3].Language != "python" || ready[3].Status != "missing" { t.Fatalf("%+v", ready) } java := read(deps(&fakeRunner{version: javaVersion}, "rc-profiler-java")) @@ -175,6 +178,11 @@ func TestPluginsListReportsEveryStatus(t *testing.T) { if incompatible := read(deps(&fakeRunner{version: `{"name":"x","version":"1","coreSchemas":["0.3.0"]}`}, "rc-profiler-java")); incompatible[2].Status != "incompatible" { t.Fatalf("%+v", incompatible[2]) } + python := read(deps(&fakeRunner{version: pythonVersion}, "runtimeconditions-python-profiler")) + if python[3].Language != "python" || python[3].Status != "ready" || python[3].Version != "0.5.0" || + python[3].Path != "/usr/bin/runtimeconditions-python-profiler" || python[3].Origin != "path" { + t.Fatalf("a Python profiler on PATH is ready without python on PATH: %+v", python[3]) + } for status, d := range map[string]Dependencies{ "missing": deps(&fakeRunner{}), "runtime-missing": deps(&fakeRunner{}, "rc-profiler-typescript"), @@ -190,16 +198,17 @@ func TestPluginsListReportsEveryStatus(t *testing.T) { func TestPluginsListTextAndHelp(t *testing.T) { code, out, _ := run(t, deps(&fakeRunner{version: readyVersion}, "rc-profiler-typescript", "node"), "plugins", "list") lines := strings.Split(strings.TrimSpace(out), "\n") - if code != 0 || len(lines) != 4 || !strings.HasPrefix(lines[0], "LANGUAGE") || + if code != 0 || len(lines) != 5 || !strings.HasPrefix(lines[0], "LANGUAGE") || !slices.Equal(strings.Fields(lines[2]), []string{"typescript", "ready", "0.2.0", "/usr/bin/rc-profiler-typescript"}) || - !slices.Equal(strings.Fields(lines[3]), []string{"java", "missing"}) { + !slices.Equal(strings.Fields(lines[3]), []string{"java", "missing"}) || + !slices.Equal(strings.Fields(lines[4]), []string{"python", "missing"}) { t.Fatalf("code=%d %q", code, out) } if code, _, errOut := run(t, deps(&fakeRunner{}), "plugins", "list", "--output", "json"); code != 2 || !strings.Contains(errOut, "unsupported output format") { t.Fatalf("code=%d %q", code, errOut) } code, out, _ = run(t, deps(&fakeRunner{}), "profile", "--help") - if code != 0 || !strings.Contains(out, "typescript") || !strings.Contains(out, "java") || !strings.Contains(out, "go ") { + if code != 0 || !strings.Contains(out, "typescript") || !strings.Contains(out, "java") || !strings.Contains(out, "python") || !strings.Contains(out, "go ") { t.Fatalf("profile help %q", out) } } @@ -252,3 +261,36 @@ func TestJavaAddOnForAnotherCoreSchemaIsNotRun(t *testing.T) { t.Fatalf("code=%d %q calls=%+v", code, errOut, runner.calls) } } + +func TestPythonAddOnReceivesItsArgumentsUnchangedAndItsOutputPassesThrough(t *testing.T) { + runner := &fakeRunner{version: pythonVersion, output: "profile: yaml\n"} + args := []string{"generate", "--project", "./svc", "--name", "orders", "--workload-uri", "https://example.com/o", "--", "--odd", "a b"} + code, out, errOut := run(t, deps(runner, "runtimeconditions-python-profiler"), append([]string{"profile", "python"}, args...)...) + if code != 0 || out != "profile: yaml\n" || errOut != "" { + t.Fatalf("code=%d out=%q err=%q", code, out, errOut) + } + if len(runner.calls) != 1 || runner.calls[0].Path != "/usr/bin/runtimeconditions-python-profiler" || !slices.Equal(runner.calls[0].Args, args) { + t.Fatalf("calls: %+v", runner.calls) + } +} + +func TestPythonAddOnThatIsNotInstalledSaysHowToGetIt(t *testing.T) { + runner := &fakeRunner{} + code, _, errOut := run(t, deps(runner, "node"), "profile", "python", "generate") + if code != 1 || strings.Count(errOut, "rc:") != 1 || !strings.Contains(errOut, "Python profiler is not installed") || + !strings.Contains(errOut, "pip install runtimeconditions-profiler") || !strings.Contains(errOut, "RC_PYTHON_PROFILER") || + strings.Contains(errOut, "Usage:") { + t.Fatalf("code=%d %q", code, errOut) + } + if len(runner.calls) != 0 { + t.Fatalf("the add-on ran: %+v", runner.calls) + } +} + +func TestPythonAddOnForAnotherCoreSchemaIsNotRun(t *testing.T) { + runner := &fakeRunner{version: `{"name":"runtimeconditions-python-profiler","version":"0.4.0","coreSchemas":["0.3.0"]}`} + code, _, errOut := run(t, deps(runner, "runtimeconditions-python-profiler"), "profile", "python", "generate") + if code != 1 || !strings.Contains(errOut, "0.4.0") || len(runner.calls) != 0 { + t.Fatalf("code=%d %q calls=%+v", code, errOut, runner.calls) + } +} diff --git a/internal/plugins/plugins.go b/internal/plugins/plugins.go index 4db0c10..85fffb3 100644 --- a/internal/plugins/plugins.go +++ b/internal/plugins/plugins.go @@ -56,8 +56,20 @@ var Java = Language{ InstallHint: "download rc-profiler-java from https://github.com/runtimeconditions/java-rc-profiler/releases and put it on PATH", } +// Python is the Python profiler, published to PyPI as runtimeconditions-profiler. It finds binding packages through the +// metadata of the Python environment it is installed in, so it has to be installed in the workload's own environment, +// not in an isolated one such as pipx makes. That environment's bin directory goes on PATH, or RC_PYTHON_PROFILER names +// the script. Its console script starts the interpreter of that environment, so rc lists no runtime for it. +var Python = Language{ + ID: "python", + Display: "Python", + Executables: []string{"runtimeconditions-python-profiler"}, + OverrideEnv: "RC_PYTHON_PROFILER", + InstallHint: "pip install runtimeconditions-profiler in the workload's virtual environment, then put that environment's bin directory on PATH", +} + // Languages returns the optional languages rc supports. -func Languages() []Language { return []Language{TypeScript, Java} } +func Languages() []Language { return []Language{TypeScript, Java, Python} } // Finder looks up executables. Tests replace both functions. type Finder struct { diff --git a/internal/plugins/plugins_test.go b/internal/plugins/plugins_test.go index a805ead..7ce9990 100644 --- a/internal/plugins/plugins_test.go +++ b/internal/plugins/plugins_test.go @@ -180,3 +180,38 @@ func TestJavaOverrideNamesAnAbsoluteExecutable(t *testing.T) { t.Fatalf("%+v %v", found, err) } } + +func TestPythonIsFoundByItsConsoleScriptAndNeedsNoRuntimeOnPath(t *testing.T) { + // The console script starts the interpreter of the environment it was installed in. + installed := map[string]string{"runtimeconditions-python-profiler": "/work/.venv/bin/runtimeconditions-python-profiler"} + found, err := finder(installed, nil).Find(Python) + if err != nil || found.Path != "/work/.venv/bin/runtimeconditions-python-profiler" || found.Origin != "path" { + t.Fatalf("%+v %v", found, err) + } + if got := finder(installed, nil).MissingRuntime(Python); got != "" { + t.Fatalf("Python lists no runtime, got %q", got) + } +} + +func TestPythonMissingSaysHowToInstallIt(t *testing.T) { + _, err := finder(map[string]string{}, nil).Find(Python) + if err == nil { + t.Fatal("expected an error") + } + for _, want := range []string{"Python profiler is not installed", "runtimeconditions-python-profiler", "install it with: " + Python.InstallHint, "RC_PYTHON_PROFILER"} { + if !strings.Contains(err.Error(), want) { + t.Errorf("%q is missing from %q", want, err) + } + } +} + +func TestPythonOverrideNamesAnAbsoluteExecutable(t *testing.T) { + installed := map[string]string{"/work/.venv/bin/runtimeconditions-python-profiler": "/work/.venv/bin/runtimeconditions-python-profiler"} + found, err := finder(installed, map[string]string{Python.OverrideEnv: "/work/.venv/bin/runtimeconditions-python-profiler"}).Find(Python) + if err != nil || found.Path != "/work/.venv/bin/runtimeconditions-python-profiler" || found.Origin != "override" { + t.Fatalf("%+v %v", found, err) + } + if _, err := finder(installed, map[string]string{Python.OverrideEnv: "runtimeconditions-python-profiler"}).Find(Python); err == nil { + t.Fatal("a relative override must be refused") + } +}