Context#

class Context(**properties: Any)#

Superclasses: Object

JSCContext represents a JavaScript execution context, where all operations take place and where the values will be associated.

When a new context is created, a global object is allocated and the built-in JavaScript objects (Object, Function, String, Array) are populated. You can execute JavaScript in the context by using evaluate() or evaluate_with_source_uri(). It’s also possible to register custom objects in the context with register_class().

Constructors#

class Context
classmethod new() → Context#

Create a new Context. The context is created in a new VirtualMachine. Use new_with_virtual_machine() to create a new Context in an existing VirtualMachine.

classmethod new_with_virtual_machine(vm: VirtualMachine) → Context#

Create a new Context in virtual_machine.

Parameters:

vm – a VirtualMachine

Methods#

class Context
check_syntax(code: str, length: int, mode: CheckSyntaxMode, uri: str, line_number: int) → tuple[CheckSyntaxResult, Exception]#

Check the given code in context for syntax errors. The line_number is the starting line number in uri; the value is one-based so the first line is 1. uri and line_number are only used to fill the exception. In case of errors exception will be set to a new Exception with the details. You can pass None to exception to ignore the error details.

Parameters:

  • code – a JavaScript script to check

  • length – length of code, or -1 if code is a nul-terminated string

  • mode – a CheckSyntaxMode

  • uri – the source URI

  • line_number – the starting line number

clear_exception() → None#

Clear the uncaught exception in context if any.

evaluate(code: str, length: int) → Value#

Evaluate code in context.

Parameters:

  • code – a JavaScript script to evaluate

  • length – length of code, or -1 if code is a nul-terminated string

evaluate_in_object(code: str, length: int, object_instance: Any, object_class: Class | None, uri: str, line_number: int) → tuple[Value, Value]#

Evaluate code and create an new object where symbols defined in code will be added as properties, instead of being added to context global object. The new object is returned as object parameter. Similar to how new_object() works, if object_instance is not None object_class must be provided too. The line_number is the starting line number in uri; the value is one-based so the first line is 1. uri and line_number will be shown in exceptions and they don’t affect the behavior of the script.

Parameters:

  • code – a JavaScript script to evaluate

  • length – length of code, or -1 if code is a nul-terminated string

  • object_instance – an object instance

  • object_class – a Class or None to use the default

  • uri – the source URI

  • line_number – the starting line number

evaluate_with_source_uri(code: str, length: int, uri: str, line_number: int) → Value#

Evaluate code in context using uri as the source URI. The line_number is the starting line number in uri; the value is one-based so the first line is 1. uri and line_number will be shown in exceptions and they don’t affect the behavior of the script.

Parameters:

  • code – a JavaScript script to evaluate

  • length – length of code, or -1 if code is a nul-terminated string

  • uri – the source URI

  • line_number – the starting line number

classmethod get_current() → Context | None#

Get the Context that is currently executing a function. This should only be called within a function or method callback, otherwise None will be returned.

get_exception() → Exception | None#

Get the last unhandled exception thrown in context by API functions calls.

get_global_object() → Value#

Get a Value referencing the context global object

get_value(name: str) → Value#

Get a property of context global object with name.

Parameters:

name – the value name

get_virtual_machine() → VirtualMachine#

Get the VirtualMachine where context was created.

pop_exception_handler() → None#

Remove the last ExceptionHandler previously pushed to context with push_exception_handler().

push_exception_handler(handler: Callable[[Context, Exception, Any], None], user_data: Any = None) → None#

Push an exception handler in context. Whenever a JavaScript exception happens in the Context, the given handler will be called. The default ExceptionHandler simply calls throw_exception() to throw the exception to the Context. If you don’t want to catch the exception, but only get notified about it, call throw_exception() in handler like the default one does. The last exception handler pushed is the only one used by the Context, use pop_exception_handler() to remove it and set the previous one. When handler is removed from the context, destroy_notify i called with user_data as parameter.

Parameters:

  • handler – a ExceptionHandler

  • user_data – user data to pass to handler

register_class(name: str, parent_class: Class | None = None, vtable: ClassVTable | None = None, destroy_notify: Callable[[Any], None] | None = None) → Class#

Register a custom class in context using the given name. If the new class inherits from another Class, the parent should be passed as parent_class, otherwise None should be used. The optional vtable parameter allows to provide a custom implementation for handling the class, for example, to handle external properties not added to the prototype. When an instance of the Class is cleared in the context, destroy_notify is called with the instance as parameter.

Parameters:

  • name – the class name

  • parent_class – a Class or None

  • vtable – an optional ClassVTable or None

  • destroy_notify – a destroy notifier for class instances

set_value(name: str, value: Value) → None#

Set a property of context global object with name and value.

Parameters:

  • name – the value name

  • value – a Value

throw(error_message: str) → None#

Throw an exception to context using the given error message. The created Exception can be retrieved with get_exception().

Parameters:

error_message – an error message

throw_exception(exception: Exception) → None#

Throw exception to context.

Parameters:

exception – a Exception

throw_with_name(error_name: str, error_message: str) → None#

Throw an exception to context using the given error name and message. The created Exception can be retrieved with get_exception().

Parameters:

  • error_name – the error name

  • error_message – an error message

Properties#

class Context
props.virtual_machine: VirtualMachine#

The type of the None singleton.