{"id":6130,"library":"pyobjc-framework-mailkit","title":"PyObjC MailKit Framework","description":"The `pyobjc-framework-mailkit` library provides Python wrappers for the macOS MailKit framework. MailKit allows developers to extend the functionality of Apple Mail, primarily through Mail app extensions. As part of the larger PyObjC project, it enables Python applications to interact with native macOS Objective-C APIs. The current version is 12.1, with releases typically tied to macOS SDK updates and Python version compatibility.","status":"active","version":"12.1","language":"en","source_language":"en","source_url":"https://github.com/ronaldoussoren/pyobjc","tags":["macos","cocoa","objc","framework","mail","applescript"],"install":[{"cmd":"pip install pyobjc-framework-mailkit","lang":"bash","label":"Install MailKit framework bindings"}],"dependencies":[{"reason":"Provides the core bridge between Python and Objective-C, essential for all PyObjC framework bindings.","package":"pyobjc-core"}],"imports":[{"symbol":"MKMailExtension","correct":"from MailKit import MKMailExtension"},{"symbol":"MKMessage","correct":"from MailKit import MKMessage"},{"note":"Commonly used core Cocoa class from the `Foundation` framework, often needed with `MailKit`.","symbol":"NSString","correct":"from Foundation import NSString"}],"quickstart":{"code":"import objc\nfrom Foundation import NSString, NSLog\n\n# This example demonstrates basic PyObjC usage. MailKit classes\n# (e.g., MKMailExtension) primarily function within a Mail app extension\n# context on macOS, not as standalone scripts.\n\ntry:\n    # Create a Python string\n    python_string = \"Hello from PyObjC MailKit environment!\"\n\n    # Convert it to an Objective-C NSString using a convenience method\n    objc_string = NSString.stringWithString_(python_string)\n\n    # Log the Objective-C string using NSLog\n    NSLog(\"%@\", objc_string)\n\n    print(f\"Python string: {python_string} (type: {type(python_string)})\")\n    print(f\"Objective-C NSString: {objc_string} (type: {type(objc_string)})\")\n    print(f\"Length of NSString: {objc_string.length()}\")\n\n    # Attempting to import a MailKit class to show the pattern\n    # from MailKit import MKMailExtension # This import might fail if not specifically linked or on older macOS\n    # if 'MKMailExtension' in globals():\n    #     print(\"MKMailExtension class is available (but requires Mail extension context for use).\")\n    # else:\n    #     print(\"MKMailExtension class not directly available in this standalone context (expected).\")\n\nexcept Exception as e:\n    print(f\"An error occurred during PyObjC interaction: {e}\")\n    print(\"Ensure you are on macOS and the PyObjC environment is correctly set up.\")","lang":"python","description":"This quickstart demonstrates basic Objective-C object interaction using `Foundation.NSString` via PyObjC. While it doesn't directly use a MailKit class, it shows the general pattern for importing and interacting with Objective-C frameworks. MailKit classes, such as `MKMailExtension`, are typically instantiated and used within the specific context of a Mail app extension on macOS, and not as standalone Python scripts."},"warnings":[{"fix":"Upgrade your Python interpreter to a supported version (e.g., Python 3.10+ for PyObjC 12.1).","message":"PyObjC versions drop support for older Python versions. Version 12.0 dropped Python 3.9, and Version 11.0 dropped Python 3.8. Ensure your Python environment meets the minimum requirements for your PyObjC version.","severity":"breaking","affected_versions":">=11.0"},{"fix":"Review any custom `init` methods in your PyObjC classes and ensure your memory management logic (especially for reference counts if manually managed) is consistent with ARC principles for initializers.","message":"Version 11.1 introduced a significant change in how PyObjC models Automatic Reference Counting (ARC) behavior for initializer methods (those in the 'init' family). This aligns PyObjC with clang's ARC documentation, meaning methods now correctly 'steal' a reference to `self` and return a new one, which might affect memory management logic in existing code.","severity":"breaking","affected_versions":">=11.1"},{"fix":"If encountering issues with `__init__` and `__new__`, ensure you are on PyObjC 10.3.1 or newer. When implementing custom `__new__`, carefully consider `__init__` usage according to Python's object model and PyObjC's specifics.","message":"In PyObjC 10.3, a change in `__init__` behavior when a class implements `__new__` could lead to unexpected issues. This was partially addressed in 10.3.1, which restored the ability to use `__init__` in such cases, but still advises against using `__init__` when relying on PyObjC's provided `__new__`.","severity":"gotcha","affected_versions":"10.3 - 10.3.1"},{"fix":"Before upgrading PyObjC or macOS, check the release notes for removed framework bindings. Update your code to use current and supported macOS APIs.","message":"PyObjC removes bindings for frameworks deprecated and removed by macOS. For example, the 'IMServicePlugIn' framework bindings were removed in PyObjC 10.0 because the framework was removed in macOS 14. This can lead to `ImportError` or `AttributeError` if attempting to use removed APIs.","severity":"breaking","affected_versions":">=10.0"},{"fix":"Always install PyObjC on a macOS version that corresponds to the PyObjC version's target SDK. Keep your Xcode Command Line Tools updated to match your macOS version.","message":"PyObjC versions are tightly coupled with specific macOS SDKs. Upgrading PyObjC often requires upgrading your macOS version and/or Xcode Command Line Tools to ensure compatibility with the framework bindings. Using an older macOS with a newer PyObjC might result in missing symbols or runtime errors.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}