avalpdf 0.1.5

PDF Accessibility Validator

avalpdf - PDF Accessibility Validator

A command-line tool for validating PDF accessibility, analyzing document structure, and generating detailed reports.

Features

Document structure analysis and support

• Document structure analysis
• Support for both local and remote PDF files

Document tags and metadata validation

• Document tagging status
• Title presence
• Language declaration (Italian)

Heading hierarchy validation

• H1 presence
• Correct heading levels sequence

Figure alt text validation

• Missing alternative text detection
• Complex or problematic alt text patterns

Tables structure validation

• Header presence and proper structure
• Empty cells detection
• Duplicate headers check
• Multiple header rows warning
• Empty tables detection

Lists structure validation

• Proper list tagging
• Detection of untagged lists (consecutive paragraphs with bullets/numbers)
• Misused list types (numbered items in unordered lists)
• List hierarchy consistency

Links validation

• Detection of non-descriptive links
• Raw URL text warnings
• Email and institutional domain exceptions

Formatting issues detection

• Excessive underscores (used for underlining)
• Spaced capital letters (like "T E S T")
• Extra spaces used for layout (3+ consecutive spaces)

Empty elements detection

• Empty paragraphs
• Whitespace-only elements
• Empty headings
• Empty spans
• Empty table cells

Output formats

• Detailed JSON structure
• Simplified JSON
• Accessibility validation report
• Console reports with color-coded structure visualization

Scoring and reporting

• Weighted scoring system based on accessibility criteria
• Detailed issue categorization (issues, warnings, successes)

Installation

Using pip

pip install avalpdf

Or uv

uv tool install avalpdf

Updates

Using pip

pip install avalpdf --upgrade

Or uv

uv tool install avalpdf --upgrade

Usage

After installation, you can run avalpdf from any directory.

Quick start

Simply run

avalpdf thesis.pdf

or

avalpdf https://example.com/document.pdf

to get a report like this

and a preview of the structure

Details

# Basic validation with console output
avalpdf document.pdf

# Complete analysis with all outputs
avalpdf document.pdf --full --simple --report

# Save reports to specific directory
avalpdf document.pdf -o /path/to/output --report --simple

# Show document structure only
avalpdf document.pdf --show-structure

# Display version information
avalpdf --version

Command Line Options

• --full: Save full JSON structure
• --simple: Save simplified JSON structure
• --report: Save validation report
• --output-dir, -o: Specify output directory
• --show-structure: Display document structure
• --show-validation: Display validation results
• --quiet, -q: Suppress console output
• --rich: Use enhanced visual formatting for document structure
• --tree: Use tree view instead of panel view with Rich formatting
• --version, -v: Display the version number and exit

Examples

1. Quick accessibility check:

avalpdf thesis.pdf

2. Generate all reports:

avalpdf report.pdf --full --simple --report -o ./analysis

3. Silent operation with report generation:

avalpdf document.pdf --report -q

4. Analyze multiple files:

for file in *.pdf; do avalpdf "$file" --report --quiet; done

Validation Output

The tool provides three types of findings:

• ✅ Successes: Correctly implemented accessibility features
• ⚠️ Warnings: Potential issues that need attention
• ❌ Issues: Problems that must be fixed

Report Format

{
  "validation_results": {
    "issues": ["..."],
    "warnings": ["..."],
    "successes": ["..."]
  }
}

License

MIT License

Support

For issues or suggestions:

• Open an issue on GitHub
• Provide the PDF file (if possible) and the complete error message
• Include the command you used and your operating system information

Local development

uv venv .test
source .test/bin/activate
uv pip install -e . --upgrade