pycheck-tool 0.1.4

A simple, dynamic sanity-check library for Python distributions.

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

pip install pycheck-tool

# Minimal health check (runs --os by default)
pycheck-tool

You can also get it via curl, by typing:

curl -fsSL https://raw.githubusercontent.com/Auberryy/pycheck/main/pycheck_tool.py | python3 -

Option B – hack on it

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.

pycheck --json > reports\health.json
# Safe to share: no absolute paths or usernames leaked

Python API

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 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