PyObjC Framework QuickLookThumbnailing

Warnings

• breaking PyObjC versions frequently drop support for older Python versions. Version 12.0 dropped Python 3.9 support, and version 11.0 dropped Python 3.8 support. Always check the `requires_python` metadata.
  Fix: Upgrade to a supported Python version (3.10+ for PyObjC 12.x).
• gotcha This library is strictly for macOS. It cannot be installed or used on other operating systems as it directly binds to macOS-specific frameworks.
  Fix: Ensure your development and deployment environment is macOS. For cross-platform thumbnail generation, consider alternatives.
• gotcha QuickLookThumbnailing APIs are asynchronous. Calls like `generateBestRepresentationForFile` return immediately and execute a completion handler later. Applications needing to wait for results must manage an event loop (e.g., using `PyObjCTools.AppHelper.runEventLoop()` and `stopEventLoop()`).
  Fix: Structure your code to handle asynchronous callbacks. If in a script, use `AppHelper.runEventLoop()` to keep the process alive until the callback completes and calls `AppHelper.stopEventLoop()`.
• breaking PyObjC 11.1 aligned its behavior with `clang`'s Automatic Reference Counting (ARC) documentation for initializer methods. Methods in the 'init' family now correctly steal a reference to `self` and return a new reference, which can affect memory management if migrating code from older PyObjC versions that relied on the previous behavior.
  Fix: Review custom Objective-C classes implemented in Python or Objective-C code interacting with Python objects, especially around `init` methods, to ensure correct reference counting and object lifecycle management.

Install

• pip install pyobjc-framework-quicklookthumbnailing pyobjc-framework-foundation Install PyObjC QuickLookThumbnailing and Foundation

Imports

• QLThumbnailGenerator

  from QuickLookThumbnailing import QLThumbnailGenerator

• NSURL

  from Foundation import NSURL

• AppHelper

  from PyObjCTools import AppHelper

Quickstart

This quickstart demonstrates how to generate a thumbnail for a local file using QLThumbnailGenerator. It creates a dummy text file, requests a thumbnail, saves the generated NSImage as a PNG, and then cleans up. Since QuickLookThumbnailing APIs are asynchronous, it utilizes PyObjCTools.AppHelper to manage the event loop until the thumbnail generation is complete.

import Foundation
from QuickLookThumbnailing import QLThumbnailGenerator
from PyObjCTools import AppHelper
import objc
import os

# Create a dummy file for demonstration
file_path = "/tmp/test_pyobjc_thumbnail.txt"
output_path = "/tmp/pyobjc_thumbnail.png"

with open(file_path, "w") as f:
    f.write("Hello, PyObjC Thumbnailing!")

file_url = Foundation.NSURL.fileURLWithPath_(file_path)

@objc.python_block_into_completion_handler
def completion_handler(thumbnail, error):
    if error:
        print(f"Error generating thumbnail: {error}")
    elif thumbnail:
        # thumbnail is an NSImage. Convert to PNG data and save.
        image_data = thumbnail.TIFFRepresentation()
        image_rep = Foundation.NSBitmapImageRep.imageRepWithData_(image_data)
        if image_rep:
            properties = Foundation.NSDictionary.dictionaryWithObject_forKey_(
                Foundation.NSNumber.numberWithFloat_(1.0), Foundation.NSImageCompressionFactor
            )
            png_data = image_rep.representationUsingType_properties_(
                Foundation.NSPNGFileType, properties
            )
            if png_data:
                png_data.writeToFile_atomically_(output_path, True)
                print(f"Thumbnail saved to {output_path}")
            else:
                print("Could not get PNG representation.")
        else:
            print("Could not create image representation.")
    else:
        print("No thumbnail generated.")
    AppHelper.stopEventLoop() # Stop the event loop after completion

print(f"Generating thumbnail for {file_path}...")

generator = QLThumbnailGenerator.sharedGenerator()
thumbnail_size = Foundation.NSSize(width=256, height=256) # Max size for the thumbnail

generator.generateBestRepresentationForFile_size_completionHandler_(
    file_url,
    thumbnail_size,
    completion_handler
)

AppHelper.runEventLoop()

# Clean up dummy files
if os.path.exists(file_path):
    os.remove(file_path)
if os.path.exists(output_path):
    print(f"Cleaned up {output_path}")