{"id":6159,"library":"pyobjc-framework-quicklookthumbnailing","title":"PyObjC Framework QuickLookThumbnailing","description":"PyObjC-framework-quicklookthumbnailing provides Python bindings for Apple's QuickLookThumbnailing framework on macOS, allowing developers to generate high-quality thumbnails for various file types programmatically. It is part of the broader PyObjC project, bridging Python with Objective-C frameworks. The current version is 12.1, with new releases typically following macOS SDK updates and Python version changes.","status":"active","version":"12.1","language":"en","source_language":"en","source_url":"https://github.com/ronaldoussoren/pyobjc","tags":["macos","objective-c","thumbnailing","quicklook","ui","apple"],"install":[{"cmd":"pip install pyobjc-framework-quicklookthumbnailing pyobjc-framework-foundation","lang":"bash","label":"Install PyObjC QuickLookThumbnailing and Foundation"}],"dependencies":[{"reason":"Provides the core bridge between Python and Objective-C, essential for all PyObjC frameworks.","package":"pyobjc-core"},{"reason":"Required for fundamental Cocoa classes like NSURL and NSSize, which are often used with QuickLookThumbnailing.","package":"pyobjc-framework-foundation","optional":false}],"imports":[{"symbol":"QLThumbnailGenerator","correct":"from QuickLookThumbnailing import QLThumbnailGenerator"},{"symbol":"NSURL","correct":"from Foundation import NSURL"},{"symbol":"AppHelper","correct":"from PyObjCTools import AppHelper"}],"quickstart":{"code":"import Foundation\nfrom QuickLookThumbnailing import QLThumbnailGenerator\nfrom PyObjCTools import AppHelper\nimport objc\nimport os\n\n# Create a dummy file for demonstration\nfile_path = \"/tmp/test_pyobjc_thumbnail.txt\"\noutput_path = \"/tmp/pyobjc_thumbnail.png\"\n\nwith open(file_path, \"w\") as f:\n    f.write(\"Hello, PyObjC Thumbnailing!\")\n\nfile_url = Foundation.NSURL.fileURLWithPath_(file_path)\n\n@objc.python_block_into_completion_handler\ndef completion_handler(thumbnail, error):\n    if error:\n        print(f\"Error generating thumbnail: {error}\")\n    elif thumbnail:\n        # thumbnail is an NSImage. Convert to PNG data and save.\n        image_data = thumbnail.TIFFRepresentation()\n        image_rep = Foundation.NSBitmapImageRep.imageRepWithData_(image_data)\n        if image_rep:\n            properties = Foundation.NSDictionary.dictionaryWithObject_forKey_(\n                Foundation.NSNumber.numberWithFloat_(1.0), Foundation.NSImageCompressionFactor\n            )\n            png_data = image_rep.representationUsingType_properties_(\n                Foundation.NSPNGFileType, properties\n            )\n            if png_data:\n                png_data.writeToFile_atomically_(output_path, True)\n                print(f\"Thumbnail saved to {output_path}\")\n            else:\n                print(\"Could not get PNG representation.\")\n        else:\n            print(\"Could not create image representation.\")\n    else:\n        print(\"No thumbnail generated.\")\n    AppHelper.stopEventLoop() # Stop the event loop after completion\n\nprint(f\"Generating thumbnail for {file_path}...\")\n\ngenerator = QLThumbnailGenerator.sharedGenerator()\nthumbnail_size = Foundation.NSSize(width=256, height=256) # Max size for the thumbnail\n\ngenerator.generateBestRepresentationForFile_size_completionHandler_(\n    file_url,\n    thumbnail_size,\n    completion_handler\n)\n\nAppHelper.runEventLoop()\n\n# Clean up dummy files\nif os.path.exists(file_path):\n    os.remove(file_path)\nif os.path.exists(output_path):\n    print(f\"Cleaned up {output_path}\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade to a supported Python version (3.10+ for PyObjC 12.x).","message":"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.","severity":"breaking","affected_versions":">=11.0"},{"fix":"Ensure your development and deployment environment is macOS. For cross-platform thumbnail generation, consider alternatives.","message":"This library is strictly for macOS. It cannot be installed or used on other operating systems as it directly binds to macOS-specific frameworks.","severity":"gotcha","affected_versions":"All"},{"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()`.","message":"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()`).","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"breaking","affected_versions":">=11.1"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}