pyfirstaid 0.1.0__py3-none-any.whl

pyfirstaid/__init__.py

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

pyfirstaid/__main__.py

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

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/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/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/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/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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,15 @@
+pyfirstaid/__init__.py,sha256=8Y2fnosuKOVOU_-gD9yw781V2Jww11ZQlpxmC31yoJU,83
+pyfirstaid/__main__.py,sha256=qus5zBx3CArE8PQGMmumBuNo76lSIqgwniIr9h8HPkM,62
+pyfirstaid/cli.py,sha256=7rtUymkg1s-o34g2xIXk37ySlaOBDG4Ckw-lLANPpTI,3733
+pyfirstaid/model.py,sha256=W73tNH6Kp89rHNpyuk7Lnt494DuI5o0AE3ZR2_cSrXA,737
+pyfirstaid/report.py,sha256=9HskRv-2zW0Yk2aXnO5t4fJWe9Plwsp3-rgE1XbBpvM,3323
+pyfirstaid/util.py,sha256=bBfLbgBBTXZQPsg1rqr7f9BtOpEokdNd92EMxjbt5lA,1514
+pyfirstaid/checks/__init__.py,sha256=Ugh2KTgcCK29vVIHtnsfB0PikqP0WO01oSwxdTB7SLU,468
+pyfirstaid/checks/pip_mismatch.py,sha256=wuhrBFHjwXl592l3JA_GPEmyCdTtjYjIFcjFKi9OQhg,3017
+pyfirstaid/checks/ssl_check.py,sha256=QBol38duu6s5hS9oQWC-wyS_HWD-XRTaIoir9oNSlWw,5203
+pyfirstaid/checks/venv.py,sha256=3abpih7p-sG4r-fwdD38ud2cMp6BKMB5YoSZHU7b_cQ,3086
+pyfirstaid-0.1.0.dist-info/METADATA,sha256=s8CYHoO91mq2ny1Twq0yD4jzTwTuFS8FsDVhBhggHQE,7468
+pyfirstaid-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+pyfirstaid-0.1.0.dist-info/entry_points.txt,sha256=BFlXV8dGrE0mvq2ezVoW5KnEVrqnTpyJf5Ips_Cw1So,51
+pyfirstaid-0.1.0.dist-info/licenses/LICENSE,sha256=9LK52_tXa2Xsaj9UGfwYN1i8ncapHRcy8_O4kO_N56U,1077
+pyfirstaid-0.1.0.dist-info/RECORD,,

pyfirstaid-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

pyfirstaid-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pyfirstaid = pyfirstaid.cli:main

pyfirstaid-0.1.0.dist-info/licenses/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.