Skip to content

fix(scriptutils): fix path resolution and wildcard extraction for absolute shebangs#345

Closed
mcexit wants to merge 1 commit into
python:mainfrom
mcexit:patch-1
Closed

fix(scriptutils): fix path resolution and wildcard extraction for absolute shebangs#345
mcexit wants to merge 1 commit into
python:mainfrom
mcexit:patch-1

Conversation

@mcexit
Copy link
Copy Markdown

@mcexit mcexit commented May 22, 2026

Description

This PR resolves a critical issue where scripts utilizing absolute or explicit relative shebangs (such as those generated by modern virtual environment managers like uv) are incorrectly intercepted, truncated, or routed to the wrong interpreter.

🐛 The Bugs

The original logic in _find_shebang_command heavily relied on pathlib.PurePath.match(). Because match() performs a loose right-aligned suffix match, PurePath("C:/uv/python.exe").match("python.exe") evaluates to True. This caused a chain reaction of unintended behaviors:

  1. The is_default Trap: Absolute paths like C:\...\python.exe incorrectly triggered the is_default check, discarding the user's isolated environment and defaulting to the system-wide global Python.
  2. The Wildcard Slicing Bug: The fallback check for python*.exe would intercept executables like C:\...\python_uv_test.exe and blindly slice the name ([6:-4]), causing the system to search for a phantom runtime tag (e.g., [ERROR] No runtime installed that matches _uv_test) and crash.
  3. Relative Execution Trap: sh_cmd.match(i["executable"]) could falsely intercept absolute shebangs if a registered runtime was using a relative executable name.

🛠️ The Fix

  • is_name_only Check: Introduced a check for path separators (/ or \) to properly distinguish between "bare names" (like py.exe or python3.14.exe) and explicit paths (C:\...\python.exe or ./python.exe).

    NOTE: This is significantly safer than checking len(sh_cmd.parts) == 1, which breaks explicit normalized relative paths (like #!./python.exe) by stripping the ./ and incorrectly flagging them as bare names.

  • Gated Fallbacks: Virtual alias lookup, the is_default override, and the tag extraction wildcards are now safely gated behind is_name_only.
  • Absolute vs Relative Validation: Added a condition (not PurePath(i["executable"]).is_absolute()) to prevent absolute shebangs from falsely matching relative executable registries.

🧪 Impact

With these changes, absolute paths are safely bypassed in the virtual lookup traps, allowing them to cleanly fall through to the LookupError at the end of the block. This exception is caught gracefully by _parse_shebang, which delegates the absolute path to shutil.which() under _find_on_path().

This restores 100% interoperability with tools like uv and explicit local paths (./python.exe), without breaking any existing PEP 397/PEP 486 behaviors for standard bare names.

…bare name rules

`PurePath.match()` performs right-aligned suffix matching, which caused absolute shebang paths (e.g., `C:\uv\python.exe`) to inadvertently evaluate true for bare names like `python.exe` or `python*.exe`.

This resulted in two critical bugs:

1. Virtual environment paths were hijacked by the `is_default` trap, falling back to the global default Python runtime instead of the specified one.
2. Custom executables (like `python_uv_test.exe`) were intercepted by the fallback wildcard search, resulting in arbitrary slicing and lookup errors for phantom version tags (e.g., `_uv_test`).

This commit introduces an `is_name_only` check (validating the absence of directory separators `/` and `\`) to safely distinguish bare commands from explicit paths. Gating the `is_default`, virtual alias, and wildcard extraction logic behind this check ensures explicit paths correctly fall through to `_find_on_path()`.
@python-cla-bot
Copy link
Copy Markdown

python-cla-bot Bot commented May 22, 2026

All commit authors signed the Contributor License Agreement.

CLA signed

@zooba
Copy link
Copy Markdown
Member

zooba commented May 22, 2026

Please file an issue first, and leave out the cheesy headings and just focus on the problem you're observing and the context it appears in.

@zooba zooba closed this May 22, 2026
@zooba
Copy link
Copy Markdown
Member

zooba commented May 22, 2026

Also, if an issue is "critical", please submit it as a security report using the Github Security Advisory feature. Otherwise, please refrain from assessing the severity of an issue - we can handle that, taking into account more than one single user.

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.

2 participants