API Notes: JavaScriptCore framework


An introduction to PyObjC describes the general method for translating Objective-C calls into Python calls, including the handling of pass-by-reference arguments and buffers.

This document describes where the PyObjC bindings for this framework are different from the general rule, such as mentioning APIs that are not supported or where the interface is different than expected.

The full API is described in Apple’s documentation, both the C and Objective-C APIs are available (but see the API Notes below).

These bindings are accessed through the JavaScriptCore package (that is, import JavaScriptCore).

API Notes

The JavaScriptCore library is very low-level and the Python bindings don’t change that. This means interacting with JavaScript through these bindings require a fairly large amount of code.

Reference counting

The various JavaScriptCore types (such as JSValueRef and JSContextRef) are C types with manual reference counting. PyObjC does not manage the reference counts for you, you’ll have to call the correct retain and release functions manually to avoid leaking memory and/or crashing.


This is a context manager that makes it easier to deal with reference counts:

with JavaScriptCore.autoreleasing(expression) as value:

is more or less equivalant to:

value = expression


The actual release function used depends on the type of value.


This function is not supported. Convert the string to a Python type using JSStringCopyCFString or JSStringGetUTF8CString.

JSObjectMake, JSObjectGetPrivate, JSObjectSetPrivate

The private data of an object is a void* in (Objective-)C, and an integer in Python. Use the objc.context object to attach arbitrary data to an object:

anObj = ... #
JavaScriptCore.JSOObjectSetPrivate(anObject, objc.context.register(aValue))
aValue = objc.context.get(JavaScriptCore.JSObjectGetPrivate(anObject))

JSStaticValue, JSStaticFunction, JSClassDefinition

These structs and functions using them are not yet supported.

JSClassCreate, kJSClassDefinitionEmpty

Not supported at the moment as this requires manual wrappers (C code).


OSX 10.9 introcuded a JSExport protocol. There is a C macro for renaming the name seen in JavaScript for a given selector. That macro is not available in Python.

To use the protocol you must use a Python that’s build with OSX 10.9 or later as the deployment target.