SAMPClient

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

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(self, mtype, function[, …]) Bind a specific MType call to a function or class method.
bind_receive_message(self, mtype, function) Bind a specific MType to a function or class method, being intended for a call or a notification.
bind_receive_notification(self, mtype, function) Bind a specific MType notification to a function or class method.
bind_receive_response(self, msg_tag, function) Bind a specific msg-tag response to a function or class method.
declare_metadata(self[, metadata]) Declare the client application metadata supported.
declare_subscriptions(self[, 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(self) Return the client private key used for the Standard Profile communications obtained at registration time (samp.private-key).
get_public_id(self) Return public client ID obtained at registration time (samp.self-id).
receive_call(self, private_key, sender_id, …) Standard callable client receive_call method.
receive_notification(self, private_key, …) Standard callable client receive_notification method.
receive_response(self, private_key, …) Standard callable client receive_response method.
register(self) Register the client to the SAMP Hub.
start(self) Start the client in a separate thread (non-blocking).
stop(self[, timeout]) Stop the client.
unbind_receive_call(self, mtype[, declare]) Remove from the calls binding table the specified MType and unsubscribe the client from it (if required).
unbind_receive_notification(self, mtype[, …]) Remove from the notifications binding table the specified MType and unsubscribe the client from it (if required).
unbind_receive_response(self, msg_tag) Remove from the responses binding table the specified message-tag.
unregister(self) 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(self, mtype, function, declare=True, metadata=None)[source]

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(self, mtype, function, declare=True, metadata=None)[source]

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(self, mtype, function, declare=True, metadata=None)[source]

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(self, msg_tag, function)[source]

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(self, metadata=None)[source]

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(self, subscriptions=None)[source]

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

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

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

Returns:
id : str

Client public ID.

receive_call(self, private_key, sender_id, msg_id, message)[source]

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(self, private_key, sender_id, message)[source]

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(self, private_key, responder_id, msg_tag, response)[source]

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

Register the client to the SAMP Hub.

start(self)[source]

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(self, timeout=10.0)[source]

Stop the client.

Parameters:
timeout : float

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

unbind_receive_call(self, mtype, declare=True)[source]

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(self, mtype, declare=True)[source]

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(self, msg_tag)[source]

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

Parameters:
msg_tag : str

Message-tag to be removed.

unregister(self)[source]

Unregister the client from the SAMP Hub.