pyfirstaid 0.3.0__tar.gz → 0.4.0__tar.gz

{pyfirstaid-0.3.0 → pyfirstaid-0.4.0}/.github/workflows/ci.yml

@@ -13,6 +13,14 @@ jobs:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
         python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
+        # Python 3.9 is end-of-life and not built for ubuntu-latest (26.04),
+        # so test it on Ubuntu 24.04 instead.
+        exclude:
+          - os: ubuntu-latest
+            python-version: "3.9"
+        include:
+          - os: ubuntu-24.04
+            python-version: "3.9"
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5

{pyfirstaid-0.3.0 → pyfirstaid-0.4.0}/.github/workflows/publish.yml

@@ -8,7 +8,7 @@ on:
       tag:
         description: "Release tag to attach pyfirstaid.pyz to"
         required: true
-        default: "v0.1.0"
+        default: "v0.4.0"
 
 jobs:
   publish:

{pyfirstaid-0.3.0 → pyfirstaid-0.4.0}/CHANGELOG.md

@@ -1,6 +1,26 @@
 # Changelog
 
-## Unreleased
+## 0.4.0
+
+Four new checks for the tools people use to manage Pythons and projects. Like the conda
+check, they only read files on disk and run no uv, Poetry, pyenv or Jupyter commands.
+
+- **New `jupyter` check**: Jupyter kernels whose Python no longer exists (deleted venv,
+  upgraded Python), an environment that has ipykernel but is not registered as a kernel,
+  and several kernels with the same name in the kernel picker.
+- **New `uv` check**: a uv project whose `.venv` was never created, is broken (its base
+  Python is gone), or is not the Python running. Also respects `UV_PROJECT_ENVIRONMENT`.
+- **New `poetry` check**: finds the project's Poetry environment (in-project `.venv` or
+  Poetry's cache folder), and warns when it is broken or not the Python running.
+- **New `pyenv` check**: a `.python-version` file (or `PYENV_VERSION`) asking for a different
+  Python than the one running, a pinned version pyenv hasn't installed, and pyenv not set
+  up in the shell. uv reads `.python-version` too, so this also helps uv users.
+- `pip-mismatch`: in an environment made by uv (which has no pip by design), it now
+  suggests `uv pip install` instead of reporting pip as missing.
+- Report: checks for tools you don't use are shown on one line ("Not used here: ...").
+  Multi-line fixes are indented properly.
+
+## 0.3.0
 
 - **New `conda` check** for problems from mixing conda and pip (something `conda doctor`
   doesn't look at):
@@ -8,7 +28,7 @@
   - pip packages installed into the conda *base* environment,
   - a conda environment that is activated, but isn't the Python actually running.
   It only reads files on disk, runs no conda or pip commands, and stays quiet when unsure.
-- README: up-to-date example output and downloads badge; author link on PyPI.
+- README: up-to-date example output; author link on PyPI.
 
 ## 0.2.3
 

{pyfirstaid-0.3.0 → pyfirstaid-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyfirstaid
-Version: 0.3.0
+Version: 0.4.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: Source, https://github.com/sai-sakalam/pyfirstaid
@@ -10,7 +10,7 @@ Project-URL: Author, https://sai-sakalam.github.io/
 Author: Sai Gavaskar Sakalam
 License-Expression: MIT
 License-File: LICENSE
-Keywords: diagnostics,environment,pip,ssl,troubleshooting,venv,virtualenv
+Keywords: conda,diagnostics,environment,jupyter,pip,poetry,pyenv,ssl,troubleshooting,uv,venv,virtualenv
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -33,14 +33,14 @@ 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://img.shields.io/pypi/dm/pyfirstaid)](https://pypistats.org/packages/pyfirstaid)
+[![Python versions](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](https://pypi.org/project/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)
+[![XERJ Corpus Hub contributor](https://hub.xerj.org/contributors/sai-sakalam/badge.svg)](https://hub.xerj.org/contributors/sai-sakalam)
 
 **First aid for broken Python environments.** One command tells you *what's broken* and *exactly how to fix it*.
 
-> **Status: early, actively developed.** 13 checks, tested on Windows, macOS and Linux (Python 3.9–3.14).
+> **Status: early, actively developed.** 17 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?*
 
 ---
@@ -61,7 +61,7 @@ system Python, and a file called `random.py` is hiding the real `random` module:
 ```console
 $ python -m pyfirstaid --share
 
-pyfirstaid 0.2.3: checking your Python environment
+pyfirstaid 0.4.0: checking your Python environment
 Python 3.13.1 (~/project/.venv/bin/python)
 
 ✔ Python 3.13.1 (supported until October 2029)
@@ -84,6 +84,7 @@ Python 3.13.1 (~/project/.venv/bin/python)
 ✔ No dependency conflicts (pip check)
 ✔ site-packages is writable
 ✔ Default text encoding is UTF-8
+- Not used here: conda, uv, poetry, pyenv, jupyter
 
 1 problem(s), 2 warning(s).
 ```
@@ -163,6 +164,24 @@ Shows which Python `python` / `python3` actually start, warns about Apple's buil
 
 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`.
 
+**"I installed a package, but my Jupyter notebook still says `ModuleNotFoundError`."**
+
+    python -m pyfirstaid --only jupyter,pip-mismatch
+
+The notebook runs a *kernel*, and the kernel may use a different Python than your terminal. pyfirstaid finds kernels that point at a deleted or moved Python, and tells you when your environment isn't registered as a kernel at all. Tip: inside a notebook, use `%pip install <package>` (not `!pip install`), so it installs into the kernel's Python.
+
+**"It works with `uv run` / `poetry run`, but not when I run `python` myself."**
+
+    python -m pyfirstaid --only uv,poetry,venv
+
+The project's packages live in its own environment. pyfirstaid tells you whether the Python running is that environment, whether it exists yet (`uv sync` / `poetry install`), or whether it broke after a Python upgrade.
+
+**"pyenv says one version, but `python --version` shows another."**
+
+    python -m pyfirstaid --only pyenv,path
+
+Compares the Python running with your `.python-version` file (or `PYENV_VERSION`), and tells you if the version isn't installed in pyenv or pyenv isn't set up in your shell.
+
 **"pip check shows conflicts and I don't know what to install."**
 
     python -m pyfirstaid --only dependencies
@@ -206,7 +225,11 @@ Download `pyfirstaid.pyz` from the [latest release](https://github.com/sai-sakal
 | `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) |
 | `conda` | A package conda installed that pip later replaced, pip packages in the conda *base* environment, a conda environment that is activated but isn't the Python running |
-| `pip-mismatch` | `pip` installs into a different Python than the one you run, pip missing, a broken `pip` command |
+| `uv` | A uv project whose environment isn't created yet, is broken (its base Python is gone), or isn't the Python running |
+| `poetry` | A Poetry project whose environment is missing, broken, or isn't the Python running |
+| `pyenv` | `.python-version` / `PYENV_VERSION` asking for a different Python than the one running, a version pyenv hasn't installed, pyenv not set up in your shell |
+| `jupyter` | Kernels pointing to a Python that no longer exists, an environment with ipykernel that isn't registered as a kernel, kernels with the same name |
+| `pip-mismatch` | `pip` installs into a different Python than the one you run, pip missing (with the `uv pip` fix in uv environments), 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 |

{pyfirstaid-0.3.0 → pyfirstaid-0.4.0}/README.md

@@ -1,13 +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://img.shields.io/pypi/dm/pyfirstaid)](https://pypistats.org/packages/pyfirstaid)
+[![Python versions](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](https://pypi.org/project/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)
+[![XERJ Corpus Hub contributor](https://hub.xerj.org/contributors/sai-sakalam/badge.svg)](https://hub.xerj.org/contributors/sai-sakalam)
 
 **First aid for broken Python environments.** One command tells you *what's broken* and *exactly how to fix it*.
 
-> **Status: early, actively developed.** 13 checks, tested on Windows, macOS and Linux (Python 3.9–3.14).
+> **Status: early, actively developed.** 17 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?*
 
 ---
@@ -28,7 +28,7 @@ system Python, and a file called `random.py` is hiding the real `random` module:
 ```console
 $ python -m pyfirstaid --share
 
-pyfirstaid 0.2.3: checking your Python environment
+pyfirstaid 0.4.0: checking your Python environment
 Python 3.13.1 (~/project/.venv/bin/python)
 
 ✔ Python 3.13.1 (supported until October 2029)
@@ -51,6 +51,7 @@ Python 3.13.1 (~/project/.venv/bin/python)
 ✔ No dependency conflicts (pip check)
 ✔ site-packages is writable
 ✔ Default text encoding is UTF-8
+- Not used here: conda, uv, poetry, pyenv, jupyter
 
 1 problem(s), 2 warning(s).
 ```
@@ -130,6 +131,24 @@ Shows which Python `python` / `python3` actually start, warns about Apple's buil
 
 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`.
 
+**"I installed a package, but my Jupyter notebook still says `ModuleNotFoundError`."**
+
+    python -m pyfirstaid --only jupyter,pip-mismatch
+
+The notebook runs a *kernel*, and the kernel may use a different Python than your terminal. pyfirstaid finds kernels that point at a deleted or moved Python, and tells you when your environment isn't registered as a kernel at all. Tip: inside a notebook, use `%pip install <package>` (not `!pip install`), so it installs into the kernel's Python.
+
+**"It works with `uv run` / `poetry run`, but not when I run `python` myself."**
+
+    python -m pyfirstaid --only uv,poetry,venv
+
+The project's packages live in its own environment. pyfirstaid tells you whether the Python running is that environment, whether it exists yet (`uv sync` / `poetry install`), or whether it broke after a Python upgrade.
+
+**"pyenv says one version, but `python --version` shows another."**
+
+    python -m pyfirstaid --only pyenv,path
+
+Compares the Python running with your `.python-version` file (or `PYENV_VERSION`), and tells you if the version isn't installed in pyenv or pyenv isn't set up in your shell.
+
 **"pip check shows conflicts and I don't know what to install."**
 
     python -m pyfirstaid --only dependencies
@@ -173,7 +192,11 @@ Download `pyfirstaid.pyz` from the [latest release](https://github.com/sai-sakal
 | `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) |
 | `conda` | A package conda installed that pip later replaced, pip packages in the conda *base* environment, a conda environment that is activated but isn't the Python running |
-| `pip-mismatch` | `pip` installs into a different Python than the one you run, pip missing, a broken `pip` command |
+| `uv` | A uv project whose environment isn't created yet, is broken (its base Python is gone), or isn't the Python running |
+| `poetry` | A Poetry project whose environment is missing, broken, or isn't the Python running |
+| `pyenv` | `.python-version` / `PYENV_VERSION` asking for a different Python than the one running, a version pyenv hasn't installed, pyenv not set up in your shell |
+| `jupyter` | Kernels pointing to a Python that no longer exists, an environment with ipykernel that isn't registered as a kernel, kernels with the same name |
+| `pip-mismatch` | `pip` installs into a different Python than the one you run, pip missing (with the `uv pip` fix in uv environments), 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 |

{pyfirstaid-0.3.0 → pyfirstaid-0.4.0}/pyproject.toml

@@ -11,7 +11,8 @@ license = "MIT"
 license-files = ["LICENSE"]
 requires-python = ">=3.9"
 authors = [{ name = "Sai Gavaskar Sakalam" }]
-keywords = ["pip", "virtualenv", "venv", "diagnostics", "troubleshooting", "ssl", "environment"]
+keywords = ["pip", "virtualenv", "venv", "diagnostics", "troubleshooting", "ssl", "environment",
+            "conda", "uv", "poetry", "pyenv", "jupyter"]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Environment :: Console",

{pyfirstaid-0.3.0 → pyfirstaid-0.4.0}/src/pyfirstaid/__init__.py

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

{pyfirstaid-0.3.0 → pyfirstaid-0.4.0}/src/pyfirstaid/checks/__init__.py

@@ -10,13 +10,17 @@ from pyfirstaid.checks import (
     conda,
     dependencies,
     encoding,
+    jupyter,
     leaks,
     path_check,
     permissions,
     pip_mismatch,
+    poetry,
+    pyenv,
     python_version,
     shadowing,
     ssl_check,
+    uv,
     venv,
 )
 from pyfirstaid.model import Check
@@ -25,6 +29,10 @@ 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(conda.CHECK_ID, "conda / pip mixing", conda.run_check),
+    Check(uv.CHECK_ID, "uv project environment", uv.run_check),
+    Check(poetry.CHECK_ID, "Poetry project environment", poetry.run_check),
+    Check(pyenv.CHECK_ID, "pyenv / .python-version", pyenv.run_check),
+    Check(jupyter.CHECK_ID, "Jupyter kernels", jupyter.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),

pyfirstaid-0.4.0/src/pyfirstaid/checks/jupyter.py

@@ -0,0 +1,183 @@
+"""Check: Jupyter kernels that point at the wrong (or a missing) Python.
+
+The classic notebook problem is "I installed the package, but the notebook can't import
+it": the notebook runs a *kernel*, and each kernel is tied to one Python. This check
+reads the kernel files (kernel.json) on disk. It runs no Jupyter commands.
+
+- kernels whose Python no longer exists (deleted or moved venv, upgraded Python),
+- this environment has ipykernel but is not registered as a kernel,
+- several kernels with the same name in the kernel picker.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import os
+import sys
+from typing import Dict, List, Optional, Tuple
+
+from pyfirstaid.model import Finding, Options, Status
+from pyfirstaid.util import in_virtualenv, is_within, norm
+
+CHECK_ID = "jupyter"
+
+Kernel = Tuple[str, str, List[str], str]  # (name, folder, argv, display name)
+
+
+def jupyter_dirs(prefix: Optional[str] = None) -> List[str]:
+    """Folders Jupyter searches for kernels, in Jupyter's own order (user, env, system)."""
+    prefix = prefix or sys.prefix
+    home = os.path.expanduser("~")
+    dirs: List[str] = []
+
+    data_dir = os.environ.get("JUPYTER_DATA_DIR")
+    if data_dir:
+        dirs.append(data_dir)
+    elif sys.platform == "darwin":
+        dirs.append(os.path.join(home, "Library", "Jupyter"))
+    elif os.name == "nt":
+        appdata = os.environ.get("APPDATA")
+        if appdata:
+            dirs.append(os.path.join(appdata, "jupyter"))
+    else:
+        xdg = os.environ.get("XDG_DATA_HOME") or os.path.join(home, ".local", "share")
+        dirs.append(os.path.join(xdg, "jupyter"))
+
+    for extra in (os.environ.get("JUPYTER_PATH") or "").split(os.pathsep):
+        if extra:
+            dirs.append(extra)
+
+    dirs.append(os.path.join(prefix, "share", "jupyter"))
+    if os.name == "nt":
+        programdata = os.environ.get("PROGRAMDATA")
+        if programdata:
+            dirs.append(os.path.join(programdata, "jupyter"))
+    else:
+        dirs.extend(["/usr/local/share/jupyter", "/usr/share/jupyter"])
+    return [os.path.join(d, "kernels") for d in dirs]
+
+
+def find_kernels(kernel_dirs: List[str]) -> List[Kernel]:
+    """All kernels, first one wins when the same name is in several folders (like Jupyter)."""
+    seen: Dict[str, Kernel] = {}
+    for base in kernel_dirs:
+        try:
+            names = sorted(os.listdir(base))
+        except OSError:
+            continue
+        for name in names:
+            folder = os.path.join(base, name)
+            spec_file = os.path.join(folder, "kernel.json")
+            if name.lower() in seen or not os.path.isfile(spec_file):
+                continue
+            try:
+                with open(spec_file, encoding="utf-8") as fh:
+                    spec = json.load(fh)
+            except (OSError, ValueError):
+                continue
+            argv = spec.get("argv") if isinstance(spec, dict) else None
+            if not isinstance(argv, list) or not argv or not all(isinstance(a, str) for a in argv):
+                continue
+            display = spec.get("display_name")
+            if not isinstance(display, str):
+                display = name
+            seen[name.lower()] = (name, folder, argv, display)
+    return list(seen.values())
+
+
+def missing_python(kernel: Kernel) -> bool:
+    """True when the kernel starts a Python by full path and that file is gone.
+
+    Kernels that use a bare `python` are fine: Jupyter runs them with its own Python.
+    """
+    exe = kernel[2][0]
+    return os.path.isabs(exe) and not os.path.exists(exe)
+
+
+def env_name(prefix: str) -> str:
+    """A readable kernel name for an environment: `.venv` folders are named after the project."""
+    base = os.path.basename(os.path.normpath(prefix))
+    if base.lower() in (".venv", "venv", "env", ".env"):
+        base = os.path.basename(os.path.dirname(os.path.normpath(prefix))) or base
+    return "".join(c if c.isalnum() or c in "-_." else "-" for c in base).strip("-") or "myenv"
+
+
+def is_registered(kernels: List[Kernel], prefix: str, executable: str) -> bool:
+    for _, _, argv, _ in kernels:
+        exe = argv[0]
+        if os.path.isabs(exe) and (norm(exe) == norm(executable) or is_within(exe, prefix)):
+            return True
+    return False
+
+
+def run_check(opts: Options, kernel_dirs: Optional[List[str]] = None,
+              prefix: Optional[str] = None, executable: Optional[str] = None,
+              has_ipykernel: Optional[bool] = None, is_env: Optional[bool] = None,
+              has_jupyter: Optional[bool] = None) -> List[Finding]:
+    prefix = prefix or sys.prefix
+    executable = executable or sys.executable
+    if has_ipykernel is None:
+        has_ipykernel = importlib.util.find_spec("ipykernel") is not None
+    if has_jupyter is None:
+        has_jupyter = any(importlib.util.find_spec(m) is not None
+                          for m in ("jupyter_server", "notebook", "jupyterlab"))
+    if is_env is None:
+        is_env = in_virtualenv() or os.path.isdir(os.path.join(prefix, "conda-meta"))
+    kernels = find_kernels(kernel_dirs if kernel_dirs is not None else jupyter_dirs(prefix))
+
+    if not kernels and not has_ipykernel:
+        return [Finding(CHECK_ID, Status.SKIP, "Jupyter not found")]
+
+    findings: List[Finding] = []
+
+    broken = [k for k in kernels if missing_python(k)]
+    if broken:
+        findings.append(Finding(
+            CHECK_ID, Status.WARN,
+            "%d Jupyter kernel(s) point to a Python that no longer exists" % len(broken),
+            detail="These kernels fail to start (often after deleting a venv or upgrading "
+                   "Python):\n" + "\n".join(
+                       "%s -> %s" % (k[0], k[2][0]) for k in broken[:8]),
+            fix="Remove each one: jupyter kernelspec remove %s\n"
+                "Then register the environment again from inside it: "
+                "python -m ipykernel install --user --name <name>" % broken[0][0],
+        ))
+
+    # Jupyter installed in this same environment already uses this Python.
+    if has_ipykernel and is_env and not has_jupyter and not is_registered(
+            kernels, prefix, executable):
+        name = env_name(prefix)
+        findings.append(Finding(
+            CHECK_ID, Status.INFO,
+            "This environment has ipykernel, but no Jupyter kernel uses it",
+            detail="Notebooks can only use this Python (and its packages) through a kernel. "
+                   "Otherwise `import` in a notebook won't see what you installed here.",
+            fix='python -m ipykernel install --user --name %s --display-name "Python (%s)"'
+                % (name, name),
+        ))
+
+    by_display: Dict[str, List[str]] = {}
+    shown: Dict[str, str] = {}
+    for name, _, _, display in kernels:
+        key = display.strip().lower()
+        by_display.setdefault(key, []).append(name)
+        shown.setdefault(key, display.strip())
+    dupes = {shown[d]: n for d, n in by_display.items() if len(n) > 1}
+    if dupes:
+        findings.append(Finding(
+            CHECK_ID, Status.INFO,
+            "Several Jupyter kernels have the same name in the kernel picker",
+            detail="\n".join("%s: %s" % (d, ", ".join(n)) for d, n in sorted(dupes.items())),
+            fix="List them with `jupyter kernelspec list`, then remove old ones "
+                "(`jupyter kernelspec remove <name>`) or re-install with a clear "
+                '--display-name "Python (project)".',
+        ))
+
+    if not findings:
+        findings.append(Finding(
+            CHECK_ID, Status.OK,
+            "%d Jupyter kernel(s) found, all point to a working Python" % len(kernels)
+            if kernels else "ipykernel installed, no kernel problems",
+        ))
+    return findings

{pyfirstaid-0.3.0 → pyfirstaid-0.4.0}/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, site_package_dirs
+from pyfirstaid.util import is_within, read_pyvenv_cfg, run, site_package_dirs
 
 CHECK_ID = "pip-mismatch"
 
@@ -50,6 +50,13 @@ def run_check(opts: Options) -> List[Finding]:
 
     code, out, err = run([sys.executable, "-m", "pip", "--version"], opts.timeout)
     if code != 0:
+        if "uv" in read_pyvenv_cfg(sys.prefix):
+            return [Finding(
+                CHECK_ID, Status.INFO,
+                "No pip in this environment (normal: it was made by uv)",
+                detail="A plain `pip install` would use some other Python's pip.",
+                fix="uv pip install <package>   (in a uv project: uv add <package>)",
+            )]
         return [Finding(
             CHECK_ID, Status.ERROR,
             "pip is not installed for this Python",

pyfirstaid-0.4.0/src/pyfirstaid/checks/poetry.py

@@ -0,0 +1,153 @@
+"""Check: Poetry projects that run the wrong environment (or a broken one).
+
+Poetry keeps each project's environment either in the project (`.venv`) or in its own
+cache folder, named `<project>-<hash>-py3.X`. This check finds those folders on disk and
+compares them with the Python that is running. It runs no Poetry commands.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import os
+import re
+import sys
+from typing import List, Optional
+
+from pyfirstaid.checks.uv import display_path
+from pyfirstaid.model import Finding, Options, Status
+from pyfirstaid.util import (
+    broken_venv_base,
+    find_upwards,
+    in_virtualenv,
+    is_within,
+    norm,
+    read_pyproject,
+)
+
+CHECK_ID = "poetry"
+
+
+def poetry_project(cwd: str) -> Optional[str]:
+    """The Poetry project folder for `cwd` (has poetry.lock or [tool.poetry]), if any."""
+    lock = find_upwards(cwd, "poetry.lock")
+    if lock:
+        return os.path.dirname(lock)
+    if "poetry" in (read_pyproject(cwd).get("tool") or {}):
+        return cwd
+    return None
+
+
+def project_name(root: str) -> Optional[str]:
+    data = read_pyproject(root)
+    for table in ((data.get("tool") or {}).get("poetry") or {}, data.get("project") or {}):
+        name = table.get("name") if isinstance(table, dict) else None
+        if isinstance(name, str) and name:
+            return name
+    return None
+
+
+def venvs_dir() -> str:
+    """Where Poetry keeps environments that are not inside the project."""
+    custom = os.environ.get("POETRY_VIRTUALENVS_PATH")
+    if custom:
+        return custom
+    cache = os.environ.get("POETRY_CACHE_DIR")
+    if not cache:
+        home = os.path.expanduser("~")
+        if sys.platform == "darwin":
+            cache = os.path.join(home, "Library", "Caches", "pypoetry")
+        elif os.name == "nt":
+            local = os.environ.get("LOCALAPPDATA") or os.path.join(home, "AppData", "Local")
+            cache = os.path.join(local, "pypoetry", "Cache")
+        else:
+            xdg = os.environ.get("XDG_CACHE_HOME") or os.path.join(home, ".cache")
+            cache = os.path.join(xdg, "pypoetry")
+    return os.path.join(cache, "virtualenvs")
+
+
+def sanitized(name: str) -> str:
+    return re.sub(r'[ $`!*@"\\\r\n\t]', "_", name.lower())[:42]
+
+
+def env_name(name: str, root: str) -> str:
+    """Poetry's environment name: <name>-<first 8 chars of a hash of the project path>."""
+    digest = hashlib.sha256(os.path.normcase(os.path.realpath(root)).encode()).digest()
+    return "%s-%s" % (sanitized(name), base64.urlsafe_b64encode(digest).decode()[:8])
+
+
+def project_envs(root: str, name: Optional[str], cache_dir: str) -> List[str]:
+    """This project's environments: an in-project .venv, plus matching cache folders."""
+    envs: List[str] = []
+    local = os.path.join(root, ".venv")
+    if os.path.isfile(os.path.join(local, "pyvenv.cfg")):
+        envs.append(local)
+    if name:
+        start = env_name(name, root) + "-py"
+        try:
+            entries = sorted(os.listdir(cache_dir))
+        except OSError:
+            entries = []
+        envs.extend(os.path.join(cache_dir, e) for e in entries if e.startswith(start))
+    return envs
+
+
+def run_check(opts: Options, prefix: Optional[str] = None, in_venv: Optional[bool] = None,
+              cache_dir: Optional[str] = None) -> List[Finding]:
+    prefix = prefix or sys.prefix
+    in_venv = in_virtualenv() if in_venv is None else in_venv
+    cache_dir = cache_dir or venvs_dir()
+    cwd = opts.cwd or os.getcwd()
+
+    root = poetry_project(cwd)
+    if not root:
+        return [Finding(CHECK_ID, Status.SKIP, "Not a Poetry project")]
+
+    name = project_name(root)
+    envs = project_envs(root, name, cache_dir)
+    findings: List[Finding] = []
+
+    working = []
+    for env in envs:
+        gone = broken_venv_base(env)
+        if not gone:
+            working.append(env)
+            continue
+        if norm(os.path.dirname(env)) == norm(root):
+            fix = "Delete the .venv folder, then run `poetry install`."
+        else:
+            version = env.rsplit("-py", 1)[-1]
+            fix = "poetry env remove python%s   then: poetry install" % version
+        findings.append(Finding(
+            CHECK_ID, Status.WARN,
+            "A Poetry environment for this project is broken: its base Python is gone",
+            detail="%s was built from %s, which no longer exists (often after upgrading "
+                   "Python)." % (display_path(env, cwd), gone),
+            fix=fix,
+        ))
+
+    # The running env counts as the project's even if the path hash changed (moved project).
+    running_is_project = any(norm(prefix) == norm(e) for e in working) or (
+        name is not None and is_within(prefix, cache_dir)
+        and os.path.basename(os.path.normpath(prefix)).startswith(sanitized(name) + "-"))
+
+    if running_is_project:
+        findings.append(Finding(CHECK_ID, Status.OK, "Running the Poetry project's environment"))
+    elif not envs:
+        findings.append(Finding(
+            CHECK_ID, Status.INFO,
+            "Poetry project, but no environment for it was found",
+            detail="project: %s" % root,
+            fix="poetry install",
+        ))
+    elif working:
+        findings.append(Finding(
+            CHECK_ID, Status.WARN if in_venv else Status.INFO,
+            "This is a Poetry project, but a DIFFERENT environment is running" if in_venv
+            else "This is a Poetry project, but its environment is not the Python running",
+            detail="project env: %s\nrunning:     %s" % (working[0], prefix),
+            fix="Run commands through Poetry: `poetry run python ...`, "
+                "or run `poetry env activate` and then the command it prints. "
+                "To check it: poetry run python -m pyfirstaid",
+        ))
+    return findings