Add email PDF compression and target-size retries

This commit is contained in:
Dandaedre 2026-10-20 11:58:30 +02:00
parent d9546e83a5
commit 76050c2f28
4 changed files with 222 additions and 11 deletions

View File

@ -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,

View File

@ -15,9 +15,49 @@ or the `DECKCRAFT_CLI` / `PDFCRAFT_CLI` environment variables.
Output goes to `<file-stem>_export/`: `<file-stem>.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

View File

@ -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()

View File

@ -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: <file-stem>_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: