ZipBundler e un piccolo tool desktop per creare piu archivi ZIP indipendenti a partire da una cartella sorgente, mantenendo ogni pacchetto entro una dimensione massima configurabile.

L'obiettivo pratico e preparare allegati gestibili per invio tramite posta elettronica aziendale, dove spesso il limite reale degli allegati e vicino a 20-25 MB.

Funzioni principali

Scelta della cartella sorgente.
Scelta della cartella di destinazione.
Dimensione massima dei pacchetti tramite spinbox.
Default a 15 MB, piu prudente per l'invio email.
Avviso inline sopra 18 MB, con richiesta di accettazione esplicita.
Creazione di pacchetti pacchetto_001.zip, pacchetto_002.zip, ecc.
Verifica della dimensione reale dello ZIP finale, non della somma dei file originali.
Ottimizzazione guidata di PDF troppo grandi.
Ottimizzazione guidata di immagini troppo grandi.
Opzione esplicita per convertire formati immagine non compressi in JPEG.
Opzione esplicita per convertire file Office grandi in PDF.

Scelta fondamentale sulla dimensione

La dimensione limite viene controllata sul file .zip finale.

Questo e importante perche la dimensione dei file originali non coincide con la dimensione dell'archivio compresso. Il programma crea ZIP temporanei di prova, misura il risultato reale e solo dopo decide se un file puo entrare nel pacchetto corrente.

PDF troppo grandi

Quando un PDF supera da solo il limite impostato, ZipBundler prova questi profili standard nell'ordine indicato, fermandosi al primo ZIP entro limite:

Ordine	Profilo	Operazione	Qualita JPEG
1	Ottimizzazione senza perdita	Pulizia e compressione interna con PyMuPDF, senza rasterizzare le pagine	Non applicabile
2	Ghostscript ebook	Preset `/ebook`	Gestita dal preset
3	Ghostscript screen	Preset `/screen`	Gestita dal preset
4	Qualita email	Pagine trasformate in immagini a 150 DPI	68/100
5	Piu leggero	Pagine trasformate in immagini a 120 DPI	60/100
6	Minimo	Pagine trasformate in immagini a 100 DPI	54/100

I profili 4-6 vengono saltati quando viene rilevato testo selezionabile significativo. I profili Ghostscript vengono saltati se il motore non e disponibile; nella build completa e incluso nell'EXE. Anche i profili standard possono ridurre sensibilmente la qualita: se rientrano nel limite vengono accettati automaticamente, secondo la regola scelta per il programma.

La ricodifica raster dei PDF nativi e evitata quando possibile, perche puo aumentare la dimensione e far perdere testo selezionabile.

Se viene creata una copia ridotta, l'originale non viene modificato. La copia viene salvata nella cartella di destinazione, dentro _pdf_ridotti_email.

Quando serve una scelta sulla qualita, la GUI mostra una preview affiancata originale/ridotto, con navigazione delle pagine.

Compressione aggiuntiva e zoom

La regola comune a PDF, immagini e conversioni Office e basata sulla dimensione reale dello ZIP del singolo file:

Se un profilo standard rientra nel limite, la copia viene usata automaticamente, senza anteprima o domande.
Se nessun profilo standard rientra, viene conservato il risultato con lo ZIP piu piccolo e mostrato in anteprima, indicando dimensione e limite.
L'utente puo accettare esplicitamente quel risultato fuori limite oppure scegliere "Rifiuta e comprimi di piu".
Ogni tentativo aggiuntivo richiede anteprima e approvazione, anche quando finalmente rientra nel limite. Ogni rifiuto passa al tentativo successivo.

Non esiste piu il ripiego automatico all'originale o al profilo 200 DPI. La chiusura dell'anteprima o "Annulla elaborazione" interrompe il lavoro senza creare nuovi ZIP. All'ultimo profilo disponibile rimangono accettazione e annullamento: nessun risultato rifiutato viene impacchettato e non viene avviato un ciclo infinito. Il limite potrebbe essere inferiore alla dimensione minima ottenibile di un documento valido.

Per i PDF, dopo ciascun rifiuto vengono proposti profili Ghostscript a 72, 60, 48, 36 e 24 DPI, poi profili raster alle stesse risoluzioni, con qualita JPEG 45, 38, 30, 24 e 18. L'anteprima indica il prossimo tentativo, avvertendo quando le pagine verranno trasformate in immagini con perdita del testo selezionabile. Ogni tentativo parte dall'originale e viene misurato dentro uno ZIP contenente quel solo PDF. I parametri Ghostscript usano i controlli di downsampling e i dizionari di compressione documentati in High Level Devices.

L'anteprima PDF dispone di modalita Adatta e zoom dal 50% al 400%, con barre di scorrimento sincronizzate tra originale e copia. Il 100% corrisponde a 96 pixel per pollice del documento; la pagina viene renderizzata nuovamente a ogni livello di zoom. La rotella scorre verticalmente; con Shift scorre orizzontalmente. La navigazione delle pagine mantiene lo zoom scelto.

Gli originali restano intatti e la ricodifica raster conserva le dimensioni fisiche delle pagine. In modalita CLI, se i profili standard non bastano, l'elaborazione si interrompe invitando a usare la GUI. Se un file fuori limite non ha un convertitore disponibile o abilitato, il programma segnala il problema e si interrompe anziche creare un pacchetto fuori limite non approvato.

Ghostscript

Ghostscript e usato come motore preferenziale per ridurre PDF nativi quando e disponibile.

Il programma cerca:

gswin64c
gswin32c
gs

Se Ghostscript non e presente, il programma salta quel passaggio e continua con le altre strategie.

Immagini troppo grandi

Per le immagini viene usata Pillow.

Formati supportati:

JPG/JPEG
PNG
TIFF/TIF
BMP
WEBP

Profili standard automatici, nell'ordine:

Profilo	Lato lungo massimo	Qualita JPEG/WebP
Qualita alta	2500 pixel	85/100
Qualita email	1800 pixel	75/100
Massima compressione	1200 pixel	60/100

Le proporzioni vengono mantenute e le immagini piu piccole non vengono ingrandite. I valori di qualita sono parametri dell'encoder, non percentuali di dimensione risparmiata. La codifica applicata dipende dal formato:

Formato	Codifica della copia ridotta
JPEG	JPEG ottimizzato e progressivo, qualita del profilo
WebP	Qualita del profilo, metodo di compressione 6
PNG	Compressione senza perdita, livello 9; riduzione dei pixel secondo il profilo
TIFF	Deflate (`tiff_adobe_deflate`), riduzione dei pixel secondo il profilo
BMP	BMP, riduzione dei pixel secondo il profilo

Per impostazione predefinita il formato originale viene mantenuto. Per esempio un TIFF ridotto resta TIFF.

Esiste pero una checkbox esplicita:

Converti formati non compressi in JPEG (es. BMP/TIFF)

Solo se questa opzione e attiva, BMP e TIFF vengono convertiti in JPEG per ottenere file molto piu leggeri.

Le copie ridotte vengono salvate in _immagini_ridotte_email.

Se i tre profili standard non bastano, il ciclo con anteprima propone lati massimi di 1000, 800, 600, 400, 200 e 100 pixel, con qualita JPEG/WebP 50, 40, 30, 24, 18 e 12. Per PNG, TIFF e BMP la riduzione aggiuntiva si basa soprattutto sul numero di pixel; la scelta di conservare il formato resta valida. L'avviso Pillow per immagini molto grandi viene riportato nel registro, senza disabilitare il limite massimo di protezione della libreria. Per i JPEG viene richiesta la decodifica ridotta prima del ridimensionamento, limitando la memoria.

File Office troppo grandi

ZipBundler puo convertire file Office grandi in PDF, ma solo se la checkbox dedicata e attiva:

Converti file Office grandi in PDF (es. DOCX -> PDF)

Formati previsti:

DOC/DOCX
XLS/XLSX
PPT/PPTX

La conversione usa Microsoft Office tramite automazione COM (win32com). Quindi richiede Office installato e funzionante sul PC.

Non esistono profili di qualita Office separati:

Documento	Passaggio standard
DOC/DOCX	Esportazione PDF tramite Microsoft Word
XLS/XLSX	Esportazione PDF tramite Microsoft Excel
PPT/PPTX	Esportazione PDF tramite Microsoft PowerPoint

Le copie PDF vengono salvate in _office_convertiti_pdf.

Se il PDF convertito entra nello ZIP, viene usato senza domande. Altrimenti passa per l'ottimizzazione PDF standard e, se ancora necessario, per lo stesso ciclo di anteprime e compressioni aggiuntive. L'anteprima confronta il PDF ottenuto da Office con la sua copia ricompressa.

LibreOffice headless e stato valutato come opzione futura, ma non e incluso per evitare di aumentare molto il peso di un eventuale eseguibile PyInstaller.

Altri formati

Per i formati non elencati viene applicata soltanto la compressione ZIP, senza ricodifica del contenuto. Se il file resta fuori limite e non esiste una conversione disponibile o abilitata, il programma segnala il problema.

Scelte conservative

Gli originali non vengono mai modificati.
Le conversioni di formato sono disattivate di default.
I risultati dei profili standard entro limite vengono accettati automaticamente.
Sopra 18 MB viene richiesto consenso esplicito, perche la codifica email puo aumentare la dimensione effettiva del messaggio.
Uno ZIP fuori limite viene creato solo dopo approvazione esplicita e contiene soltanto il file accettato.

Verifica del flusso PDF

python -m unittest test_pdf_workflow -v

I test verificano l'accettazione automatica dei profili standard entro limite, il ciclo rifiuto/ricompressione/anteprima, l'annullamento, il mantenimento dei formati immagine, i file effettivamente inseriti negli ZIP, lo zoom e gli avvisi Pillow. Se Ghostscript e disponibile, verificano anche la ricodifica reale con conservazione del testo selezionabile. I test Office simulano la conversione COM.

Uso GUI

python .\zipbundler.py

Uso CLI

python .\zipbundler.py C:\percorso\cartella --output C:\percorso\output --size-mb 15

Opzioni:

--convert-uncompressed-images
--convert-office-to-pdf

Dipendenze Python

pip install -r requirements.txt

Dipendenze principali:

CustomTkinter
Pillow
PyMuPDF

Per Office COM serve anche pywin32, installato nell'ambiente in cui viene eseguito il programma.

Eseguibile Windows

La build completa crea dist\ZipBundler.exe: un eseguibile portabile che include Python, CustomTkinter/Tcl/Tk, Pillow, PyMuPDF, pywin32 e Ghostscript. Sul PC di destinazione non serve installare Python o Ghostscript. Non sono inclusi i documenti di prova in SDS.

Script disponibile:

.\build_exe.ps1 -Clean

Lo script:

installa le dipendenze Python;
installa PyInstaller se necessario;
include lo splash screen assets/splash.png;
crea un eseguibile Windows dist\ZipBundler.exe;
include Ghostscript se trova gswin64c, gswin32c o gs nel PATH; senza il motore la build completa si interrompe;
controlla l'esito dei comandi prima di dichiarare completata la build.

Per ricostruire usando le dipendenze gia installate:

.\build_exe.ps1 -SkipDependencyInstall

L'opzione -SkipGhostscriptBundle produce invece una versione incompleta del motore PDF avanzato, che richiede Ghostscript esterno. Non e la build completa.

Verifica della build completa, da eseguire sul PC di sviluppo:

python verify_exe.py

La verifica controlla i componenti incorporati nell'EXE e avvia il programma con Python e Ghostscript esterni esclusi dal PATH. Crea un PDF con testo selezionabile e una foto di prova, verifica gli ZIP finali sotto soglia, il mantenimento del testo PDF e il formato JPEG. Usa solo cartelle temporanee.

Lo splash screen riporta ZipBundler, versione 1.0 e ai.teamstudio.it.

Componenti inclusi o gestiti:

CustomTkinter, Pillow e PyMuPDF vengono inclusi da PyInstaller come dipendenze Python;
Ghostscript e incluso nella build completa, con le risorse della sua installazione;
Microsoft Office non viene incluso: la conversione Office -> PDF usa Office COM e richiede Office installato sul PC di destinazione.

Da valutare in futuro:

eventuale icona applicativa;
firma dell'eseguibile, se necessaria in ambiente aziendale.