pycmdcheck

A comprehensive Python package checker inspired by R CMD check

What is pycmdcheck?

pycmdcheck is a quality assurance tool for Python packages that performs comprehensive checks across multiple dimensions:

• Structure - README, LICENSE, pyproject.toml, src layout
• Metadata - Project name, version, description, classifiers, URLs
• Tests - Test directory, test execution, coverage, naming conventions
• Documentation - Docstrings, docs directory, API docs, broken links
• Code Quality - Linting, type hints, complexity, dead code, doctests
• Dependencies - Version pinning, lockfiles, circular imports, freshness
• Security - Credential exposure, insecure functions, vulnerabilities
• Build - Package builds, wheel creation, installation, imports
• Release - Changelog, semantic versioning, git tags

Quick Start

Installation

pip install pycmdcheck

Or with uv:

uv add pycmdcheck

Command Line Usage

Check the current directory:

pycmdcheck check

Check a specific package:

pycmdcheck check ./my-package

Auto-fix issues:

pycmdcheck fix

Get help on a specific check:

pycmdcheck explain ST001

Python API

import pycmdcheck

# Check a package
results = pycmdcheck.check("./my-package")

# View results
print(f"Passed: {results.passed}")
print(f"Failed: {results.failed}")
print(f"Exit code: {results.exit_code}")

# Iterate over results
for result in results.all_results:
    if result.status == "failed":
        print(f"{result.check_id}: {result.message}")

Available Checks

pycmdcheck includes 65 checks across 9 groups:

Group	Checks	Description
structure	ST001-ST012	README, LICENSE, pyproject.toml, src layout, exports, CONTRIBUTING, CODE_OF_CONDUCT, pre-commit, CI
metadata	MT001-MT012	Name, version, description, classifiers, URLs, keywords, OSI license, author email
tests	TS001-TS005	Test directory, execution, coverage, naming, discoverability
documentation	DC001-DC007	Docstrings, docs directory, API docs, broken links, README structure, badges
code-quality	CQ001-CQ009	Ruff, type hints, TODOs, mypy, complexity, doctests, type hint coverage
dependencies	DP001-DP005	Pinned deps, lockfile, freshness, circular imports
security	SC001-SC006	Credentials, insecure functions, vulnerabilities, deprecated APIs
build	BD001-BD004	Build, wheel, install, import verification
release	RL001-RL005	Changelog, semver, git tags, citation, PyPI

See the Checks section for detailed documentation on each check.

Configuration

Configure pycmdcheck in your pyproject.toml:

[tool.pycmdcheck]
skip = ["MT003"]  # Skip specific checks
error_on = "warning"  # Exit with error on warnings too

# Check-specific configuration
[tool.pycmdcheck.checks.TS002]
parallel = true
workers = "auto"

[tool.pycmdcheck.checks.TS003]
coverage_threshold = 70

See Configuration for all options.

GitHub Actions

Add pycmdcheck to your CI pipeline:

- name: Run pycmdcheck
  run: |
    pip install pycmdcheck
    pycmdcheck check --format github .

See GitHub Actions for detailed setup instructions.

Profiles

Use profiles for common use cases:

# Strict - fail on any issue
pycmdcheck check --profile strict

# pyOpenSci - checks for pyOpenSci review
pycmdcheck check --profile pyopensci

# CI - optimized for CI pipelines
pycmdcheck check --profile ci

# Release - focus on release-critical checks
pycmdcheck check --profile release

See Profiles for details on built-in and custom profiles.

Features

• 65 comprehensive checks - Structure, metadata, tests, docs, code quality, security, and more
• Multiple output formats - Rich terminal, JSON, GitHub Actions, SARIF, JUnit XML, Markdown, HTML
• Built-in profiles - strict, relaxed, ci, release, pyopensci
• Auto-fix support - Automatically fix common issues
• Configurable severity - Control what causes CI failures
• Parallel execution - Run checks and tests concurrently
• Watch mode - Re-run checks on file changes
• Incremental mode - Only check modified files
• Baseline management - Ignore known issues
• Plugin system - Extend with custom checks
• Custom profiles - Define reusable check configurations