Host¶

class stencila.Host[source]¶

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. PythonContext, 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 HostHttpServer. 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¶

Get the identifier of the Host

Returns:	An identification string

key¶

Get the seurity key for this Host

Returns:	A key string

user_dir()[source]¶

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.

Returns:	A filesystem path

temp_dir()[source]¶

Get the current Stencila temporary directory.

Returns:	A filesystem path

environs()[source]¶

types()[source]¶

manifest()[source]¶

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

register()[source]¶: Registration 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.

startup(environ)[source]¶

shutdown(host)[source]¶

create(type, args={})[source]¶

Create a new instance of a type

Parameters:	type – Type of instance args – Arguments to be passed to type constructor
Returns:	Name of newly created instance

get(name)[source]¶

Get an instance

Parameters:	name – Name of instance
Returns:	The instance

call(name, method, arg=None)[source]¶

Call a method of an instance

Parameters:	name – Name of instance method – Name of instance method kwargs – A dictionary of method arguments
Returns:	Result of method call

delete(name)[source]¶

Delete an instance

Parameters:	name – Name of instance

start(address='127.0.0.1', port=2000, quiet=False)[source]¶

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)[source]¶

Stop serving this host

Returns:	self

run(address='127.0.0.1', port=2000)[source]¶: Start serving this host and wait for connections indefinitely

spawn()[source]¶

servers¶

Get a list of servers for this host.

Currenty, only a HostHttpServer is implemented but in the future onther servers for a host may be added (e.g. HostWebsocketServer)

Returns:	A dictionary of server details

generate_token(host=None)[source]¶

Generate a request token.

Returns:	A JWT token string

authorize_token(token)[source]¶

Authorize a request token.

Throws an error if the token is invalid.

Parameters:	token – A JWT token string

view()[source]¶

View this host in the browser

Opens the default browser at the URL of this host