SAMPClient

class astropy.samp.SAMPClient(hub, name=None, description=None, metadata=None, addr=None, port=0, callable=True)

Bases: object

Utility class which provides facilities to create and manage a SAMP compliant XML-RPC server that acts as SAMP callable client application.

Parameters:

hub : SAMPHubProxy

An instance of SAMPHubProxy to be used for messaging with the SAMP Hub.

name : str, optional

Client name (corresponding to samp.name metadata keyword).

description : str, optional

Client description (corresponding to samp.description.text metadata keyword).

metadata : dict, optional

Client application metadata in the standard SAMP format.

addr : str, optional

Listening address (or IP). This defaults to 127.0.0.1 if the internet is not reachable, otherwise it defaults to the host name.

port : int, optional

Listening XML-RPC server socket port. If left set to 0 (the default), the operating system will select a free port.

callable : bool, optional

Whether the client can receive calls and notifications. If set to False, then the client can send notifications and calls, but can not receive any.

Attributes Summary

is_registered	Whether the client is currently registered.
is_running	Whether the client is currently running.

Methods Summary

bind_receive_call(mtype, function[, …])	Bind a specific MType call to a function or class method.
bind_receive_message(mtype, function[, …])	Bind a specific MType to a function or class method, being intended for a call or a notification.
bind_receive_notification(mtype, function[, …])	Bind a specific MType notification to a function or class method.
bind_receive_response(msg_tag, function)	Bind a specific msg-tag response to a function or class method.
declare_metadata([metadata])	Declare the client application metadata supported.
declare_subscriptions([subscriptions])	Declares the MTypes the client wishes to subscribe to, implicitly defined with the MType binding methods bind_receive_notification() and bind_receive_call().
get_private_key()	Return the client private key used for the Standard Profile communications obtained at registration time (samp.private-key).
get_public_id()	Return public client ID obtained at registration time (samp.self-id).
receive_call(private_key, sender_id, msg_id, …)	Standard callable client receive_call method.
receive_notification(private_key, sender_id, …)	Standard callable client receive_notification method.
receive_response(private_key, responder_id, …)	Standard callable client receive_response method.
register()	Register the client to the SAMP Hub.
start()	Start the client in a separate thread (non-blocking).
stop([timeout])	Stop the client.
unbind_receive_call(mtype[, declare])	Remove from the calls binding table the specified MType and unsubscribe the client from it (if required).
unbind_receive_notification(mtype[, declare])	Remove from the notifications binding table the specified MType and unsubscribe the client from it (if required).
unbind_receive_response(msg_tag)	Remove from the responses binding table the specified message-tag.
unregister()	Unregister the client from the SAMP Hub.

Attributes Documentation

is_registered

Whether the client is currently registered.

is_running

Whether the client is currently running.

Methods Documentation

bind_receive_call(mtype, function, declare=True, metadata=None)

Bind a specific MType call to a function or class method.

The function must be of the form:

def my_function_or_method(<self,> private_key, sender_id, msg_id,
                          mtype, params, extra)

where private_key is the client private-key, sender_id is the notification sender ID, msg_id is the Hub message-id, mtype is the message MType, params is the message parameter set (content of "samp.params") and extra is a dictionary containing any extra message map entry. The client is automatically declared subscribed to the MType by default.

Parameters:

mtype : str

MType to be caught.

function : callable

Application function to be used when mtype is received.

declare : bool, optional

Specify whether the client must be automatically declared as subscribed to the MType (see also declare_subscriptions()).

metadata : dict, optional

Dictionary containing additional metadata to declare associated with the MType subscribed to (see also declare_subscriptions()).

bind_receive_message(mtype, function, declare=True, metadata=None)

Bind a specific MType to a function or class method, being intended for a call or a notification.

The function must be of the form:

def my_function_or_method(<self,> private_key, sender_id, msg_id,
                          mtype, params, extra)

where private_key is the client private-key, sender_id is the notification sender ID, msg_id is the Hub message-id (calls only, otherwise is None), mtype is the message MType, params is the message parameter set (content of "samp.params") and extra is a dictionary containing any extra message map entry. The client is automatically declared subscribed to the MType by default.

Parameters:

mtype : str

MType to be caught.

function : callable

Application function to be used when mtype is received.

declare : bool, optional

Specify whether the client must be automatically declared as subscribed to the MType (see also declare_subscriptions()).

metadata : dict, optional

Dictionary containing additional metadata to declare associated with the MType subscribed to (see also declare_subscriptions()).

bind_receive_notification(mtype, function, declare=True, metadata=None)

Bind a specific MType notification to a function or class method.

The function must be of the form:

def my_function_or_method(<self,> private_key, sender_id, mtype,
                          params, extra)

where private_key is the client private-key, sender_id is the notification sender ID, mtype is the message MType, params is the notified message parameter set (content of "samp.params") and extra is a dictionary containing any extra message map entry. The client is automatically declared subscribed to the MType by default.

Parameters:

mtype : str

MType to be caught.

function : callable

Application function to be used when mtype is received.

declare : bool, optional

Specify whether the client must be automatically declared as subscribed to the MType (see also declare_subscriptions()).

metadata : dict, optional

Dictionary containing additional metadata to declare associated with the MType subscribed to (see also declare_subscriptions()).

bind_receive_response(msg_tag, function)

Bind a specific msg-tag response to a function or class method.

The function must be of the form:

def my_function_or_method(<self,> private_key, responder_id,
                          msg_tag, response)

where private_key is the client private-key, responder_id is the message responder ID, msg_tag is the message-tag provided at call time and response is the response received.

Parameters:

msg_tag : str

Message-tag to be caught.

function : callable

Application function to be used when msg_tag is received.

declare_metadata(metadata=None)

Declare the client application metadata supported.

Parameters:

metadata : dict, optional

Dictionary containing the client application metadata as defined in the SAMP definition document. If omitted, then no metadata are declared.

declare_subscriptions(subscriptions=None)

Declares the MTypes the client wishes to subscribe to, implicitly defined with the MType binding methods bind_receive_notification() and bind_receive_call().

An optional subscriptions map can be added to the final map passed to the declare_subscriptions() method.

Parameters:

subscriptions : dict, optional

Dictionary containing the list of MTypes to subscribe to, with the same format of the subscriptions map passed to the declare_subscriptions() method.

get_private_key()

Return the client private key used for the Standard Profile communications obtained at registration time (samp.private-key).

Returns:

key : str

Client private key.

get_public_id()

Return public client ID obtained at registration time (samp.self-id).

Returns:

id : str

Client public ID.

receive_call(private_key, sender_id, msg_id, message)

Standard callable client receive_call method.

This method is automatically handled when the bind_receive_call() method is used to bind distinct operations to MTypes. In case of a customized callable client implementation that inherits from the SAMPClient class this method should be overwritten.

Note

When overwritten, this method must always return a string result (even empty).

Parameters:

private_key : str

Client private key.

sender_id : str

Sender public ID.

msg_id : str

Message ID received.

message : dict

Received message.

Returns:

confirmation : str

Any confirmation string.

receive_notification(private_key, sender_id, message)

Standard callable client receive_notification method.

This method is automatically handled when the bind_receive_notification() method is used to bind distinct operations to MTypes. In case of a customized callable client implementation that inherits from the SAMPClient class this method should be overwritten.

Note

When overwritten, this method must always return a string result (even empty).

Parameters:

private_key : str

Client private key.

sender_id : str

Sender public ID.

message : dict

Received message.

Returns:

confirmation : str

Any confirmation string.

receive_response(private_key, responder_id, msg_tag, response)

Standard callable client receive_response method.

This method is automatically handled when the bind_receive_response() method is used to bind distinct operations to MTypes. In case of a customized callable client implementation that inherits from the SAMPClient class this method should be overwritten.

Note

When overwritten, this method must always return a string result (even empty).

Parameters:

private_key : str

Client private key.

responder_id : str

Responder public ID.

msg_tag : str

Response message tag.

response : dict

Received response.

Returns:

confirmation : str

Any confirmation string.

register()

Register the client to the SAMP Hub.

start()

Start the client in a separate thread (non-blocking).

This only has an effect if callable was set to True when initializing the client.

stop(timeout=10.0)

Stop the client.

Parameters:

timeout : float

Timeout after which to give up if the client cannot be cleanly shut down.

unbind_receive_call(mtype, declare=True)

Remove from the calls binding table the specified MType and unsubscribe the client from it (if required).

Parameters:

mtype : str

MType to be removed.

declare : bool

Specify whether the client must be automatically declared as unsubscribed from the MType (see also declare_subscriptions()).

unbind_receive_notification(mtype, declare=True)

Remove from the notifications binding table the specified MType and unsubscribe the client from it (if required).

Parameters:

mtype : str

MType to be removed.

declare : bool

Specify whether the client must be automatically declared as unsubscribed from the MType (see also declare_subscriptions()).

unbind_receive_response(msg_tag)

Remove from the responses binding table the specified message-tag.

Parameters:

msg_tag : str

Message-tag to be removed.

unregister()

Unregister the client from the SAMP Hub.