PyObjC Framework FinderSync

Warnings

• breaking PyObjC versions frequently drop support for older Python versions. PyObjC 12.0 dropped Python 3.9 support, and PyObjC 11.0 dropped Python 3.8 support. Future versions will likely continue this trend.
  Fix: Upgrade to a supported Python version (e.g., Python 3.10+ for PyObjC 12.x).
• breaking PyObjC 11.1 aligned its internal behavior for 'init' methods with clang's Automatic Reference Counting (ARC) documentation. This means 'init' methods are now correctly modeled as stealing a reference to self and returning a new reference, potentially affecting custom memory management logic or bridging in older code.
  Fix: Review custom 'init' method implementations, especially those interacting with manual memory management, to ensure compatibility with ARC-compliant reference counting. Most pure Python usage should be unaffected unless directly managing Objective-C object lifetimes.
• gotcha In PyObjC 10.3, calling __init__ on PyObjC-proxied classes was restricted when the class relies on PyObjC's provided __new__. While partially re-enabled in 10.3.1 for user-implemented __new__, code relying on PyObjC's __new__ still cannot use __init__. Instead, use Objective-C style initialization (e.g., MyClass.alloc().init()) or override __new__ and handle initialization there.
  Fix: For classes using PyObjC's default __new__, use Objective-C style initialization (alloc().init()). If you need __init__, ensure your class or a superclass provides its own __new__ implementation.
• gotcha Prior to PyObjC 10.1, `os.fspath()` did not work correctly with Cocoa `NSURL` objects (or `CFURLRef`) that referred to local filesystem paths, raising a `TypeError` for other URL types. While fixed in 10.1, older PyObjC versions required manual path conversion for `NSURL` objects.
  Fix: Upgrade to PyObjC 10.1 or later. Alternatively, manually convert `NSURL` to a Python path string using `url.path()` for `file://` URLs.
• gotcha PyObjC 11.0 introduced experimental support for free-threading (PEP 703) in Python 3.13. However, PyObjC does not fully support the experimental free threading in Python 3.13, which required significant changes in its core. Exercise caution and thoroughly test any code running with free-threading enabled.
  Fix: If encountering issues with free-threading in Python 3.13, consider disabling free-threading or using a different Python version until PyObjC provides full and stable support.

Install

• pip install pyobjc-framework-findersync Install pyobjc-framework-findersync

Imports

• FIFinderSyncController

  from FinderSync import FIFinderSyncController

• FIFinderSync

  from FinderSync import FIFinderSync

Quickstart

This quickstart demonstrates how to define a Python class as a delegate for the `FIFinderSync` protocol and how to configure the `FIFinderSyncController`. Note that a Finder Sync Extension must be packaged within a macOS application bundle and configured via its `Info.plist` to be loaded by the Finder. This script is for illustrative purposes and will not register a functional Finder Sync extension by itself.

import objc
from FinderSync import FIFinderSync, FIFinderSyncController
from Foundation import NSURL
import os

class MyFinderSyncDelegate(FIFinderSync):
    """
    A minimal Finder Sync delegate class.
    In a real Finder Sync Extension, this class would implement methods
    like `requestBadgeIdentifierForURL_` or `toolbarItemImageForURL_`.
    """
    def init(self):
        self = objc.super().init()
        print("MyFinderSyncDelegate initialized.")
        return self

    # Example: You would implement FinderSync methods here.
    # def requestBadgeIdentifierForURL_(self, url):
    #     print(f"Requesting badge for: {url}")
    #     return "MyBadgeIdentifier" # Define this in Info.plist

def setup_finder_sync():
    """
    Illustrates how to configure the Finder Sync Controller.
    Note: This script itself cannot become a Finder Sync Extension.
    A Finder Sync Extension must be embedded within a host application
    bundle and configured via its Info.plist to be loaded by Finder.
    This code demonstrates the PyObjC API usage within such an extension.
    """
    controller = FIFinderSyncController.sharedExtensionController()

    if controller:
        # Create an instance of our delegate
        delegate_instance = MyFinderSyncDelegate.alloc().init()
        controller.setDelegate_(delegate_instance)

        # Specify directories to monitor
        # For demonstration, let's try to monitor the user's Downloads folder
        downloads_path = os.path.expanduser("~/Downloads")
        downloads_url = NSURL.fileURLWithPath_(downloads_path)

        controller.setDirectoryURLs_([downloads_url])

        print(f"FinderSyncController delegate set: {controller.delegate()}")
        print(f"Watching directories: {controller.directoryURLs()}")
        print("\nNote: For this to take effect, this code must be run from within")
        print("a properly configured macOS Finder Sync Extension bundle.")
        print("Simply running this Python script will not register the extension.")
    else:
        print("FIFinderSyncController.sharedExtensionController() returned None.")
        print("This usually means the code is not running within a Finder Sync Extension process.")
        print("A Finder Sync Extension requires specific macOS bundle setup to function.")

if __name__ == "__main__":
    setup_finder_sync()