Add email PDF compression and target-size retries
This commit is contained in:
parent
d9546e83a5
commit
76050c2f28
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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()
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
Loading…
Reference in New Issue