Skip to content

Cover interpreter selection in the debugging guide - #65

Merged
shivamsn97 merged 1 commit into
mainfrom
docs/debugging-interpreter-selection
Aug 6, 2026
Merged

Cover interpreter selection in the debugging guide#65
shivamsn97 merged 1 commit into
mainfrom
docs/debugging-interpreter-selection

Conversation

@shivamsn97

Copy link
Copy Markdown
Member

The issue

The debugging guide told readers that the debugger "checks it has pyxle before launching and guides you if not", and that a too-old interpreter means "run pip install --upgrade pyxle-framework". Both were incomplete in a way that misled people who hit the error with a working pyxle installed:

  • The launch runs under VS Code's selected interpreter, and the usual cause of the error is that the right pyxle lives in a different environment. Upgrading the selected one is then the wrong fix — switching to the right one is.
  • Nothing told the reader how to see or change that interpreter from a .pyxl file. The Python extension only shows its interpreter indicator for .py files, so the environment driving the launch was effectively invisible.
  • The guide implied the check was version-based. It is capability-based, which matters for editable/dev installs whose recorded version lags the code on disk.

The change

Docs only — no framework code.

  • Requirements: note that both debug configurations use the selected interpreter, and point at the status-bar item (and the Pyxle: Select Python Interpreter command) that Pyxle Language Tools shows while a .pyxl file is open.
  • Troubleshooting: the "too old" entry now offers switching environments as the first remedy alongside upgrading, and states that the check tests what the interpreter can run rather than the version its package metadata reports — so an editable install with stale dist-info is not refused.

The editor-side behaviour these lines describe is in pyxle-dev/pyxle-langkit#13. The changelog entry is under Unreleased so the published docs don't describe an editor release that isn't out yet.

Checklist

  • pytest passes and coverage stays ≥ 95% (no code changed — docs only)
  • ruff check pyxle/ tests/ is clean (no code changed)
  • New behavior has tests in the matching tests/ directory (n/a — documentation change)
  • Touched the parser or SSR? Added regression tests and verified pyxle init + pyxle dev still work end-to-end (n/a — neither touched)
  • One focused change; commit messages follow Conventional Commits (scope: compiler, ssr, cli, …)

Both VS Code debug configurations run the dev server under the interpreter VS
Code has selected, so point at the status-bar item and the Pyxle: Select Python
Interpreter command that Pyxle Language Tools shows while a .pyxl file is open,
rather than only telling the reader to upgrade.

Also note that the pre-launch check tests what the interpreter can run instead
of the version its package metadata reports, so an editable install with stale
dist-info is not refused.
@shivamsn97
shivamsn97 merged commit 31cd243 into main Aug 6, 2026
10 checks passed
@shivamsn97
shivamsn97 deleted the docs/debugging-interpreter-selection branch August 6, 2026 13:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant