pdf-to-pptx-tool

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

pdf-to-pptx-tool

pdf-to-pptx-tool logo

Python Version License: MIT Code style: ruff Type checked: mypy AI Generated Built with Claude Code

A professional CLI tool that converts PDF documents into PowerPoint presentations

Table of Contents

About

pdf-to-pptx-tool is a Python CLI tool built with modern tooling and best practices.

Features

  • 📄 PDF to PowerPoint Conversion: Convert PDF documents to PPTX format
  • 🎨 Customizable Quality: Adjustable DPI (72-600) for quality vs file size
  • 📐 16:9 Slides: Professional widescreen format (10" × 5.625")
  • 🖼️ Full-Page Images: Each PDF page becomes a full-slide image
  • 📊 Multi-level Verbosity: Progressive logging (-v/-vv/-vvv) for debugging
  • 🐚 Shell Completion: Native completion for bash, zsh, and fish
  • ✅ Type-Safe: Strict mypy checking for reliability
  • 🔒 Security Scanned: bandit, pip-audit, and gitleaks
  • ⚡ Modern Tooling: Built with Click, uv, and Python 3.14+

Installation

Prerequisites

  • Python 3.14 or higher
  • uv package manager
  • poppler system library (for PDF rendering)
    # macOS
brew install poppler

# Ubuntu/Debian
sudo apt-get install poppler-utils

# Fedora
sudo dnf install poppler-utils

Install from source

# Clone the repository
git clone https://github.com/dnvriend/pdf-to-pptx-tool.git
cd pdf-to-pptx-tool

# Install globally with uv
uv tool install .

Install with mise (recommended for development)

cd pdf-to-pptx-tool
mise trust
mise install
uv sync
uv tool install .

Verify installation

pdf-to-pptx-tool --version

Usage

Convert PDF to PowerPoint

# Basic conversion (default 200 DPI)
pdf-to-pptx-tool convert document.pdf slides.pptx

# High quality conversion (300 DPI)
pdf-to-pptx-tool convert report.pdf presentation.pptx --dpi 300

# With verbose logging to see progress
pdf-to-pptx-tool -v convert input.pdf output.pptx

# With debug logging for troubleshooting
pdf-to-pptx-tool -vv convert problematic.pdf fixed.pptx

Show Help

# General help
pdf-to-pptx-tool --help

# Convert command help
pdf-to-pptx-tool convert --help

# Completion command help
pdf-to-pptx-tool completion --help

# Show version
pdf-to-pptx-tool --version

Convert Command

The convert command transforms PDF documents into PowerPoint presentations.

Syntax

pdf-to-pptx-tool convert INPUT_PDF OUTPUT_PPTX [OPTIONS]

Arguments

  • INPUT_PDF: Path to the input PDF file (required)
  • OUTPUT_PPTX: Path to the output PowerPoint file (required)
  • --dpi INTEGER: Resolution for conversion (default: 200)
    • Range: 72-600 DPI
    • Higher DPI = better quality but larger files
    • Recommended: 200-300 for most presentations

DPI Quality Guidelines

DPI Quality File Size Best For
72 Low Smallest Quick previews, draft slides
150 Medium Small Web presentations, email
200 Good Medium Default - recommended for most
300 High Large Print quality, detailed diagrams
600 Very High Very Large Professional print, posters

Examples

# Basic conversion with default 200 DPI
pdf-to-pptx-tool convert quarterly-report.pdf q4-presentation.pptx

# High quality for detailed diagrams
pdf-to-pptx-tool convert technical-doc.pdf slides.pptx --dpi 300

# Quick preview with lower quality
pdf-to-pptx-tool convert draft.pdf preview.pptx --dpi 150

# Batch conversion
for pdf in *.pdf; do
  pdf-to-pptx-tool convert "$pdf" "${pdf%.pdf}.pptx"
done

Output Format

  • Aspect Ratio: 16:9 widescreen
  • Slide Size: 10 inches × 5.625 inches
  • Layout: One full-slide image per PDF page
  • Image Format: PNG embedded in slides
  • Compatibility: PowerPoint 2007+ (Windows/Mac/Online)

Multi-Level Verbosity Logging

The CLI supports progressive verbosity levels for debugging and troubleshooting. All logs output to stderr, keeping stdout clean for data piping.

Logging Levels

Flag Level Output Use Case
(none) WARNING Errors and warnings only Production, quiet mode
-v INFO + High-level operations Normal debugging
-vv DEBUG + Detailed info, full tracebacks Development, troubleshooting
-vvv TRACE + Library internals Deep debugging

Examples

# Quiet mode - only errors and warnings
pdf-to-pptx-tool

# INFO - see operations and progress
pdf-to-pptx-tool -v
# Output:
# [INFO] pdf-to-pptx-tool started
# [INFO] pdf-to-pptx-tool completed

# DEBUG - see detailed information
pdf-to-pptx-tool -vv
# Output:
# [INFO] pdf-to-pptx-tool started
# [DEBUG] Running with verbose level: 2
# [INFO] pdf-to-pptx-tool completed

# TRACE - see library internals (configure in logging_config.py)
pdf-to-pptx-tool -vvv

Customizing Library Logging

To enable DEBUG logging for third-party libraries at TRACE level (-vvv), edit pdf_to_pptx_tool/logging_config.py:

# Configure dependent library loggers at TRACE level (-vvv)
if verbose_count >= 3:
    logging.getLogger("requests").setLevel(logging.DEBUG)
    logging.getLogger("urllib3").setLevel(logging.DEBUG)
    # Add your project-specific library loggers here

Shell Completion

The CLI provides native shell completion for bash, zsh, and fish shells.

Supported Shells

Shell Version Requirement Status
Bash ≥ 4.4 ✅ Supported
Zsh Any recent version ✅ Supported
Fish ≥ 3.0 ✅ Supported
PowerShell Any version ❌ Not Supported

Installation

Quick Setup (Temporary)

# Bash - active for current session only
eval "$(pdf-to-pptx-tool completion bash)"

# Zsh - active for current session only
eval "$(pdf-to-pptx-tool completion zsh)"

# Fish - active for current session only
pdf-to-pptx-tool completion fish | source

Permanent Setup (Recommended)

# Bash - add to ~/.bashrc
echo 'eval "$(pdf-to-pptx-tool completion bash)"' >> ~/.bashrc
source ~/.bashrc

# Zsh - add to ~/.zshrc
echo 'eval "$(pdf-to-pptx-tool completion zsh)"' >> ~/.zshrc
source ~/.zshrc

# Fish - save to completions directory
mkdir -p ~/.config/fish/completions
pdf-to-pptx-tool completion fish > ~/.config/fish/completions/pdf-to-pptx-tool.fish

File-based Installation (Better Performance)

For better shell startup performance, generate completion scripts to files:

# Bash
pdf-to-pptx-tool completion bash > ~/.pdf-to-pptx-tool-complete.bash
echo 'source ~/.pdf-to-pptx-tool-complete.bash' >> ~/.bashrc

# Zsh
pdf-to-pptx-tool completion zsh > ~/.pdf-to-pptx-tool-complete.zsh
echo 'source ~/.pdf-to-pptx-tool-complete.zsh' >> ~/.zshrc

# Fish (automatic loading from completions directory)
mkdir -p ~/.config/fish/completions
pdf-to-pptx-tool completion fish > ~/.config/fish/completions/pdf-to-pptx-tool.fish

Usage

Once installed, completion works automatically:

# Tab completion for commands
pdf-to-pptx-tool <TAB>
# Shows: completion

# Tab completion for options
pdf-to-pptx-tool --<TAB>
# Shows: --verbose --version --help

# Tab completion for shell types
pdf-to-pptx-tool completion <TAB>
# Shows: bash zsh fish

Getting Help

# View completion installation instructions
pdf-to-pptx-tool completion --help

Development

Setup Development Environment

# Clone repository
git clone https://github.com/dnvriend/pdf-to-pptx-tool.git
cd pdf-to-pptx-tool

# Install dependencies
make install

# Show available commands
make help

Available Make Commands

make install                 # Install dependencies
make format                  # Format code with ruff
make lint                    # Run linting with ruff
make typecheck               # Run type checking with mypy
make test                    # Run tests with pytest
make security-bandit         # Python security linter
make security-pip-audit      # Dependency vulnerability scanner
make security-gitleaks       # Secret/API key detection
make security                # Run all security checks
make check                   # Run all checks (lint, typecheck, test, security)
make pipeline                # Run full pipeline (format, lint, typecheck, test, security, build, install-global)
make build                   # Build package
make run ARGS="..."          # Run pdf-to-pptx-tool locally
make clean                   # Remove build artifacts

Project Structure

pdf-to-pptx-tool/
├── pdf_to_pptx_tool/    # Main package
│   ├── __init__.py
│   ├── cli.py          # CLI entry point
│   └── utils.py        # Utility functions
├── tests/              # Test suite
│   ├── __init__.py
│   └── test_utils.py
├── pyproject.toml      # Project configuration
├── Makefile            # Development commands
├── README.md           # This file
├── LICENSE             # MIT License
└── CLAUDE.md           # Development documentation

Testing

Run the test suite:

# Run all tests
make test

# Run tests with verbose output
uv run pytest tests/ -v

# Run specific test file
uv run pytest tests/test_utils.py

# Run with coverage
uv run pytest tests/ --cov=pdf_to_pptx_tool

Security

The project includes lightweight security tools providing 80%+ coverage with fast scan times:

Security Tools

Tool Purpose Speed Coverage
bandit Python code security linting ⚡⚡ Fast SQL injection, hardcoded secrets, unsafe functions
pip-audit Dependency vulnerability scanning ⚡⚡ Fast Known CVEs in dependencies
gitleaks Secret and API key detection ⚡⚡⚡ Very Fast Secrets in code and git history

Running Security Scans

# Run all security checks (~5-8 seconds)
make security

# Or run individually
make security-bandit       # Python security linting
make security-pip-audit    # Dependency CVE scanning
make security-gitleaks     # Secret detection

Prerequisites

gitleaks must be installed separately:

# macOS
brew install gitleaks

# Linux
# See: https://github.com/gitleaks/gitleaks#installation

Security checks run automatically in make check and make pipeline.

What's Protected

  • ✅ AWS credentials (AKIA*, ASIA*, etc.)
  • ✅ GitHub tokens (ghp_*, gho_*, etc.)
  • ✅ API keys and secrets
  • ✅ Private keys
  • ✅ Slack tokens
  • ✅ 100+ other secret types

Contributing

Contributions are welcome! Please follow these guidelines:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Run the full pipeline (make pipeline)
  5. Commit your changes (git commit -m 'Add amazing feature')
  6. Push to the branch (git push origin feature/amazing-feature)
  7. Open a Pull Request

Code Style

  • Follow PEP 8 guidelines
  • Use type hints for all functions
  • Write docstrings for public functions
  • Format code with ruff
  • Pass all linting and type checks

License

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

Author

Dennis Vriend

Acknowledgments

  • Built with Click for CLI framework
  • Developed with uv for fast Python tooling

Generated with AI

This project was generated using Claude Code, an AI-powered development tool by Anthropic. Claude Code assisted in creating the project structure, implementation, tests, documentation, and development tooling.

Made with ❤️ using Python 3.14

本页内容由上游仓库自动镜像，如有疑问请访问原始仓库。