📄 PDFusion

A lightweight Python utility for effortlessly merging multiple PDF files into a single document.

📋 Table of Contents

• 📝 Description
  • 🚀 Key Features
• 📂 Repository Structure
• 💻 Installation
  • For Users 🌟
  • For Developers 🔧
• 🎮 Usage
  • Command Line Interface
  • Python API
• 🛠️ Development
  • Running Tests
• 🤝 Contributing
• 👨‍💻 Author
• 📜 License
• 🌟 Star History
• 🙏 Acknowledgments

📝 Description

PDFusion 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.

🚀 Key Features

• 📁 Merge all PDFs in a directory with a single command
• 🔄 Automatic alphabetical ordering of files
• ⏱️ Timestamp-based output naming option
• 🛠️ Both CLI and Python API support
• 💡 Clear progress feedback and error handling
• 🔒 Maintains original PDF quality
• 📝 Detailed logging of the merge process
• 🔍 Type hints with full mypy support
• 🧪 Comprehensive test coverage (>90%)
• 📊 Performance benchmarks included
• 🐛 Custom exception handling
• 🎯 Supports Python 3.11+

📂 Repository Structure

graph TD
    A[pdfusion/] --> B[pdfusion/]
    A --> C[tests/]
    A --> D[examples/]
    A --> E[Documentation]
    
    B --> B1[__init__.py]
    B --> B2[exceptions.py]
    B --> B3[logging.py]
    B --> B4[pdfusion.py]
    B --> B5[py.typed]
    
    C --> C1[__init__.py]
    C --> C2[conftest.py]
    C --> C3[test files]
    
    D --> D1[basic_usage.py]
    
    E --> E1[README.md]
    E --> E2[LICENSE]
    E --> E3[CONTRIBUTING.md]
    E --> E4[Configuration Files]

Loading

💻 Installation

For Users 🌟

pip install pdfusion

For Developers 🔧

graph LR
    A[Clone Repository] --> B[Create Virtual Environment]
    B --> C[Activate Environment]
    C --> D[Install Dependencies]
    D --> E[Ready to Develop!]

Loading

1. Clone the repository:

   git clone https://github.com/BjornMelin/pdfusion.git
   cd pdfusion

2. Create a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: .\venv\Scripts\activate

   Note: You can also use virtualenv instead of venv. See the Virtual Environment Setup Guide for more details.

3. Install development dependencies:

   pip install -r requirements-dev.txt

🎮 Usage

Quick Start Guide

1. Install PDFusion

   pip install pdfusion

2. Prepare Your PDFs

   • Create a directory with your PDF files

   • Example structure:

     my_pdfs/
     ├── document1.pdf
     ├── document2.pdf
     └── document3.pdf
     

3. Run PDFusion

Command Line Interface

graph LR
    A[Input Directory] --> B[PDFusion CLI]
    B --> C[Processing]
    C --> D[Merged PDF]
    style B fill:#f9f,stroke:#333,stroke-width:4px

Loading

# Basic usage
pdfusion /path/to/pdfs -o merged.pdf

# With verbose output
pdfusion /path/to/pdfs -v

# Auto timestamp filename
pdfusion /path/to/pdfs

CLI Options

• -o, --output: Output filename (optional)
• -v, --verbose: Enable verbose output
• --version: Show version number
• -h, --help: Show help message

Python API

from pdfusion import merge_pdfs

# Example 1: Basic usage
result = merge_pdfs(
    input_dir="/path/to/pdfs",
    output_file="merged.pdf"
)
print(f"Merged {result.files_merged} files into {result.output_path}")

# Example 2: With verbose output and auto timestamp
result = merge_pdfs(
    input_dir="/path/to/pdfs",
    verbose=True
)
print(f"Total pages in merged PDF: {result.total_pages}")

# Example 3: Full options
result = merge_pdfs(
    input_dir="/path/to/pdfs",
    output_file="merged.pdf",
    verbose=True,
    sort_files=True,  # Sort files alphabetically
    add_bookmarks=True  # Add bookmarks for each merged PDF
)

Example Project Structure

Create a simple script merge_my_pdfs.py:

from pdfusion import merge_pdfs
import logging

# Set up logging (optional)
logging.basicConfig(level=logging.INFO)

# Merge PDFs
try:
    result = merge_pdfs(
        input_dir="./my_pdfs",
        output_file="merged_document.pdf",
        verbose=True
    )
    print(f"Successfully merged {result.files_merged} files!")
    print(f"Output saved to: {result.output_path}")
    print(f"Total pages: {result.total_pages}")

except Exception as e:
    print(f"Error merging PDFs: {e}")

Run your script:

python merge_my_pdfs.py

Output Format

The merge_pdfs function returns a result object with the following attributes:

• files_merged: Number of files merged
• output_path: Path to the merged PDF
• total_pages: Total number of pages in the merged PDF
• processing_time: Time taken to merge the PDFs

🛠️ Development

Running Tests

# Run all tests
pytest

# Run with coverage report
pytest --cov=pdfusion

# Run performance benchmarks
pytest tests/test_pdfusion.py -v -m benchmark

# Run specific test file
pytest tests/test_pdfusion.py -v

🤝 Contributing

graph LR
    A[Fork Repository] --> B[Create Feature Branch]
    B --> C[Make Changes]
    C --> D[Commit Changes]
    D --> E[Push to Branch]
    E --> F[Open Pull Request]
    style F fill:#f96,stroke:#333,stroke-width:4px

Loading

1. Fork the repository
2. Create your feature branch (git checkout -b feat/version/AmazingFeature)
3. Commit your changes (git commit -m 'type(scope): Add some AmazingFeature')
4. Push to the branch (git push origin feat/version/AmazingFeature)
5. Open a Pull Request (feat(scope): Add some AmazingFeature)

👨‍💻 Author

Bjorn Melin

AWS-certified Solutions Architect and Developer with expertise in cloud architecture and modern development practices. Connect with me on:

• 🌐 GitHub
• 💼 LinkedIn

Project Link: https://github.com/BjornMelin/pdfusion

📜 License

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

🌟 Star History

🙏 Acknowledgments

• 🐍 Python
• 📄 pypdf2
• 🏷️ GitHub Badges

⚡ Built with Python 3.11 + pypdf2 by Bjorn Melin