{"id":31320601,"url":"https://github.com/jluster96/pdf-package-analyzer","last_synced_at":"2025-10-05T19:04:16.539Z","repository":{"id":316008158,"uuid":"1061555713","full_name":"jluster96/PDF-Package-Analyzer","owner":"jluster96","description":"A comprehensive Python tool for analyzing PDF files and determining the best PDF processing library for each file. The analyzer tests PDFs against multiple libraries (pypdf, PyMuPDF, pdfplumber) and provides detailed compatibility reports and recommendations.","archived":false,"fork":false,"pushed_at":"2025-09-22T05:06:22.000Z","size":62,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-09-22T07:07:58.847Z","etag":null,"topics":["analysis","analytics","compatibility","ocr","pdf","pdf-document","pdfplumber","pymupdf","pypdf","pypdf2","python","python3","quality","testing","text-processing","text-shaping"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jluster96.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-22T04:46:54.000Z","updated_at":"2025-09-22T05:06:25.000Z","dependencies_parsed_at":"2025-09-22T07:08:01.943Z","dependency_job_id":"e5fd065e-e288-4bc0-b1ee-15e86a8dea9b","html_url":"https://github.com/jluster96/PDF-Package-Analyzer","commit_stats":null,"previous_names":["jluster96/pdf-package-analyzer"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/jluster96/PDF-Package-Analyzer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jluster96%2FPDF-Package-Analyzer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jluster96%2FPDF-Package-Analyzer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jluster96%2FPDF-Package-Analyzer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jluster96%2FPDF-Package-Analyzer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jluster96","download_url":"https://codeload.github.com/jluster96/PDF-Package-Analyzer/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jluster96%2FPDF-Package-Analyzer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276953985,"owners_count":25734618,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-25T02:00:09.612Z","response_time":80,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["analysis","analytics","compatibility","ocr","pdf","pdf-document","pdfplumber","pymupdf","pypdf","pypdf2","python","python3","quality","testing","text-processing","text-shaping"],"created_at":"2025-09-25T16:51:09.679Z","updated_at":"2025-09-25T16:51:10.728Z","avatar_url":"https://github.com/jluster96.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PDF Package Analyzer\n\nA comprehensive Python tool for analyzing PDF files and determining the best PDF processing library for each file. The analyzer tests PDFs against multiple libraries (pypdf, PyMuPDF, pdfplumber) and provides detailed compatibility reports and recommendations.\n\n## 🚀 Features\n\n- **Multi-library Testing**: Tests PDFs against pypdf, PyMuPDF, and pdfplumber\n- **Comprehensive Analysis**: Evaluates text extraction, metadata access, and error handling\n- **Detailed Reporting**: Generates JSON reports and text summaries\n- **Timeout Protection**: Prevents hanging on problematic PDFs\n- **Progress Tracking**: Visual progress bars and logging\n- **Modular Architecture**: Clean, maintainable code structure\n- **CLI Interface**: Easy-to-use command-line interface\n\n## 📁 Project Structure\n\n```\npdf-package-analyzer/\n├── main.py              # CLI interface and main entry point\n├── modules/             # Core analysis modules\n│   ├── __init__.py     # Package initialization\n│   ├── analyzer.py     # Main PDFAnalyzer class\n│   ├── models.py       # Data classes and result containers\n│   ├── pdf_libraries.py # PDF library testing logic\n│   └── utils.py        # Utility functions (timeout handling, etc.)\n├── files/\n│   ├── docs/           # Directory containing PDF files to analyze\n│   └── docs-info/      # Analysis results and logs\n├── pyproject.toml      # Project configuration and dependencies\n├── requirements.txt    # Python dependencies\n└── README.md           # This file\n```\n\n## 🛠️ Installation\n\n### Prerequisites\n\n- Python 3.11 or higher\n- [uv](https://docs.astral.sh/uv/) (recommended) or pip\n\n### Using uv (Recommended)\n\n```bash\n# Clone the repository\ngit clone https://github.com/jluster96/PDF-Package-Analyzer.git\ncd pdf-analyzer\n\n# Install dependencies\nuv sync\n\n# Run the analyzer\nuv run main.py\n```\n\n### Using pip\n\n```bash\n# Clone the repository\ngit clone https://github.com/jluster96/PDF-Package-Analyzer.git\ncd pdf-analyzer\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n\n# Install dependencies\npip install -r requirements.txt\n\n# Run the analyzer\npython main.py\n```\n\n## 📖 Usage\n\n### Basic Usage\n\n```bash\n# Analyze all PDFs in the default directory (files/docs)\nuv run main.py\n\n# Analyze PDFs in a specific directory\nuv run main.py --docs_dir /path/to/your/pdfs\n\n# Limit the number of files to process\nuv run main.py --limit 10\n\n# Enable verbose logging\nuv run main.py --verbose\n```\n\n### Command Line Options\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--docs_dir` | Directory containing PDF files | `files/docs` |\n| `--info_dir` | Directory to store analysis results | `{docs_dir}-info` |\n| `--report_output` | Output report file name | `pdf_analysis_report.json` |\n| `--summary_output` | Output summary file name | Auto-generated |\n| `--timeout` | Timeout in seconds for each library test | `30` |\n| `--limit` | Limit number of PDF files to process | Process all |\n| `--verbose`, `-v` | Enable verbose logging | `False` |\n| `--quiet` | Quiet mode: `progress`, `logs`, or `all` | None |\n| `--recommendation_only` | Show only recommended package and percentage | `False` |\n\n### Examples\n\n```bash\n# Quick analysis with custom timeout\nuv run main.py --timeout 60 --limit 5\n\n# Silent analysis with custom output directory\nuv run main.py --quiet all --info_dir results --docs_dir my_pdfs\n\n# Verbose analysis with custom report name\nuv run main.py --verbose --report_output my_analysis.json\n\n# Show only recommendations\nuv run main.py --recommendation_only\n```\n\n## 📊 Output\n\nThe analyzer generates several output files in the info directory:\n\n### JSON Report (`pdf_analysis_report.json`)\nDetailed analysis results including:\n- Individual file test results\n- Library performance metrics\n- Error details and recommendations\n- Overall statistics\n\n### Summary Report (`pdf_analysis_summary.txt`)\nHuman-readable summary with:\n- Overall statistics\n- Library recommendations\n- Common issues found\n- Performance insights\n\n### Log File (`pdf_test_results.log`)\nDetailed execution log with:\n- Processing steps\n- Error messages\n- Performance metrics\n- Debug information (if verbose mode enabled)\n\n## 🏗️ Architecture\n\nThe project follows a modular architecture for maintainability and testability:\n\n### Core Modules\n\n- **`main.py`**: CLI interface and argument parsing\n- **`modules/analyzer.py`**: Main analysis orchestration and report generation\n- **`modules/models.py`**: Data structures for test results\n- **`modules/pdf_libraries.py`**: PDF library testing implementations\n- **`modules/utils.py`**: Utility functions (timeout handling, threading)\n\n### Key Classes\n\n- **`PDFAnalyzer`**: Main analysis class that orchestrates the entire process\n- **`PDFTestResult`**: Container for individual PDF test results\n\n## 🔧 Development\n\n### Adding New PDF Libraries\n\n1. Add the library to `requirements.txt` and `pyproject.toml` (or use 'uv add [package]' and 'uv sync')\n2. Implement test functions in `modules/pdf_libraries.py`\n3. Update the analyzer to include the new library\n4. Add corresponding result fields to `PDFTestResult`\n\n### Adding New Features\n\n- **New analysis features**: Modify `modules/analyzer.py`\n- **New data models**: Add classes to `modules/models.py`\n- **New utilities**: Add functions to `modules/utils.py`\n- **New CLI options**: Modify `main.py`\n\n### Testing\n\n```bash\n# Run with test files\nuv run main.py --docs_dir test_files --verbose\n\n# Test specific functionality\nuv run main.py --limit 1 --timeout 10\n```\n\n## 📋 Dependencies\n\n- **pypdf** (≥3.0.0): PDF manipulation library\n- **PyMuPDF** (≥1.23.0): High-performance PDF processing\n- **pdfplumber** (≥0.9.0): PDF text extraction and analysis\n- **tqdm** (≥4.65.0): Progress bars and visual feedback\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## 📄 License\n\nCopyright (C) 2025 Jeff Luster, mailto:jeff.luster96@gmail.com\nLicense: GNU AFFERO GPL 3.0, https://www.gnu.org/licenses/agpl-3.0.html\nThis program is free software: you can redistribute it and/or modify\nit under the terms of the GNU Affero General Public License as published by\nthe Free Software Foundation, either version 3 of the License, or\n(at your option) any later version.\nFull license text can be found in the file \"COPYING.txt\".\nFull copyright text can be found in the file \"main.py\".\n\n## 🆘 Troubleshooting\n\n### Common Issues\n\n**\"No PDF files found to analyze\"**\n- Ensure the `--docs_dir` contains PDF files\n- Check file permissions\n- Verify the directory path is correct\n\n**Timeout errors**\n- Increase the `--timeout` value for large or complex PDFs\n- Check if PDFs are corrupted or password-protected\n\n**Memory issues**\n- Use `--limit` to process files in smaller batches\n- Ensure sufficient system memory for large PDFs\n\n### Getting Help\n\n- Check the log file for detailed error information\n- Use `--verbose` flag for additional debugging output\n- Review the JSON report for specific file issues\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjluster96%2Fpdf-package-analyzer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjluster96%2Fpdf-package-analyzer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjluster96%2Fpdf-package-analyzer/lists"}