pyfirstaid 0.1.0__tar.gz

pyfirstaid-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check src tests scripts
+      - name: Test
+        run: python -m pytest -q
+      - name: Run pyfirstaid on the CI machine (report only)
+        shell: bash
+        run: python -m pyfirstaid || true
+
+  pyz:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build single-file pyfirstaid.pyz
+        run: python scripts/build_pyz.py
+      - name: Smoke test
+        run: python dist/pyfirstaid.pyz --offline || true
+      - uses: actions/upload-artifact@v4
+        with:
+          name: pyfirstaid.pyz
+          path: dist/pyfirstaid.pyz

pyfirstaid-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,45 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Release tag to attach pyfirstaid.pyz to"
+        required: true
+        default: "v0.1.0"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build package (wheel + sdist)
+        run: |
+          python -m pip install build
+          python -m build
+
+      - name: Build single-file pyfirstaid.pyz (kept OUT of dist/)
+        run: |
+          python scripts/build_pyz.py
+          mkdir -p pyz-out
+          mv dist/pyfirstaid.pyz pyz-out/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+
+      - name: Attach pyfirstaid.pyz to the GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release upload "${{ github.event.release.tag_name || inputs.tag }}" pyz-out/pyfirstaid.pyz --clobber

pyfirstaid-0.1.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0
+
+First version, 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`.
+Single-file build: `python scripts/build_pyz.py` creates `dist/pyfirstaid.pyz`.

pyfirstaid-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sai Gavaskar Sakalam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyfirstaid-0.1.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.5
+Name: pyfirstaid
+Version: 0.1.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
+Author: Sai Gavaskar Sakalam
+License-Expression: MIT
+License-File: LICENSE
+Keywords: diagnostics,environment,pip,ssl,troubleshooting,venv,virtualenv
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: System :: Installation/Setup
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 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.1, early.** 3 checks work today, and more are on the roadmap.
+> 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 real run: the virtual environment's Python is running, but the `pip` command on PATH belongs to the system Python:
+
+```console
+$ python -m pyfirstaid
+
+pyfirstaid 0.1.0: checking your Python environment
+Python 3.13.1 (~/project/.venv/bin/python)
+
+✔ Virtual environment active: ~/project/.venv
+✘ `pip` installs into a DIFFERENT Python
+    pip    -> /usr/lib/python3/dist-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).
+```
+
+## 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 .
+python -m pyfirstaid
+```
+
+Or build the **single file**, which needs no install and works even when pip is broken:
+
+```bash
+python scripts/build_pyz.py
+python dist/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.
+
+**"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
+
+| 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 |
+
+## 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.** It runs as a single file (`python pyfirstaid.pyz`). A PyPI release is coming.
+- **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/README.md

@@ -0,0 +1,151 @@
+# 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.1, early.** 3 checks work today, and more are on the roadmap.
+> 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 real run: the virtual environment's Python is running, but the `pip` command on PATH belongs to the system Python:
+
+```console
+$ python -m pyfirstaid
+
+pyfirstaid 0.1.0: checking your Python environment
+Python 3.13.1 (~/project/.venv/bin/python)
+
+✔ Virtual environment active: ~/project/.venv
+✘ `pip` installs into a DIFFERENT Python
+    pip    -> /usr/lib/python3/dist-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).
+```
+
+## 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 .
+python -m pyfirstaid
+```
+
+Or build the **single file**, which needs no install and works even when pip is broken:
+
+```bash
+python scripts/build_pyz.py
+python dist/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.
+
+**"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
+
+| 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 |
+
+## 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.** It runs as a single file (`python pyfirstaid.pyz`). A PyPI release is coming.
+- **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/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pyfirstaid"
+dynamic = ["version"]
+description = "First aid for broken Python environments: finds what's wrong and tells you how to fix it."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "Sai Gavaskar Sakalam" }]
+keywords = ["pip", "virtualenv", "venv", "diagnostics", "troubleshooting", "ssl", "environment"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Debuggers",
+    "Topic :: System :: Installation/Setup",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "ruff>=0.5"]
+
+[project.scripts]
+pyfirstaid = "pyfirstaid.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/sai-sakalam/pyfirstaid"
+Issues = "https://github.com/sai-sakalam/pyfirstaid/issues"
+
+[tool.hatch.version]
+path = "src/pyfirstaid/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pyfirstaid"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B"]

pyfirstaid-0.1.0/scripts/build_pyz.py

@@ -0,0 +1,28 @@
+"""Build dist/pyfirstaid.pyz: a single file that runs with `python pyfirstaid.pyz`.
+
+It needs no installation, so it works even when pip is broken.
+Usage: python scripts/build_pyz.py
+"""
+
+import shutil
+import tempfile
+import zipapp
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+
+
+def main() -> None:
+    dist = ROOT / "dist"
+    dist.mkdir(exist_ok=True)
+    target = dist / "pyfirstaid.pyz"
+    with tempfile.TemporaryDirectory() as tmp:
+        shutil.copytree(ROOT / "src" / "pyfirstaid", Path(tmp) / "pyfirstaid",
+                        ignore=shutil.ignore_patterns("__pycache__", "*.pyc"))
+        zipapp.create_archive(tmp, target, interpreter="/usr/bin/env python3",
+                              main="pyfirstaid.cli:_run")
+    print("built", target)
+
+
+if __name__ == "__main__":
+    main()

pyfirstaid-0.1.0/src/pyfirstaid/__init__.py

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

pyfirstaid-0.1.0/src/pyfirstaid/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from pyfirstaid.cli import main
+
+sys.exit(main())

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

@@ -0,0 +1,14 @@
+"""Registry of all checks. Add new checks to ALL_CHECKS."""
+
+from __future__ import annotations
+
+from typing import List
+
+from pyfirstaid.checks import pip_mismatch, ssl_check, venv
+from pyfirstaid.model import Check
+
+ALL_CHECKS: List[Check] = [
+    Check(venv.CHECK_ID, "Virtual environment", venv.run_check),
+    Check(pip_mismatch.CHECK_ID, "pip / python match", pip_mismatch.run_check),
+    Check(ssl_check.CHECK_ID, "SSL / HTTPS to PyPI", ssl_check.run_check),
+]

pyfirstaid-0.1.0/src/pyfirstaid/checks/pip_mismatch.py

@@ -0,0 +1,86 @@
+"""Check: does the `pip` command install into the Python you are running?"""
+
+from __future__ import annotations
+
+import re
+import shutil
+import site
+import sys
+from typing import List, Optional, Tuple
+
+from pyfirstaid.model import Finding, Options, Status
+from pyfirstaid.util import is_within, run
+
+CHECK_ID = "pip-mismatch"
+
+_PIP_RE = re.compile(r"^pip (?P<ver>\S+) from (?P<loc>.+?) \(python (?P<py>\d+\.\d+)\)\s*$")
+
+
+def parse_pip_version(output: str) -> Optional[Tuple[str, str, str]]:
+    """Parse `pip --version` output into (pip_version, location, python_version)."""
+    for line in output.splitlines():
+        m = _PIP_RE.match(line.strip())
+        if m:
+            return m.group("ver"), m.group("loc"), m.group("py")
+    return None
+
+
+def pip_belongs_here(location: str, pip_python: str, running_python: str,
+                     prefixes: List[str]) -> bool:
+    """True if a pip install at `location` serves the running interpreter."""
+    if pip_python != running_python:
+        return False
+    return any(is_within(location, p) for p in prefixes if p)
+
+
+def _allowed_prefixes() -> List[str]:
+    prefixes = [sys.prefix]
+    if site.ENABLE_USER_SITE:
+        user_site = site.getusersitepackages()
+        if isinstance(user_site, str):
+            prefixes.append(user_site)
+    return prefixes
+
+
+def run_check(opts: Options) -> List[Finding]:
+    running = "%d.%d" % sys.version_info[:2]
+
+    code, out, err = run([sys.executable, "-m", "pip", "--version"], opts.timeout)
+    if code != 0:
+        return [Finding(
+            CHECK_ID, Status.ERROR,
+            "pip is not installed for this Python",
+            detail=(err or out)[-300:],
+            fix="python -m ensurepip --upgrade",
+        )]
+
+    pip_cmd = shutil.which("pip") or shutil.which("pip3")
+    if not pip_cmd:
+        return [Finding(
+            CHECK_ID, Status.INFO,
+            "No `pip` command on PATH (python -m pip works)",
+            fix="Use `python -m pip install <package>`. It always targets the right Python.",
+        )]
+
+    code, out, err = run([pip_cmd, "--version"], opts.timeout)
+    parsed = parse_pip_version(out) if code == 0 else None
+    if not parsed:
+        return [Finding(
+            CHECK_ID, Status.WARN,
+            "The `pip` command on PATH is broken",
+            detail="%s\n%s" % (pip_cmd, (err or out)[-300:]),
+            fix="python -m pip install --force-reinstall pip",
+        )]
+
+    _, location, pip_python = parsed
+    if pip_belongs_here(location, pip_python, running, _allowed_prefixes()):
+        return [Finding(CHECK_ID, Status.OK, "`pip` installs into this Python")]
+
+    return [Finding(
+        CHECK_ID, Status.ERROR,
+        "`pip` installs into a DIFFERENT Python",
+        detail="pip    -> %s (python %s)\npython -> %s (python %s)" % (
+            location, pip_python, sys.executable, running),
+        fix="Use `python -m pip install <package>` instead of `pip install`. "
+            "If a virtual environment should be active, activate it first.",
+    )]

pyfirstaid-0.1.0/src/pyfirstaid/checks/ssl_check.py

@@ -0,0 +1,123 @@
+"""Check: can this Python make verified HTTPS connections to PyPI?"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import List
+
+from pyfirstaid.model import Finding, Options, Status
+
+CHECK_ID = "ssl"
+
+CERT_ENV_VARS = ("SSL_CERT_FILE", "SSL_CERT_DIR", "REQUESTS_CA_BUNDLE",
+                 "CURL_CA_BUNDLE", "PIP_CERT")
+PROXY_ENV_VARS = ("HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy")
+TEST_URL = "https://pypi.org/simple/pip/"
+
+CORPORATE_FIX = (
+    "If you are behind a company proxy or VPN, it is probably inspecting HTTPS traffic. "
+    "Ask IT for the company root certificate (.pem), then run: "
+    "python -m pip config set global.cert /path/to/company-ca.pem  "
+    "(also: set SSL_CERT_FILE=/path/to/company-ca.pem). "
+    "Upgrading pip can also help: python -m pip install --upgrade pip"
+)
+
+
+def bad_cert_env_vars(environ=os.environ) -> List[str]:
+    """Return env vars that point at certificate files/dirs that do not exist."""
+    return [name for name in CERT_ENV_VARS
+            if environ.get(name) and not os.path.exists(environ[name])]
+
+
+def classify_error(exc: BaseException) -> str:
+    """Map a connection exception to 'cert', 'ssl' or 'network'."""
+    import ssl
+
+    reason = getattr(exc, "reason", exc)
+    if (isinstance(reason, ssl.SSLCertVerificationError)
+            or "CERTIFICATE_VERIFY_FAILED" in str(reason)):
+        return "cert"
+    if isinstance(reason, ssl.SSLError):
+        return "ssl"
+    return "network"
+
+
+def run_check(opts: Options) -> List[Finding]:
+    try:
+        import ssl
+    except ImportError:
+        return [Finding(
+            CHECK_ID, Status.ERROR, "This Python was built WITHOUT SSL support",
+            detail="`import ssl` failed, so pip cannot download anything.",
+            fix="Reinstall Python from python.org or your package manager "
+                "(if you compiled it yourself, install the OpenSSL dev package first).",
+        )]
+
+    findings: List[Finding] = []
+    for name in bad_cert_env_vars():
+        findings.append(Finding(
+            CHECK_ID, Status.ERROR, "%s points to a file that does not exist" % name,
+            detail="%s=%s" % (name, os.environ[name]),
+            fix="Fix the path, or remove the variable (unset %s)." % name,
+        ))
+
+    paths = ssl.get_default_verify_paths()
+    no_ca = not ((paths.cafile and os.path.exists(paths.cafile))
+                 or (paths.capath and os.path.isdir(paths.capath) and os.listdir(paths.capath)))
+    if sys.platform == "darwin" and no_ca and not os.environ.get("SSL_CERT_FILE"):
+        findings.append(Finding(
+            CHECK_ID, Status.WARN, "No CA certificates configured for this macOS Python",
+            detail="python.org installers on macOS need a one-time certificate install.",
+            fix='Run: open "/Applications/Python %d.%d/Install Certificates.command"'
+                % sys.version_info[:2],
+        ))
+
+    if opts.offline:
+        findings.append(Finding(CHECK_ID, Status.SKIP,
+                                "Skipped connection test to pypi.org (--offline)"))
+        return findings
+
+    import urllib.error
+    import urllib.request
+
+    try:
+        req = urllib.request.Request(TEST_URL, method="HEAD",
+                                     headers={"User-Agent": "pyfirstaid"})
+        with urllib.request.urlopen(req, timeout=opts.timeout,
+                                    context=ssl.create_default_context()):
+            pass
+        findings.append(Finding(CHECK_ID, Status.OK,
+                                "HTTPS to pypi.org works (%s)" % ssl.OPENSSL_VERSION))
+    except urllib.error.HTTPError as exc:
+        # The TLS handshake and certificate check succeeded; the server (or a
+        # proxy) answered with an HTTP error code.
+        findings.append(Finding(
+            CHECK_ID, Status.INFO,
+            "SSL certificates OK, but pypi.org answered HTTP %s" % exc.code,
+            detail="A proxy or firewall may be blocking PyPI." if exc.code in (403, 407) else "",
+            fix="If pip installs fail, check your proxy settings or ask IT to allow pypi.org "
+                "and files.pythonhosted.org.",
+        ))
+    except Exception as exc:  # noqa: BLE001 - we classify every failure
+        kind = classify_error(exc)
+        if kind == "cert":
+            findings.append(Finding(
+                CHECK_ID, Status.ERROR, "SSL certificate verification FAILED for pypi.org",
+                detail=str(exc)[:300], fix=CORPORATE_FIX,
+            ))
+        elif kind == "ssl":
+            findings.append(Finding(
+                CHECK_ID, Status.ERROR, "SSL error connecting to pypi.org",
+                detail=str(exc)[:300], fix=CORPORATE_FIX,
+            ))
+        else:
+            proxies = [v for v in PROXY_ENV_VARS if os.environ.get(v)]
+            findings.append(Finding(
+                CHECK_ID, Status.WARN, "Could not reach pypi.org",
+                detail=str(exc)[:300] + (
+                    "\nProxy variables set: %s" % ", ".join(proxies) if proxies else ""),
+                fix="Check your internet connection, VPN or proxy settings. "
+                    "Use --offline to skip this test.",
+            ))
+    return findings

pyfirstaid-0.1.0/src/pyfirstaid/checks/venv.py

@@ -0,0 +1,82 @@
+"""Check: is a virtual environment active, and is it the right one?"""
+
+from __future__ import annotations
+
+import os
+import sys
+import sysconfig
+from typing import List, Optional
+
+from pyfirstaid.model import Finding, Options, Status
+from pyfirstaid.util import in_virtualenv, norm
+
+CHECK_ID = "venv"
+
+CANDIDATE_DIRS = (".venv", "venv", "env", ".env")
+
+
+def find_unused_venv(cwd: str) -> Optional[str]:
+    """Return the path of a virtual environment folder in `cwd`, if any."""
+    for name in CANDIDATE_DIRS:
+        path = os.path.join(cwd, name)
+        if os.path.isfile(os.path.join(path, "pyvenv.cfg")):
+            return path
+    return None
+
+
+def activate_command(venv_path: str) -> str:
+    if os.name == "nt":
+        return r"%s\Scripts\activate" % venv_path
+    return "source %s/bin/activate" % venv_path
+
+
+def is_externally_managed() -> bool:
+    stdlib = sysconfig.get_paths().get("stdlib", "")
+    return bool(stdlib) and os.path.isfile(os.path.join(stdlib, "EXTERNALLY-MANAGED"))
+
+
+def run_check(opts: Options) -> List[Finding]:
+    findings: List[Finding] = []
+    cwd = opts.cwd or os.getcwd()
+    activated = os.environ.get("VIRTUAL_ENV")
+    conda = os.environ.get("CONDA_PREFIX")
+
+    if in_virtualenv():
+        findings.append(Finding(CHECK_ID, Status.OK,
+                                "Virtual environment active: %s" % sys.prefix))
+    elif conda and norm(conda) == norm(sys.prefix):
+        findings.append(Finding(
+            CHECK_ID, Status.INFO, "Running in a conda environment: %s" % sys.prefix,
+            fix="For conda-specific checks, also run `conda doctor`.",
+        ))
+    else:
+        unused = find_unused_venv(cwd)
+        if unused:
+            findings.append(Finding(
+                CHECK_ID, Status.WARN,
+                "Found a virtual environment that is NOT being used",
+                detail="%s exists, but this Python is %s" % (unused, sys.executable),
+                fix=activate_command(os.path.relpath(unused, cwd)),
+            ))
+        elif is_externally_managed():
+            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), "
+                       "so `pip install` will fail with 'externally-managed-environment'.",
+                fix="python -m venv .venv  &&  " + activate_command(".venv"),
+            ))
+        else:
+            findings.append(Finding(
+                CHECK_ID, Status.INFO, "No virtual environment active",
+                fix="Recommended: python -m venv .venv  &&  " + activate_command(".venv"),
+            ))
+
+    if activated and norm(activated) != norm(sys.prefix):
+        findings.append(Finding(
+            CHECK_ID, Status.WARN,
+            "Your shell activated a DIFFERENT virtual environment",
+            detail="activated: %s\nrunning:   %s" % (activated, sys.prefix),
+            fix="Run `deactivate`, then activate the environment you meant to use.",
+        ))
+    return findings

pyfirstaid-0.1.0/src/pyfirstaid/cli.py

@@ -0,0 +1,97 @@
+"""Command-line entry point: `python -m pyfirstaid` or `pyfirstaid`."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+import traceback
+from typing import List, Optional
+
+from pyfirstaid import __version__
+from pyfirstaid.checks import ALL_CHECKS
+from pyfirstaid.model import Check, Finding, Options, Status
+from pyfirstaid.report import render_json, render_text
+
+EXIT_OK, EXIT_PROBLEMS, EXIT_INTERNAL = 0, 1, 2
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="pyfirstaid",
+        description="First aid for broken Python environments: "
+                    "finds what's wrong and tells you how to fix it.",
+    )
+    p.add_argument("--json", action="store_true", help="output machine-readable JSON")
+    p.add_argument("--share", action="store_true",
+                   help="hide your username and home folder so the report is safe to share")
+    p.add_argument("--offline", action="store_true", help="skip checks that need the internet")
+    p.add_argument("--strict", action="store_true", help="exit with code 1 on warnings too")
+    p.add_argument("--only", metavar="IDS", help="comma-separated check ids to run")
+    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("--version", action="version", version="pyfirstaid " + __version__)
+    return p
+
+
+def select_checks(only: Optional[str], skip: Optional[str]) -> List[Check]:
+    checks = list(ALL_CHECKS)
+    if only:
+        wanted = {s.strip() for s in only.split(",") if s.strip()}
+        checks = [c for c in checks if c.id in wanted]
+    if skip:
+        unwanted = {s.strip() for s in skip.split(",") if s.strip()}
+        checks = [c for c in checks if c.id not in unwanted]
+    return checks
+
+
+def run_checks(checks: List[Check], opts: Options) -> List[Finding]:
+    findings: List[Finding] = []
+    for check in checks:
+        try:
+            findings.extend(check.run(opts))
+        except Exception as exc:  # noqa: BLE001 - a broken check must never crash the tool
+            findings.append(Finding(
+                check.id, Status.SKIP, "%s: check could not run" % check.title,
+                detail="%s: %s" % (type(exc).__name__, exc),
+                fix="Please report this at https://github.com/sai-sakalam/pyfirstaid/issues",
+            ))
+    return findings
+
+
+def use_color(no_color: bool) -> bool:
+    if no_color or os.environ.get("NO_COLOR"):
+        return False
+    return hasattr(sys.stdout, "isatty") and sys.stdout.isatty() and os.name != "nt" \
+        or bool(os.environ.get("WT_SESSION"))  # Windows Terminal supports ANSI
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    if args.list:
+        for c in ALL_CHECKS:
+            print("%-14s %s" % (c.id, c.title))
+        return EXIT_OK
+
+    try:
+        findings = run_checks(select_checks(args.only, args.skip), Options(offline=args.offline))
+        if args.json:
+            print(render_json(findings, share=args.share))
+        else:
+            print(render_text(findings, color=use_color(args.no_color), share=args.share))
+    except Exception:  # noqa: BLE001
+        traceback.print_exc()
+        return EXIT_INTERNAL
+
+    if any(f.status == Status.ERROR for f in findings):
+        return EXIT_PROBLEMS
+    if args.strict and any(f.status == Status.WARN for f in findings):
+        return EXIT_PROBLEMS
+    return EXIT_OK
+
+
+def _run() -> None:
+    """Entry point for the single-file pyfirstaid.pyz."""
+    sys.exit(main())

pyfirstaid-0.1.0/src/pyfirstaid/model.py

@@ -0,0 +1,43 @@
+"""Data model shared by all checks."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from enum import Enum
+from typing import Callable, List, Optional
+
+
+class Status(str, Enum):
+    OK = "ok"
+    INFO = "info"
+    WARN = "warn"
+    ERROR = "error"
+    SKIP = "skip"
+
+
+@dataclass
+class Finding:
+    check: str
+    status: Status
+    title: str
+    detail: str = ""
+    fix: str = ""
+
+    def to_dict(self) -> dict:
+        d = asdict(self)
+        d["status"] = self.status.value
+        return d
+
+
+@dataclass
+class Check:
+    id: str
+    title: str
+    run: Callable[["Options"], List[Finding]]
+
+
+@dataclass
+class Options:
+    offline: bool = False
+    timeout: float = 8.0
+    cwd: Optional[str] = None

pyfirstaid-0.1.0/src/pyfirstaid/report.py

@@ -0,0 +1,107 @@
+"""Render findings as text or JSON, with optional privacy redaction."""
+
+from __future__ import annotations
+
+import getpass
+import json
+import os
+import platform
+import sys
+from typing import Dict, List
+
+from pyfirstaid import __version__
+from pyfirstaid.model import Finding, Status
+
+SYMBOLS = {
+    Status.OK: ("✔", "[ok]"),
+    Status.INFO: ("i", "[i]"),
+    Status.WARN: ("!", "[!]"),
+    Status.ERROR: ("✘", "[x]"),
+    Status.SKIP: ("-", "[-]"),
+}
+COLORS = {Status.OK: "32", Status.INFO: "36", Status.WARN: "33",
+          Status.ERROR: "31", Status.SKIP: "90"}
+
+
+def redact(text: str) -> str:
+    """Hide the home directory and username so reports are safe to share."""
+    if not text:
+        return text
+    home = os.path.expanduser("~")
+    if home and home not in ("~", "/"):
+        text = text.replace(home, "~")
+    try:
+        user = getpass.getuser()
+    except Exception:  # noqa: BLE001 - getuser can fail in odd environments
+        user = ""
+    if user and len(user) > 2:
+        text = text.replace(user, "<user>")
+    return text
+
+
+def environment_summary() -> Dict[str, str]:
+    return {
+        "python": platform.python_version(),
+        "implementation": platform.python_implementation(),
+        "executable": sys.executable,
+        "prefix": sys.prefix,
+        "platform": platform.platform(),
+    }
+
+
+def _can_encode(s: str) -> bool:
+    enc = getattr(sys.stdout, "encoding", None) or "ascii"
+    try:
+        s.encode(enc)
+        return True
+    except (UnicodeEncodeError, LookupError):
+        return False
+
+
+def summarize(findings: List[Finding]) -> Dict[str, int]:
+    return {s.value: sum(1 for f in findings if f.status == s) for s in Status}
+
+
+def render_json(findings: List[Finding], share: bool = False) -> str:
+    data = {
+        "tool": "pyfirstaid",
+        "version": __version__,
+        "environment": environment_summary(),
+        "summary": summarize(findings),
+        "findings": [f.to_dict() for f in findings],
+    }
+    text = json.dumps(data, indent=2, ensure_ascii=False)
+    return redact(text) if share else text
+
+
+def render_text(findings: List[Finding], color: bool = False, share: bool = False) -> str:
+    unicode_ok = _can_encode("✔✘")
+
+    def paint(status: Status, s: str) -> str:
+        return "\033[%sm%s\033[0m" % (COLORS[status], s) if color else s
+
+    env = environment_summary()
+    lines = [
+        "pyfirstaid %s: checking your Python environment" % __version__,
+        "Python %s (%s)" % (env["python"], env["executable"]),
+        "",
+    ]
+    for f in findings:
+        sym = SYMBOLS[f.status][0 if unicode_ok else 1]
+        lines.append("%s %s" % (paint(f.status, sym), f.title))
+        for d in filter(None, f.detail.splitlines()):
+            lines.append("    " + d)
+        if f.fix:
+            lines.append("    fix: " + f.fix)
+
+    counts = summarize(findings)
+    lines.append("")
+    if counts["error"] == 0 and counts["warn"] == 0:
+        lines.append(paint(Status.OK, "No problems found."))
+    else:
+        lines.append("%d problem(s), %d warning(s)." % (counts["error"], counts["warn"]))
+    if not share:
+        lines.append("Tip: run with --share for a privacy-safe report "
+                     "you can paste into a bug report.")
+    text = "\n".join(lines)
+    return redact(text) if share else text

pyfirstaid-0.1.0/src/pyfirstaid/util.py

@@ -0,0 +1,51 @@
+"""Small helpers used by checks. Standard library only."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from typing import List, Optional, Tuple
+
+
+def run(cmd: List[str], timeout: float = 15.0) -> Tuple[int, str, str]:
+    """Run a command and return (returncode, stdout, stderr).
+
+    Never raises: a missing executable or a timeout returns code 127 / 124.
+    """
+    try:
+        proc = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            env={**os.environ, "PIP_DISABLE_PIP_VERSION_CHECK": "1"},
+        )
+        return proc.returncode, proc.stdout.strip(), proc.stderr.strip()
+    except FileNotFoundError:
+        return 127, "", "executable not found"
+    except subprocess.TimeoutExpired:
+        return 124, "", "timed out after %ss" % timeout
+    except OSError as exc:
+        return 126, "", str(exc)
+
+
+def norm(path: Optional[str]) -> str:
+    """Normalise a path for comparison (absolute, resolved case on Windows)."""
+    if not path:
+        return ""
+    return os.path.normcase(os.path.abspath(path))
+
+
+def is_within(path: str, parent: str) -> bool:
+    path, parent = norm(path), norm(parent)
+    if not path or not parent:
+        return False
+    try:
+        return os.path.commonpath([path, parent]) == parent
+    except ValueError:  # different drives on Windows
+        return False
+
+
+def in_virtualenv() -> bool:
+    return sys.prefix != getattr(sys, "base_prefix", sys.prefix)

pyfirstaid-0.1.0/tests/test_checks.py

@@ -0,0 +1,80 @@
+import os
+import ssl
+import sys
+import urllib.error
+
+from pyfirstaid.checks import pip_mismatch, ssl_check, venv
+from pyfirstaid.model import Options, Status
+
+# --- pip-mismatch -----------------------------------------------------------
+
+def test_parse_pip_version_posix():
+    out = "pip 24.0 from /usr/lib/python3/dist-packages/pip (python 3.13)"
+    assert pip_mismatch.parse_pip_version(out) == (
+        "24.0", "/usr/lib/python3/dist-packages/pip", "3.13")
+
+
+def test_parse_pip_version_windows_path_with_spaces():
+    out = r"pip 25.1 from C:\Program Files\Python313\Lib\site-packages\pip (python 3.13)"
+    assert pip_mismatch.parse_pip_version(out)[1].endswith(r"site-packages\pip")
+
+
+def test_parse_pip_version_garbage():
+    assert pip_mismatch.parse_pip_version("Traceback (most recent call last):") is None
+
+
+def test_pip_belongs_here(tmp_path):
+    prefix = str(tmp_path / "venv")
+    loc = os.path.join(prefix, "lib", "site-packages", "pip")
+    assert pip_mismatch.pip_belongs_here(loc, "3.13", "3.13", [prefix])
+    assert not pip_mismatch.pip_belongs_here(loc, "3.12", "3.13", [prefix])
+    assert not pip_mismatch.pip_belongs_here("/usr/lib/pip", "3.13", "3.13", [prefix])
+
+
+def test_pip_check_runs_without_crashing():
+    findings = pip_mismatch.run_check(Options(offline=True))
+    assert findings and all(f.check == "pip-mismatch" for f in findings)
+
+
+# --- venv -------------------------------------------------------------------
+
+def test_find_unused_venv(tmp_path):
+    assert venv.find_unused_venv(str(tmp_path)) is None
+    (tmp_path / ".venv").mkdir()
+    (tmp_path / ".venv" / "pyvenv.cfg").write_text("home = /usr/bin\n")
+    assert venv.find_unused_venv(str(tmp_path)).endswith(".venv")
+
+
+def test_activate_command_mentions_path():
+    assert ".venv" in venv.activate_command(".venv")
+
+
+def test_wrong_venv_activated(monkeypatch, tmp_path):
+    monkeypatch.setenv("VIRTUAL_ENV", str(tmp_path / "some-other-venv"))
+    findings = venv.run_check(Options(cwd=str(tmp_path)))
+    assert any("DIFFERENT virtual environment" in f.title for f in findings)
+
+
+# --- ssl --------------------------------------------------------------------
+
+def test_bad_cert_env_vars(tmp_path):
+    good = tmp_path / "ca.pem"
+    good.write_text("x")
+    env = {"SSL_CERT_FILE": str(tmp_path / "missing.pem"), "REQUESTS_CA_BUNDLE": str(good)}
+    assert ssl_check.bad_cert_env_vars(env) == ["SSL_CERT_FILE"]
+
+
+def test_classify_error():
+    cert = urllib.error.URLError(ssl.SSLCertVerificationError("CERTIFICATE_VERIFY_FAILED"))
+    assert ssl_check.classify_error(cert) == "cert"
+    assert ssl_check.classify_error(urllib.error.URLError(ssl.SSLError("bad"))) == "ssl"
+    assert ssl_check.classify_error(urllib.error.URLError(OSError("no route"))) == "network"
+
+
+def test_ssl_offline_skips_network(monkeypatch):
+    for name in ssl_check.CERT_ENV_VARS:
+        monkeypatch.delenv(name, raising=False)
+    findings = ssl_check.run_check(Options(offline=True))
+    assert any(f.status == Status.SKIP for f in findings)
+    if sys.platform != "darwin":
+        assert all(f.status != Status.ERROR for f in findings)

pyfirstaid-0.1.0/tests/test_cli.py

@@ -0,0 +1,56 @@
+import json
+import os
+
+from pyfirstaid import cli, report
+from pyfirstaid.model import Check, Finding, Options, Status
+
+
+def test_list(capsys):
+    assert cli.main(["--list"]) == 0
+    out = capsys.readouterr().out
+    assert "pip-mismatch" in out and "venv" in out and "ssl" in out
+
+
+def test_json_output_is_valid(capsys):
+    code = cli.main(["--offline", "--json"])
+    data = json.loads(capsys.readouterr().out)
+    assert code in (0, 1)
+    assert data["tool"] == "pyfirstaid"
+    assert {"ok", "info", "warn", "error", "skip"} <= set(data["summary"])
+    assert all({"check", "status", "title", "detail", "fix"} <= set(f) for f in data["findings"])
+
+
+def test_only_and_skip():
+    assert [c.id for c in cli.select_checks("venv", None)] == ["venv"]
+    assert "ssl" not in [c.id for c in cli.select_checks(None, "ssl")]
+
+
+def test_crashing_check_is_reported_not_raised():
+    def boom(opts):
+        raise RuntimeError("kaboom")
+
+    findings = cli.run_checks([Check("boom", "Boom", boom)], Options())
+    assert findings[0].status == Status.SKIP and "kaboom" in findings[0].detail
+
+
+def test_exit_codes(monkeypatch):
+    def fake(statuses):
+        return lambda checks, opts: [Finding("x", s, "t") for s in statuses]
+
+    monkeypatch.setattr(cli, "run_checks", fake([Status.OK]))
+    assert cli.main(["--json"]) == 0
+    monkeypatch.setattr(cli, "run_checks", fake([Status.WARN]))
+    assert cli.main(["--json"]) == 0
+    assert cli.main(["--json", "--strict"]) == 1
+    monkeypatch.setattr(cli, "run_checks", fake([Status.ERROR]))
+    assert cli.main(["--json"]) == 1
+
+
+def test_redact_hides_home():
+    home = os.path.expanduser("~")
+    assert home not in report.redact("path is %s/project" % home)
+
+
+def test_text_report_shows_fix():
+    text = report.render_text([Finding("x", Status.ERROR, "Broken", "why", "do this")])
+    assert "Broken" in text and "fix: do this" in text and "1 problem(s)" in text