thumbmoves 0.1.0__tar.gz

thumbmoves-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PixelCue contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

thumbmoves-0.1.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: thumbmoves
+Version: 0.1.0
+Summary: ThumbMoves: cross-platform Python access to native operating-system thumbnail caches.
+Author: Kieran Simkin
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/kieransimkin/PixelCue/tree/main/packages/thumbmoves
+Project-URL: Repository, https://github.com/kieransimkin/PixelCue
+Project-URL: Issues, https://github.com/kieransimkin/PixelCue/issues
+Project-URL: Releases, https://github.com/kieransimkin/PixelCue/releases
+Keywords: thumbnail,cache,windows,freedesktop,quicklook
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Desktop Environment :: File Managers
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Pillow>=10.0
+Requires-Dist: comtypes>=1.4; platform_system == "Windows"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# ThumbMoves
+
+Part of the DanceFlow ecosystem, **ThumbMoves** is a small cross-platform Python library for retrieving **existing thumbnails from the operating system's thumbnail cache** without opening the original media file.
+
+```python
+from thumbmoves import get_cached_thumbnail
+
+result = get_cached_thumbnail("/photos/example.jpg", (320, 240))
+if result:
+    print(result.backend, result.size)
+    open("thumb.jpg", "wb").write(result.data)
+```
+
+Or if you only want bytes:
+
+```python
+from thumbmoves import get_cached_thumbnail_bytes
+
+jpeg = get_cached_thumbnail_bytes("/photos/example.jpg")
+```
+
+## Platform behavior
+
+| Platform | Backend | Strict cache-only? | Behavior |
+|---|---|---:|---|
+| Windows | Shell `IShellItemImageFactory` | Yes | Requests `SIIGBF_INCACHEONLY | SIIGBF_THUMBNAILONLY` |
+| Linux / Unix desktops | Freedesktop thumbnail spec | Yes | Reads `$XDG_CACHE_HOME/thumbnails` / `~/.cache/thumbnails` by canonical file-URI MD5 |
+| macOS | Quick Look capability | No public equivalent | Returns a miss rather than trigger thumbnail generation |
+
+The API is intentionally conservative: a cache miss is `None`. It never falls back to decoding the source file. Applications can implement their own fallback after the cache lookup.
+
+## Installation
+
+Install from PyPI after the first production release:
+
+```bash
+python -m pip install thumbmoves
+```
+
+The same tested wheel and source distribution are attached to the matching GitHub release with `SHA256SUMS.txt`. Test releases are published separately on TestPyPI.
+
+Or install a checkout for local development:
+
+```bash
+python -m pip install -e .[dev]
+pytest
+```
+
+Windows installs `comtypes` automatically through a platform-scoped dependency. Other platforms do not install it.
+
+Release tags use the `thumbmoves-vX.Y.Z` form because ThumbMoves currently lives in the PixelCue repository.
+
+## CLI
+
+```bash
+thumbmoves ~/Pictures/photo.jpg --size 320x240 -o thumb.jpg
+```
+
+Exit code `0` means cache hit; `1` means cache miss.
+
+## Design goals
+
+- no dependency on a GUI toolkit;
+- no opening the source media file;
+- no implicit thumbnail generation in the cache-only API;
+- one stable API across platforms;
+- Pillow images and encoded bytes both available;
+- OS-specific code isolated in backend modules.
+
+## License
+
+MIT.

thumbmoves-0.1.0/README.md

@@ -0,0 +1,72 @@
+# ThumbMoves
+
+Part of the DanceFlow ecosystem, **ThumbMoves** is a small cross-platform Python library for retrieving **existing thumbnails from the operating system's thumbnail cache** without opening the original media file.
+
+```python
+from thumbmoves import get_cached_thumbnail
+
+result = get_cached_thumbnail("/photos/example.jpg", (320, 240))
+if result:
+    print(result.backend, result.size)
+    open("thumb.jpg", "wb").write(result.data)
+```
+
+Or if you only want bytes:
+
+```python
+from thumbmoves import get_cached_thumbnail_bytes
+
+jpeg = get_cached_thumbnail_bytes("/photos/example.jpg")
+```
+
+## Platform behavior
+
+| Platform | Backend | Strict cache-only? | Behavior |
+|---|---|---:|---|
+| Windows | Shell `IShellItemImageFactory` | Yes | Requests `SIIGBF_INCACHEONLY | SIIGBF_THUMBNAILONLY` |
+| Linux / Unix desktops | Freedesktop thumbnail spec | Yes | Reads `$XDG_CACHE_HOME/thumbnails` / `~/.cache/thumbnails` by canonical file-URI MD5 |
+| macOS | Quick Look capability | No public equivalent | Returns a miss rather than trigger thumbnail generation |
+
+The API is intentionally conservative: a cache miss is `None`. It never falls back to decoding the source file. Applications can implement their own fallback after the cache lookup.
+
+## Installation
+
+Install from PyPI after the first production release:
+
+```bash
+python -m pip install thumbmoves
+```
+
+The same tested wheel and source distribution are attached to the matching GitHub release with `SHA256SUMS.txt`. Test releases are published separately on TestPyPI.
+
+Or install a checkout for local development:
+
+```bash
+python -m pip install -e .[dev]
+pytest
+```
+
+Windows installs `comtypes` automatically through a platform-scoped dependency. Other platforms do not install it.
+
+Release tags use the `thumbmoves-vX.Y.Z` form because ThumbMoves currently lives in the PixelCue repository.
+
+## CLI
+
+```bash
+thumbmoves ~/Pictures/photo.jpg --size 320x240 -o thumb.jpg
+```
+
+Exit code `0` means cache hit; `1` means cache miss.
+
+## Design goals
+
+- no dependency on a GUI toolkit;
+- no opening the source media file;
+- no implicit thumbnail generation in the cache-only API;
+- one stable API across platforms;
+- Pillow images and encoded bytes both available;
+- OS-specific code isolated in backend modules.
+
+## License
+
+MIT.

thumbmoves-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "thumbmoves"
+version = "0.1.0"
+description = "ThumbMoves: cross-platform Python access to native operating-system thumbnail caches."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Kieran Simkin"}]
+keywords = ["thumbnail", "cache", "windows", "freedesktop", "quicklook"]
+dependencies = [
+  "Pillow>=10.0",
+  "comtypes>=1.4; platform_system == 'Windows'",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Operating System :: Microsoft :: Windows",
+  "Operating System :: POSIX :: Linux",
+  "Operating System :: MacOS",
+  "Programming Language :: Python :: 3",
+  "Topic :: Desktop Environment :: File Managers",
+  "Topic :: Multimedia :: Graphics",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.scripts]
+thumbmoves = "thumbmoves.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/kieransimkin/PixelCue/tree/main/packages/thumbmoves"
+Repository = "https://github.com/kieransimkin/PixelCue"
+Issues = "https://github.com/kieransimkin/PixelCue/issues"
+Releases = "https://github.com/kieransimkin/PixelCue/releases"
+
+[tool.setuptools.packages.find]
+where = ["src"]

thumbmoves-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

thumbmoves-0.1.0/src/thumbmoves/__init__.py

@@ -0,0 +1,18 @@
+from .api import (
+    BackendInfo,
+    ThumbnailResult,
+    backend_info,
+    get_cached_thumbnail,
+    get_cached_thumbnail_bytes,
+    get_cached_thumbnail_image,
+)
+
+__all__ = [
+    "BackendInfo",
+    "ThumbnailResult",
+    "backend_info",
+    "get_cached_thumbnail",
+    "get_cached_thumbnail_bytes",
+    "get_cached_thumbnail_image",
+]
+__version__ = "0.1.0"

thumbmoves-0.1.0/src/thumbmoves/api.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from PIL import Image
+
+from .common import DEFAULT_MAX_SIZE, encode_image, fit_image, normalize_size
+
+
+@dataclass(frozen=True)
+class BackendInfo:
+    name: str
+    platform: str
+    cache_only_supported: bool
+    notes: str = ""
+
+
+@dataclass(frozen=True)
+class ThumbnailResult:
+    data: bytes
+    image: Image.Image
+    backend: str
+    path: Path
+    output_format: str
+    cache_only: bool = True
+
+    @property
+    def size(self) -> tuple[int, int]:
+        return self.image.size
+
+
+def backend_info(platform: str | None = None) -> BackendInfo:
+    platform = platform or sys.platform
+    if platform == "win32":
+        return BackendInfo("windows-shell", platform, True,
+                           "IShellItemImageFactory with INCACHEONLY + THUMBNAILONLY")
+    if platform == "darwin":
+        return BackendInfo("macos-quicklook", platform, False,
+                           "Quick Look has no public strict cache-only query")
+    return BackendInfo("freedesktop-xdg", platform, True,
+                       "Freedesktop thumbnail-spec cache lookup")
+
+
+def get_cached_thumbnail_image(
+    path: str | Path,
+    max_size: tuple[int, int] = DEFAULT_MAX_SIZE,
+) -> Image.Image | None:
+    """Return an existing OS-managed thumbnail as a Pillow image.
+
+    This function never opens the original media file and never intentionally
+    asks the OS to generate a thumbnail. On macOS, where no public strict
+    cache-only Quick Look API exists, it returns ``None``.
+    """
+    p = Path(path)
+    max_size = normalize_size(max_size)
+
+    if sys.platform == "win32":
+        from .backends.windows import load_cached_thumbnail
+        image = load_cached_thumbnail(p, max(max_size))
+    elif sys.platform == "darwin":
+        from .backends.macos import load_cached_thumbnail
+        image = load_cached_thumbnail(p)
+    else:
+        from .backends.freedesktop import load_cached_thumbnail
+        image = load_cached_thumbnail(p)
+
+    return fit_image(image, max_size) if image is not None else None
+
+
+def get_cached_thumbnail(
+    path: str | Path,
+    max_size: tuple[int, int] = DEFAULT_MAX_SIZE,
+    *,
+    output_format: str = "JPEG",
+    quality: int = 82,
+) -> ThumbnailResult | None:
+    image = get_cached_thumbnail_image(path, max_size=max_size)
+    if image is None:
+        return None
+    fmt = str(output_format).upper()
+    return ThumbnailResult(
+        data=encode_image(image, output_format=fmt, quality=quality),
+        image=image,
+        backend=backend_info().name,
+        path=Path(path),
+        output_format=fmt,
+        cache_only=True,
+    )
+
+
+def get_cached_thumbnail_bytes(
+    path: str | Path,
+    max_size: tuple[int, int] = DEFAULT_MAX_SIZE,
+    *,
+    output_format: str = "JPEG",
+    quality: int = 82,
+) -> bytes | None:
+    result = get_cached_thumbnail(
+        path, max_size=max_size, output_format=output_format, quality=quality
+    )
+    return result.data if result is not None else None

thumbmoves-0.1.0/src/thumbmoves/backends/freedesktop.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import hashlib
+import os
+from pathlib import Path
+from PIL import Image
+
+
+def load_cached_thumbnail(path: Path) -> Image.Image | None:
+    """Load an existing Freedesktop/XDG thumbnail without generating one."""
+    try:
+        resolved = path.expanduser().resolve(strict=True)
+        uri = resolved.as_uri()
+        digest = hashlib.md5(uri.encode("utf-8")).hexdigest() + ".png"
+        cache_home = Path(os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache")
+
+        for bucket in ("xx-large", "x-large", "large", "normal"):
+            candidate = cache_home / "thumbnails" / bucket / digest
+            if not candidate.is_file():
+                continue
+            try:
+                with Image.open(candidate) as cached:
+                    info = dict(cached.info)
+                    thumb_uri = info.get("Thumb::URI")
+                    thumb_mtime = info.get("Thumb::MTime")
+                    if thumb_uri and str(thumb_uri) != uri:
+                        continue
+                    if thumb_mtime is not None:
+                        try:
+                            if int(thumb_mtime) != int(resolved.stat().st_mtime):
+                                continue
+                        except (TypeError, ValueError, OSError):
+                            continue
+                    cached.load()
+                    return cached.copy()
+            except Exception:
+                continue
+    except Exception:
+        return None
+    return None

thumbmoves-0.1.0/src/thumbmoves/backends/macos.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from pathlib import Path
+from PIL import Image
+
+
+def load_cached_thumbnail(path: Path) -> Image.Image | None:
+    """macOS has no public strict cache-only Quick Look query.
+
+    The cross-platform cache-only API therefore returns a clean miss instead of
+    causing Quick Look to generate a thumbnail. A future backend can add a
+    documented cache-only mechanism if Apple exposes one.
+    """
+    return None

thumbmoves-0.1.0/src/thumbmoves/backends/windows.py

@@ -0,0 +1,136 @@
+\
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from PIL import Image
+
+
+def load_cached_thumbnail(path: Path, requested_size: int) -> Image.Image | None:
+    """Retrieve an existing Windows Shell thumbnail without generating one."""
+    if sys.platform != "win32":
+        return None
+
+    try:
+        import ctypes
+        from ctypes import POINTER, Structure, byref, cast, c_void_p, c_wchar_p
+        from ctypes.wintypes import BYTE, DWORD, HANDLE, HBITMAP, LONG, UINT, WORD
+        from comtypes import COMMETHOD, GUID, HRESULT, IUnknown, CoInitialize, CoUninitialize
+    except Exception:
+        return None
+
+    class SIZE(Structure):
+        _fields_ = [("cx", LONG), ("cy", LONG)]
+
+    class BITMAP(Structure):
+        _fields_ = [
+            ("bmType", LONG), ("bmWidth", LONG), ("bmHeight", LONG),
+            ("bmWidthBytes", LONG), ("bmPlanes", WORD), ("bmBitsPixel", WORD),
+            ("bmBits", c_void_p),
+        ]
+
+    class BITMAPINFOHEADER(Structure):
+        _fields_ = [
+            ("biSize", DWORD), ("biWidth", LONG), ("biHeight", LONG),
+            ("biPlanes", WORD), ("biBitCount", WORD), ("biCompression", DWORD),
+            ("biSizeImage", DWORD), ("biXPelsPerMeter", LONG),
+            ("biYPelsPerMeter", LONG), ("biClrUsed", DWORD),
+            ("biClrImportant", DWORD),
+        ]
+
+    class RGBQUAD(Structure):
+        _fields_ = [
+            ("rgbBlue", BYTE), ("rgbGreen", BYTE), ("rgbRed", BYTE),
+            ("rgbReserved", BYTE),
+        ]
+
+    class BITMAPINFO(Structure):
+        _fields_ = [("bmiHeader", BITMAPINFOHEADER), ("bmiColors", RGBQUAD * 1)]
+
+    class IShellItemImageFactory(IUnknown):
+        _case_insensitive_ = True
+        _iid_ = GUID("{bcc18b79-ba16-442f-80c4-8a59c30c463b}")
+        _idlflags_ = []
+
+    IShellItemImageFactory._methods_ = [
+        COMMETHOD([], HRESULT, "GetImage", (["in"], SIZE, "size"),
+                  (["in"], UINT, "flags"), (["out"], POINTER(HBITMAP), "phbm"))
+    ]
+
+    shell32 = ctypes.windll.shell32
+    gdi32 = ctypes.windll.gdi32
+    user32 = ctypes.windll.user32
+
+    shell32.SHCreateItemFromParsingName.argtypes = [c_wchar_p, c_void_p, POINTER(GUID), POINTER(c_void_p)]
+    shell32.SHCreateItemFromParsingName.restype = HRESULT
+    gdi32.GetObjectW.argtypes = [HANDLE, ctypes.c_int, c_void_p]
+    gdi32.GetObjectW.restype = ctypes.c_int
+    gdi32.GetDIBits.argtypes = [HANDLE, HANDLE, UINT, UINT, c_void_p, POINTER(BITMAPINFO), UINT]
+    gdi32.GetDIBits.restype = ctypes.c_int
+    gdi32.DeleteObject.argtypes = [HANDLE]
+    gdi32.DeleteObject.restype = ctypes.c_int
+    user32.GetDC.argtypes = [HANDLE]
+    user32.GetDC.restype = HANDLE
+    user32.ReleaseDC.argtypes = [HANDLE, HANDLE]
+    user32.ReleaseDC.restype = ctypes.c_int
+
+    SIIGBF_THUMBNAILONLY = 0x00000008
+    SIIGBF_INCACHEONLY = 0x00000010
+    flags = SIIGBF_THUMBNAILONLY | SIIGBF_INCACHEONLY
+    DIB_RGB_COLORS = 0
+    BI_RGB = 0
+
+    initialized = False
+    hbitmap = None
+    dc = None
+    factory_ptr = c_void_p()
+    try:
+        CoInitialize()
+        initialized = True
+        hr = shell32.SHCreateItemFromParsingName(
+            str(path).replace("/", "\\"), None,
+            byref(IShellItemImageFactory._iid_), byref(factory_ptr),
+        )
+        if hr < 0 or not factory_ptr.value:
+            return None
+
+        factory = cast(factory_ptr, POINTER(IShellItemImageFactory))
+        hbitmap = factory.GetImage(SIZE(requested_size, requested_size), flags)
+        if not hbitmap:
+            return None
+
+        bitmap = BITMAP()
+        if not gdi32.GetObjectW(hbitmap, ctypes.sizeof(bitmap), byref(bitmap)):
+            return None
+        width, height = int(bitmap.bmWidth), abs(int(bitmap.bmHeight))
+        if width <= 0 or height <= 0:
+            return None
+
+        bmi = BITMAPINFO()
+        bmi.bmiHeader.biSize = ctypes.sizeof(BITMAPINFOHEADER)
+        bmi.bmiHeader.biWidth = width
+        bmi.bmiHeader.biHeight = -height
+        bmi.bmiHeader.biPlanes = 1
+        bmi.bmiHeader.biBitCount = 32
+        bmi.bmiHeader.biCompression = BI_RGB
+
+        raw = ctypes.create_string_buffer(width * height * 4)
+        dc = user32.GetDC(None)
+        if not dc:
+            return None
+        lines = gdi32.GetDIBits(dc, hbitmap, 0, height, raw, byref(bmi), DIB_RGB_COLORS)
+        if lines != height:
+            return None
+        return Image.frombuffer("RGBA", (width, height), raw.raw, "raw", "BGRA", 0, 1).copy()
+    except Exception:
+        return None
+    finally:
+        if dc:
+            try: user32.ReleaseDC(None, dc)
+            except Exception: pass
+        if hbitmap:
+            try: gdi32.DeleteObject(hbitmap)
+            except Exception: pass
+        if initialized:
+            try: CoUninitialize()
+            except Exception: pass

thumbmoves-0.1.0/src/thumbmoves/cli.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from .api import backend_info, get_cached_thumbnail
+
+
+def _size(value: str) -> tuple[int, int]:
+    try:
+        width, height = value.lower().split("x", 1)
+        return int(width), int(height)
+    except Exception as exc:
+        raise argparse.ArgumentTypeError("size must look like 320x240") from exc
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Read an existing OS thumbnail cache entry")
+    parser.add_argument("path", type=Path)
+    parser.add_argument("-o", "--output", type=Path)
+    parser.add_argument("--size", type=_size, default=(320, 240))
+    parser.add_argument("--format", default="JPEG")
+    args = parser.parse_args(argv)
+
+    info = backend_info()
+    result = get_cached_thumbnail(args.path, args.size, output_format=args.format)
+    if result is None:
+        print(f"MISS backend={info.name} path={args.path}")
+        return 1
+
+    output = args.output or Path.cwd() / (args.path.stem + ".thumb." + args.format.lower())
+    output.write_bytes(result.data)
+    print(f"HIT backend={result.backend} size={result.size[0]}x{result.size[1]} output={output}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

thumbmoves-0.1.0/src/thumbmoves/common.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import io
+from PIL import Image
+
+DEFAULT_MAX_SIZE = (320, 240)
+
+
+def normalize_size(max_size: tuple[int, int]) -> tuple[int, int]:
+    width, height = int(max_size[0]), int(max_size[1])
+    if width <= 0 or height <= 0:
+        raise ValueError("max_size dimensions must be positive")
+    return width, height
+
+
+def fit_image(image: Image.Image, max_size: tuple[int, int]) -> Image.Image:
+    max_size = normalize_size(max_size)
+    out = image.convert("RGB").copy()
+    out.thumbnail(max_size)
+    return out
+
+
+def encode_image(
+    image: Image.Image,
+    *,
+    output_format: str = "JPEG",
+    quality: int = 82,
+) -> bytes:
+    fmt = str(output_format).upper()
+    out = io.BytesIO()
+    kwargs = {}
+    if fmt in {"JPEG", "JPG", "WEBP"}:
+        kwargs["quality"] = int(quality)
+    if fmt in {"JPEG", "JPG"}:
+        kwargs["optimize"] = True
+    image.save(out, format=fmt, **kwargs)
+    return out.getvalue()

thumbmoves-0.1.0/src/thumbmoves.egg-info/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: thumbmoves
+Version: 0.1.0
+Summary: ThumbMoves: cross-platform Python access to native operating-system thumbnail caches.
+Author: Kieran Simkin
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/kieransimkin/PixelCue/tree/main/packages/thumbmoves
+Project-URL: Repository, https://github.com/kieransimkin/PixelCue
+Project-URL: Issues, https://github.com/kieransimkin/PixelCue/issues
+Project-URL: Releases, https://github.com/kieransimkin/PixelCue/releases
+Keywords: thumbnail,cache,windows,freedesktop,quicklook
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Desktop Environment :: File Managers
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Pillow>=10.0
+Requires-Dist: comtypes>=1.4; platform_system == "Windows"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# ThumbMoves
+
+Part of the DanceFlow ecosystem, **ThumbMoves** is a small cross-platform Python library for retrieving **existing thumbnails from the operating system's thumbnail cache** without opening the original media file.
+
+```python
+from thumbmoves import get_cached_thumbnail
+
+result = get_cached_thumbnail("/photos/example.jpg", (320, 240))
+if result:
+    print(result.backend, result.size)
+    open("thumb.jpg", "wb").write(result.data)
+```
+
+Or if you only want bytes:
+
+```python
+from thumbmoves import get_cached_thumbnail_bytes
+
+jpeg = get_cached_thumbnail_bytes("/photos/example.jpg")
+```
+
+## Platform behavior
+
+| Platform | Backend | Strict cache-only? | Behavior |
+|---|---|---:|---|
+| Windows | Shell `IShellItemImageFactory` | Yes | Requests `SIIGBF_INCACHEONLY | SIIGBF_THUMBNAILONLY` |
+| Linux / Unix desktops | Freedesktop thumbnail spec | Yes | Reads `$XDG_CACHE_HOME/thumbnails` / `~/.cache/thumbnails` by canonical file-URI MD5 |
+| macOS | Quick Look capability | No public equivalent | Returns a miss rather than trigger thumbnail generation |
+
+The API is intentionally conservative: a cache miss is `None`. It never falls back to decoding the source file. Applications can implement their own fallback after the cache lookup.
+
+## Installation
+
+Install from PyPI after the first production release:
+
+```bash
+python -m pip install thumbmoves
+```
+
+The same tested wheel and source distribution are attached to the matching GitHub release with `SHA256SUMS.txt`. Test releases are published separately on TestPyPI.
+
+Or install a checkout for local development:
+
+```bash
+python -m pip install -e .[dev]
+pytest
+```
+
+Windows installs `comtypes` automatically through a platform-scoped dependency. Other platforms do not install it.
+
+Release tags use the `thumbmoves-vX.Y.Z` form because ThumbMoves currently lives in the PixelCue repository.
+
+## CLI
+
+```bash
+thumbmoves ~/Pictures/photo.jpg --size 320x240 -o thumb.jpg
+```
+
+Exit code `0` means cache hit; `1` means cache miss.
+
+## Design goals
+
+- no dependency on a GUI toolkit;
+- no opening the source media file;
+- no implicit thumbnail generation in the cache-only API;
+- one stable API across platforms;
+- Pillow images and encoded bytes both available;
+- OS-specific code isolated in backend modules.
+
+## License
+
+MIT.

thumbmoves-0.1.0/src/thumbmoves.egg-info/SOURCES.txt

@@ -0,0 +1,21 @@
+LICENSE
+README.md
+pyproject.toml
+src/thumbmoves/__init__.py
+src/thumbmoves/api.py
+src/thumbmoves/cli.py
+src/thumbmoves/common.py
+src/thumbmoves.egg-info/PKG-INFO
+src/thumbmoves.egg-info/SOURCES.txt
+src/thumbmoves.egg-info/dependency_links.txt
+src/thumbmoves.egg-info/entry_points.txt
+src/thumbmoves.egg-info/requires.txt
+src/thumbmoves.egg-info/top_level.txt
+src/thumbmoves/backends/__init__.py
+src/thumbmoves/backends/freedesktop.py
+src/thumbmoves/backends/macos.py
+src/thumbmoves/backends/windows.py
+tests/test_api.py
+tests/test_freedesktop.py
+tests/test_source_contracts.py
+tests/test_thumbmoves_identity.py

thumbmoves-0.1.0/src/thumbmoves.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

thumbmoves-0.1.0/src/thumbmoves.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+thumbmoves = thumbmoves.cli:main

thumbmoves-0.1.0/src/thumbmoves.egg-info/requires.txt

@@ -0,0 +1,7 @@
+Pillow>=10.0
+
+[:platform_system == "Windows"]
+comtypes>=1.4
+
+[dev]
+pytest>=8

thumbmoves-0.1.0/src/thumbmoves.egg-info/top_level.txt

@@ -0,0 +1 @@
+thumbmoves

thumbmoves-0.1.0/tests/test_api.py

@@ -0,0 +1,20 @@
+from thumbmoves import backend_info
+from thumbmoves.common import normalize_size
+
+
+def test_backend_info_is_cross_platform_api():
+    assert backend_info("win32").name == "windows-shell"
+    assert backend_info("win32").cache_only_supported is True
+    assert backend_info("darwin").name == "macos-quicklook"
+    assert backend_info("darwin").cache_only_supported is False
+    assert backend_info("linux").name == "freedesktop-xdg"
+
+
+def test_size_validation():
+    assert normalize_size((320, 240)) == (320, 240)
+    try:
+        normalize_size((0, 240))
+    except ValueError:
+        pass
+    else:
+        raise AssertionError("expected ValueError")

thumbmoves-0.1.0/tests/test_freedesktop.py

@@ -0,0 +1,27 @@
+import hashlib
+from pathlib import Path
+from PIL import Image, PngImagePlugin
+
+from thumbmoves.api import get_cached_thumbnail
+
+
+def test_freedesktop_cache_lookup(tmp_path, monkeypatch):
+    source = tmp_path / "photo.jpg"
+    source.write_bytes(b"not-opened-by-library")
+    uri = source.resolve().as_uri()
+    digest = hashlib.md5(uri.encode("utf-8")).hexdigest() + ".png"
+
+    cache = tmp_path / "cache" / "thumbnails" / "large"
+    cache.mkdir(parents=True)
+    info = PngImagePlugin.PngInfo()
+    info.add_text("Thumb::URI", uri)
+    info.add_text("Thumb::MTime", str(int(source.stat().st_mtime)))
+    Image.new("RGB", (640, 480), "white").save(cache / digest, pnginfo=info)
+
+    monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path / "cache"))
+    monkeypatch.setattr("sys.platform", "linux")
+    result = get_cached_thumbnail(source, (160, 120))
+    assert result is not None
+    assert result.backend == "freedesktop-xdg"
+    assert result.size == (160, 120)
+    assert result.data.startswith(b"\xff\xd8")

thumbmoves-0.1.0/tests/test_source_contracts.py

@@ -0,0 +1,22 @@
+from pathlib import Path
+
+ROOT = Path(__file__).parents[1]
+
+
+def test_windows_backend_uses_strict_cache_flags():
+    source = (ROOT / "src/thumbmoves/backends/windows.py").read_text()
+    assert "SIIGBF_INCACHEONLY = 0x00000010" in source
+    assert "SIIGBF_THUMBNAILONLY = 0x00000008" in source
+    assert "SIIGBF_THUMBNAILONLY | SIIGBF_INCACHEONLY" in source
+    assert "DeleteObject" in source
+
+
+def test_freedesktop_backend_uses_uri_md5():
+    source = (ROOT / "src/thumbmoves/backends/freedesktop.py").read_text()
+    assert 'hashlib.md5(uri.encode("utf-8")).hexdigest() + ".png"' in source
+    assert '("xx-large", "x-large", "large", "normal")' in source
+
+
+def test_library_has_no_pixelcue_dependency():
+    for path in (ROOT / "src/thumbmoves").rglob("*.py"):
+        assert "pixelcue" not in path.read_text().casefold()

thumbmoves-0.1.0/tests/test_thumbmoves_identity.py

@@ -0,0 +1,20 @@
+from pathlib import Path
+import thumbmoves
+
+ROOT = Path(__file__).parents[1]
+
+
+def test_public_package_name_and_version():
+    assert thumbmoves.__version__ == "0.1.0"
+
+
+def test_project_identity_is_thumbmoves():
+    pyproject = (ROOT / "pyproject.toml").read_text(encoding="utf-8")
+    assert 'name = "thumbmoves"' in pyproject
+    assert 'thumbmoves = "thumbmoves.cli:main"' in pyproject
+
+
+def test_no_old_import_namespace_remains():
+    assert (ROOT / "src/thumbmoves").is_dir()
+    for path in (ROOT / "src/thumbmoves").rglob("*.py"):
+        assert "os_thumbnail_cache" not in path.read_text(encoding="utf-8")