Host

class stencila.Host

A Host allows you to create, get, run methods of, and delete instances of various types. The types can be thought of a “services” provided by the host e.g. NoteContext, FilesystemStorer

The API of a host is similar to that of a HTTP server. It’s methods names (e.g. post, get) are similar to HTTP methods (e.g. POST, GET) but the sematics sometimes differ (e.g. a host’s put() method is used to call an instance method)

A Host is not limited to beng served by HTTP and it’s methods are exposed by both HostHttpServer and HostWebsocketServer. Those other classes are responsible for tasks associated with their communication protocol (e.g. serialising and deserialising objects).

This is a singleton class. There should only ever be one Host in memory in each process (although, for purposes of testing, this is not enforced)

id

user_dir()

Get the current user’s Stencila data directory.

This is the directory that Stencila configuration settings, such as the installed Stencila hosts, and document buffers get stored.

temp_dir()

Get the current Stencila temporary directory

environ()

Get the environment of this host including the version of Node.js and versions of installed packages (local and globals)

Returns:The environment as a dictionary of dictionaries

manifest()

Get a manifest for this host

The manifest describes the host and it’s capabilities. It is used by peer hosts to determine which “types” this host provides and which “instances” have already been instantiated.

Returns:A manifest object

install()

Installation of a host involves creating a file py.json inside of the user’s Stencila data (see user_dir()) directory which describes the capabilities of this host.

post(type, name=None, options={})

Create a new instance of a type

Parameters:

• type – Type of instance
• name – Name of new instance
• options – Additional arguments to pass to constructor

Returns:

Address of newly created instance

get(id)

Get an instance

Parameters:id – ID of instance Returns:The instance

put(id, method, kwargs={})

Call a method of an instance

Parameters:

• id – ID of instance
• method – Name of instance method
• kwargs – A dictionary of method arguments

Returns:

Result of method call

delete(id)

Delete an instance

Parameters:id – ID of instance

start(address='127.0.0.1', port=2000, authorization=True, quiet=False)

Start serving this host

Currently, HTTP is the only server available for hosts. We plan to implement a HostWebsocketServer soon.

Returns:self

stop(quiet=False)

Stop serving this host

Returns:self

run(address='127.0.0.1', port=2000, authorization=True, quiet=False, echo=False)

Start serving this host and wait for connections indefinitely

servers

urls

view()

View this host in the browser

Opens the default browser at the URL of this host