APIInterface¶

class jetstream.apiinterface.APIInterface(socket_interface, sync_interface, logging_interface, listen=False)¶

This is the primary API interface for JetStream. The methods on the API interface are used to establish a connection to a JetStream server.

An APIInterface should be constructed from the JetStream API factory.

Example

api_interface = JetStream().api()

There are two ways to connect to a JetStream server.

First, you can use the connect and disconnect methods.

Example

api_interface.connect()

# Issue commands.

api_interface.disconnect()

Or, you can use the interface as a context manager.

Example

with api_interface:
    # Issue commands.

The API interface exposes additional interfaces to control the different aspects of a JetStream server. These interfaces are accessed through their respective namespaces.

Use api.send to access methods related to sending files.

Example

api = JetStream().api()
api.send.<method>()

Attributes¶

APIInterface.api_version¶

The API version supported by the currently connected server.

This is used by the API interfaces to determine whether they are compatible with the connected server. If a method is not compatible with the reported API version it will raise ApiVersionError.

APIInterface.serverAddress¶

Returns the server address used for this connection.

This property is read only. It must be assigned from connect().

APIInterface.serverPort¶

Returns the server port used for this connection.

This property is read only. It must be assigned from connect().

APIInterface.timeoutSeconds¶

Returns the timeout, in seconds, used to terminate blocking commands.

This property is read only. It must be assigned from connect().

Note

Timeout functionality is currently unimplemented.

Method Summary¶

`connect`	Connects to a JetStream server.
`disconnect`	Immediately disconnects this interface from the JetStream server.
`get_cipher`	Returns a three-value tuple containing the name of the cipher being used, the version of the SSL protocol that defines its use, and the number of secret bits being used.
`get_listen_socket`	Get a low level listening socket for API connections from JetStream server.
`get_server_certificate`	Returns server’s certificate as a PEM-encoded string if secure connection is established; else returns None
`get_server_certificate_info`	Returns server’s certificate info as a dict if secure connection is established; else returns None
`is_connected`	Returns True if this API interface is connected; else returns False.
`is_secured`	Returns True if this API interface is secured; else returns False.
`listen`	Listens for a connection from JetStream server.
`secure_socket`	Wrap the given socket in SSL.
`send_command`	Sends a raw API command to the server, returning the response

Method Documentation¶

APIInterface.connect(serverAddress=NULL, serverPort=NULL, timeoutSeconds=NULL, certificatePath=NULL, sslCertificateRequirements=VerifyMode.CERT_NONE)¶

Connects to a JetStream server.

If this interface is already connected, calling this method will fail.

Note

Timeout functionality is currently unimplemented.

Parameters

serverAddress (str) – The address (host name) of the server to connect to.
serverPort (int) – The port on which to connect.
timeoutSeconds (float) – A timeout, in seconds, used to terminate blocking commands. If unassigned, blocking commands will never unblock.
certificatePath (str) – Certificate of the JetStream server you are connecting to. Setting the certificatePath implies strict SSL certificate checks.
sslCertificateRequirements (int) – Level of strictness when checking SSL certificates. Can be one of: ssl.CERT_NONE (0), ssl.CERT_OPTIONAL (1), or ssl.CERT_REQUIRED (2).

APIInterface.disconnect()¶

Immediately disconnects this interface from the JetStream server.

If this interface is not connected to a JetStream server, this does nothing.

APIInterface.get_cipher()¶: Returns a three-value tuple containing the name of the cipher being used, the version of the SSL protocol that defines its use, and the number of secret bits being used. If no secure connection has been established, returns None.

APIInterface.get_listen_socket(listenAddress=NULL, listenPort=NULL, timeoutSeconds=NULL, certificatePath=NULL)¶

Get a low level listening socket for API connections from JetStream server.

This is useful when JetStream server started with --api-connect argument. If this interface is already connected, calling this method will fail.

Parameters

listenAddress (str) – The address (host name) to listen on for incoming connections.
listenPort (int) – The port on which to listen.
timeoutSeconds (float) – A timeout, in seconds, used to terminate blocking commands. If unassigned, blocking commands will never unblock.
certificatePath (str) – Certificate of the JetStream server you are connecting to.

APIInterface.get_server_certificate()¶: Returns server’s certificate as a PEM-encoded string if secure connection is established; else returns None

APIInterface.get_server_certificate_info()¶: Returns server’s certificate info as a dict if secure connection is established; else returns None

APIInterface.is_connected()¶: Returns True if this API interface is connected; else returns False.

APIInterface.is_secured()¶: Returns True if this API interface is secured; else returns False.

APIInterface.listen(listenAddress=NULL, listenPort=NULL, timeoutSeconds=NULL, certificatePath=NULL)¶

Listens for a connection from JetStream server.

This is useful when JetStream server started with --api-connect argument. If this interface is already connected, calling this method will fail.

Note

Timeout functionality is currently unimplemented.

Parameters

listenAddress (str) – The address (host name) to listen on for incoming connections.
listenPort (int) – The port on which to listen.
timeoutSeconds (float) – A timeout, in seconds, used to terminate blocking commands. If unassigned, blocking commands will never unblock.
certificatePath (str) – Certificate of the JetStream server you are connecting to.

APIInterface.secure_socket(socket)¶

Wrap the given socket in SSL.

This is useful for securing sockets when listening for incoming connections with get_listen_socket().

Parameters: socket (socketobject) – The socket to secure.

APIInterface.send_command(command, options=None)¶: Sends a raw API command to the server, returning the response