image-optimizer-webui 1.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,3 @@
1
+ """Image Optimizer — batch image compression with a local web UI."""
2
+
3
+ __version__ = "1.1.0"
@@ -0,0 +1,2 @@
1
+ from image_optimizer.main import main
2
+ main()
@@ -0,0 +1,430 @@
1
+ """Fetch and install the external encoder binaries on first use.
2
+
3
+ Why this exists
4
+ ---------------
5
+ The wheel deliberately contains Python only. `pngquant` is GPL-3.0-or-later,
6
+ and shipping its .exe from PyPI would put GPLv3 §6's "offer the Corresponding
7
+ Source" obligation on every downstream user of this package — the same reason
8
+ most distro packages keep the tool separate. `oxipng`, `mozjpeg`/`cjpeg` and
9
+ `libavif`/`avifenc` are permissively licensed, but they are still
10
+ architecture-specific blobs that have no business inside a `py3-none-any`
11
+ sdist/wheel. So: download the exact upstream release once, verify it, and
12
+ keep it in the per-user data directory.
13
+
14
+ Trust model
15
+ -----------
16
+ The pinned SHA-256 is the *only* thing that makes a download executable.
17
+ Every artifact either carries the publisher's own archive digest (oxipng,
18
+ libavif) or a digest of the one file we pull out of the archive (pngquant,
19
+ mozjpeg). A mismatch is discarded — never "warn and continue". The URL scheme
20
+ is not load-bearing; a local test server over plain HTTP is fine because the
21
+ digest still has to match. Conversely, an artifact with no digest at all is
22
+ rejected before a single byte is requested.
23
+
24
+ Nothing here is allowed to prevent the app from starting: a missing binary
25
+ only removes the output formats that need it (see
26
+ `Optimizer.available_modes`), and WebP via Pillow always works. Offline or
27
+ behind an internal firewall, we print the exact manual instructions instead.
28
+ """
29
+
30
+ from __future__ import annotations
31
+
32
+ import hashlib
33
+ import os
34
+ import platform
35
+ import sys
36
+ import tarfile
37
+ import tempfile
38
+ import urllib.error
39
+ import urllib.request
40
+ import zipfile
41
+ from dataclasses import dataclass, field
42
+ from pathlib import Path
43
+ from typing import Iterable, Optional
44
+
45
+ # One socket-level timeout per operation; a hung connection must not wedge
46
+ # startup forever (same reasoning as SUBPROCESS_TIMEOUT in optimizer.py).
47
+ DOWNLOAD_TIMEOUT = 60
48
+
49
+ # Ceiling for a single archive. The largest pinned artifact (libavif's
50
+ # windows-artifacts.zip) is ~15 MB; a response far beyond this is a wrong URL
51
+ # or a hostile redirect, and has no reason to fill the disk.
52
+ MAX_DOWNLOAD_BYTES = 200 * 1024 * 1024
53
+ MAX_MEMBER_BYTES = 120 * 1024 * 1024
54
+
55
+ _CHUNK = 256 * 1024
56
+ USER_AGENT = "image-optimizer (binary bootstrap)"
57
+
58
+
59
+ class DownloadError(RuntimeError):
60
+ """Raised when an artifact cannot be fetched, verified, or unpacked."""
61
+
62
+
63
+ @dataclass(frozen=True)
64
+ class Artifact:
65
+ """One pinnable upstream release.
66
+
67
+ `sha256` is the publisher's digest for the whole archive when they
68
+ publish one; `member_sha256` is the digest of the single executable we
69
+ extract, used when they don't. At least one must be set.
70
+ """
71
+
72
+ tool: str
73
+ version: str
74
+ url: str
75
+ member: str
76
+ sha256: Optional[str] = None
77
+ member_sha256: Optional[str] = None
78
+ kind: str = "zip" # "zip" | "tar.gz"
79
+ executable: bool = False
80
+
81
+ @property
82
+ def filename(self) -> str:
83
+ return self.member
84
+
85
+
86
+ # --- Windows x86-64 -------------------------------------------------------
87
+ # pngquant: pngquant.org serves a version-less URL (pngquant-windows.zip) and
88
+ # no checksum, so the digest below pins the executable itself. At the time of
89
+ # writing the Windows build is still the 2.17.0 C release even though
90
+ # pngquant.org advertises 3.0.3 for macOS/Linux; if upstream ever swaps the
91
+ # Windows payload, verification fails loudly and this entry needs a bump
92
+ # rather than silently installing an unverified newer binary.
93
+ _WINDOWS_AMD64: tuple[Artifact, ...] = (
94
+ Artifact(
95
+ tool="pngquant",
96
+ version="2.17.0",
97
+ url="https://pngquant.org/pngquant-windows.zip",
98
+ member="pngquant.exe",
99
+ member_sha256="7aadad6a50aa5c40cfcb20f9478c92f6030360a3424bc262ce383dc1e97fb86a",
100
+ ),
101
+ Artifact(
102
+ tool="oxipng",
103
+ version="10.1.1",
104
+ url="https://github.com/shssoichiro/oxipng/releases/download/v10.1.1/"
105
+ "oxipng-10.1.1-x86_64-pc-windows-msvc.zip",
106
+ member="oxipng.exe",
107
+ sha256="0f57b33abb46c76258ac8e20be604a48208141d514bc2936b5200ed626976dd8",
108
+ ),
109
+ Artifact(
110
+ tool="cjpeg",
111
+ version="4.0.3",
112
+ url="https://github.com/mozilla/mozjpeg/releases/download/v4.0.3/"
113
+ "mozjpeg-v4.0.3-win-x64.zip",
114
+ member="cjpeg-static.exe",
115
+ member_sha256="dac0b9d64f660a150ef03a6137836592528c30fc3fd5e39511c2cff7a8206ae1",
116
+ ),
117
+ Artifact(
118
+ tool="avifenc",
119
+ version="1.4.2",
120
+ url="https://github.com/AOMediaCodec/libavif/releases/download/v1.4.2/"
121
+ "windows-artifacts.zip",
122
+ member="avifenc.exe",
123
+ sha256="cb2d9fea43dcbab1d0707e3b37eb7b08070ad2fb60a2c188c39ec12382c0484a",
124
+ member_sha256="42312321ed9f715987cb3623292eaedc778970b45efb9b1de62ce795f61991a0",
125
+ ),
126
+ )
127
+
128
+
129
+ # --- macOS / Linux --------------------------------------------------------
130
+ # oxipng publishes a checksummed static build for every mainstream
131
+ # target triple, so it is the one tool that is safe to fetch on POSIX.
132
+ # pngquant/mozjpeg only ship Windows binaries officially, and libavif's
133
+ # POSIX archives are dynamically linked against a toolchain we cannot
134
+ # guarantee — those stay manual (`brew`/`apt`/`dnf`) rather than risking a
135
+ # binary that fails at exec time.
136
+ _POSIX_OXIPNG: dict[tuple[str, str], Artifact] = {
137
+ ("darwin", "x86_64"): Artifact(
138
+ tool="oxipng",
139
+ version="10.1.1",
140
+ url="https://github.com/shssoichiro/oxipng/releases/download/v10.1.1/"
141
+ "oxipng-10.1.1-x86_64-apple-darwin.tar.gz",
142
+ member="oxipng",
143
+ sha256="8f23d1bc9cd5b3f88e84f1cca77b461f6900aa20f2ecbf84f729cd12530c5a53",
144
+ kind="tar.gz",
145
+ executable=True,
146
+ ),
147
+ ("darwin", "arm64"): Artifact(
148
+ tool="oxipng",
149
+ version="10.1.1",
150
+ url="https://github.com/shssoichiro/oxipng/releases/download/v10.1.1/"
151
+ "oxipng-10.1.1-aarch64-apple-darwin.tar.gz",
152
+ member="oxipng",
153
+ sha256="615a401629b5cc104bdc775ac962abd67ab2f3084f0b3b1ba9c51e9b76c3964f",
154
+ kind="tar.gz",
155
+ executable=True,
156
+ ),
157
+ ("linux", "x86_64"): Artifact(
158
+ tool="oxipng",
159
+ version="10.1.1",
160
+ url="https://github.com/shssoichiro/oxipng/releases/download/v10.1.1/"
161
+ "oxipng-10.1.1-x86_64-unknown-linux-gnu.tar.gz",
162
+ member="oxipng",
163
+ sha256="5988392e88fc3d03f562f2d565e5c12a095223ae8bd983576f2aaff2fadf3738",
164
+ kind="tar.gz",
165
+ executable=True,
166
+ ),
167
+ ("linux", "arm64"): Artifact(
168
+ tool="oxipng",
169
+ version="10.1.1",
170
+ url="https://github.com/shssoichiro/oxipng/releases/download/v10.1.1/"
171
+ "oxipng-10.1.1-aarch64-unknown-linux-gnu.tar.gz",
172
+ member="oxipng",
173
+ sha256="a69c9dbb110463746153bf9b56488a293747e1d90dc1f30d24af3d9615165b98",
174
+ kind="tar.gz",
175
+ executable=True,
176
+ ),
177
+ }
178
+
179
+
180
+ MANUAL_HINTS = {
181
+ "win32": " winget install pngquant / choco install pngquant oxipng mozjpeg",
182
+ "darwin": " brew install pngquant oxipng mozjpeg libavif",
183
+ "linux": " sudo apt install pngquant oxipng mozjpeg libavif-bin (Fedora: dnf install "
184
+ "pngquant oxipng mozjpeg-dtools libavif-tools)",
185
+ }
186
+
187
+
188
+ def _machine() -> str:
189
+ machine = platform.machine().lower()
190
+ if machine in ("amd64", "x86_64", "x64"):
191
+ return "x86_64"
192
+ if machine in ("arm64", "aarch64"):
193
+ return "arm64"
194
+ return machine or "unknown"
195
+
196
+
197
+ def binary_dir() -> Path:
198
+ """Per-user install location for the downloaded executables.
199
+
200
+ Deliberately outside the package directory: site-packages is frequently
201
+ read-only (system Python, pipx, container images), and a per-user cache is
202
+ what every other self-bootstrapping tool uses.
203
+ """
204
+ if sys.platform == "win32":
205
+ base = os.environ.get("LOCALAPPDATA") or os.environ.get("APPDATA")
206
+ root = Path(base) if base else Path.home() / "AppData" / "Local"
207
+ return root / "ImageOptimizer" / "bin"
208
+ if sys.platform == "darwin":
209
+ return Path.home() / "Library" / "Application Support" / "ImageOptimizer" / "bin"
210
+ data = os.environ.get("XDG_DATA_HOME")
211
+ root = Path(data) if data else Path.home() / ".local" / "share"
212
+ return root / "image-optimizer" / "bin"
213
+
214
+
215
+ def artifacts_for_current_platform() -> tuple[Artifact, ...]:
216
+ """The artifacts we are willing to fetch here (may legitimately be empty)."""
217
+ if sys.platform == "win32":
218
+ return _WINDOWS_AMD64 if _machine() == "x86_64" else ()
219
+ return (_POSIX_OXIPNG[(_platform_key(), _machine())],) if (
220
+ (_platform_key(), _machine()) in _POSIX_OXIPNG
221
+ ) else ()
222
+
223
+
224
+ def _platform_key() -> str:
225
+ return "darwin" if sys.platform == "darwin" else "linux"
226
+
227
+
228
+ def _sha256_file(path: Path) -> str:
229
+ digest = hashlib.sha256()
230
+ with open(path, "rb") as fh:
231
+ for chunk in iter(lambda: fh.read(_CHUNK), b""):
232
+ digest.update(chunk)
233
+ return digest.hexdigest()
234
+
235
+
236
+ def _download(url: str, dest: Path) -> int:
237
+ request = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
238
+ total = 0
239
+ try:
240
+ with urllib.request.urlopen(request, timeout=DOWNLOAD_TIMEOUT) as response:
241
+ with open(dest, "wb") as fh:
242
+ while True:
243
+ chunk = response.read(_CHUNK)
244
+ if not chunk:
245
+ break
246
+ total += len(chunk)
247
+ if total > MAX_DOWNLOAD_BYTES:
248
+ raise DownloadError(
249
+ f"response exceeded {MAX_DOWNLOAD_BYTES // (1024 * 1024)} MB"
250
+ )
251
+ fh.write(chunk)
252
+ except urllib.error.HTTPError as exc:
253
+ raise DownloadError(f"HTTP {exc.code} from {url}") from exc
254
+ except urllib.error.URLError as exc:
255
+ raise DownloadError(f"network error: {exc.reason}") from exc
256
+ except TimeoutError as exc:
257
+ raise DownloadError(f"timed out after {DOWNLOAD_TIMEOUT}s") from exc
258
+ if total == 0:
259
+ raise DownloadError("empty response")
260
+ return total
261
+
262
+
263
+ def _read_member(artifact: Artifact, archive: Path) -> bytes:
264
+ """Pull out the one executable we want, by basename.
265
+
266
+ Matching on `Path(name).name` (and never calling extract/extractall) is
267
+ what makes archive traversal impossible: a hostile entry called
268
+ `../../evil.exe` simply never matches the expected filename, and we never
269
+ write outside the target path anyway.
270
+ """
271
+ if artifact.kind == "zip":
272
+ with zipfile.ZipFile(archive) as zf:
273
+ for info in zf.infolist():
274
+ if info.is_dir() or Path(info.filename).name != artifact.member:
275
+ continue
276
+ if info.file_size > MAX_MEMBER_BYTES:
277
+ raise DownloadError(f"{artifact.member} is unreasonably large")
278
+ with zf.open(info) as fh:
279
+ return fh.read()
280
+ raise DownloadError(f"{artifact.member} not found inside the archive")
281
+ if artifact.kind == "tar.gz":
282
+ with tarfile.open(archive, "r:*") as tf:
283
+ for info in tf.getmembers():
284
+ if not info.isfile() or Path(info.name).name != artifact.member:
285
+ continue
286
+ if info.size > MAX_MEMBER_BYTES:
287
+ raise DownloadError(f"{artifact.member} is unreasonably large")
288
+ handle = tf.extractfile(info)
289
+ if handle is None:
290
+ continue
291
+ with handle:
292
+ return handle.read()
293
+ raise DownloadError(f"{artifact.member} not found inside the archive")
294
+ raise DownloadError(f"unsupported archive kind {artifact.kind!r}")
295
+
296
+
297
+ def _install_artifact(artifact: Artifact, target_dir: Path, *, force: bool, out) -> str:
298
+ """Return "present" or "installed"; raise DownloadError on any failure."""
299
+ target = target_dir / artifact.filename
300
+
301
+ if target.exists() and not force:
302
+ # An existing file is only trusted when we can re-verify it; otherwise
303
+ # (oxipng on POSIX, whose digest covers the archive rather than the
304
+ # binary) we take its presence at face value — re-downloading a 500 KB
305
+ # tarball on every start would be worse than the risk it mitigates.
306
+ if artifact.member_sha256:
307
+ if _sha256_file(target) == artifact.member_sha256:
308
+ print(f"[Binaries] {artifact.tool} {artifact.version} already installed", file=out)
309
+ return "present"
310
+ print(
311
+ f"[Binaries] {artifact.tool} at {target} does not match the pinned "
312
+ f"{artifact.version} digest — reinstalling",
313
+ file=out,
314
+ )
315
+ else:
316
+ print(f"[Binaries] {artifact.tool} {artifact.version} already installed", file=out)
317
+ return "present"
318
+
319
+ if not (artifact.sha256 or artifact.member_sha256):
320
+ raise DownloadError("refusing to download an artifact with no pinned digest")
321
+
322
+ target_dir.mkdir(parents=True, exist_ok=True)
323
+ with tempfile.TemporaryDirectory(prefix="imgopt-dl-") as tmp:
324
+ archive = Path(tmp) / "archive"
325
+ print(f"[Binaries] downloading {artifact.tool} {artifact.version} from {artifact.url}", file=out)
326
+ size = _download(artifact.url, archive)
327
+ if artifact.sha256 and _sha256_file(archive) != artifact.sha256:
328
+ raise DownloadError("archive SHA-256 mismatch — discarded")
329
+ payload = _read_member(artifact, archive)
330
+ if artifact.member_sha256:
331
+ actual = hashlib.sha256(payload).hexdigest()
332
+ if actual != artifact.member_sha256:
333
+ raise DownloadError(
334
+ f"{artifact.member} SHA-256 mismatch (got {actual}) — discarded"
335
+ )
336
+
337
+ # Write-then-rename so a crash or a second instance never leaves a
338
+ # half-written executable where _find_binary would happily exec it.
339
+ staging = target.with_name(target.name + ".part")
340
+ staging.write_bytes(payload)
341
+ if artifact.executable and sys.platform != "win32":
342
+ os.chmod(staging, 0o755)
343
+ os.replace(staging, target)
344
+ print(f"[Binaries] installed {artifact.tool} {artifact.version} ({size // 1024} KB) -> {target}", file=out)
345
+ return "installed"
346
+
347
+
348
+ @dataclass
349
+ class EnsureReport:
350
+ installed: list[str] = field(default_factory=list)
351
+ present: list[str] = field(default_factory=list)
352
+ failed: dict[str, str] = field(default_factory=dict)
353
+ skipped: list[str] = field(default_factory=list)
354
+ unsupported: list[str] = field(default_factory=list)
355
+
356
+ @property
357
+ def ok(self) -> bool:
358
+ return not self.failed
359
+
360
+
361
+ def _print_manual_help(artifact: Artifact, reason: str, out) -> None:
362
+ print(f"[Warning] {artifact.tool} {artifact.version} unavailable: {reason}", file=out)
363
+ print(f" Manual install: {artifact.url}", file=out)
364
+ print(f" then put {artifact.member} in: {binary_dir()}", file=out)
365
+ if artifact.member_sha256:
366
+ print(f" expected SHA-256: {artifact.member_sha256}", file=out)
367
+ elif artifact.sha256:
368
+ print(f" expected archive SHA-256: {artifact.sha256}", file=out)
369
+
370
+
371
+ def _print_platform_help(platform_key: str, out) -> None:
372
+ hint = MANUAL_HINTS.get(platform_key)
373
+ if hint:
374
+ print("[Binaries] No automatic download for this platform/architecture.", file=out)
375
+ print(f"[Binaries] Install the tools with your package manager instead:\n{hint}", file=out)
376
+ print(f"[Binaries] Binaries are also found on PATH; anything you install there is used as-is.", file=out)
377
+
378
+
379
+ def ensure_binaries(
380
+ *,
381
+ download: bool = True,
382
+ force: bool = False,
383
+ artifacts: Optional[Iterable[Artifact]] = None,
384
+ out=None,
385
+ ) -> EnsureReport:
386
+ """Make sure the platform's encoders are present, fetching what is pinned.
387
+
388
+ Never raises: a failure is reported (with manual instructions) and the
389
+ caller keeps starting, because WebP still works with no external tool at
390
+ all. `artifacts` is injectable for tests.
391
+ """
392
+ out = out if out is not None else sys.stdout
393
+ report = EnsureReport()
394
+
395
+ if getattr(sys, "frozen", False):
396
+ # The standalone exe bundles its binaries; nothing to fetch.
397
+ report.skipped.append("frozen build")
398
+ return report
399
+
400
+ selected = tuple(artifacts) if artifacts is not None else artifacts_for_current_platform()
401
+ if not selected:
402
+ _print_platform_help(sys.platform if sys.platform in MANUAL_HINTS else "linux", out)
403
+ return report
404
+
405
+ if not download:
406
+ report.skipped.extend(a.tool for a in selected)
407
+ print("[Binaries] --no-download given; skipping automatic fetch", file=out)
408
+ return report
409
+
410
+ target_dir = binary_dir()
411
+ for artifact in selected:
412
+ try:
413
+ status = _install_artifact(artifact, target_dir, force=force, out=out)
414
+ except DownloadError as exc:
415
+ report.failed[artifact.tool] = str(exc)
416
+ _print_manual_help(artifact, str(exc), out)
417
+ except OSError as exc:
418
+ report.failed[artifact.tool] = str(exc)
419
+ _print_manual_help(artifact, f"filesystem error: {exc}", out)
420
+ else:
421
+ getattr(report, status).append(artifact.tool)
422
+ return report
423
+
424
+
425
+ def missing_tools_hint() -> str:
426
+ """One-line hint used by the startup banner."""
427
+ return (
428
+ "Missing encoders can be fetched automatically on next start "
429
+ f"(into {binary_dir()}), or installed manually."
430
+ )