pyfirstaid 0.2.1__tar.gz → 0.2.2__tar.gz

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

@@ -1,5 +1,15 @@
 # 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyfirstaid
-Version: 0.2.1
+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.1.** 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?*
 
 ---

{pyfirstaid-0.2.1 → 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.1.** 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?*
 
 ---

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

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

{pyfirstaid-0.2.1 → 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.1 → 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.1 → 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.1 → 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