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>()

See also

Use api.recv to access methods related to receiving files.

Example

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

See also

Use api.server to access methods for common server operations.

Example

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

See also

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=0)

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