pyfirstaid 0.1.0__tar.gz → 0.2.0__tar.gz

pyfirstaid-0.2.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/

pyfirstaid-0.2.0/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## 0.2.0
+
+Nine new checks, bringing the total to 12:
+
+- **python-version**: Python past (or close to) end of life, pre-release Pythons, and Apple's
+  built-in Command Line Tools Python on macOS.
+- **path**: typing `python` / `python3` runs a *different* Python, or opens the Windows
+  Microsoft Store shortcut.
+- **leaks**: `PYTHONPATH` / `PYTHONHOME` set, and venvs that can see system packages.
+- **shadowing**: files like `random.py` or `requests.py` in the current folder that hide real
+  modules.
+- **compiled**: packages with compiled files built for a different Python version.
+- **broken-installs**: packages installed twice, `~` leftovers from interrupted installs,
+  and corrupted metadata.
+- **dependencies**: dependency conflicts from `pip check`, each with a suggested fix.
+- **permissions**: venvs that are not writable (e.g. created with sudo).
+- **encoding**: default text encoding that is not UTF-8.
+
+## 0.1.0
+
+First release, with 3 checks:
+
+- **venv**: is a virtual environment active, is an unused `.venv` sitting in the folder,
+  is a *different* venv activated in your shell, and does the system Python block pip (PEP 668)?
+- **pip-mismatch**: does the `pip` command install into a different Python than the one you run?
+- **ssl**: can Python reach pypi.org over HTTPS, and are certificate settings
+  (`SSL_CERT_FILE`, `REQUESTS_CA_BUNDLE`, `PIP_CERT`, macOS certificates) valid?
+
+Options: `--json`, `--share`, `--offline`, `--strict`, `--only`, `--skip`, `--list`.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyfirstaid
-Version: 0.1.0
+Version: 0.2.0
 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.1, early.** 3 checks work today, and more are on the roadmap.
+> **Status: v0.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?*
 
 ---
@@ -41,40 +41,51 @@ This was discussed on the Python forum: [Standard Library Health Check Module](h
 
 ## Example
 
-A real run: the virtual environment's Python is running, but the `pip` command on PATH belongs to the system Python:
+A run inside a project folder where the venv's Python is running, `pip` belongs to the
+system Python, and a file called `random.py` is hiding the real `random` module:
 
 ```console
-$ python -m pyfirstaid
+$ python -m pyfirstaid --share
 
-pyfirstaid 0.1.0: checking your Python environment
+pyfirstaid 0.2.0: checking your Python environment
 Python 3.13.1 (~/project/.venv/bin/python)
 
+✔ Python 3.13.1 (supported until October 2029)
 ✔ Virtual environment active: ~/project/.venv
 ✘ `pip` installs into a DIFFERENT Python
-    pip    -> /usr/lib/python3/dist-packages/pip (python 3.13)
+    pip    -> /opt/homebrew/lib/python3.13/site-packages/pip (python 3.13)
     python -> ~/project/.venv/bin/python (python 3.13)
     fix: Use `python -m pip install <package>` instead of `pip install`. If a virtual environment should be active, activate it first.
-✔ HTTPS to pypi.org works (OpenSSL 3.0.13 30 Jan 2024)
-
-1 problem(s), 0 warning(s).
+! Typing `python3` runs a DIFFERENT Python than this one
+    python3 -> /opt/homebrew
+    this Python -> ~/project/.venv
+    fix: Activate the virtual environment you want, or call Python by its full path. To change the default, put the right Python's folder first in PATH.
+✔ No PYTHONPATH / PYTHONHOME leaks
+! `random.py` in this folder hides the standard library module `random`
+    `import random` will load your file instead, which causes confusing errors like "module 'random' has no attribute ...".
+    fix: Rename it (e.g. my_random.py) and delete any __pycache__ folder next to it.
+✔ HTTPS to pypi.org works (OpenSSL 3.4.0 22 Oct 2024)
+✔ 12 compiled package(s) match this Python
+✔ No broken or duplicate installs (1 folder(s) scanned)
+✔ No dependency conflicts (pip check)
+✔ site-packages is writable
+✔ Default text encoding is UTF-8
+
+1 problem(s), 2 warning(s).
 ```
 
 ## Try it
 
-pyfirstaid is not on PyPI yet. To run it from source:
-
 ```bash
-git clone https://github.com/sai-sakalam/pyfirstaid
-cd pyfirstaid
-python -m pip install .
+pip install pyfirstaid          # or: pipx install pyfirstaid
 python -m pyfirstaid
 ```
 
-Or build the **single file**, which needs no install and works even when pip is broken:
+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:
 
 ```bash
-python scripts/build_pyz.py
-python dist/pyfirstaid.pyz
+python pyfirstaid.pyz
 ```
 
 ### Options
@@ -104,6 +115,48 @@ Usually `pip` installed into a different Python, or your virtual environment isn
 
 This checks whether a company proxy is intercepting HTTPS and whether your certificate settings point at real files.
 
+**"`module 'random' has no attribute 'randint'`" (or the same with `json`, `requests`, ...)**
+
+    python -m pyfirstaid --only shadowing
+
+A file in your folder with the same name as a real module (`random.py`, `json.py`, `requests.py`) is being imported instead of the real one. pyfirstaid names the file to rename.
+
+**"I upgraded Python and now a package fails with `ImportError` / `undefined symbol` / `DLL load failed`."**
+
+    python -m pyfirstaid --only compiled,broken-installs
+
+Compiled packages built for your *old* Python version, or half-removed installs, are the usual cause. You get the exact reinstall command.
+
+**"`python3 --version` still shows the old version after I installed a new Python."**
+
+    python3 -m pyfirstaid --only path,python-version
+
+Shows which Python `python` / `python3` actually start, warns about Apple's built-in Python on macOS and the Microsoft Store shortcut on Windows, and flags Pythons past end of life.
+
+**"pip says ERROR: Could not install packages due to an OSError: Permission denied."**
+
+    python -m pyfirstaid --only permissions,venv
+
+Tells you whether you're installing into a read-only system Python (use a venv or pipx) or into a venv that was created with `sudo`.
+
+**"pip check shows conflicts and I don't know what to install."**
+
+    python -m pyfirstaid --only dependencies
+
+Each conflict comes with a ready-to-run `pip install` command.
+
+**"`UnicodeDecodeError` when reading a file, but it works on my colleague's machine."**
+
+    python -m pyfirstaid --only encoding
+
+Your default text encoding is not UTF-8 (common on Windows and minimal Linux/Docker images). pyfirstaid shows the one-line fix.
+
+**"My venv picks up packages I never installed in it."**
+
+    python -m pyfirstaid --only leaks
+
+`PYTHONPATH` or `PYTHONHOME` set in your shell profile is the usual reason.
+
 **"I'm reporting a bug and the maintainer asked for my environment details."**
 
     python -m pyfirstaid --share
@@ -124,18 +177,22 @@ Download `pyfirstaid.pyz` from the [latest release](https://github.com/sai-sakal
 
 ## Checks
 
-| Status | Check | What it catches |
-|---|---|---|
-| ✅ v0.1 | `venv` | No venv active, an unused `.venv` in the folder, a *different* venv activated in your shell, a system Python that blocks pip (PEP 668) |
-| ✅ v0.1 | `pip-mismatch` | `pip` installs into a different Python than the one you run, pip missing, a broken `pip` command |
-| ✅ v0.1 | `ssl` | Certificate failures reaching PyPI (corporate proxies), certificate variables pointing at missing files, macOS certificates not installed, Python built without SSL |
-| 🔜 planned | `compiled` | Compiled packages built for a different Python version |
-| 🔜 planned | `broken-installs` | Duplicate or half-removed packages |
-| 🔜 planned | `dependencies` | Dependency conflicts (`pip check`) |
-| 🔜 planned | `path` | Several Pythons on PATH hiding each other |
-| 🔜 planned | `leaks` | `PYTHONPATH` or user-site packages leaking into a venv |
-| 🔜 planned | `permissions` | No write access to site-packages |
-| 🔜 planned | `encoding` | Locale and encoding problems |
+| Check | What it catches |
+|---|---|
+| `python-version` | Python past (or close to) end of life, pre-release Pythons, Apple's built-in Command Line Tools Python |
+| `venv` | No venv active, an unused `.venv` in the folder, a *different* venv activated in your shell, a system Python that blocks pip (PEP 668) |
+| `pip-mismatch` | `pip` installs into a different Python than the one you run, pip missing, a broken `pip` command |
+| `path` | Typing `python` / `python3` runs a *different* Python, or the Windows Microsoft Store shortcut |
+| `leaks` | `PYTHONPATH` / `PYTHONHOME` set, venvs that can see system packages |
+| `shadowing` | Files like `random.py` or `requests.py` in your folder that hide real modules |
+| `ssl` | Certificate failures reaching PyPI (corporate proxies), certificate variables pointing at missing files, macOS certificates not installed, Python built without SSL |
+| `compiled` | Packages with compiled files built for a different Python version |
+| `broken-installs` | Packages installed twice, `~` leftovers from interrupted installs, corrupted metadata |
+| `dependencies` | Dependency conflicts (`pip check`), each with a suggested fix |
+| `permissions` | Virtual environments you can't install into (e.g. created with sudo) |
+| `encoding` | Default text encoding that is not UTF-8 |
+
+Run one or a few: `python -m pyfirstaid --only shadowing,path`. List them all: `python -m pyfirstaid --list`.
 
 ## How is this different?
 
@@ -151,7 +208,7 @@ Download `pyfirstaid.pyz` from the [latest release](https://github.com/sai-sakal
 
 ## Design principles
 
-- **Works when pip is broken.** It runs as a single file (`python pyfirstaid.pyz`). A PyPI release is coming.
+- **Works when pip is broken.** Install with `pip install pyfirstaid`, or run the single file `python pyfirstaid.pyz` without installing.
 - **Zero dependencies.** Standard library only, Python 3.9+.
 - **Every problem comes with a fix command,** not just a description.
 - **Conservative.** It's better to miss an edge case than to raise a false alarm.

pyfirstaid-0.2.0/README.md

@@ -0,0 +1,208 @@
+# pyfirstaid 🩹
+[![CI](https://github.com/sai-sakalam/pyfirstaid/actions/workflows/ci.yml/badge.svg)](https://github.com/sai-sakalam/pyfirstaid/actions/workflows/ci.yml)
+
+**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).
+> Feedback is very welcome in [Issues](https://github.com/sai-sakalam/pyfirstaid/issues). *Which problems do you hit most?*
+
+---
+
+## Why
+
+"It works on my machine" usually comes down to a broken environment: `pip` installing into a different Python than you run, SSL errors behind a corporate proxy, or a virtual environment that isn't active.
+
+The errors are cryptic, the fixes are scattered across Stack Overflow, and there's no single command that checks it all.
+
+This was discussed on the Python forum: [Standard Library Health Check Module](https://discuss.python.org/t/standard-library-health-check-module/105153). The advice there was to start it as a package on PyPI.
+
+## Example
+
+A run inside a project folder where the venv's Python is running, `pip` belongs to the
+system Python, and a file called `random.py` is hiding the real `random` module:
+
+```console
+$ python -m pyfirstaid --share
+
+pyfirstaid 0.2.0: checking your Python environment
+Python 3.13.1 (~/project/.venv/bin/python)
+
+✔ Python 3.13.1 (supported until October 2029)
+✔ Virtual environment active: ~/project/.venv
+✘ `pip` installs into a DIFFERENT Python
+    pip    -> /opt/homebrew/lib/python3.13/site-packages/pip (python 3.13)
+    python -> ~/project/.venv/bin/python (python 3.13)
+    fix: Use `python -m pip install <package>` instead of `pip install`. If a virtual environment should be active, activate it first.
+! Typing `python3` runs a DIFFERENT Python than this one
+    python3 -> /opt/homebrew
+    this Python -> ~/project/.venv
+    fix: Activate the virtual environment you want, or call Python by its full path. To change the default, put the right Python's folder first in PATH.
+✔ No PYTHONPATH / PYTHONHOME leaks
+! `random.py` in this folder hides the standard library module `random`
+    `import random` will load your file instead, which causes confusing errors like "module 'random' has no attribute ...".
+    fix: Rename it (e.g. my_random.py) and delete any __pycache__ folder next to it.
+✔ HTTPS to pypi.org works (OpenSSL 3.4.0 22 Oct 2024)
+✔ 12 compiled package(s) match this Python
+✔ No broken or duplicate installs (1 folder(s) scanned)
+✔ No dependency conflicts (pip check)
+✔ site-packages is writable
+✔ Default text encoding is UTF-8
+
+1 problem(s), 2 warning(s).
+```
+
+## Try it
+
+```bash
+pip install pyfirstaid          # or: pipx install pyfirstaid
+python -m pyfirstaid
+```
+
+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:
+
+```bash
+python pyfirstaid.pyz
+```
+
+### Options
+
+| Option | What it does |
+|---|---|
+| `--share` | Hides your username and home folder, so the report is safe to paste into a bug report |
+| `--json` | Machine-readable output for CI and scripts |
+| `--offline` | Skips checks that need the internet |
+| `--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 |
+
+Exit codes: `0` means no problems, `1` means problems were found, `2` means pyfirstaid itself failed.
+
+## Common situations
+
+**"I installed a package, but `import` says it doesn't exist."**
+
+    python -m pyfirstaid --only pip-mismatch,venv
+
+Usually `pip` installed into a different Python, or your virtual environment isn't active. pyfirstaid tells you which, and how to fix it.
+
+**"pip install fails with SSL: CERTIFICATE_VERIFY_FAILED at work."**
+
+    python -m pyfirstaid --only ssl
+
+This checks whether a company proxy is intercepting HTTPS and whether your certificate settings point at real files.
+
+**"`module 'random' has no attribute 'randint'`" (or the same with `json`, `requests`, ...)**
+
+    python -m pyfirstaid --only shadowing
+
+A file in your folder with the same name as a real module (`random.py`, `json.py`, `requests.py`) is being imported instead of the real one. pyfirstaid names the file to rename.
+
+**"I upgraded Python and now a package fails with `ImportError` / `undefined symbol` / `DLL load failed`."**
+
+    python -m pyfirstaid --only compiled,broken-installs
+
+Compiled packages built for your *old* Python version, or half-removed installs, are the usual cause. You get the exact reinstall command.
+
+**"`python3 --version` still shows the old version after I installed a new Python."**
+
+    python3 -m pyfirstaid --only path,python-version
+
+Shows which Python `python` / `python3` actually start, warns about Apple's built-in Python on macOS and the Microsoft Store shortcut on Windows, and flags Pythons past end of life.
+
+**"pip says ERROR: Could not install packages due to an OSError: Permission denied."**
+
+    python -m pyfirstaid --only permissions,venv
+
+Tells you whether you're installing into a read-only system Python (use a venv or pipx) or into a venv that was created with `sudo`.
+
+**"pip check shows conflicts and I don't know what to install."**
+
+    python -m pyfirstaid --only dependencies
+
+Each conflict comes with a ready-to-run `pip install` command.
+
+**"`UnicodeDecodeError` when reading a file, but it works on my colleague's machine."**
+
+    python -m pyfirstaid --only encoding
+
+Your default text encoding is not UTF-8 (common on Windows and minimal Linux/Docker images). pyfirstaid shows the one-line fix.
+
+**"My venv picks up packages I never installed in it."**
+
+    python -m pyfirstaid --only leaks
+
+`PYTHONPATH` or `PYTHONHOME` set in your shell profile is the usual reason.
+
+**"I'm reporting a bug and the maintainer asked for my environment details."**
+
+    python -m pyfirstaid --share
+
+Paste the output into the issue. Your username and home folder are hidden.
+
+**"I want CI to fail if the environment is broken."**
+
+    python -m pyfirstaid --offline --strict --json > env-report.json
+
+The exit code is `1` if there are problems, and the JSON report can be saved as a build artifact.
+
+**"pip itself is broken, so I can't install anything."**
+
+Download `pyfirstaid.pyz` from the [latest release](https://github.com/sai-sakalam/pyfirstaid/releases) and run:
+
+    python pyfirstaid.pyz
+
+## Checks
+
+| Check | What it catches |
+|---|---|
+| `python-version` | Python past (or close to) end of life, pre-release Pythons, Apple's built-in Command Line Tools Python |
+| `venv` | No venv active, an unused `.venv` in the folder, a *different* venv activated in your shell, a system Python that blocks pip (PEP 668) |
+| `pip-mismatch` | `pip` installs into a different Python than the one you run, pip missing, a broken `pip` command |
+| `path` | Typing `python` / `python3` runs a *different* Python, or the Windows Microsoft Store shortcut |
+| `leaks` | `PYTHONPATH` / `PYTHONHOME` set, venvs that can see system packages |
+| `shadowing` | Files like `random.py` or `requests.py` in your folder that hide real modules |
+| `ssl` | Certificate failures reaching PyPI (corporate proxies), certificate variables pointing at missing files, macOS certificates not installed, Python built without SSL |
+| `compiled` | Packages with compiled files built for a different Python version |
+| `broken-installs` | Packages installed twice, `~` leftovers from interrupted installs, corrupted metadata |
+| `dependencies` | Dependency conflicts (`pip check`), each with a suggested fix |
+| `permissions` | Virtual environments you can't install into (e.g. created with sudo) |
+| `encoding` | Default text encoding that is not UTF-8 |
+
+Run one or a few: `python -m pyfirstaid --only shadowing,path`. List them all: `python -m pyfirstaid --list`.
+
+## How is this different?
+
+| Tool | What it does | Gap pyfirstaid fills |
+|---|---|---|
+| `pip check` | Finds dependency conflicts | Only covers one kind of problem |
+| `conda doctor` | Health checks for conda environments | Doesn't cover pip, venv or uv |
+| pymedic | Lists environment info (versions, packages) | Reports, but doesn't diagnose or suggest fixes |
+| pyenv-doctor | Early-stage environment checks | Single release so far |
+| env-repair | Repairs conda and pip environments | Changes your environment; pyfirstaid only diagnoses, safely |
+
+**pyfirstaid's focus:** diagnose the problem, explain it in plain English, and give a copy-paste fix.
+
+## Design principles
+
+- **Works when pip is broken.** Install with `pip install pyfirstaid`, or run the single file `python pyfirstaid.pyz` without installing.
+- **Zero dependencies.** Standard library only, Python 3.9+.
+- **Every problem comes with a fix command,** not just a description.
+- **Conservative.** It's better to miss an edge case than to raise a false alarm.
+- **Never crashes.** A check that fails internally is reported, and the rest still run.
+- **Diagnose only.** It never changes your environment.
+
+## Scope
+
+**In:** pip, venv and uv on Windows, macOS and Linux.
+**Out (for now):** conda (use `conda doctor`), Poetry and pyenv specifics, automatic repair.
+
+## Contributing
+
+- Hit an environment error? [Open an issue](https://github.com/sai-sakalam/pyfirstaid/issues) with the error message, the cause and the fix. Real cases decide which checks come next.
+- Development: `python -m pip install -e ".[dev]"`, then `python -m pytest` and `ruff check src tests`.
+- A new check is one file in `src/pyfirstaid/checks/` that returns a list of `Finding`s, registered in `checks/__init__.py`.
+
+## License
+
+MIT

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

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

pyfirstaid-0.2.0/src/pyfirstaid/__main__.py

@@ -0,0 +1,13 @@
+import os
+import sys
+
+# `python -m pyfirstaid` puts the current folder first on sys.path, so a user's
+# random.py, json.py, ... would be imported instead of the real modules that
+# pyfirstaid needs. Drop it: pyfirstaid itself is already imported at this point.
+_cwd = os.path.normcase(os.path.abspath(os.getcwd()))
+sys.path[:] = [p for p in sys.path
+               if p and os.path.normcase(os.path.abspath(p)) != _cwd]
+
+from pyfirstaid.cli import main  # noqa: E402
+
+sys.exit(main())

pyfirstaid-0.2.0/src/pyfirstaid/checks/__init__.py

@@ -0,0 +1,36 @@
+"""Registry of all checks. Add new checks to ALL_CHECKS."""
+
+from __future__ import annotations
+
+from typing import List
+
+from pyfirstaid.checks import (
+    broken_installs,
+    compiled,
+    dependencies,
+    encoding,
+    leaks,
+    path_check,
+    permissions,
+    pip_mismatch,
+    python_version,
+    shadowing,
+    ssl_check,
+    venv,
+)
+from pyfirstaid.model import Check
+
+ALL_CHECKS: List[Check] = [
+    Check(python_version.CHECK_ID, "Python version", python_version.run_check),
+    Check(venv.CHECK_ID, "Virtual environment", venv.run_check),
+    Check(pip_mismatch.CHECK_ID, "pip / python match", pip_mismatch.run_check),
+    Check(path_check.CHECK_ID, "python on PATH", path_check.run_check),
+    Check(leaks.CHECK_ID, "PYTHONPATH / PYTHONHOME", leaks.run_check),
+    Check(shadowing.CHECK_ID, "Files hiding real modules", shadowing.run_check),
+    Check(ssl_check.CHECK_ID, "SSL / HTTPS to PyPI", ssl_check.run_check),
+    Check(compiled.CHECK_ID, "Compiled packages", compiled.run_check),
+    Check(broken_installs.CHECK_ID, "Broken installs", broken_installs.run_check),
+    Check(dependencies.CHECK_ID, "Dependency conflicts", dependencies.run_check),
+    Check(permissions.CHECK_ID, "Install permissions", permissions.run_check),
+    Check(encoding.CHECK_ID, "Text encoding", encoding.run_check),
+]

pyfirstaid-0.2.0/src/pyfirstaid/checks/broken_installs.py

@@ -0,0 +1,69 @@
+"""Check: duplicate, half-removed or corrupted package installs."""
+
+from __future__ import annotations
+
+import os
+import re
+from typing import Dict, List
+
+from pyfirstaid.model import Finding, Options, Status
+from pyfirstaid.util import site_package_dirs
+
+CHECK_ID = "broken-installs"
+
+_META_RE = re.compile(r"^(?P<name>.+?)-(?P<ver>[^-]+)\.(?:dist-info|egg-info)$")
+
+
+def normalize(name: str) -> str:
+    return re.sub(r"[-_.]+", "-", name).lower()
+
+
+def scan_dir(directory: str) -> List[Finding]:
+    findings: List[Finding] = []
+    try:
+        entries = os.listdir(directory)
+    except OSError:
+        return findings
+
+    versions: Dict[str, List[str]] = {}
+    for entry in entries:
+        path = os.path.join(directory, entry)
+        if entry.startswith("~"):
+            findings.append(Finding(
+                CHECK_ID, Status.WARN, "Leftover from an interrupted install: %s" % entry,
+                detail="pip renames packages to '~...' while removing them; this one was "
+                       "never cleaned up and can break imports.",
+                fix="Delete the folder: %s" % path,
+            ))
+            continue
+        m = _META_RE.match(entry)
+        if not m:
+            continue
+        versions.setdefault(normalize(m.group("name")), []).append(entry)
+        if entry.endswith(".dist-info") and not os.path.isfile(os.path.join(path, "METADATA")):
+            findings.append(Finding(
+                CHECK_ID, Status.ERROR, "Corrupted install: %s has no METADATA" % entry,
+                fix="python -m pip install --force-reinstall %s" % m.group("name"),
+            ))
+
+    for name, metas in sorted(versions.items()):
+        if len(metas) > 1:
+            findings.append(Finding(
+                CHECK_ID, Status.WARN, "%s is installed more than once" % name,
+                detail="in %s:\n%s" % (directory, "\n".join(sorted(metas))),
+                fix="python -m pip uninstall -y %s, repeat until it is gone, "
+                    "then python -m pip install %s" % (name, name),
+            ))
+    return findings
+
+
+def run_check(opts: Options) -> List[Finding]:
+    findings: List[Finding] = []
+    dirs = site_package_dirs()
+    for d in dirs:
+        findings.extend(scan_dir(d))
+    if not findings:
+        findings.append(Finding(
+            CHECK_ID, Status.OK,
+            "No broken or duplicate installs (%d folder(s) scanned)" % len(dirs)))
+    return findings

pyfirstaid-0.2.0/src/pyfirstaid/checks/compiled.py

@@ -0,0 +1,76 @@
+"""Check: compiled extension files built for a different Python version."""
+
+from __future__ import annotations
+
+import importlib.machinery
+import os
+import re
+from typing import Dict, List, Optional, Sequence, Set
+
+from pyfirstaid.model import Finding, Options, Status
+
+CHECK_ID = "compiled"
+
+# Matches version-tagged extension files, e.g. _core.cpython-312-x86_64-linux-gnu.so,
+# _core.cp312-win_amd64.pyd, _core.abi3.so. Untagged "_core.so" is always accepted.
+_TAG_RE = re.compile(r"\.((?:cpython-|cp|pypy|graalpy)[0-9][^.]*|abi3)\.(so|pyd)$")
+
+
+def mismatched_tag(filename: str, valid_suffixes: Sequence[str]) -> Optional[str]:
+    """Return the ABI tag if `filename` is tagged for a different interpreter, else None."""
+    base = os.path.basename(filename.replace("\\", "/"))
+    m = _TAG_RE.search(base)
+    if not m:
+        return None
+    suffix = ".%s.%s" % (m.group(1), m.group(2))
+    return None if suffix in valid_suffixes else m.group(1)
+
+
+def running_tag() -> str:
+    for s in importlib.machinery.EXTENSION_SUFFIXES:
+        m = _TAG_RE.search("x" + s)
+        if m and m.group(1) != "abi3":
+            return m.group(1)
+    return "this Python"
+
+
+def run_check(opts: Options) -> List[Finding]:
+    import importlib.metadata as md
+
+    valid = importlib.machinery.EXTENSION_SUFFIXES
+    bad: Dict[str, Set[str]] = {}
+    compiled_count = 0
+    seen: Set[str] = set()
+
+    for dist in md.distributions():
+        name = (dist.metadata["Name"] or "").strip()
+        if not name or name.lower() in seen:
+            continue
+        seen.add(name.lower())
+        has_ext = False
+        for f in dist.files or []:
+            s = str(f)
+            if not s.endswith((".so", ".pyd")) or ".libs/" in s.replace("\\", "/"):
+                continue
+            has_ext = True
+            tag = mismatched_tag(s, valid)
+            if tag:
+                bad.setdefault(name, set()).add(tag)
+        compiled_count += has_ext
+
+    if not bad:
+        return [Finding(CHECK_ID, Status.OK,
+                        "%d compiled package(s) match this Python" % compiled_count)]
+
+    findings = []
+    for name, tags in sorted(bad.items())[:10]:
+        findings.append(Finding(
+            CHECK_ID, Status.ERROR,
+            "%s was built for a different Python" % name,
+            detail="files are tagged %s, but this is %s" % (", ".join(sorted(tags)), running_tag()),
+            fix="python -m pip install --force-reinstall --no-cache-dir %s" % name,
+        ))
+    if len(bad) > 10:
+        findings.append(Finding(CHECK_ID, Status.INFO,
+                                "...and %d more packages with the same problem" % (len(bad) - 10)))
+    return findings