From 76050c2f281e41b0dea0ca3bb59f0472ebd5fc03 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Tue, 20 Oct 2026 11:58:30 +0200 Subject: [PATCH] Add email PDF compression and target-size retries --- AGENTS.md | 4 +- docs/exporter.md | 42 +++++++++++++++++- tests/test_exporter.py | 97 ++++++++++++++++++++++++++++++++++++++++++ tools/exporter.py | 90 +++++++++++++++++++++++++++++++++++---- 4 files changed, 222 insertions(+), 11 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 591871b..d41ca6c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,7 +20,9 @@ with quick-start examples and links to detailed documentation in `docs/`. for redirected output; `tests/test_progress.py` checks display cleanup. - `tools/exporter.py` uses DeckCraft to export PPTX presentations to PDF or PNG slides, and PdfCraft to render PDF pages as PNGs. It discovers CLI executables or - locally installed AppImages. PDF-to-PDF is a successful no-op. + locally installed AppImages. PDF-to-PDF is a successful no-op unless compression + is requested. Ghostscript powers `--pdf-quality` and bounded `--target-size` + attempts; an unmet target must not publish output or replace existing files. - `tests/test_exporter.py` covers exporter validation, no-op behavior, conversion failures, and overwrite behavior. - `tests/test_pptx_videos.py` covers slide discovery, extraction, temporary probing, diff --git a/docs/exporter.md b/docs/exporter.md index 98022cf..d577d4e 100644 --- a/docs/exporter.md +++ b/docs/exporter.md @@ -15,9 +15,49 @@ or the `DECKCRAFT_CLI` / `PDFCRAFT_CLI` environment variables. Output goes to `_export/`: `.pdf` and/or numbered PNGs inside `images/`. Images default to 144 DPI. Existing output requires `--overwrite`, which replaces generated files and removes stale numbered -slide/page PNGs. PDF-to-PDF is a successful no-op; other input extensions are +slide/page PNGs. PDF-to-PDF is a successful no-op unless compression is requested; other input extensions are errors. Rendering completes in temporary storage before output is copied. +## Smaller PDFs for email + +```sh +python3 tools/exporter.py presentation.pptx --output pdf --pdf-quality email +python3 tools/exporter.py presentation.pptx --output pdf --target-size 5MB +python3 tools/exporter.py document.pdf --output pdf --pdf-quality email --target-size 5MB +``` + +Compression requires **Ghostscript** (`gs` on `PATH`). `--dpi` only controls PNG +resolution. `--pdf-quality` controls PDF image downsampling: + +| Quality | Image resolution | +| --- | --- | +| `original` (default) | No compression pass | +| `print` | 300 DPI | +| `email` | 150 DPI | +| `screen` | 72 DPI | + +These presets use Ghostscript's ebook compression settings with the indicated +image resolution. They reduce image detail without deliberately rasterizing +text and vector graphics. A quality preset alone does not guarantee a file size; +the original is retained if it is smaller than the compressed result. + +`--target-size` accepts bytes or units such as `5MB`, `500KB`, and `2.5MiB` +(`MB` = 1,000,000 bytes; `MiB` = 1,048,576 bytes). It starts at the selected +quality, or 300 DPI if no compression preset was selected, then tries lower +resolutions: 150, 120, 96, 72, 50, and 36 DPI. Each pass uses the original PDF +to avoid accumulating compression damage. It stops at the first result strictly +below the target, with at most seven attempts. Progress shows each attempt and +its resulting byte count. A PDF already below the target is copied unchanged. + +Very small targets can noticeably degrade images, and some documents cannot +reach the requested size. In that case the command fails, reports the smallest +size achieved, and publishes no output; existing exports remain untouched. +The target applies to the PDF file itself, not email encoding overhead. +PDF compression writes a separate export and never changes the input. + +Ghostscript rewrites the PDF, so some interactive content or annotations may +change. See its [PDF output documentation](https://ghostscript.readthedocs.io/en/latest/VectorDevices.html). + Interactive terminals show an updating progress line, with page counts for PDF rendering and a spinner during DeckCraft's bulk export. Only output paths, the final summary, and warnings/errors remain afterward. Redirected output uses diff --git a/tests/test_exporter.py b/tests/test_exporter.py index ba64a63..fc23543 100644 --- a/tests/test_exporter.py +++ b/tests/test_exporter.py @@ -106,6 +106,103 @@ class ExporterTests(unittest.TestCase): self.assertFalse((images / 'page-0002.png').exists()) self.assertEqual((images / 'page-0001.png').read_bytes(), b'new image') + def compressor(self, sizes, commands): + sizes = iter(sizes) + + def fake_run(command, **kwargs): + commands.append(command) + output = next(arg.split('=', 1)[1] for arg in command + if str(arg).startswith('-sOutputFile=')) + Path(output).write_bytes(b'x' * next(sizes)) + return '' + return fake_run + + def test_target_retries_original_and_stops_below_limit(self): + source = self.root / 'input.pdf' + source.write_bytes(b'x' * 2000) + commands = [] + with patch.object(exporter.shutil, 'which', return_value='/fake/gs'), \ + patch.object(exporter, 'find_cli', side_effect=AssertionError('PDF compression needs no craft CLI')), \ + patch.object(exporter, 'run', side_effect=self.compressor([1500, 1000, 900], commands)): + self.assertEqual(self.invoke(source, '--output', 'pdf', '--target-size', '1KB'), 0) + self.assertEqual(len(commands), 3) # equal to target is not below it + self.assertTrue(all(command[-1] == source for command in commands)) + self.assertIn('-dColorImageResolution=300', commands[0]) + self.assertIn('-dColorImageResolution=120', commands[-1]) + self.assertEqual((self.root / 'input_export/input.pdf').stat().st_size, 900) + self.assertEqual(source.stat().st_size, 2000) + + def test_unreachable_target_is_bounded_and_preserves_existing_output(self): + source = self.root / 'input.pdf' + source.write_bytes(b'x' * 2000) + output = self.root / 'input_export' + output.mkdir() + (output / 'input.pdf').write_bytes(b'keep') + commands = [] + with patch.object(exporter.shutil, 'which', return_value='/fake/gs'), \ + patch.object(exporter, 'run', side_effect=self.compressor([1500] * 7, commands)): + self.assertEqual(self.invoke(source, '--output', 'pdf', '--target-size', '100B', '--overwrite'), 1) + self.assertEqual(len(commands), 7) + self.assertEqual((output / 'input.pdf').read_bytes(), b'keep') + + def test_email_quality_keeps_original_if_compression_grows_file(self): + source = self.root / 'input.pdf' + source.write_bytes(b'x' * 1000) + commands = [] + with patch.object(exporter.shutil, 'which', return_value='/fake/gs'), \ + patch.object(exporter, 'run', side_effect=self.compressor([1500], commands)): + self.assertEqual(self.invoke(source, '--output', 'pdf', '--pdf-quality', 'email', '--dpi', '24'), 0) + self.assertEqual(len(commands), 1) + self.assertIn('-dColorImageResolution=150', commands[0]) + self.assertEqual((self.root / 'input_export/input.pdf').read_bytes(), source.read_bytes()) + + def test_already_below_target_needs_no_compressor(self): + source = self.root / 'input.pdf' + source.write_bytes(b'pdf') + with patch.object(exporter.shutil, 'which', side_effect=AssertionError('no tool needed')): + self.assertEqual(self.invoke(source, '--output', 'pdf', '--target-size', '1MB'), 0) + self.assertEqual((self.root / 'input_export/input.pdf').read_bytes(), b'pdf') + + def test_missing_compressor_and_failed_pass_publish_nothing(self): + source = self.root / 'input.pdf' + source.write_bytes(b'pdf') + with patch.object(exporter.shutil, 'which', return_value=None): + self.assertEqual(self.invoke(source, '--output', 'pdf', '--pdf-quality', 'email'), 1) + with patch.object(exporter.shutil, 'which', return_value='/fake/gs'), \ + patch.object(exporter, 'run', side_effect=RuntimeError('compression failed')): + self.assertEqual(self.invoke(source, '--output', 'pdf', '--pdf-quality', 'email'), 1) + self.assertFalse((self.root / 'input_export').exists()) + + def test_size_units_and_pdf_option_validation(self): + self.assertEqual(exporter.byte_size('2.5MB'), 2500000) + self.assertEqual(exporter.byte_size('2MiB'), 2097152) + self.assertEqual(exporter.byte_size('100'), 100) + for args in [('--target-size', '0'), ('--target-size', '-2MB'), + ('--target-size', 'NaN'), ('--target-size', '5TB'), + ('--target-size', '2MB'), ('--pdf-quality', 'email')]: + with self.subTest(args=args), self.assertRaises(SystemExit) as error: + self.invoke(self.root / 'input.pdf', '--output', 'images', *args) + self.assertEqual(error.exception.code, 2) + + def test_pptx_compresses_after_convert(self): + source = self.root / 'input.pptx' + source.touch() + commands = [] + compress = self.compressor([500], commands) + + def fake_run(command, **kwargs): + if command[1] == 'convert': + Path(command[-1]).write_bytes(b'x' * 1000) + return '' + self.assertEqual(Path(command[-1]).name, 'export.pdf') + return compress(command) + + with patch.object(exporter.shutil, 'which', return_value='/fake/gs'), \ + patch.object(exporter, 'find_cli', return_value=Path('/fake/cli')), \ + patch.object(exporter, 'run', side_effect=fake_run): + self.assertEqual(self.invoke(source, '--output', 'pdf', '--pdf-quality', 'email'), 0) + self.assertEqual((self.root / 'input_export/input.pdf').stat().st_size, 500) + if __name__ == '__main__': unittest.main() diff --git a/tools/exporter.py b/tools/exporter.py index dfa5d54..1d8fc4a 100644 --- a/tools/exporter.py +++ b/tools/exporter.py @@ -1,6 +1,7 @@ #!/usr/bin/env python3 """Export PPTX to PDF/PNG with DeckCraft, or PDF to PNG with PdfCraft.""" import argparse +from decimal import Decimal import json import os from pathlib import Path @@ -30,6 +31,62 @@ def positive_int(value): return number +def byte_size(value): + match = re.fullmatch(r'\s*(\d+(?:\.\d+)?)\s*(B|KB|MB|GB|KiB|MiB|GiB)?\s*', value, re.I) + if not match: + raise argparse.ArgumentTypeError('Use a positive size such as 5MB or 2.5MiB.') + unit = (match[2] or 'B').upper() + scale = {'B': 1, 'KB': 1000, 'MB': 1000**2, 'GB': 1000**3, + 'KIB': 1024, 'MIB': 1024**2, 'GIB': 1024**3}[unit] + size = int(Decimal(match[1]) * scale) + if size < 1: + raise argparse.ArgumentTypeError('Target size must be at least one byte.') + return size + + +def compress_pdf(source, work, quality, target_size): + """Try bounded downsampling passes, always using the original PDF.""" + original_size = source.stat().st_size + if target_size and original_size < target_size: + status(f'PDF already under target: {original_size:,} bytes.', 'success') + return source + gs = shutil.which('gs') + if not gs: + raise RuntimeError('PDF compression requires Ghostscript (gs). Install Ghostscript and retry.') + first_dpi = {'original': 300, 'print': 300, 'email': 150, 'screen': 72}[quality] + resolutions = [first_dpi] + if target_size: + resolutions += [dpi for dpi in (150, 120, 96, 72, 50, 36) if dpi < first_dpi] + best, best_size = source, original_size + for attempt, dpi in enumerate(resolutions, 1): + status(f'Compressing PDF [{attempt}/{len(resolutions)}]: {dpi} DPI images' + + (f', target < {target_size:,} bytes...' if target_size else '...')) + candidate = work / f'compressed-{attempt}.pdf' + command = [gs, '-sDEVICE=pdfwrite', '-dSAFER', '-dBATCH', '-dNOPAUSE', + '-dPDFSETTINGS=/ebook', '-dAutoRotatePages=/None', + '-dEmbedAllFonts=true', '-dSubsetFonts=true', + '-dPassThroughJPEGImages=false', '-dPassThroughJPXImages=false', + f'-sOutputFile={candidate}'] + for kind in ('Color', 'Gray', 'Mono'): + command += [f'-dDownsample{kind}Images=true', + f'-d{kind}ImageResolution={dpi}', + f'-d{kind}ImageDownsampleThreshold=1.0'] + run([*command, '-f', source]) + if not candidate.is_file() or not candidate.stat().st_size: + raise RuntimeError('Ghostscript did not create a PDF.') + size = candidate.stat().st_size + status(f'Compression pass: {size:,} bytes (original {original_size:,}).') + if size < best_size: + best, best_size = candidate, size + if target_size and best_size < target_size: + break + if target_size and best_size >= target_size: + raise RuntimeError(f'Could not reach target < {target_size:,} bytes; smallest result ' + f'was {best_size:,} bytes. No output replaced. Try a larger target.') + status(f'PDF size: {original_size:,} → {best_size:,} bytes.', 'success', persist=True) + return best + + def run(command, **kwargs): result = subprocess.run([str(arg) for arg in command], capture_output=True, text=True, errors='replace', **kwargs) @@ -78,9 +135,11 @@ def find_cli(app, override, work): return path -def export(source, formats, destination, dpi, overwrite, cli_override, progress=None): +def export(source, formats, destination, dpi, overwrite, cli_override, progress=None, + pdf_quality='original', target_size=None): is_deck = source.suffix.lower() == '.pptx' - if not is_deck and 'pdf' in formats: + compression = pdf_quality != 'original' or target_size is not None + if not is_deck and 'pdf' in formats and not compression: status(f'Already PDF; nothing to convert: {source}', 'success', persist=True) formats = [format for format in formats if format != 'pdf'] if not formats: @@ -100,13 +159,18 @@ def export(source, formats, destination, dpi, overwrite, cli_override, progress= app = 'deckcraft' if is_deck else 'pdfcraft' with tempfile.TemporaryDirectory(prefix='exporter-') as temp: work = Path(temp) - cli = find_cli(app, cli_override, work) + cli = find_cli(app, cli_override, work) if is_deck or 'images' in formats else None rendered = work / 'images' + pdf = source if 'pdf' in formats: - status('Exporting presentation to PDF...') - run([cli, 'convert', source, work / 'export.pdf']) - if not (work / 'export.pdf').is_file() or not (work / 'export.pdf').stat().st_size: - raise RuntimeError('DeckCraft did not create a PDF.') + if is_deck: + pdf = work / 'export.pdf' + status('Exporting presentation to PDF...') + run([cli, 'convert', source, pdf]) + if not pdf.is_file() or not pdf.stat().st_size: + raise RuntimeError('DeckCraft did not create a PDF.') + if compression: + pdf = compress_pdf(pdf, work, pdf_quality, target_size) if 'images' in formats: rendered.mkdir() if is_deck: @@ -135,7 +199,7 @@ def export(source, formats, destination, dpi, overwrite, cli_override, progress= # Publish only after all requested conversions succeed. destination.mkdir(parents=True, exist_ok=True) if 'pdf' in formats: - shutil.copy2(work / 'export.pdf', pdf_target) + shutil.copy2(pdf, pdf_target) status(f'PDF: {pdf_target}', 'success', persist=True) if 'images' in formats: images_target.mkdir(exist_ok=True) @@ -159,10 +223,18 @@ def main(argv=None): parser.add_argument('-d', '--output-dir', type=Path, help='Destination directory (default: _export)') parser.add_argument('--dpi', type=positive_int, default=144, help='PNG resolution (default: 144)') + parser.add_argument('--pdf-quality', choices=('original', 'print', 'email', 'screen'), + default='original', help='PDF image quality: original (default), print (300 DPI), ' + 'email (150 DPI), screen (72 DPI). Compression requires Ghostscript.') + parser.add_argument('--target-size', type=byte_size, metavar='SIZE', + help='Try progressively stronger PDF compression to get below e.g. 5MB. ' + 'Fails without publishing if the target cannot be reached.') parser.add_argument('--overwrite', action='store_true', help='Replace existing generated output files') parser.add_argument('--deckcraft-cli', help='DeckCraft CLI executable or AppImage') parser.add_argument('--pdfcraft-cli', help='PdfCraft CLI executable or AppImage') args = parser.parse_args(argv) + if 'pdf' not in args.output and (args.pdf_quality != 'original' or args.target_size is not None): + parser.error('--pdf-quality and --target-size require --output pdf (or pdf,images).') source = args.file.expanduser().resolve() if source.suffix.lower() not in ('.pptx', '.pdf'): parser.error(f'Unsupported input type: {source.suffix or "(no extension)"}. Expected .pptx or .pdf.') @@ -174,7 +246,7 @@ def main(argv=None): status(f'Source: {source}') export(source, args.output, destination, args.dpi, args.overwrite, args.deckcraft_cli if source.suffix.lower() == '.pptx' else args.pdfcraft_cli, - progress=progress) + progress=progress, pdf_quality=args.pdf_quality, target_size=args.target_size) status('Done.', 'success', persist=True) return 0 except (OSError, RuntimeError, ValueError) as error: