Javascript Context

According to the ECMAScript [1] standard, we need enter an execution context before execute any script code.

JSContext is a sandboxed execution context with its own set of built-in objects and functions.

You could create a JSContext instance, enter it with JSContext.enter(), and use it to execute code with JSContext.eval(). The best practice is to leave the context with JSContext.leave() if you never need it.

>>> ctxt = JSContext()               # create a context with an implicit global object
>>> ctxt.enter()                     # enter the context (also support with statement)
>>> ctxt.eval("1+2")                 # evalute the javascript expression and return a native python int
3
>>> ctxt.leave()                     # leave the context and release the related resources

Note

To ensure the context could be enter/leave at the right time, we suggest to use the with statement (Python 2.5 or later).

with JSContext() as ctxt:
    print ctxt.eval("1+2") # 3

You could also check the current or calling context with the static properties.

Property Description
JSContext.current The context that is on the top of the stack.
JSContext.entered The last entered context.
JSContext.calling The context of the calling JavaScript code.
JSContext.inContext Returns true if V8 has a current context.

Global Object

The execution context has a global object, which could be access from the Python side with JSContext.locals, or access from the Javascript side with the global namespace. The Python and Javascript code could use it to do seamless interoperable logic, PyV8 will automatic do the Type Conversion, Function Call and Exception Translation.

with JSContext() as ctxt:
    ctxt.eval("a = 1")
    print ctxt.locals.a     # 1

    ctxt.locals.a = 2
    print ctxt.eval("a")    # 2

If you want to provide more complicated properties and methods to the Javascript code, you could pass a customized global object instance when create the JSContext.

class Global(JSClass):
    version = "1.0"

    def hello(self, name):
        return "Hello " + name

with JSContext(Global()) as ctxt:
    print ctxt.eval("version")          # 1.0
    print ctxt.eval("hello('World')")   # Hello World
    print ctxt.eval("hello.toString()") # function () { [native code] }

Note

If you want your global object more like a real Javascript object, you should inherit from the JSClass which provides a lot of helper methods such as JSClass.toString(), JSClass.watch() etc.

Reuseable Extension

Besides the customized Global Object, there is a more powerful mechanism JSExtension which could encapsulate the related Javascript or Python script in a reusable module, and define it when create a JSContext instance.

src = 'function hello(name) { return "Hello " + name + " from Javascript"; }'
ext = JSExtension("hello/javascript", src)

with JSContext(extensions=['hello/javascript']) as ctxt:
    print ctxt.eval("hello('World')") # Hello World from Javascript

The extension also could be implement with the Python code, just like the JNI [3] for the Java.

src = "native function hello();"
ext = JSExtension("hello/python", src, lambda func: lambda name: "Hello " + name + " from Python")

with JSContext(extensions=['hello/python']) as ctxt:
    print ctxt.eval("hello('World')") # Hello World from Python

If your extensions has dependencies extensions, you could define it in JSExtension.__init__(), and check it later with the JSExtension.dependencies property. The v8 engine will load the extensions one by one base on its dependencies.

JSContext - the execution context.

class PyV8.JSContext(obj=None, extensions=None, ctxt=None)

JSContext is an execution context.

__init__(global=None, extensions=[]) → JSContext object
Parameters:
  • global (object) – the global object
  • extensions (list) – the name of extensions
Return type:

JSContext instance

__init__(ctxt) → JSContext object
Parameters:ctxt (JSContext) – an exists JSContext instance
Return type:a cloned JSContext instance
eval(source, name='', line=-1, col=-1, precompiled=None) → object:

eval( (JSContext)arg1, (str)source [, (str)name=’’ [, (int)line=-1 [, (int)col=-1 [, (object)precompiled=None]]]]) -> object :

C++ signature :
class boost::python::api::object eval(class CContext {lvalue},class std::basic_string<char,struct std::char_traits<char>,class std::allocator<char> > [,class std::basic_string<char,struct std::char_traits<char>,class std::allocator<char> >=’’ [,int=-1 [,int=-1 [,class boost::python::api::object=None]]]])

eval( (JSContext)arg1, (unicode)source [, (unicode)name=u’’ [, (int)line=-1 [, (int)col=-1 [, (object)precompiled=None]]]]) -> object :

C++ signature :
class boost::python::api::object eval(class CContext {lvalue},class std::basic_string<wchar_t,struct std::char_traits<wchar_t>,class std::allocator<wchar_t> > [,class std::basic_string<wchar_t,struct std::char_traits<wchar_t>,class std::allocator<wchar_t> >=u’’ [,int=-1 [,int=-1 [,class boost::python::api::object=None]]]])

Execute the Javascript code in source and return the result

Parameters:
  • source (str or unicode) – the Javascript code
  • name (str) – the name of the Javascript code
  • line (integer) – the start line number of the Javascript code
  • col (integer) – the start column number of the Javascript code
  • precompiled (buffer) – the precompiled buffer of Javascript code
Return type:

the result

__enter__() → JSContext object
__exit__(exc_type, exc_value, traceback) → None
current

The context that is on the top of the stack.

entered

The last entered context.

calling

The context of the calling JavaScript code.

inContext

Returns true if V8 has a current context.

enter()
enter( (JSContext)arg1) -> None :

Enter this context. After entering a context, all code compiled and run is compiled and run in this context.

C++ signature :
void enter(class CContext {lvalue})
leave()
leave( (JSContext)arg1) -> None :

Exit this context. Exiting the current context restores the context that was in place when entering the current context.

C++ signature :
void leave(class CContext {lvalue})
locals

Local variables within context

JSExtension - reusable script module

class PyV8.JSExtension

JSExtension is a reusable script module.

__init__(name, source, callback=None, dependencies=[], register=True) → JSExtension object

__init__( (object)arg1, (str)name, (str)source [, (object)callback=None [, (list)dependencies=[] [, (bool)register=True]]]) -> None :

C++ signature :
void __init__(struct _object *,class std::basic_string<char,struct std::char_traits<char>,class std::allocator<char> >,class std::basic_string<char,struct std::char_traits<char>,class std::allocator<char> > [,class boost::python::api::object=None [,class boost::python::list=[] [,bool=True]]])
Parameters:
  • name (str) – the extension name
  • source (str) – the Javascript code
  • callback (func) – the native Python code
  • dependencies (list) – the dependencies extensions
  • register (bool) – register the extension
Return type:

A reusable JSExtension module

register()
register( (JSExtension)arg1) -> None :

Register the extension

C++ signature :
void register(class CExtension {lvalue})
autoEnable

Enable the extension by default.

dependencies

The extension dependencies which will be load before this extension

name

The name of extension

registered

The extension has been registerd

source

The source code of extension

Footnotes

[1]ECMAScript is the scripting language standardized by Ecma International in the ECMA-262 specification and ISO/IEC 16262. The language is widely used for client-side scripting on the web, in the form of several well-known dialects such as JavaScript, JScript, and ActionScript.
[2]

There are three types of ECMAScript executable code:

  • Global code is source text that is treated as an ECMAScript Program.
  • Eval code is the source text supplied to the built-in eval function.
  • Function code is source text that is parsed as part of a FunctionBody.
[3]Java Native Interface (JNI) is a programming framework that enables Java code running in a Java Virtual Machine (JVM) to call and to be called[1] by native applications (programs specific to a hardware and operating system platform) and libraries written in other languages such as C, C++ and assembly.

Table Of Contents

Previous topic

Public API

Next topic

Javascript Engine

This Page