pycheck-tool 0.1.4
A simple, dynamic sanity-check library for Python distributions.
Requires Python: >=3.9

# pycheck-tool

[![PyPI version](https://img.shields.io/pypi/v/pycheck-tool.svg)](https://pypi.org/project/pycheck-tool/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Versions](https://img.shields.io/pypi/pyversions/pycheck-tool.svg)](https://pypi.org/project/pycheck-tool/)
[![Downloads](https://static.pepy.tech/badge/pycheck-tool)](https://pepy.tech/project/pycheck-tool)

> **pycheck-tool** is the safe, zero-dependency way to answer "Is this Python install healthy?" — whether you're a beginner sharing logs or a maintainer shipping CI.

## At a Glance

| | |
|-|-|
| **Current version** | `0.1.4` |
| **Python support** | 3.9 – 3.13 |
| **License** | MIT |
| **Maintainer** | Aubrey |
| **Status** | Battle-tested and production-ready |

## Features

- **No dependencies** – works anywhere Python does.
- **Two-tier checks** – run `--os` for a quick stdlib sweep or `--all` when you need every package exercised.
- **Friendly CLI aliases** – `pycheck-tool`, `pycheck`, and `do_check` all point to the same entry point.
- **JSON with the *Dutcho* filter** – usernames and home paths are scrubbed automatically, so you can paste logs without leaking `/Users/you`.
- **Capability probes** – built-in filesystem + SSL diagnostics with clear pass/fail status codes.
- **Hostile environment resilience** – survives corrupted `sys.modules`, broken imports, and malformed distributions without crashing.
- **Debug diagnostics** – use `--debug` to see which modules failed to import.
- **Spam protection** – use `--limit N` to cap output when checking many packages.
- **Release automation** – published via Trusted Publishing as soon as you cut a GitHub Release.

## Quick Start

### Option A – use it

```powershell
pip install pycheck-tool

# Minimal health check (runs --os by default)
pycheck-tool
```

You can also get it via `curl`, by typing:

```bash
curl -fsSL https://raw.githubusercontent.com/Auberryy/pycheck/main/pycheck_tool.py | python3 -
```

### Option B – hack on it

```powershell
git clone https://github.com/Auberryy/pycheck.git
cd pycheck
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .[dev]
pytest
```

## Command cheat sheet

| When you need… | Run |
| --- | --- |
| Fast confidence in stdlib modules | `pycheck --os` |
| Exhaustive audit of installed packages | `pycheck --all` |
| Shareable JSON (sanitized) | `pycheck --json > report.json` |
| Human + JSON in one go | `pycheck --os --json` |
| Debug failing imports | `pycheck --os --debug` |
| Limit output spam | `pycheck --all --limit 10` |
| Backwards-compatible names | `pycheck-tool` or `do_check` |

## JSON reports & the Dutcho filter

`--json` emits machine-friendly output (perfect for Neovim, editors, CI). Before printing, every string is sanitized:

- Home directory prefixes become `~`.
- Usernames are replaced with `<user>`.
- Capability entries (filesystem, SSL) share the exact status you can copy/paste online.

```powershell
pycheck --json > reports\health.json
# Safe to share: no absolute paths or usernames leaked
```

## Python API

```python
import pycheck

# Quick stdlib check
if pycheck.doSanityCheck(pycheck.OS):
    print("OS Library is good")

# Full package audit
result = pycheck.doSanityCheck(pycheck.ALL)
if result:
    print(f"{result} libraries are fine!")

# Get list of failed imports for diagnostics
failed = pycheck.get_failed_imports(pycheck.OS)
if failed:
    print(f"Failed to import: {failed}")

# Check specific capabilities
ssl_result = pycheck.check_ssl_support()
fs_result = pycheck.check_filesystem_access()
```

Use the API when you want to embed health checks into your own tooling or CI scripts.

## Capability probes

Each run appends capability entries to the report:

- `filesystem_access` – verifies we can write/read a temp file.
- `ssl` – ensures the `ssl` module imports and can create a default context.

Failures cause a non-zero exit code so CI can gate on them.

## Robustness

pycheck is designed to survive hostile environments:

- **Corrupted sys.modules** – handles `None`, integers, or broken objects where modules should be.
- **Broken distributions** – gracefully skips packages with corrupted metadata.
- **Import side effects** – catches exceptions from packages that crash during import.
- **Ctrl+C support** – properly propagates `KeyboardInterrupt` and `SystemExit`.

## Development & release flow

1. Work on a feature branch, add tests (use `unittest.mock` to simulate failures).
2. Run `pytest` and `pycheck --json` before pushing.
3. Open a PR. Once merged, create a GitHub Release — the `publish.yml` workflow builds and uploads to PyPI with trusted publishing (no tokens to copy).

See [`CONTRIBUTING.md`](CONTRIBUTING.md) for full guidelines, including the "Zero Dependencies Forever" rule.

## Project layout

```
src/pycheck/
├── __init__.py   # Package exports and version
├── checker.py    # Core sanity-check logic
├── cli.py        # CLI entry point and argument parsing
└── utils.py      # Sanitization helpers
tests/            # pytest suite with mocked failure scenarios
examples/         # Tiny runnable snippets
pycheck_tool.py   # Standalone single-file version
```