pyfirstaid 0.2.0__tar.gz → 0.2.2__tar.gz

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

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.2.2
+
+Fixes found by testing on a real Mac with Homebrew Python:
+
+- **Fix: false "pip installs into a DIFFERENT Python" on Homebrew** (and other setups where
+  site-packages lives outside Python's own folder). Paths are now also compared with symlinks
+  resolved.
+- **Dependency conflicts inside a system / Homebrew Python** are now reported as information
+  with safe advice, instead of a `pip install` fix that the system would refuse (PEP 668).
+
+## 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.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyfirstaid
-Version: 0.2.0
+Version: 0.2.2
 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.2.** 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.2}/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.2.** 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.2}/src/pyfirstaid/__init__.py

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

{pyfirstaid-0.2.0 → pyfirstaid-0.2.2}/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.2}/src/pyfirstaid/checks/dependencies.py

@@ -7,7 +7,7 @@ import sys
 from typing import List
 
 from pyfirstaid.model import Finding, Options, Status
-from pyfirstaid.util import run
+from pyfirstaid.util import in_virtualenv, run
 
 CHECK_ID = "dependencies"
 
@@ -25,6 +25,13 @@ def fix_for(line: str) -> str:
     return "python -m pip install --upgrade <the package named above>"
 
 
+def system_managed() -> bool:
+    """A Python that refuses pip installs (PEP 668) and is not a venv."""
+    from pyfirstaid.checks.venv import is_externally_managed
+
+    return is_externally_managed() and not in_virtualenv()
+
+
 def run_check(opts: Options) -> List[Finding]:
     code, out, err = run([sys.executable, "-m", "pip", "check"], timeout=max(opts.timeout, 30))
     if code in (124, 126, 127) or "No module named pip" in err:
@@ -33,6 +40,18 @@ def run_check(opts: Options) -> List[Finding]:
         return [Finding(CHECK_ID, Status.OK, "No dependency conflicts (pip check)")]
 
     lines = [ln for ln in out.splitlines() if ln.strip()]
+    if system_managed():
+        # pip install would be refused here (PEP 668), and these packages belong to
+        # Homebrew / the OS, so a conflict is informational, not something to fix with pip.
+        return [Finding(
+            CHECK_ID, Status.INFO,
+            "%d dependency conflict(s) inside your system / Homebrew Python (usually harmless)"
+            % len(lines),
+            detail="\n".join(lines[:8]),
+            fix="Don't pip install into this Python. Do your work in a venv "
+                "(python -m venv .venv). If it causes real errors, reinstall Python with the "
+                "tool that installed it (e.g. brew reinstall python).",
+        )]
     findings = [Finding(CHECK_ID, Status.WARN, "Dependency conflict", detail=ln, fix=fix_for(ln))
                 for ln in lines[:8]]
     if len(lines) > 8:

{pyfirstaid-0.2.0 → pyfirstaid-0.2.2}/src/pyfirstaid/checks/pip_mismatch.py

@@ -9,7 +9,7 @@ import sys
 from typing import List, Optional, Tuple
 
 from pyfirstaid.model import Finding, Options, Status
-from pyfirstaid.util import is_within, run
+from pyfirstaid.util import is_within, run, site_package_dirs
 
 CHECK_ID = "pip-mismatch"
 
@@ -34,7 +34,10 @@ def pip_belongs_here(location: str, pip_python: str, running_python: str,
 
 
 def _allowed_prefixes() -> List[str]:
-    prefixes = [sys.prefix]
+    # Homebrew (and some Linux distros) keep site-packages OUTSIDE sys.prefix,
+    # e.g. /opt/homebrew/lib/python3.14/site-packages, so include every
+    # site-packages folder this interpreter actually uses.
+    prefixes = [sys.prefix] + site_package_dirs()
     if site.ENABLE_USER_SITE:
         user_site = site.getusersitepackages()
         if isinstance(user_site, str):

{pyfirstaid-0.2.0 → pyfirstaid-0.2.2}/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.2/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.0 → pyfirstaid-0.2.2}/src/pyfirstaid/util.py

@@ -31,10 +31,14 @@ def run(cmd: List[str], timeout: float = 15.0) -> Tuple[int, str, str]:
 
 
 def norm(path: Optional[str]) -> str:
-    """Normalise a path for comparison (absolute, resolved case on Windows)."""
+    """Normalise a path for comparison: symlinks resolved, case-folded on Windows.
+
+    Resolving symlinks matters on macOS/Homebrew, where e.g.
+    /opt/homebrew/opt/python@3.14 links into /opt/homebrew/Cellar/...
+    """
     if not path:
         return ""
-    return os.path.normcase(os.path.abspath(path))
+    return os.path.normcase(os.path.realpath(path))
 
 
 def is_within(path: str, parent: str) -> bool:

pyfirstaid-0.2.2/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

{pyfirstaid-0.2.0 → pyfirstaid-0.2.2}/tests/test_more_checks.py

@@ -146,3 +146,44 @@ def test_all_checks_registered():
     ids = [c.id for c in ALL_CHECKS]
     assert len(ids) == len(set(ids)) == 12
     assert os.path.basename(__file__)  # keeps `os` used
+
+
+# --- v0.2.2 regressions found on a real Mac (Homebrew) ------------------------
+
+def test_pip_in_homebrew_site_packages_outside_prefix(tmp_path):
+    # Homebrew: sys.prefix is .../Frameworks/Python.framework/Versions/3.14, but
+    # site-packages lives in /opt/homebrew/lib/python3.14/site-packages
+    from pyfirstaid.checks import pip_mismatch
+
+    prefix = str(tmp_path / "Frameworks" / "Versions" / "3.14")
+    site_dir = str(tmp_path / "lib" / "python3.14" / "site-packages")
+    loc = os.path.join(site_dir, "pip")
+    assert not pip_mismatch.pip_belongs_here(loc, "3.14", "3.14", [prefix])
+    assert pip_mismatch.pip_belongs_here(loc, "3.14", "3.14", [prefix, site_dir])
+
+
+def test_norm_resolves_symlinks(tmp_path):
+    from pyfirstaid.util import norm
+
+    real = tmp_path / "Cellar" / "python"
+    real.mkdir(parents=True)
+    link = tmp_path / "opt-python"
+    link.symlink_to(real)
+    assert norm(str(link)) == norm(str(real))
+
+
+def test_dependency_conflicts_in_system_python_are_info(monkeypatch):
+    monkeypatch.setattr(dependencies, "system_managed", lambda: True)
+    monkeypatch.setattr(dependencies, "run", lambda cmd, timeout=0: (
+        1, "wheel 0.48.0 requires packaging, which is not installed.", ""))
+    findings = dependencies.run_check(Options())
+    assert len(findings) == 1 and findings[0].status == Status.INFO
+    assert "pip install" not in findings[0].fix.split("Don't pip install")[-1].split(".")[0]
+
+
+def test_dependency_conflicts_in_venv_are_warnings(monkeypatch):
+    monkeypatch.setattr(dependencies, "system_managed", lambda: False)
+    monkeypatch.setattr(dependencies, "run", lambda cmd, timeout=0: (
+        1, "wheel 0.48.0 requires packaging, which is not installed.", ""))
+    findings = dependencies.run_check(Options())
+    assert findings[0].status == Status.WARN and 'install "packaging"' in findings[0].fix