Reporting Formats

pycmdcheck supports multiple output formats to fit different use cases, from interactive terminal usage to CI integration and documentation generation.

Output Formats

Rich (Default)

The default format provides colorful, well-organized terminal output using the Rich library.

pycmdcheck

Options:

• --verbose / -v: Show all checks including passed ones
• --quiet / -q: Minimal output, show only failures

JSON

Machine-readable JSON output for programmatic processing.

pycmdcheck --format json

The JSON output includes:

• Package information
• Summary counts
• Detailed results per group
• Skipped checks and fixture errors

Example:

{
  "version": "1.0.0",
  "pycmdcheck_version": "0.1.0",
  "package": {
    "name": "my-package",
    "path": "/path/to/my-package",
    "version": "1.0.0"
  },
  "summary": {
    "passed": 15,
    "failed": 2,
    "warnings": 1,
    "notes": 0,
    "skipped": 0,
    "total": 17
  },
  "groups": [...]
}

GitHub Actions

Outputs GitHub Actions workflow annotations for seamless CI integration.

pycmdcheck --format github

This produces annotations like:

::error file=pyproject.toml,line=1::Missing description
::warning::Missing changelog

Markdown

Generates markdown-formatted reports, ideal for PR comments or documentation.

pycmdcheck --format markdown

Options:

• --quiet: Use compact format (shorter output for PR comments)

Example output:

# pycmdcheck: my-package v1.0.0

:x: **2 failed**, :white_check_mark: 15 passed (17 total)

## Structure

| Status | ID | Check | Severity | Message |
|:------:|:---|:------|:---------|:--------|
| :white_check_mark: | ST001 | Has README |  |  |
| :x: | ST002 | Has LICENSE | ERROR | No LICENSE file found |
| | | | | :bulb: Create a LICENSE file |

HTML

Generates a complete, self-contained HTML report with embedded CSS.

pycmdcheck check --format html -o report.html

Features:

• Responsive design (works on mobile)
• Summary cards with pass/fail counts
• Color-coded severity indicators
• No external dependencies (all CSS embedded)

SARIF

Generates SARIF (Static Analysis Results Interchange Format) output for integration with code analysis tools.

pycmdcheck check --format sarif -o results.sarif

SARIF is supported by:

• GitHub Advanced Security
• Azure DevOps
• VS Code SARIF Viewer extension
• Many static analysis platforms

JUnit XML

Generates JUnit XML format for CI systems that support test result parsing.

pycmdcheck check --format junit -o results.xml

JUnit XML is supported by:

• Jenkins
• GitLab CI
• Azure DevOps
• CircleCI
• Most CI/CD platforms

The output maps:

• Check groups → Test suites
• Individual checks → Test cases
• Check failures → Test failures with message and details

Badge Generation

Generate SVG badges to display your package’s check status in documentation.

pycmdcheck --badge badge.svg

The badge will be:

• Green when all checks pass
• Red when any checks fail

Using the Badge

In your README.md:

![pycmdcheck](./badge.svg)

You can also generate a badge alongside other output:

pycmdcheck --format json -o results.json --badge badge.svg

Dynamic Badges

For dynamic badge URLs (useful for GitHub README badges), use the Python API:

from pycmdcheck.output import generate_badge_url

url = generate_badge_url(passed=15, failed=0)
# Returns: https://img.shields.io/badge/pycmdcheck-15%20passing-brightgreen?style=flat

Writing Output to Files

All formats support writing to a file instead of stdout:

# Write JSON report
pycmdcheck --format json -o results.json

# Write HTML report
pycmdcheck --format html -o report.html

# Write Markdown report
pycmdcheck --format markdown -o CHECKS.md

Combining Options

You can combine output format options:

# Generate both JSON output and a badge
pycmdcheck --format json -o results.json --badge badge.svg

# Quiet markdown for PR comments
pycmdcheck --format markdown --quiet

# Verbose rich output to a file
pycmdcheck --verbose -o checks.txt

Python API

All formatters are available through the Python API:

from pycmdcheck import check
from pycmdcheck.output import (
    MarkdownFormatter,
    HTMLFormatter,
    generate_badge,
    generate_badge_url,
)

# Run checks
results = check("/path/to/package")

# Generate markdown
md_formatter = MarkdownFormatter(compact=False)
markdown = md_formatter.format(results)

# Generate HTML
html_formatter = HTMLFormatter()
html = html_formatter.format(results)

# Generate badge SVG
badge_svg = generate_badge(
    passed=results.passed,
    failed=results.failed,
    label="pycmdcheck"
)

# Generate shields.io URL
badge_url = generate_badge_url(
    passed=results.passed,
    failed=results.failed
)

Format Comparison

Format	Best For	Machine Readable	Human Readable
rich	Interactive terminal	No	Yes
json	CI/CD pipelines, tools	Yes	Somewhat
github	GitHub Actions annotations	Yes	Yes
markdown	PR comments, docs	No	Yes
html	Shareable reports	No	Yes
sarif	Code analysis platforms	Yes	No
junit	CI test result parsing	Yes	Somewhat