pymonkey — Access SpiderMonkey from Python

This module offers a low-level interface to the Mozilla SpiderMonkey JavaScript engine.

exception pymonkey.error

This is the type of any SpiderMonkey-related errors thrown by this module.

pymonkey.undefined

This is the singleton that represents the JavaScript value undefined, as Python has no equivalent representation (JavaScript’s null is mapped to Python’s None object). For instance:

>>> cx = pymonkey.Runtime().new_context()
>>> cx.evaluate_script(cx.new_object(), '', '<string>', 1)
pymonkey.undefined

This object also has a “falsy” value:

>>> if not pymonkey.undefined:
...   print "See, it's falsy!"
See, it's falsy!

class pymonkey.Object

This is the type of JavaScript objects. Such objects can only be created via Pymonkey calls like Context.new_object() or through the execution of JS code, but this type object can be used with Python’s built-in isinstance() to verify that an object is a JS object, like so:

>>> obj = pymonkey.Runtime().new_context().new_object()
>>> isinstance(obj, pymonkey.Object)
True

get_runtime()

Returns the Runtime that the object belongs to.

class pymonkey.Function

This is the type of JavaScript functions, which is a subtype of Object.

class pymonkey.Context

This is the type of JavaScript context objects. Contexts can only be created via a call to Runtime.new_context(), but this type object can be used with Python’s built-in isinstance() to verify that an object is a context, like so:

>>> cx = pymonkey.Runtime().new_context()
>>> isinstance(cx, pymonkey.Context)
True

get_runtime()

Returns the Runtime that the context belongs to.

new_object([private_obj])

Creates a new Object instance and returns it. private_obj is any Python object that is privately stored within the new JS object; it can be retrieved using get_object_private().

new_function(callable, name)

Creates a new Function instance that wraps the given Python callable. In JS-land, the function will have the given name.

When the function is executed from JavaScript, callable will be passed three positional arguments.

The first argument is a Context that represents the JS context which is calling the function.

The second argument is an Object that represents the value of this for the duration of the call.

The third argument is a tuple containing the arguments passed to the function.

For instance:

>>> def add(cx, this, args):
...   return args[0] + args[1]
>>> cx = pymonkey.Runtime().new_context()
>>> obj = cx.new_object()
>>> cx.define_property(obj, 'add', cx.new_function(add, 'add'))
>>> cx.evaluate_script(obj, 'add(1, 1);', '<string>', 1)
2

define_property(object, name, value)

Creates a new property on object, bypassing any JavaScript setters.

get_property(object, name)

Finds the specified property on object and returns its value, possibly invoking a JavaScript getter.

Example:

>>> cx = pymonkey.Runtime().new_context()
>>> obj = cx.new_object()
>>> cx.define_property(obj, 'beets', 'i like beets.')
>>> cx.get_property(obj, 'beets')
u'i like beets.'

Note also that calling this function on undefined properties yields undefined:

>>> cx.get_property(obj, 'carrots')
pymonkey.undefined

get_object_private(object)

Returns the private_obj passed to new_object() when object was first created. If it doesn’t exist, None is returned.

If object was created with new_function(), then this method returns the Python callable wrapped by object.

This functionality is useful if you want to securely represent Python objects in JS-land.

clear_object_private(object)

Clears the private_obj passed to new_object() when object was first created. If it doesn’t exist, this function returns nothing.

If object was created with new_function(), then this method effectively “unbinds” the Python callable wrapped by object. If object is later called, an exception will be raised.

evaluate_script(globalobj, code, filename, lineno)

Evaluates the text code using globalobj as the global object/scope.

It’s assumed that code is coming from the file named by filename; the first line of code is assumed to be line number lineno of filename. This metadata is very useful for debugging stack traces, exceptions, and so forth.

For example:

>>> cx = pymonkey.Runtime().new_context()
>>> obj = cx.new_object()
>>> cx.init_standard_classes(obj)
>>> cx.evaluate_script(obj, '5 * Math', '<string>', 1)
nan

call_function(thisobj, func, args)

Calls a JavaScript function.

thisobj is an Object that will be used as the value of this when the function executes, func is the Function to execute, and args is a tuple of arguments to pass to the function.

For instance:

>>> cx = pymonkey.Runtime().new_context()
>>> obj = cx.new_object()
>>> cx.init_standard_classes(obj)
>>> Math = cx.get_property(obj, 'Math')
>>> floor = cx.get_property(Math, 'floor')
>>> cx.call_function(Math, floor, (5.3,))
5

init_standard_classes(object)

Defines the standard JavaScript classes on the given Object, such as Array, eval, undefined, and so forth. For more information, see the documentation to JS_InitStandardClasses(), which this method wraps.

class pymonkey.Runtime

Creates a new JavaScript runtime. JS objects created by the runtime may only interact with other JS objects of the same runtime.

new_context()

Creates a new Context object and returns it. Contexts are best conceptualized as threads of execution in a JS runtme; each one has a program counter, a current exception state, and so forth. JS objects may be freely accessed and changed by contexts that are associated with the same JS runtime as the objects.