API Notes: JavaScriptCore framework

Introduction

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.

API Level

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.

A future version of these bindings might grow a simpler to use convenience API, but that is unlikely to happen soon because I have no pressing need for such an API. Contributions that make the JavaScriptCore APIs easier to use would be greatly appreciated.

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.

autoreleasing

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

with JavaScriptCore.autoreleasing(expression) as value:
   pass

is more or less equivalant to:

value = expression
try:
     pass

finally:
     JavaScriptCore.JSReleaseContext(value)

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

JSStringGetCharactersPtr

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).

JSExport

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.