Registry / pyobjc-framework-findersync

pyobjc-framework-findersync

JSON →
library12.2pypypiunverified

pyobjc-framework-findersync provides Python wrappers for the macOS FinderSync.framework, allowing Python applications to extend Finder functionality. It is part of the larger PyObjC project, which provides a bridge between Python and Objective-C, enabling Python code to interact with macOS Cocoa frameworks. The PyObjC project, including its framework wrappers, typically releases new versions in alignment with macOS SDK updates and Python version support changes.

pip install pyobjc-framework-findersync
INSTALL
IMPORT
SIG · PYOBJC-FRAMEWORK-F
P
pyobjc-framework-findersync
pythonv12.2
Install
Import
Disk
Pass rate
0/ 10
Env Coverage0 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v? · pip install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
build_error
glibc
py 3.103.920 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

FIFinderSyncController
from FinderSync import FIFinderSyncController
FIFinderSync
from FinderSync import FIFinderSync

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()
Debug
Known issues
breakingPyObjC 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).
affects: >=11.0
breakingPyObjC 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.
affects: >=11.1
gotchaIn 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.
affects: >=10.3
gotchaPrior 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.
affects: <10.1
gotchaPyObjC 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.
affects: >=11.0
Upgrade
Version history
12.2latest on PyPI · released May 30, 2026
Audit
Dependencies
pyobjc-corerequiredCore bridge for Python to Objective-C, required by all pyobjc-framework-* packages.
pyobjc-framework-AppKitoptionalProvides core UI framework bindings often used with FinderSync extensions, usually pulled in transitively.
pyobjc-framework-FoundationoptionalProvides core utility and base classes often used with FinderSync extensions, usually pulled in transitively.
Agent activity
2 hits · last 30 days
node
2
Resources
pyobjc-framework-findersync — pip install pyobjc-framework-findersync · libregistry