# API Notes: JavaScriptCore framework

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.

### `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.