pyfirstaid 0.2.0__tar.gz → 0.2.1__tar.gz

{pyfirstaid-0.2.0 → pyfirstaid-0.2.1}/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.2.1
+
+- **Fix: correct results when installed with pipx or `uv tool`.** These tools put pyfirstaid in
+  its own private environment, so it used to diagnose *that* environment and report false
+  problems (e.g. "pip installs into a DIFFERENT Python"). It now checks the Python you get
+  when you type `python3`, and says so in a short note.
+- **New `--python PATH` option** to check any interpreter, e.g. `--python python3.12` or
+  `--python .venv/bin/python`. The target doesn't need pyfirstaid installed.
+- Files in the current folder (e.g. `random.py`) can no longer break pyfirstaid itself.
+- Clearer message when no compiled packages are installed.
+
 ## 0.2.0
 
 Nine new checks, bringing the total to 12:

{pyfirstaid-0.2.0 → pyfirstaid-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyfirstaid
-Version: 0.2.0
+Version: 0.2.1
 Summary: First aid for broken Python environments: finds what's wrong and tells you how to fix it.
 Project-URL: Homepage, https://github.com/sai-sakalam/pyfirstaid
 Project-URL: Issues, https://github.com/sai-sakalam/pyfirstaid/issues
@@ -26,7 +26,7 @@ Description-Content-Type: text/markdown
 
 **First aid for broken Python environments.** One command tells you *what's broken* and *exactly how to fix it*.
 
-> **Status: v0.2.** 12 checks, tested on Windows, macOS and Linux (Python 3.9–3.14).
+> **Status: v0.2.1.** 12 checks, tested on Windows, macOS and Linux (Python 3.9–3.14).
 > Feedback is very welcome in [Issues](https://github.com/sai-sakalam/pyfirstaid/issues). *Which problems do you hit most?*
 
 ---
@@ -81,6 +81,15 @@ pip install pyfirstaid          # or: pipx install pyfirstaid
 python -m pyfirstaid
 ```
 
+Installed with **pipx** or **`uv tool`**? pyfirstaid then lives in its own private environment, so it
+automatically checks the Python you get when you type `python3`, and tells you so. To check a
+different one, use `--python`:
+
+```bash
+pyfirstaid --python .venv/bin/python     # a project's virtual environment
+pyfirstaid --python python3.12           # any Python on your PATH
+```
+
 No install possible (for example, pip itself is broken)? Download `pyfirstaid.pyz` from the
 [latest release](https://github.com/sai-sakalam/pyfirstaid/releases) and run:
 
@@ -98,6 +107,7 @@ python pyfirstaid.pyz
 | `--strict` | Exits with code 1 on warnings too (useful in CI) |
 | `--only venv,ssl` / `--skip ssl` | Runs only some checks, or skips some |
 | `--list` | Lists all checks |
+| `--python PATH` | Checks a different Python (path or command, e.g. `python3.12`). It doesn't need pyfirstaid installed |
 
 Exit codes: `0` means no problems, `1` means problems were found, `2` means pyfirstaid itself failed.
 

{pyfirstaid-0.2.0 → pyfirstaid-0.2.1}/README.md

@@ -3,7 +3,7 @@
 
 **First aid for broken Python environments.** One command tells you *what's broken* and *exactly how to fix it*.
 
-> **Status: v0.2.** 12 checks, tested on Windows, macOS and Linux (Python 3.9–3.14).
+> **Status: v0.2.1.** 12 checks, tested on Windows, macOS and Linux (Python 3.9–3.14).
 > Feedback is very welcome in [Issues](https://github.com/sai-sakalam/pyfirstaid/issues). *Which problems do you hit most?*
 
 ---
@@ -58,6 +58,15 @@ pip install pyfirstaid          # or: pipx install pyfirstaid
 python -m pyfirstaid
 ```
 
+Installed with **pipx** or **`uv tool`**? pyfirstaid then lives in its own private environment, so it
+automatically checks the Python you get when you type `python3`, and tells you so. To check a
+different one, use `--python`:
+
+```bash
+pyfirstaid --python .venv/bin/python     # a project's virtual environment
+pyfirstaid --python python3.12           # any Python on your PATH
+```
+
 No install possible (for example, pip itself is broken)? Download `pyfirstaid.pyz` from the
 [latest release](https://github.com/sai-sakalam/pyfirstaid/releases) and run:
 
@@ -75,6 +84,7 @@ python pyfirstaid.pyz
 | `--strict` | Exits with code 1 on warnings too (useful in CI) |
 | `--only venv,ssl` / `--skip ssl` | Runs only some checks, or skips some |
 | `--list` | Lists all checks |
+| `--python PATH` | Checks a different Python (path or command, e.g. `python3.12`). It doesn't need pyfirstaid installed |
 
 Exit codes: `0` means no problems, `1` means problems were found, `2` means pyfirstaid itself failed.
 

{pyfirstaid-0.2.0 → pyfirstaid-0.2.1}/src/pyfirstaid/__init__.py

@@ -1,3 +1,3 @@
 """pyfirstaid: first aid for broken Python environments."""
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"

{pyfirstaid-0.2.0 → pyfirstaid-0.2.1}/src/pyfirstaid/checks/compiled.py

@@ -59,6 +59,8 @@ def run_check(opts: Options) -> List[Finding]:
         compiled_count += has_ext
 
     if not bad:
+        if compiled_count == 0:
+            return [Finding(CHECK_ID, Status.OK, "No compiled packages installed")]
         return [Finding(CHECK_ID, Status.OK,
                         "%d compiled package(s) match this Python" % compiled_count)]
 

{pyfirstaid-0.2.0 → pyfirstaid-0.2.1}/src/pyfirstaid/cli.py

@@ -8,7 +8,7 @@ import sys
 import traceback
 from typing import List, Optional
 
-from pyfirstaid import __version__
+from pyfirstaid import __version__, delegate
 from pyfirstaid.checks import ALL_CHECKS
 from pyfirstaid.model import Check, Finding, Options, Status
 from pyfirstaid.report import render_json, render_text
@@ -31,6 +31,10 @@ def build_parser() -> argparse.ArgumentParser:
     p.add_argument("--skip", metavar="IDS", help="comma-separated check ids to skip")
     p.add_argument("--list", action="store_true", help="list available checks and exit")
     p.add_argument("--no-color", action="store_true", help="disable colored output")
+    p.add_argument("--python", metavar="PATH",
+                   help="check this Python instead (path or command, e.g. python3.12). "
+                        "Default: the Python running pyfirstaid, or `python3` on PATH "
+                        "when pyfirstaid is installed with pipx / uv tool")
     p.add_argument("--version", action="version", version="pyfirstaid " + __version__)
     return p
 
@@ -67,7 +71,54 @@ def use_color(no_color: bool) -> bool:
         or bool(os.environ.get("WT_SESSION"))  # Windows Terminal supports ANSI
 
 
+def forwarded(argv: List[str]) -> List[str]:
+    """Command-line arguments minus --python, to pass on to the target interpreter."""
+    out, skip_next = [], False
+    for a in argv:
+        if skip_next:
+            skip_next = False
+        elif a == "--python":
+            skip_next = True
+        elif not a.startswith("--python="):
+            out.append(a)
+    return out
+
+
+def maybe_delegate(args: argparse.Namespace, argv: List[str]) -> Optional[int]:
+    """Re-run inside another interpreter when needed. Returns its exit code, or None."""
+    if os.environ.get(delegate.DELEGATED_ENV):
+        return None
+    if args.python:
+        target = delegate.resolve(args.python)
+        if not target:
+            print("pyfirstaid: cannot find Python %r" % args.python, file=sys.stderr)
+            return EXIT_INTERNAL
+        reason = "--python"
+    elif delegate.in_tool_venv(sys.prefix):
+        target = delegate.default_target()
+        if not target:
+            return None
+        reason = "tool"
+    else:
+        return None
+
+    info = delegate.probe(target)
+    if info is None or not info[0]:
+        print("pyfirstaid: %s %s; checking the Python that runs pyfirstaid instead."
+              % (target, "does not start" if info is None else "is older than Python 3.9"),
+              file=sys.stderr)
+        return None
+    if delegate.same_environment(info[1]):
+        return None
+    if reason == "tool" and not args.json:
+        print("Note: pyfirstaid is installed in its own environment (pipx / uv tool), so it is "
+              "checking the Python you get with `python3`: %s\n"
+              "      Use --python PATH to check a different one.\n" % target, file=sys.stderr)
+    return delegate.run_in(target, forwarded(argv))
+
+
 def main(argv: Optional[List[str]] = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
     args = build_parser().parse_args(argv)
 
     if args.list:
@@ -75,6 +126,10 @@ def main(argv: Optional[List[str]] = None) -> int:
             print("%-16s %s" % (c.id, c.title))
         return EXIT_OK
 
+    code = maybe_delegate(args, argv)
+    if code is not None:
+        return code
+
     try:
         findings = run_checks(select_checks(args.only, args.skip), Options(offline=args.offline))
         if args.json:

pyfirstaid-0.2.1/src/pyfirstaid/delegate.py

@@ -0,0 +1,85 @@
+"""Run the checks inside *another* Python interpreter.
+
+pyfirstaid must examine the Python the user actually works with. When it is
+installed with pipx or `uv tool`, it runs from its own private virtual
+environment, so it re-runs itself inside the target interpreter instead.
+pyfirstaid has no dependencies, so the target does not need it installed.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from typing import List, Optional, Tuple
+
+DELEGATED_ENV = "PYFIRSTAID_DELEGATED"
+
+_TOOL_VENV_MARKERS = ("/pipx/venvs/", "/uv/tools/", "/pipx/.cache/")
+
+# Runs inside the target interpreter. Drop the current folder from sys.path so a
+# user's random.py or json.py can't break pyfirstaid, then import it from argv[1].
+_BOOTSTRAP = (
+    "import sys; sys.path[:] = [p for p in sys.path if p not in ('', '.')]; "
+    "sys.path.insert(0, sys.argv.pop(1)); "
+    "from pyfirstaid.cli import main; sys.exit(main(sys.argv[1:]))"
+)
+
+
+def in_tool_venv(prefix: str) -> bool:
+    """True if `prefix` is a private tool environment made by pipx or `uv tool`."""
+    p = prefix.replace("\\", "/").lower() + "/"
+    return any(m in p for m in _TOOL_VENV_MARKERS)
+
+
+def default_target() -> Optional[str]:
+    """The interpreter the user gets when typing `python3` (or `python`)."""
+    return shutil.which("python3") or shutil.which("python")
+
+
+def resolve(python: str) -> Optional[str]:
+    """Accept a path or a command name such as `python3.12`."""
+    if os.path.sep in python or (os.altsep and os.altsep in python):
+        return python if os.path.exists(python) else None
+    return shutil.which(python)
+
+
+def package_root() -> str:
+    """Folder (or .pyz file) that contains the `pyfirstaid` package."""
+    import pyfirstaid
+
+    return os.path.dirname(os.path.dirname(os.path.abspath(pyfirstaid.__file__)))
+
+
+def probe(target: str) -> Optional[Tuple[bool, str]]:
+    """Ask `target` for (is Python 3.9+, sys.prefix). None if it does not start."""
+    try:
+        out = subprocess.run(
+            [target, "-c", "import sys; print(sys.version_info >= (3, 9)); print(sys.prefix)"],
+            capture_output=True, text=True, timeout=15,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    lines = out.stdout.strip().splitlines()
+    if out.returncode != 0 or len(lines) < 2:
+        return None
+    return lines[0] == "True", lines[1]
+
+
+def same_environment(target_prefix: str) -> bool:
+    """Venv interpreters are often links to the same binary, so compare sys.prefix."""
+    def key(p: str) -> str:
+        return os.path.normcase(os.path.realpath(p))
+
+    return key(target_prefix) == key(sys.prefix)
+
+
+def build_command(target: str, forwarded_args: List[str]) -> List[str]:
+    return [target, "-c", _BOOTSTRAP, package_root()] + list(forwarded_args)
+
+
+def run_in(target: str, forwarded_args: List[str]) -> int:
+    env = dict(os.environ)
+    env[DELEGATED_ENV] = "1"
+    return subprocess.call(build_command(target, forwarded_args), env=env)

pyfirstaid-0.2.1/tests/test_delegate.py

@@ -0,0 +1,50 @@
+import os
+import subprocess
+import sys
+
+from pyfirstaid import cli, delegate
+
+
+def test_in_tool_venv():
+    assert delegate.in_tool_venv(
+        "/Users/me/Library/Application Support/pipx/venvs/pyfirstaid")
+    assert delegate.in_tool_venv("/home/me/.local/share/pipx/venvs/pyfirstaid")
+    assert delegate.in_tool_venv("/home/me/.local/share/uv/tools/pyfirstaid")
+    assert delegate.in_tool_venv(r"C:\Users\me\pipx\venvs\pyfirstaid")
+    assert not delegate.in_tool_venv("/home/me/project/.venv")
+    assert not delegate.in_tool_venv("/opt/homebrew/opt/python@3.14")
+
+
+def test_forwarded_drops_python_option():
+    assert cli.forwarded(["--share", "--python", "/x/python", "--only", "venv"]) == \
+        ["--share", "--only", "venv"]
+    assert cli.forwarded(["--python=/x/python", "--json"]) == ["--json"]
+
+
+def test_resolve_command_name_and_path():
+    assert delegate.resolve(sys.executable) == sys.executable
+    assert delegate.resolve(os.path.join("no", "such", "python")) is None
+
+
+def test_probe_and_same_environment():
+    ok, prefix = delegate.probe(sys.executable)
+    assert ok and delegate.same_environment(prefix)
+    assert not delegate.same_environment("/somewhere/else")
+
+
+def test_unknown_python_is_an_error(capsys):
+    assert cli.main(["--python", "/definitely/not/a/python"]) == cli.EXIT_INTERNAL
+
+
+def test_delegated_run_produces_report():
+    # Run pyfirstaid "inside" this same interpreter through the bootstrap command,
+    # exactly as --python would for another interpreter.
+    cmd = delegate.build_command(sys.executable, ["--only", "encoding", "--json"])
+    env = dict(os.environ, **{delegate.DELEGATED_ENV: "1"})
+    out = subprocess.run(cmd, capture_output=True, text=True, env=env, timeout=60)
+    assert out.returncode == 0, out.stderr
+    assert '"check": "encoding"' in out.stdout
+
+
+def test_probe_missing_python():
+    assert delegate.probe("/definitely/not/a/python") is None