{"id":22436547,"url":"https://github.com/bjornmelin/pdfusion","last_synced_at":"2025-03-27T08:42:55.567Z","repository":{"id":264370701,"uuid":"893168243","full_name":"BjornMelin/pdfusion","owner":"BjornMelin","description":"A lightweight Python utility for effortlessly merging multiple PDF files into a single document.","archived":false,"fork":false,"pushed_at":"2024-11-24T00:40:22.000Z","size":41,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-01T13:42:27.493Z","etag":null,"topics":["automation","batch-processing","cli","command-line-tool","document-management","document-processing","file-management","pdf","pdf-manipulation","pdf-merger","pdf-tools","pypdf2","python","python-library","utilities"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BjornMelin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2024-11-23T18:00:03.000Z","updated_at":"2024-11-27T23:19:41.000Z","dependencies_parsed_at":"2024-11-23T19:38:17.630Z","dependency_job_id":null,"html_url":"https://github.com/BjornMelin/pdfusion","commit_stats":null,"previous_names":["bjornmelin/pdfusion"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BjornMelin%2Fpdfusion","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BjornMelin%2Fpdfusion/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BjornMelin%2Fpdfusion/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BjornMelin%2Fpdfusion/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BjornMelin","download_url":"https://codeload.github.com/BjornMelin/pdfusion/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245813169,"owners_count":20676763,"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","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":["automation","batch-processing","cli","command-line-tool","document-management","document-processing","file-management","pdf","pdf-manipulation","pdf-merger","pdf-tools","pypdf2","python","python-library","utilities"],"created_at":"2024-12-06T00:08:14.633Z","updated_at":"2025-03-27T08:42:55.546Z","avatar_url":"https://github.com/BjornMelin.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 📄 PDFusion\n\nA lightweight Python utility for effortlessly merging multiple PDF files into a single document.\n\n[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://choosealicense.com/licenses/mit/)\n[![Python 3.11](https://img.shields.io/badge/python-3.11-blue.svg)](https://www.python.org/downloads/release/python-3110/)\n[![Contributions Welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](CONTRIBUTING.md)\n[![GitHub](https://img.shields.io/badge/GitHub-BjornMelin-181717?logo=github)](https://github.com/BjornMelin)\n[![LinkedIn](https://img.shields.io/badge/LinkedIn-Bjorn%20Melin-0077B5?logo=linkedin)](https://www.linkedin.com/in/bjorn-melin/)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n\n## 📋 Table of Contents\n\n- [📝 Description](#-description)\n  - [🚀 Key Features](#-key-features)\n- [📂 Repository Structure](#-repository-structure)\n- [💻 Installation](#-installation)\n  - [For Users 🌟](#for-users-)\n  - [For Developers 🔧](#for-developers-)\n- [🎮 Usage](#-usage)\n  - [Command Line Interface](#command-line-interface)\n  - [Python API](#python-api)\n- [🛠️ Development](#️-development)\n  - [Running Tests](#running-tests)\n- [🤝 Contributing](#-contributing)\n- [👨‍💻 Author](#-author)\n- [📜 License](#-license)\n- [🌟 Star History](#-star-history)\n- [🙏 Acknowledgments](#-acknowledgments)\n\n## 📝 Description\n\nPDFusion is a simple yet powerful command-line tool that makes it easy to combine multiple PDF files into a single document while preserving the original quality. Perfect for combining reports, consolidating documentation, or organizing digital paperwork.\n\n### 🚀 Key Features\n\n- 📁 Merge all PDFs in a directory with a single command\n- 🔄 Automatic alphabetical ordering of files\n- ⏱️ Timestamp-based output naming option\n- 🛠️ Both CLI and Python API support\n- 💡 Clear progress feedback and error handling\n- 🔒 Maintains original PDF quality\n- 📝 Detailed logging of the merge process\n- 🔍 Type hints with full mypy support\n- 🧪 Comprehensive test coverage (\u003e90%)\n- 📊 Performance benchmarks included\n- 🐛 Custom exception handling\n- 🎯 Supports Python 3.11+\n\n## 📂 Repository Structure\n\n```mermaid\ngraph TD\n    A[pdfusion/] --\u003e B[pdfusion/]\n    A --\u003e C[tests/]\n    A --\u003e D[examples/]\n    A --\u003e E[Documentation]\n    \n    B --\u003e B1[__init__.py]\n    B --\u003e B2[exceptions.py]\n    B --\u003e B3[logging.py]\n    B --\u003e B4[pdfusion.py]\n    B --\u003e B5[py.typed]\n    \n    C --\u003e C1[__init__.py]\n    C --\u003e C2[conftest.py]\n    C --\u003e C3[test files]\n    \n    D --\u003e D1[basic_usage.py]\n    \n    E --\u003e E1[README.md]\n    E --\u003e E2[LICENSE]\n    E --\u003e E3[CONTRIBUTING.md]\n    E --\u003e E4[Configuration Files]\n```\n\n## 💻 Installation\n\n### For Users 🌟\n\n```bash\npip install pdfusion\n```\n\n### For Developers 🔧\n\n```mermaid\ngraph LR\n    A[Clone Repository] --\u003e B[Create Virtual Environment]\n    B --\u003e C[Activate Environment]\n    C --\u003e D[Install Dependencies]\n    D --\u003e E[Ready to Develop!]\n```\n\n1. Clone the repository:\n\n    ```bash\n    git clone https://github.com/BjornMelin/pdfusion.git\n    cd pdfusion\n    ```\n\n2. Create a virtual environment:\n\n    ```bash\n    python -m venv venv\n    source venv/bin/activate  # On Windows: .\\venv\\Scripts\\activate\n    ```\n\n    \u003e **Note:** You can also use `virtualenv` instead of `venv`. See the [Virtual Environment Setup Guide](docs/virtualenv-setup.md) for more details.\n\n3. Install development dependencies:\n\n    ```bash\n    pip install -r requirements-dev.txt\n    ```\n\n## 🎮 Usage\n\n### Quick Start Guide\n\n1. **Install PDFusion**\n\n   ```bash\n   pip install pdfusion\n   ```\n\n2. **Prepare Your PDFs**\n   - Create a directory with your PDF files\n   - Example structure:\n\n     ```plaintext\n     my_pdfs/\n     ├── document1.pdf\n     ├── document2.pdf\n     └── document3.pdf\n     ```\n\n3. **Run PDFusion**\n\n### Command Line Interface\n\n```mermaid\ngraph LR\n    A[Input Directory] --\u003e B[PDFusion CLI]\n    B --\u003e C[Processing]\n    C --\u003e D[Merged PDF]\n    style B fill:#f9f,stroke:#333,stroke-width:4px\n```\n\n```bash\n# Basic usage\npdfusion /path/to/pdfs -o merged.pdf\n\n# With verbose output\npdfusion /path/to/pdfs -v\n\n# Auto timestamp filename\npdfusion /path/to/pdfs\n```\n\n#### CLI Options\n\n- `-o, --output`: Output filename (optional)\n- `-v, --verbose`: Enable verbose output\n- `--version`: Show version number\n- `-h, --help`: Show help message\n\n### Python API\n\n```python\nfrom pdfusion import merge_pdfs\n\n# Example 1: Basic usage\nresult = merge_pdfs(\n    input_dir=\"/path/to/pdfs\",\n    output_file=\"merged.pdf\"\n)\nprint(f\"Merged {result.files_merged} files into {result.output_path}\")\n\n# Example 2: With verbose output and auto timestamp\nresult = merge_pdfs(\n    input_dir=\"/path/to/pdfs\",\n    verbose=True\n)\nprint(f\"Total pages in merged PDF: {result.total_pages}\")\n\n# Example 3: Full options\nresult = merge_pdfs(\n    input_dir=\"/path/to/pdfs\",\n    output_file=\"merged.pdf\",\n    verbose=True,\n    sort_files=True,  # Sort files alphabetically\n    add_bookmarks=True  # Add bookmarks for each merged PDF\n)\n```\n\n### Example Project Structure\n\nCreate a simple script `merge_my_pdfs.py`:\n\n```python\nfrom pdfusion import merge_pdfs\nimport logging\n\n# Set up logging (optional)\nlogging.basicConfig(level=logging.INFO)\n\n# Merge PDFs\ntry:\n    result = merge_pdfs(\n        input_dir=\"./my_pdfs\",\n        output_file=\"merged_document.pdf\",\n        verbose=True\n    )\n    print(f\"Successfully merged {result.files_merged} files!\")\n    print(f\"Output saved to: {result.output_path}\")\n    print(f\"Total pages: {result.total_pages}\")\n\nexcept Exception as e:\n    print(f\"Error merging PDFs: {e}\")\n```\n\nRun your script:\n\n```bash\npython merge_my_pdfs.py\n```\n\n### Output Format\n\nThe `merge_pdfs` function returns a result object with the following attributes:\n\n- `files_merged`: Number of files merged\n- `output_path`: Path to the merged PDF\n- `total_pages`: Total number of pages in the merged PDF\n- `processing_time`: Time taken to merge the PDFs\n\n## 🛠️ Development\n\n### Running Tests\n\n```bash\n# Run all tests\npytest\n\n# Run with coverage report\npytest --cov=pdfusion\n\n# Run performance benchmarks\npytest tests/test_pdfusion.py -v -m benchmark\n\n# Run specific test file\npytest tests/test_pdfusion.py -v\n```\n\n## 🤝 Contributing\n\n```mermaid\ngraph LR\n    A[Fork Repository] --\u003e B[Create Feature Branch]\n    B --\u003e C[Make Changes]\n    C --\u003e D[Commit Changes]\n    D --\u003e E[Push to Branch]\n    E --\u003e F[Open Pull Request]\n    style F fill:#f96,stroke:#333,stroke-width:4px\n```\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feat/version/AmazingFeature`)\n3. Commit your changes (`git commit -m 'type(scope): Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feat/version/AmazingFeature`)\n5. Open a Pull Request (`feat(scope): Add some AmazingFeature`)\n\n## 👨‍💻 Author\n\n### Bjorn Melin\n\n[![AWS Certified Solutions Architect](https://images.credly.com/size/110x110/images/0e284c3f-5164-4b21-8660-0d84737941bc/image.png)](https://www.credly.com/org/amazon-web-services/badge/aws-certified-solutions-architect-associate)\n[![AWS Certified Developer](https://images.credly.com/size/110x110/images/b9feab85-1a43-4f6c-99a5-631b88d5461b/image.png)](https://www.credly.com/org/amazon-web-services/badge/aws-certified-developer-associate)\n[![AWS Certified AI Practitioner](https://images.credly.com/size/110x110/images/4d4693bb-530e-4bca-9327-de07f3aa2348/image.png)](https://www.credly.com/org/amazon-web-services/badge/aws-certified-ai-practitioner)\n[![AWS Certified Cloud Practitioner](https://images.credly.com/size/110x110/images/00634f82-b07f-4bbd-a6bb-53de397fc3a6/image.png)](https://www.credly.com/org/amazon-web-services/badge/aws-certified-cloud-practitioner)\n\nAWS-certified Solutions Architect and Developer with expertise in cloud architecture and modern development practices. Connect with me on:\n\n- 🌐 [GitHub](https://github.com/BjornMelin)\n- 💼 [LinkedIn](https://www.linkedin.com/in/bjorn-melin/)\n\nProject Link: [https://github.com/BjornMelin/pdfusion](https://github.com/BjornMelin/pdfusion)\n\n## 📜 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🌟 Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=bjornmelin/pdfusion\u0026type=Date)](https://star-history.com/#bjornmelin/pdfusion\u0026Date)\n\n## 🙏 Acknowledgments\n\n- 🐍 [Python](https://www.python.org/)\n- 📄 [pypdf2](https://pypdf.readthedocs.io/en/stable/)\n- 🏷️ [GitHub Badges](https://shields.io/)\n\n\u003cdiv align=\"center\"\u003e\n    \u003ch3\u003e⚡ Built with Python 3.11 + pypdf2 by Bjorn Melin\u003c/h3\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbjornmelin%2Fpdfusion","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbjornmelin%2Fpdfusion","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbjornmelin%2Fpdfusion/lists"}