pdf-section-binding 1.0.0__py3-none-any.whl

pdf_section_binding/__init__.py

@@ -0,0 +1,15 @@
+"""PDF Section Binding - A CLI tool for reordering PDF pages for bookbinding."""
+
+from .version import __version__, __author__, __email__, __description__
+from .core import calculate_signature_order, SectionBindingProcessor
+from .cli import main
+
+__all__ = [
+    "__version__",
+    "__author__",
+    "__email__",
+    "__description__",
+    "calculate_signature_order",
+    "SectionBindingProcessor",
+    "main",
+]

pdf_section_binding/cli.py

@@ -0,0 +1,380 @@
+"""Enhanced CLI interface for PDF section binding."""
+
+import argparse
+import os
+import sys
+import traceback
+from pathlib import Path
+from typing import Optional
+
+from .core import SectionBindingProcessor, print_binding_instructions
+from .version import __version__, __description__
+
+
+# ANSI color codes for better CLI experience
+class Colors:
+    """ANSI color codes for terminal output."""
+
+    RESET = "\033[0m"
+    BOLD = "\033[1m"
+    DIM = "\033[2m"
+    RED = "\033[91m"
+    GREEN = "\033[92m"
+    YELLOW = "\033[93m"
+    BLUE = "\033[94m"
+    MAGENTA = "\033[95m"
+    CYAN = "\033[96m"
+    WHITE = "\033[97m"
+
+    @classmethod
+    def colorize(cls, text: str, color: str) -> str:
+        """Colorize text if terminal supports it."""
+        if os.getenv("NO_COLOR") or not sys.stdout.isatty():
+            return text
+        return f"{color}{text}{cls.RESET}"
+
+    @classmethod
+    def success(cls, text: str) -> str:
+        """Green success text."""
+        return cls.colorize(text, cls.GREEN)
+
+    @classmethod
+    def error(cls, text: str) -> str:
+        """Red error text."""
+        return cls.colorize(text, cls.RED)
+
+    @classmethod
+    def warning(cls, text: str) -> str:
+        """Yellow warning text."""
+        return cls.colorize(text, cls.YELLOW)
+
+    @classmethod
+    def info(cls, text: str) -> str:
+        """Blue info text."""
+        return cls.colorize(text, cls.BLUE)
+
+    @classmethod
+    def highlight(cls, text: str) -> str:
+        """Cyan highlighted text."""
+        return cls.colorize(text, cls.CYAN)
+
+
+def format_file_size(size_bytes: int) -> str:
+    """Format file size in human readable format."""
+    for unit in ["B", "KB", "MB", "GB"]:
+        if size_bytes < 1024.0:
+            return f"{size_bytes:.1f} {unit}"
+        size_bytes /= 1024.0
+    return f"{size_bytes:.1f} TB"
+
+
+def suggest_signature_sizes(current: int) -> str:
+    """Suggest alternative signature sizes."""
+    if current % 4 != 0:
+        suggested_lower = (current // 4) * 4
+        suggested_higher = ((current // 4) + 1) * 4
+        return f"Try: {suggested_lower} or {suggested_higher}"
+
+    common_sizes = [4, 8, 12, 16, 20, 24, 28, 32, 40, 48, 56, 64]
+    nearby = [s for s in common_sizes if abs(s - current) <= 8 and s != current]
+    if nearby:
+        return f"Common alternatives: {', '.join(map(str, nearby[:3]))}"
+    return "Common sizes: 4, 8, 16, 32, 40"
+
+
+def validate_pdf_file(filepath: str) -> Optional[str]:
+    """Validate PDF file and return error message if invalid."""
+    if not os.path.exists(filepath):
+        return f"File not found: {filepath}"
+
+    if not os.path.isfile(filepath):
+        return f"Path is not a file: {filepath}"
+
+    if not os.access(filepath, os.R_OK):
+        return f"File is not readable: {filepath}"
+
+    # Check file size
+    size = os.path.getsize(filepath)
+    if size == 0:
+        return f"File is empty: {filepath}"
+
+    if size > 500 * 1024 * 1024:  # 500MB
+        return f"File is very large ({format_file_size(size)}). Processing may be slow."
+
+    # Basic PDF validation
+    try:
+        with open(filepath, "rb") as f:
+            header = f.read(4)
+            if header != b"%PDF":
+                return f"File does not appear to be a valid PDF: {filepath}"
+    except (OSError, IOError) as e:
+        return f"Error reading file: {e}"
+
+    return None
+
+
+def create_parser() -> argparse.ArgumentParser:
+    """Create and configure the argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="pdf-section-binding",
+        description=__description__,
+        epilog="""
+Examples:
+  %(prog)s book.pdf                    # Basic usage (8-page signatures)
+  %(prog)s book.pdf -s 40              # 10 papers per signature
+  %(prog)s book.pdf -o output.pdf      # Specify output file
+  %(prog)s book.pdf --dry-run          # Preview without creating file
+  %(prog)s book.pdf -v                 # Verbose output
+        """,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+    # Positional arguments
+    parser.add_argument("input", help="Input PDF file path")
+
+    # Optional arguments
+    parser.add_argument(
+        "-o",
+        "--output",
+        help="Output PDF file path (default: input_name_section_bound.pdf)",
+    )
+
+    parser.add_argument(
+        "-s",
+        "--signature-size",
+        type=int,
+        default=8,
+        metavar="PAGES",
+        help="Pages per signature (must be multiple of 4, default: 8). "
+        "Common: 4, 8, 16, 32, 40. Formula: papers = pages ÷ 4",
+    )
+
+    # Behavior flags
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be done without creating output file",
+    )
+
+    parser.add_argument(
+        "-v", "--verbose", action="store_true", help="Enable verbose output"
+    )
+
+    parser.add_argument(
+        "-q", "--quiet", action="store_true", help="Suppress all output except errors"
+    )
+
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {__version__}"
+    )
+
+    # Advanced options
+    parser.add_argument(
+        "--force", action="store_true", help="Overwrite output file if it exists"
+    )
+
+    return parser
+
+
+def validate_arguments(args: argparse.Namespace) -> None:
+    """Validate command line arguments.
+
+    Args:
+        args: Parsed command line arguments
+
+    Raises:
+        SystemExit: If validation fails
+    """
+    # Enhanced PDF file validation
+    pdf_error = validate_pdf_file(args.input)
+    if pdf_error:
+        if "very large" in pdf_error:
+            print(Colors.warning(f"Warning: {pdf_error}"), file=sys.stderr)
+        else:
+            print(Colors.error(f"Error: {pdf_error}"), file=sys.stderr)
+            sys.exit(1)
+
+    # Enhanced signature size validation
+    if args.signature_size % 4 != 0:
+        suggestions = suggest_signature_sizes(args.signature_size)
+        print(
+            Colors.error(
+                "Error: Signature size must be a multiple of 4 (each paper = 4 pages)."
+            ),
+            file=sys.stderr,
+        )
+        print(
+            Colors.info(f"You specified {args.signature_size}. {suggestions}"),
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    if args.signature_size < 4:
+        print(
+            Colors.error("Error: Signature size must be at least 4 pages (1 paper)."),
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    if args.signature_size > 128:
+        print(
+            Colors.error(
+                f"Error: Signature size too large ({args.signature_size}). "
+                "Maximum recommended: 128 pages (32 papers)."
+            ),
+            file=sys.stderr,
+        )
+        print(
+            Colors.info(
+                "Large signature sizes make folding difficult and may not bind well."
+            ),
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    # Generate output filename if not provided
+    if not args.output:
+        input_path = Path(args.input)
+        args.output = str(input_path.with_stem(f"{input_path.stem}_section_bound"))
+
+    # Validate output path
+    if not args.dry_run:
+        output_path = Path(args.output)
+
+        # Check if output file exists and --force not specified
+        if output_path.exists() and not args.force:
+            print(
+                f"Error: Output file '{args.output}' already exists. "
+                "Use --force to overwrite.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+        # Check if output directory is writable
+        output_dir = output_path.parent
+        if not output_dir.exists():
+            try:
+                output_dir.mkdir(parents=True)
+            except PermissionError:
+                print(
+                    f"Error: Cannot create output directory '{output_dir}'.",
+                    file=sys.stderr,
+                )
+                sys.exit(1)
+
+        if not os.access(output_dir, os.W_OK):
+            print(
+                f"Error: No write permission for output directory '{output_dir}'.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+    # Validate conflicting options
+    if args.quiet and args.verbose:
+        print("Error: Cannot use both --quiet and --verbose options.", file=sys.stderr)
+        sys.exit(1)
+
+
+def main() -> int:
+    """Main CLI entry point.
+
+    Returns:
+        Exit code (0 for success, non-zero for error)
+    """
+    try:
+        # Parse arguments
+        parser = create_parser()
+        args = parser.parse_args()
+
+        # Validate arguments
+        validate_arguments(args)
+
+        # Configure output verbosity
+        verbose = args.verbose and not args.quiet
+        quiet = args.quiet
+
+        if not quiet:
+            print(Colors.highlight(f"PDF Section Binding Tool v{__version__}"))
+            print("=" * 50)
+
+        # Create processor
+        processor = SectionBindingProcessor(verbose=verbose)
+
+        # Process the PDF
+        result = processor.process_pdf(
+            input_path=args.input,
+            output_path=args.output,
+            signature_size=args.signature_size,
+            dry_run=args.dry_run,
+        )
+
+        # Print results and instructions
+        if not quiet:
+            if args.dry_run:
+                print(f"\n{Colors.info('🔍 DRY RUN ANALYSIS:')}")
+                print(
+                    f"Would process "
+                    f"{Colors.highlight(str(result['total_pages']))} pages"
+                )
+                print(
+                    f"Would create "
+                    f"{Colors.highlight(str(result['total_signatures']))} "
+                    "signatures"
+                )
+                print(
+                    f"Would need "
+                    f"{Colors.highlight(str(result['total_papers']))} "
+                    "papers total"
+                )
+                print(f"Would save to: {Colors.highlight(result['output_path'])}")
+            else:
+                print(
+                    f"\n{Colors.success('✅ Successfully created:')} "
+                    f"{Colors.highlight(result['output_path'])}"
+                )
+                print(
+                    f"{Colors.info('📊 Processed')} "
+                    f"{Colors.highlight(str(result['total_pages']))} pages into "
+                    f"{Colors.highlight(str(result['output_pages']))} "
+                    "reordered pages"
+                )
+
+        # Print binding instructions
+        print_binding_instructions(result, quiet=quiet)
+
+        return 0
+
+    except KeyboardInterrupt:
+        if not (locals().get("args") and args.quiet):
+            print(
+                f"\n{Colors.error('❌ Operation cancelled by user.')}", file=sys.stderr
+            )
+        return 130  # Standard exit code for SIGINT
+
+    except FileNotFoundError as e:
+        print(Colors.error(f"❌ File error: {e}"), file=sys.stderr)
+        return 2
+
+    except PermissionError as e:
+        print(Colors.error(f"❌ Permission error: {e}"), file=sys.stderr)
+        return 13
+
+    except ValueError as e:
+        print(Colors.error(f"❌ Invalid input: {e}"), file=sys.stderr)
+        return 22
+
+    except RuntimeError as e:
+        print(Colors.error(f"❌ Runtime error: {e}"), file=sys.stderr)
+        if locals().get("args") and args.verbose:
+            traceback.print_exc()
+        return 1
+
+    except (OSError, IOError) as e:
+        print(Colors.error(f"❌ System error: {e}"), file=sys.stderr)
+        if locals().get("args") and args.verbose:
+            traceback.print_exc()
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pdf_section_binding/core.py

@@ -0,0 +1,252 @@
+"""Core functionality for PDF section binding."""
+
+from typing import List
+from PyPDF2 import PdfReader, PdfWriter
+
+
+def create_progress_bar(current: int, total: int, width: int = 50) -> str:
+    """Create a simple progress bar string."""
+    if total == 0:
+        return "[" + "=" * width + "]"
+
+    progress = current / total
+    filled = int(width * progress)
+    progress_bar = "=" * filled + "-" * (width - filled)
+    percentage = int(progress * 100)
+    return f"[{progress_bar}] {percentage:3d}% ({current}/{total})"
+
+
+def show_progress(current: int, total: int, prefix: str = "Progress") -> None:
+    """Show progress bar for terminal output."""
+    if total < 50:  # Don't show progress for small files
+        return
+
+    if current % max(1, total // 20) == 0 or current == total:  # Update every 5%
+        progress_bar = create_progress_bar(current, total)
+        print(f"\r{prefix}: {progress_bar}", end="", flush=True)
+        if current == total:
+            print()  # New line when complete
+
+
+def calculate_signature_order(total_pages: int, signature_size: int) -> List[int]:
+    """
+    Calculate the page order for section binding.
+
+    For section binding, pages are arranged so that when printed double-sided
+    and folded, they appear in correct reading order.
+
+    Args:
+        total_pages: Total number of pages in the PDF
+        signature_size: Number of pages per signature (must be multiple of 4)
+
+    Returns:
+        Ordered list of page numbers for section binding
+
+    Raises:
+        ValueError: If signature_size is not a multiple of 4 or is invalid
+    """
+    if signature_size % 4 != 0:
+        raise ValueError(
+            f"Signature size must be a multiple of 4, got {signature_size}"
+        )
+
+    if signature_size < 4:
+        raise ValueError(f"Signature size must be at least 4, got {signature_size}")
+
+    # Pad pages to make them divisible by signature size
+    padded_pages = (
+        (total_pages + signature_size - 1) // signature_size
+    ) * signature_size
+
+    # Create list of pages (1-indexed)
+    pages = list(range(1, total_pages + 1))
+
+    # Add blank pages if needed
+    while len(pages) < padded_pages:
+        pages.append(None)  # None represents blank pages
+
+    # Calculate signature order
+    reordered_pages = []
+
+    # Process each signature
+    for signature_start in range(0, padded_pages, signature_size):
+        # Calculate the correct order for this signature
+        signature_order = []
+
+        for i in range(signature_size // 2):
+            left_page = signature_start + i
+            right_page = signature_start + signature_size - 1 - i
+
+            # Add the pages for this sheet
+            if right_page < len(pages):
+                signature_order.append(pages[right_page])
+            if left_page < len(pages):
+                signature_order.append(pages[left_page])
+
+        reordered_pages.extend(signature_order)
+
+    return [p for p in reordered_pages if p is not None]
+
+
+class SectionBindingProcessor:
+    """Main processor for PDF section binding operations."""
+
+    def __init__(self, verbose: bool = False):
+        """Initialize processor.
+
+        Args:
+            verbose: Whether to output verbose information
+        """
+        self.verbose = verbose
+
+    def log(self, message: str) -> None:
+        """Log a message if verbose mode is enabled."""
+        if self.verbose:
+            print(f"[INFO] {message}")
+
+    def process_pdf(
+        self,
+        input_path: str,
+        output_path: str,
+        signature_size: int = 8,
+        dry_run: bool = False,
+    ) -> dict:
+        """
+        Process a PDF for section binding.
+
+        Args:
+            input_path: Path to input PDF
+            output_path: Path to output PDF
+            signature_size: Pages per signature (default: 8)
+            dry_run: If True, don't create output file, just analyze
+
+        Returns:
+            Dictionary with processing information
+
+        Raises:
+            FileNotFoundError: If input file doesn't exist
+            PermissionError: If unable to read input or write output
+            ValueError: If signature size is invalid
+        """
+        try:
+            # Read the input PDF
+            self.log(f"Reading PDF: {input_path}")
+            reader = PdfReader(input_path)
+            total_pages = len(reader.pages)
+
+            self.log(f"Total pages: {total_pages}")
+            self.log(f"Signature size: {signature_size}")
+
+            # Calculate page order
+            page_order = calculate_signature_order(total_pages, signature_size)
+
+            # Calculate statistics
+            papers_per_signature = signature_size // 4
+            total_signatures = (total_pages + signature_size - 1) // signature_size
+            total_papers = total_signatures * papers_per_signature
+
+            result = {
+                "input_path": input_path,
+                "output_path": output_path,
+                "total_pages": total_pages,
+                "signature_size": signature_size,
+                "papers_per_signature": papers_per_signature,
+                "total_signatures": total_signatures,
+                "total_papers": total_papers,
+                "page_order": page_order,
+                "dry_run": dry_run,
+            }
+
+            if dry_run:
+                self.log("Dry run mode - not creating output file")
+                return result
+
+            # Create output PDF
+            self.log("Creating reordered PDF...")
+            writer = PdfWriter()
+
+            # Add pages in the calculated order
+            for i, page_num in enumerate(page_order):
+                # Show progress for large documents
+                if not dry_run and self.verbose and total_pages > 50:
+                    show_progress(i + 1, len(page_order), "Creating PDF")
+                elif not dry_run and i % 100 == 0 and total_pages > 200:
+                    # Show minimal progress for very large files even without verbose
+                    self.log(f"Processing page {i+1}/{len(page_order)}...")
+
+                if page_num and page_num <= total_pages:
+                    writer.add_page(reader.pages[page_num - 1])  # Convert to 0-indexed
+
+            # Write the output PDF
+            self.log(f"Writing output: {output_path}")
+            with open(output_path, "wb") as output_file:
+                writer.write(output_file)
+
+            result["output_pages"] = len(writer.pages)
+            self.log(
+                f"Successfully created {output_path} with {len(writer.pages)} pages"
+            )
+
+            return result
+
+        except FileNotFoundError as e:
+            raise FileNotFoundError(f"Input file not found: {input_path}") from e
+        except PermissionError as e:
+            raise PermissionError(f"Permission error: {e}") from e
+        except Exception as e:
+            raise RuntimeError(f"Unexpected error processing PDF: {e}") from e
+
+
+def print_binding_instructions(result: dict, quiet: bool = False) -> None:
+    """Print binding instructions based on processing result."""
+    if quiet:
+        return
+
+    # Import Colors here to avoid circular imports
+    try:
+        from .cli import Colors
+    except ImportError:
+        # Fallback if Colors not available
+        class Colors:
+            """Fallback color class when CLI colors are not available."""
+
+            @staticmethod
+            def highlight(text):
+                """Return text without highlighting."""
+                return text
+
+            @staticmethod
+            def info(text):
+                """Return text without info formatting."""
+                return text
+
+            @staticmethod
+            def success(text):
+                """Return text without success formatting."""
+                return text
+
+    print("\n" + "=" * 60)
+    print(Colors.highlight("SECTION BINDING INSTRUCTIONS"))
+    print("=" * 60)
+    print(f"📄 Input: {Colors.info(result['input_path'])}")
+    print(f"📋 Total pages: {Colors.highlight(str(result['total_pages']))}")
+    print(
+        f"📐 Signature size: {Colors.highlight(str(result['signature_size']))}" " pages"
+    )
+    print(
+        f"📎 Papers per signature: "
+        f"{Colors.highlight(str(result['papers_per_signature']))}"
+    )
+    print(f"📚 Total signatures: {Colors.highlight(str(result['total_signatures']))}")
+    print(f"🗞️  Total papers needed: {Colors.highlight(str(result['total_papers']))}")
+
+    if not result["dry_run"]:
+        print(f"💾 Output: {Colors.success(result['output_path'])}")
+
+    print(f"\n{Colors.info('📋 PRINTING & BINDING STEPS:')}")
+    print("1. Print the output PDF double-sided (flip on long edge)")
+    print(f"2. Each {result['papers_per_signature']} papers forms one signature")
+    print("3. Fold each signature in half along the center")
+    print("4. Stack all signatures in order")
+    print("5. Bind along the folded edge (staple, glue, or spiral bind)")
+    print("=" * 60)

pdf_section_binding/version.py

@@ -0,0 +1,8 @@
+"""Version information for pdf-section-binding."""
+
+__version__ = "1.0.0"
+__author__ = "Sravan Kumar Rekandar"
+__email__ = "sravankumarrekandar@example.com"
+__description__ = (
+    "A CLI tool for reordering PDF pages for section binding (bookbinding)"
+)

pdf_section_binding-1.0.0.dist-info/METADATA

@@ -0,0 +1,324 @@
+Metadata-Version: 2.4
+Name: pdf-section-binding
+Version: 1.0.0
+Summary: A CLI tool for reordering PDF pages for section binding (bookbinding)
+Home-page: https://github.com/sravankumarrekandar/pdf-section-binding
+Author: Sravan Kumar Rekandar
+Author-email: Sravan Kumar Rekandar <sravankumarrekandar@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/yourusername/pdf-section-binding
+Project-URL: Bug Reports, https://github.com/yourusername/pdf-section-binding/issues
+Project-URL: Source, https://github.com/yourusername/pdf-section-binding
+Project-URL: Documentation, https://github.com/yourusername/pdf-section-binding#readme
+Keywords: pdf,bookbinding,section-binding,printing,cli,page-reordering,signatures,folding
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
+Classifier: Topic :: Printing
+Classifier: Topic :: Utilities
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyPDF2>=3.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=22.0.0; extra == "dev"
+Requires-Dist: flake8>=5.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Requires-Dist: pytest-cov>=4.0.0; extra == "test"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# PDF Section Binding Tool
+
+This tool reorders PDF pages for section binding (bookbinding), where pages are arranged in signatures (folded sheets) so that when printed and folded, they appear in the correct reading order.
+
+## Installation
+
+### From PyPI (Recommended)
+
+```bash
+pip install pdf-section-binding
+```
+
+### From Source
+
+1. Clone the repository:
+```bash
+git clone https://github.com/yourusername/pdf-section-binding.git
+cd pdf-section-binding
+```
+
+2. Create and activate virtual environment:
+```bash
+python3 -m venv venv
+source venv/bin/activate  # On macOS/Linux
+# or
+venv\Scripts\activate  # On Windows
+```
+
+3. Install in development mode:
+```bash
+pip install -e .
+```
+
+## Usage
+
+After installation, use the `pdf-section-binding` command (or the shorter `section-binding` alias):
+
+```bash
+pdf-section-binding input.pdf [options]
+```
+
+### Command Line Options
+
+- `-o, --output`: Output PDF file path (default: `input_name_section_bound.pdf`)
+- `-s, --signature-size`: Pages per signature - must be multiple of 4 (default: 8)
+- `--dry-run`: Preview analysis without creating output file
+- `-v, --verbose`: Enable verbose output with progress tracking
+- `-q, --quiet`: Suppress all output except errors
+- `--force`: Overwrite output file if it exists
+- `--version`: Show version information
+- `-h, --help`: Show help message
+
+### Examples
+
+```bash
+# Basic usage with 8-page signatures (2 papers per signature)
+pdf-section-binding book.pdf
+
+# Specify output file and 4-page signatures (1 paper per signature)  
+pdf-section-binding book.pdf -o output.pdf -s 4
+
+# Use 16-page signatures (4 papers per signature)
+pdf-section-binding book.pdf -s 16
+
+# Use 40-page signatures (10 papers per signature)
+pdf-section-binding book.pdf -s 40
+
+# Preview without creating file (dry run)
+pdf-section-binding book.pdf --dry-run
+
+# Verbose output with progress tracking
+pdf-section-binding book.pdf -v
+
+# Quiet mode (minimal output)
+pdf-section-binding book.pdf -q
+
+# Force overwrite existing output
+pdf-section-binding book.pdf --force
+```
+
+## Features
+
+✨ **Enhanced CLI Tool**
+- 🎨 **Colorized output** for better user experience
+- 📊 **Progress tracking** for large documents
+- 🔍 **Dry run mode** to preview without creating files
+- ⚡ **Fast processing** with optimized algorithms
+- 🛡️ **Robust error handling** with helpful suggestions
+- 📏 **Flexible signature sizes** (any multiple of 4)
+
+🔧 **Advanced Options**
+- Verbose and quiet modes
+- Force overwrite protection
+- Input validation with helpful error messages
+- Multiple command aliases (`pdf-section-binding` or `section-binding`)
+
+📦 **Library Usage**
+- Use as a Python library in your own projects
+- Clean API with `SectionBindingProcessor` class
+- Comprehensive test suite included
+
+## CLI Features in Detail
+
+### Smart Error Messages
+The tool provides helpful suggestions when you make mistakes:
+
+```bash
+$ pdf-section-binding book.pdf -s 15
+Error: Signature size must be a multiple of 4 (each paper = 4 pages).
+You specified 15. Try: 12 or 16
+```
+
+### Progress Tracking
+For large documents, see progress in real-time:
+
+```bash
+$ pdf-section-binding large-book.pdf -v
+PDF Section Binding Tool v1.0.0
+==================================================
+[INFO] Reading PDF: large-book.pdf
+[INFO] Total pages: 1500
+[INFO] Signature size: 8
+[INFO] Creating reordered PDF...
+Creating PDF: [████████████████████████████████████████████████] 100% (1500/1500)
+[INFO] Writing output: large-book_section_bound.pdf
+✅ Successfully created: large-book_section_bound.pdf
+```
+
+### Dry Run Analysis
+Preview the binding setup without creating files:
+
+```bash
+$ pdf-section-binding book.pdf --dry-run
+🔍 DRY RUN ANALYSIS:
+Would process 701 pages
+Would create 88 signatures  
+Would need 176 papers total
+Would save to: book_section_bound.pdf
+```
+
+Section binding involves:
+
+1. **Signature Creation**: Pages are grouped into signatures (folded sheets)
+2. **Page Reordering**: Pages are rearranged so that when printed double-sided and folded, they appear in correct reading order
+3. **Printing**: Print the reordered PDF double-sided
+4. **Folding**: Fold each signature in half
+5. **Binding**: Stack signatures and bind along the fold
+
+## Signature Sizes
+
+- **4 pages**: Each signature uses 1 paper (2 pages front, 2 pages back)
+- **8 pages**: Each signature uses 2 papers (4 pages front, 4 pages back)
+- **16 pages**: Each signature uses 4 papers (8 pages front, 8 pages back)
+- **32 pages**: Each signature uses 8 papers (16 pages front, 16 pages back)
+- **40 pages**: Each signature uses 10 papers (20 pages front, 20 pages back)
+- **Custom sizes**: Any multiple of 4 pages (e.g., 12=3 papers, 20=5 papers, 24=6 papers)
+
+## Paper Calculation
+
+**Formula**: `Papers per signature = Signature size ÷ 4`
+
+Examples:
+- 10 papers = 40 pages per signature
+- 6 papers = 24 pages per signature  
+- 3 papers = 12 pages per signature
+
+## Example Output
+
+For a 4-page signature with pages 1, 2, 3, 4:
+- The reordered sequence would be: [4, 1, 3, 2]
+- When printed double-sided and folded, you get pages in order: 1, 2, 3, 4
+
+## Generated Files
+
+This tool was used to process the book in `data/book.pdf`:
+
+- `data/book_section_bound.pdf` - Default 8-page signatures (2 papers each)
+- `data/book_40page_signature.pdf` - 40-page signatures (10 papers each)
+
+## Publishing to PyPI
+
+This package is ready for PyPI publication! Here's how to publish it:
+
+### Prerequisites
+
+1. Create accounts on [PyPI](https://pypi.org/) and [TestPyPI](https://test.pypi.org/)
+2. Install build tools:
+   ```bash
+   pip install build twine
+   ```
+
+### Build and Upload
+
+1. **Build the package:**
+   ```bash
+   python -m build
+   ```
+
+2. **Test on TestPyPI first:**
+   ```bash
+   twine upload --repository testpypi dist/*
+   ```
+
+3. **Upload to PyPI:**
+   ```bash
+   twine upload dist/*
+   ```
+
+### Package Structure
+
+The package follows modern Python packaging standards:
+
+```
+pdf-section-binding/
+├── src/pdf_section_binding/    # Source code
+│   ├── __init__.py
+│   ├── cli.py                  # Enhanced CLI interface
+│   ├── core.py                 # Core processing logic
+│   └── version.py              # Version and metadata
+├── tests/                      # Comprehensive test suite
+├── pyproject.toml              # Modern packaging config
+├── setup.py                    # Fallback setup config
+├── LICENSE                     # MIT license
+├── README.md                   # This file
+└── requirements.txt            # Dependencies
+
+```
+
+### Development Setup
+
+For development work:
+
+```bash
+# Clone and setup
+git clone <your-repo-url>
+cd pdf-section-binding
+
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # or venv\Scripts\activate on Windows
+
+# Install in development mode
+pip install -e .[dev]
+
+# Run tests
+pytest
+
+# Run with coverage
+pytest --cov=pdf_section_binding
+
+# Format code
+black src/ tests/
+
+# Lint code
+pylint src/ tests/
+
+# Type checking
+mypy src/
+```
+
+## Requirements
+
+- Python 3.7+
+- PyPDF2 library
+
+## Binding Instructions
+
+After running the script:
+
+1. Print the output PDF double-sided (flip on long edge)
+2. Cut or separate the printed sheets by signature
+3. Fold each signature in half along the center
+4. Stack all signatures in order
+5. Bind along the folded edge using:
+   - Saddle stitching (stapling)
+   - Perfect binding (glue)
+   - Spiral binding
+   - Or other binding methods

pdf_section_binding-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+pdf_section_binding/__init__.py,sha256=7EucSTcj9lj8j-rpWZDMP_24A657gA2znv97ZzHbW5Q,414
+pdf_section_binding/cli.py,sha256=u4JVDy6-_FBe1Ie4DZ12ruiaDCMT0pAZvJY9S8r5vuo,11604
+pdf_section_binding/core.py,sha256=hsq8pyy7Hw9c1NSTfnX9Zp6GhIOxHjVBMX8-V-PTb6g,8958
+pdf_section_binding/version.py,sha256=gkFzipRY3Y91FTMo3jJta1QwMOwWITZKmNsiuVuarYo,255
+pdf_section_binding-1.0.0.dist-info/licenses/LICENSE,sha256=OphKV48tcMv6ep-7j-8T6nycykPT0g8ZlMJ9zbGvdPs,1066
+pdf_section_binding-1.0.0.dist-info/METADATA,sha256=6Q12htDOTV4I2G6pIA86gqTOuzVnmglXHkKO9GsDyCc,9542
+pdf_section_binding-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pdf_section_binding-1.0.0.dist-info/entry_points.txt,sha256=LHMx24JfaML_v-WnFW4--Q522gcOo_cEoG378hJGwlQ,116
+pdf_section_binding-1.0.0.dist-info/top_level.txt,sha256=YpD4FK2NE0ODPhxz2VkN8LT1rpmqSxdcOwHIpF2Qcdk,20
+pdf_section_binding-1.0.0.dist-info/RECORD,,

pdf_section_binding-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pdf_section_binding-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+pdf-section-binding = pdf_section_binding.cli:main
+section-binding = pdf_section_binding.cli:main

pdf_section_binding-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Your Name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pdf_section_binding-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pdf_section_binding