pyfirstaid 0.2.1__tar.gz → 0.2.3__tar.gz

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

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.2.3
+
+- Clearer PEP 668 message: it now says the block can come from your OS *or* a package
+  manager such as Homebrew.
+- PyPI page: version, Python-versions, downloads and license badges; Source and Changelog
+  links; per-version Python classifiers (3.9–3.14).
+
+## 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.3}/PKG-INFO

@@ -1,9 +1,11 @@
 Metadata-Version: 2.5
 Name: pyfirstaid
-Version: 0.2.1
+Version: 0.2.3
 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: Source, https://github.com/sai-sakalam/pyfirstaid
 Project-URL: Issues, https://github.com/sai-sakalam/pyfirstaid/issues
+Project-URL: Changelog, https://github.com/sai-sakalam/pyfirstaid/blob/main/CHANGELOG.md
 Author: Sai Gavaskar Sakalam
 License-Expression: MIT
 License-File: LICENSE
@@ -13,6 +15,13 @@ Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Debuggers
 Classifier: Topic :: System :: Installation/Setup
 Requires-Python: >=3.9
@@ -22,11 +31,15 @@ Requires-Dist: ruff>=0.5; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # pyfirstaid 🩹
+[![PyPI](https://img.shields.io/pypi/v/pyfirstaid)](https://pypi.org/project/pyfirstaid/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pyfirstaid)](https://pypi.org/project/pyfirstaid/)
+[![Downloads](https://static.pepy.tech/badge/pyfirstaid/month)](https://pepy.tech/projects/pyfirstaid)
 [![CI](https://github.com/sai-sakalam/pyfirstaid/actions/workflows/ci.yml/badge.svg)](https://github.com/sai-sakalam/pyfirstaid/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/sai-sakalam/pyfirstaid/blob/main/LICENSE)
 
 **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: early, actively developed.** 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.3}/README.md

@@ -1,9 +1,13 @@
 # pyfirstaid 🩹
+[![PyPI](https://img.shields.io/pypi/v/pyfirstaid)](https://pypi.org/project/pyfirstaid/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pyfirstaid)](https://pypi.org/project/pyfirstaid/)
+[![Downloads](https://static.pepy.tech/badge/pyfirstaid/month)](https://pepy.tech/projects/pyfirstaid)
 [![CI](https://github.com/sai-sakalam/pyfirstaid/actions/workflows/ci.yml/badge.svg)](https://github.com/sai-sakalam/pyfirstaid/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/sai-sakalam/pyfirstaid/blob/main/LICENSE)
 
 **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: early, actively developed.** 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.3}/pyproject.toml

@@ -18,6 +18,13 @@ classifiers = [
     "Intended Audience :: Developers",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3 :: Only",
     "Topic :: Software Development :: Debuggers",
     "Topic :: System :: Installation/Setup",
 ]
@@ -31,7 +38,9 @@ pyfirstaid = "pyfirstaid.cli:main"
 
 [project.urls]
 Homepage = "https://github.com/sai-sakalam/pyfirstaid"
+Source = "https://github.com/sai-sakalam/pyfirstaid"
 Issues = "https://github.com/sai-sakalam/pyfirstaid/issues"
+Changelog = "https://github.com/sai-sakalam/pyfirstaid/blob/main/CHANGELOG.md"
 
 [tool.hatch.version]
 path = "src/pyfirstaid/__init__.py"

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

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

{pyfirstaid-0.2.1 → pyfirstaid-0.2.3}/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.3}/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.3}/src/pyfirstaid/checks/venv.py

@@ -62,7 +62,8 @@ def run_check(opts: Options) -> List[Finding]:
             findings.append(Finding(
                 CHECK_ID, Status.WARN,
                 "No virtual environment, and this system Python blocks pip installs",
-                detail="Your OS marks this Python as externally managed (PEP 668), "
+                detail="Your OS or package manager (e.g. Homebrew) marks this Python as "
+                       "externally managed (PEP 668), "
                        "so `pip install` will fail with 'externally-managed-environment'.",
                 fix="python -m venv .venv  &&  " + activate_command(".venv"),
             ))

{pyfirstaid-0.2.1 → pyfirstaid-0.2.3}/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.3}/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