{"id":5804,"library":"pyobjc-framework-corelocation","title":"CoreLocation Framework for PyObjC","description":"pyobjc-framework-corelocation provides Python wrappers for Apple's CoreLocation framework on macOS. It is part of the PyObjC project, a bidirectional bridge enabling Python scripts to interact with Objective-C libraries, including macOS Cocoa frameworks. This framework offers interfaces for obtaining a machine's physical location, allowing for geo-aware applications. The current version is 12.1 and it maintains an active release cadence, typically aligning with macOS SDK updates and Python version support.","status":"active","version":"12.1","language":"en","source_language":"en","source_url":"https://github.com/ronaldoussoren/pyobjc","tags":["macos","objective-c","framework","location","corelocation"],"install":[{"cmd":"pip install pyobjc-framework-corelocation","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core component of the PyObjC bridge, providing fundamental Python-Objective-C interoperability.","package":"pyobjc-core","optional":false},{"reason":"Provides core Cocoa framework bindings often implicitly relied upon by other frameworks for fundamental Objective-C classes (e.g., Foundation.NSRunLoop).","package":"pyobjc-framework-cocoa","optional":false}],"imports":[{"note":"Classes and functions within the CoreLocation framework are then accessed as attributes of the imported module (e.g., CoreLocation.CLLocationManager).","symbol":"CoreLocation","correct":"import CoreLocation"}],"quickstart":{"code":"import objc\nfrom CoreLocation import CLGeocoder\nfrom Foundation import NSRunLoop, NSDate, NSObject\nimport time\n\n\nclass GeocoderDelegate(NSObject):\n    # This is a delegate class to handle geocoding results asynchronously.\n    # In a real application, you might use a more robust threading/event loop setup.\n    def init(self):\n        self = super(GeocoderDelegate, self).init()\n        if not self: return None\n        self.results = {\"placemarks\": [], \"error\": None}\n        self.completed = False\n        return self\n\n    def geocoder_didGeocodePlacemarks_error_(self, geocoder, placemarks, error):\n        if error:\n            self.results[\"error\"] = error.localizedDescription()\n        elif placemarks:\n            self.results[\"placemarks\"] = placemarks\n        self.completed = True\n\ndef forward_geocode(address: str) -> list[dict]:\n    with objc.autorelease_pool():\n        geocoder = CLGeocoder.alloc().init()\n        delegate = GeocoderDelegate.alloc().init()\n        \n        # Call the Objective-C method with a Python delegate\n        geocoder.geocodeAddressString_completionHandler_(address, \n            lambda placemarks, error: delegate.geocoder_didGeocodePlacemarks_error_(geocoder, placemarks, error))\n\n        # Keep the runloop active until the geocoding is complete\n        # This is a blocking loop for demonstration; for GUI apps, the main runloop handles this.\n        timeout = time.time() + 10  # 10-second timeout\n        while not delegate.completed and time.time() < timeout:\n            NSRunLoop.currentRunLoop().runMode_beforeDate_(\n                \"NSDefaultRunLoopMode\", NSDate.dateWithTimeIntervalSinceNow_(0.1)\n            )\n        \n        if not delegate.completed:\n            raise TimeoutError(\"Geocoding request timed out.\")\n\n        if delegate.results[\"error\"]:\n            raise Exception(f\"Geocoding error: {delegate.results['error']}\")\n\n        formatted_results = []\n        for pm in delegate.results[\"placemarks\"]:\n            loc = pm.location()\n            if loc:\n                coord = loc.coordinate()\n                formatted_results.append({\n                    \"latitude\": coord.latitude,\n                    \"longitude\": coord.longitude,\n                    \"name\": pm.name(),\n                    \"locality\": pm.locality(),\n                    \"country\": pm.country()\n                })\n        return formatted_results\n\nif __name__ == \"__main__\":\n    try:\n        locations = forward_geocode(\"1 Infinite Loop, Cupertino, CA\")\n        if locations:\n            print(\"\\nLocation found:\")\n            for loc in locations:\n                for key, value in loc.items():\n                    if value:\n                        print(f\"  {key}: {value}\")\n        else:\n            print(\"No locations found.\")\n    except Exception as e:\n        print(f\"Error: {e}\")","lang":"python","description":"This quickstart demonstrates how to perform forward geocoding using `CLGeocoder` from the `CoreLocation` framework. It shows the typical PyObjC pattern of initializing Objective-C objects, setting up a Python delegate to handle asynchronous callbacks, and running a `NSRunLoop` to process events until the operation completes. Note that CoreLocation APIs require network access for geocoding and user permission prompts on macOS."},"warnings":[{"fix":"Upgrade your Python environment to Python 3.10 or later for PyObjC 12.x. Always check `requires_python` on PyPI or the PyObjC changelog for specific version requirements.","message":"PyObjC frequently drops support for older Python versions. PyObjC 12.0 dropped support for Python 3.9, and PyObjC 11.0 dropped Python 3.8. Ensure your Python version is compatible with the PyObjC version you are installing.","severity":"breaking","affected_versions":"11.0, 12.0"},{"fix":"Review code that interacts with object initialization, especially custom subclasses or factory methods, to ensure correct reference handling. Explicit memory management is rarely needed in Python, but understanding the underlying Objective-C semantics is crucial for correct behavior.","message":"PyObjC 11.1 changed how initializer methods (`init` family) are modeled, now correctly reflecting that they 'steal' a reference to `self` and return a new one, as per clang's ARC documentation. This affects object lifecycle and reference counting.","severity":"breaking","affected_versions":">=11.1"},{"fix":"Only use `pyobjc-framework-corelocation` in macOS environments. Attempting to install or run on Windows/Linux will result in errors.","message":"PyObjC is a macOS-specific library and will not install or run on other operating systems. The frameworks it wraps (like CoreLocation) are Apple-proprietary and only available on macOS.","severity":"gotcha","affected_versions":"all"},{"fix":"Always check for `None` before calling methods on PyObjC-wrapped objects that might originate from Objective-C `nil` values. E.g., `if my_obj is not None: my_obj.doSomething_()`.","message":"Unlike Objective-C, where sending a message to `nil` (equivalent to Python `None`) is a no-op, attempting to call a method on a Python `None` object (which PyObjC translates from `nil`) will raise an `AttributeError`.","severity":"gotcha","affected_versions":"all"},{"fix":"Ensure your macOS application bundle is properly signed. Handle user permission requests gracefully in your application logic. Location services may not function as expected in scripts run directly without a proper application context.","message":"CoreLocation services require specific user permissions and proper binary signing on macOS. Unsigned or ad-hoc signed applications may not be able to access location data, and users will be prompted for permission upon first access.","severity":"gotcha","affected_versions":"all"},{"fix":"For console applications or background threads, ensure you start and periodically run `NSRunLoop.currentRunLoop().runMode_beforeDate_()` to allow CoreLocation to deliver updates to your delegate.","message":"CoreLocation delegate methods are invoked on the `NSRunLoop` of the thread where the `CLLocationManager` object was initialized. If you are not in a GUI application's main thread, you must explicitly run a `NSRunLoop` for delegate callbacks to be processed.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}