Skip to content

README.md

Latest commit

 

History

History
234 lines (167 loc) · 5.95 KB

README.md

File metadata and controls

234 lines (167 loc) · 5.95 KB

PermitCheck

Tests PyPI version Python Versions License

A fast, modern license compliance checker for Python projects

PermitCheck automatically scans your dependencies and validates them against your license policy. Built with performance in mind, it features parallel processing, smart caching, and multiple output formats for seamless integration into any workflow.

✨ Features

  • 🚀 Parallel Processing - Fast dependency scanning with concurrent license lookups
  • 💾 Smart Caching - Intelligent caching system to speed up repeated scans
  • 🎯 SPDX Expression Support - Handles complex license expressions like MIT OR Apache-2.0
  • 📊 Multiple Output Formats - Console, JSON, HTML, Markdown, CSV, and SARIF
  • 🔍 Enhanced Detection - Extracts licenses from metadata, classifiers, LICENSE files, and READMEs
  • ⚙️ Flexible Configuration - YAML or TOML-based policy configuration
  • 🔌 Plugin Architecture - Extensible design for future language support
  • 🤖 CI/CD Ready - Easy integration with GitHub Actions, GitLab CI, and more

📦 Installation

pip install permitcheck

Or using uv:

uv add permitcheck

🚀 Quick Start

Basic Usage

Check Python dependencies with console output:

permitcheck -l python

Output Formats

Generate reports in different formats:

# JSON output for CI/CD pipelines
permitcheck -l python --format json

# HTML report with charts and styling
permitcheck -l python --format html -o report.html

# Markdown for documentation
permitcheck -l python --format markdown -o compliance.md

# CSV for spreadsheet analysis
permitcheck -l python --format csv -o licenses.csv

# SARIF for security tools integration
permitcheck -l python --format sarif -o results.sarif

Configuration

Create a permitcheck.yaml in your project root:

allowed_licenses:
  - MIT
  - Apache-2.0
  - BSD-3-Clause
  - ISC

trigger_error_licenses:
  - GPL-3.0
  - AGPL-3.0
  - Proprietary
  - Unknown

skip_libraries:
  - internal-package

Or use pyproject.toml:

[licenses]
allowed = ["MIT", "Apache-2.0", "BSD-3-Clause"]
trigger_error = ["GPL-3.0", "AGPL-3.0", "Proprietary"]
skip_libraries = []

📖 Documentation

📚 Complete Documentation - Full documentation index with guides and references

Quick Links:

For Contributors:

🔧 CLI Options

Options:
  -l, --lang LANG         Languages to check: python, npm
  --format FORMAT         Output format: console, json, simple, html, markdown, csv, sarif
  -o, --output FILE       Write output to file instead of stdout
  -v, --version           Show version number
  -V, --verbose           Enable verbose output
  -q, --quiet             Suppress non-error output
  --clear-cache           Clear the license cache
  --no-cache              Disable caching for this run
  -h, --help              Show help message

💡 Examples

CI/CD Integration

GitHub Actions:

- name: Check License Compliance
  run: |
    pip install permitcheck
    permitcheck -l python --format sarif -o results.sarif
    
- name: Upload Results
  uses: github/codeql-action/upload-sarif@v2
  with:
    sarif_file: results.sarif

GitLab CI:

license-check:
  script:
    - pip install permitcheck
    - permitcheck -l python --format json
  artifacts:
    reports:
      license_scanning: license-report.json

Advanced Usage

# Verbose output with detailed information
permitcheck -l python --verbose

# Quiet mode for CI (only errors)
permitcheck -l python --quiet

# Force fresh scan (bypass cache)
permitcheck -l python --no-cache

# Multiple output formats
permitcheck -l python --format html -o report.html
permitcheck -l python --format json -o results.json

🎯 Use Cases

  • Pre-commit Hooks - Validate licenses before committing
  • CI/CD Pipelines - Automated compliance checks on every build
  • Dependency Audits - Regular license compliance reviews
  • Security Scanning - Integrate with security tools via SARIF
  • Documentation - Generate license reports for stakeholders

🛠️ Development

Setup

git clone https://github.com/kirankotari/permitcheck.git
cd permitcheck
uv sync

Running Tests

# All tests
uv run pytest

# With coverage
uv run pytest --cov=permitcheck --cov-report=html

# Specific test suite
uv run pytest tests/test_integration.py -v

Code Quality

# Format code
uv run black permitcheck tests

# Lint
uv run pylint permitcheck

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🙏 Acknowledgments

  • SPDX for standardized license identifiers
  • All contributors who have helped improve this project

📞 Support

Made with ❤️ by Kiran Kumar Kotari