API

Platform Object

class v8cffi.platform._Platform[source]

V8 platform environment. The underlying platform is a singleton that must only be initialized once per process.

Should be used through platform

Variables:
  • natives_path (str) – Path to natives_blob.bin
  • snapshot_path (str) – Path to snapshot_blob.bin
create_vm()[source]

Create a VM for running JS scripts within an isolated environment

Returns:Instance of VM
Return type:VM
is_alive()[source]

Check is initialized and was not exited

Returns:Whether the platform is alive or not
Return type:bool
set_up()[source]

Initialize the V8 platform. Remember to call tear_down() before exiting the application. It’s recommended to use a with statement instead of this method to ensure clean up.

This must only be called once in an application lifetime

Raises:V8MemoryError – if there is no memory for allocating it, the process should die afterwards anyway, there is little point in catching this
tear_down()[source]

Destructs the V8 platform

v8cffi.platform.platform – Platform object (singleton)

V8 platform environment. The underlying platform is a singleton that must only be initialized once per process.

Should be used through platform

Variables:
  • natives_path (str) – Path to natives_blob.bin
  • snapshot_path (str) – Path to snapshot_blob.bin

VM Object

class v8cffi.vm.VM(platform)[source]

Holds the VM state (V8 isolate). Running scripts within a VM is thread-safe, but only a single thread will execute code at a given time (there is a Global Lock). It’s feasible to run one VM per thread or to have a pre-initialized pool.

There may be many VMs per platform

Parameters:platform (_Platform) – Initialized platform
create_context()[source]

Create a Context for running JS scripts

Returns:Instance of Context
Return type:Context
get_c_vm()[source]

@Private Return the underlying C VM

Returns:struct cdata
Return type:ffi.CData
is_alive()[source]

Check the vm is initialized and was not exited

Returns:Whether the vm is alive or not
Return type:bool
set_up()[source]

Initialize the VM. Remember to call tear_down() before exiting the application. It’s recommended to use a with statement instead of this method to ensure clean up

Raises:V8MemoryError – if there is no memory for allocating it, the process should die afterwards anyway, there is little point in catching this
tear_down()[source]

Destructs the VM

Context Object

class v8cffi.context.Context(vm)[source]

An execution environment that allows separate, unrelated, JS applications to run in a single instance of V8. It may be thought as a browser tab.

Running scripts within the same Context is thread-safe.

There may be many Contexts per VM

Parameters:vm (VM) – Initialized VM
load_libs(scripts_paths)[source]

Load script files into the context. This can be thought as the HTML script tag. The files content must be utf-8 encoded.

This is a shortcut for reading the files and pass the content to run_script()

Parameters:

scripts_paths (list) – Script file paths.

Raises:
  • OSError – If there was an error manipulating the files. This should not normally be caught
  • V8Error – if there was an error running the JS script
run_script(script, identifier='<anonymous>')[source]

Run a JS script within the context. All code is ran synchronously, there is no event loop. It’s thread-safe

Parameters:
  • script (bytes or str) – utf-8 encoded or unicode string
  • identifier (bytes or str) – utf-8 encoded or unicode string. This is used as the name of the script (ie: in stack-traces)
Returns:

Result of running the JS script

Return type:

str

Raises:

V8Error – if there was an error running the JS script

set_up()[source]

Initialize the context. Remember to call tear_down() before exiting the application. It’s recommended to use a with statement instead of this method to ensure clean up

Raises:V8MemoryError – if there is no memory for allocating it, the process should die afterwards anyway, there is little point in catching this
tear_down()[source]

Destructs the context

Shortcuts Module

v8cffi.shortcuts.set_up()[source]

Set ups the V8 machinery: platform, VM and context.

This function is not thread-safe, it must be called from a place where is guaranteed it will be called once and only once. Probably within the main-thread at import time.

v8cffi.shortcuts.get_context()[source]

Return a global V8 context.

set_up() must has been called

Returns:Global V8 context
Return type:Context