Source

pyobjc / pyobjc-core / Doc / metadata / bridgesupport.rst

Full commit

BridgeSupport XML files

Introduction

PyObjC 2.0 introduced a way to load enhanced API descriptions from XML "bridgesupport" files. The format of this file is shared between a number of bridges, although later releases of PyObjC added more capabilities that aren't in the official format.

As of PyObjC 2.4 [1] use of bridgesupport files is deprecated, the :doc:`compiled metadata system <compiled>` allows for faster and lazy loading.

Basic structure and use

Bridgesupport files are XML files with a root element "signatures" that has child elements for various kind of API descriptions. The API descriptions contain information that cannot be extracted at runtime, such as the names and types of global variables (constants), enum labels, function prototypes and additional information about method signatures.

PyObjC supports loading bridgesupport files when initializing a module using :func:`initFrameworkWrapper`, as well as parsing the contents of bridgesupport files using :func:`parseBridgeSupport`.

The function :func:`initFrameworkWrapper` is basicly a one-step solution for wrapping a framework: it loads the framework bundle and bridgesupport file and then initializes the contents of the wrapper module. Bridgesupport files are located using a search path:

  1. "PyObjC.brigesupport" next to the module calling :func:`initFrameworkWrapper`.

  2. A resource file inside the framework itself (with suffix ".bridgesupport" and the same basename as the framework, located in subdirectory "BridgeSupport").

  3. A resource name with the same basename as the framework and suffix ".bridgesupport" in "/System/Library/BridgeSupport"

    Note

    PyObjC will not load bridgesupport files from "/Library/BridgeSupport" or "~/Library/BridgeSupport" to avoid depending on system-specif files that could make a bundled PyObjC application non-portable.

When a bridgesupport is loaded from the last two location the function also looks for "PyObjCOverrides.bridgesupport" next to the module that called :func:`initFrameworkWrapper`.

Creating a library wrapper

The easiest way to create a framework wrapper using bridgesupport files is to use a python package where the "__init__.py" contains a call of :func:`initFrameworkWrapper`

import objc as _objc

__bundle__ = _objc.initFrameworkWrapper("FrameworkName",
                     frameworkIdentifier="com.apple.Framework",
                     frameworkPath=_objc.pathForFramework("/System/Library/Frameworks/FrameworkName.framework")
                     globals=globals())

The framework name, identifier and path should be replaced by the information for the framework you are wrapping.

The :func:`initFrameworkWrapper` will load bridgesupport files from a file named "PyObjC.bridgesupport" next to the "__init__.py" when such a file exist, and otherwise from the default location in the framework itself.

Detailed file structure

API description

Footnotes

[1]Technically, deprecation started in PyObjC 2.5, the bridgesupport system was temporarily removed in PyObjC 2.4.