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:

hubSAMPHubProxy

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

namepython:str, optional

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

descriptionpython:str, optional

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

metadatapython:dict, optional

Client application metadata in the standard SAMP format.

addrpython: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.

portpython:int, optional

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

callablebool, 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:

mtypepython:str

MType to be caught.

functionpython:callable()

Application function to be used when mtype is received.

declarebool, optional

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

metadatapython: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:

mtypepython:str

MType to be caught.

functionpython:callable()

Application function to be used when mtype is received.

declarebool, optional

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

metadatapython: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:

mtypepython:str

MType to be caught.

functionpython:callable()

Application function to be used when mtype is received.

declarebool, optional

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

metadatapython: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_tagpython:str

Message-tag to be caught.

functionpython:callable()

Application function to be used when msg_tag is received.

declare_metadata(metadata=None)

Declare the client application metadata supported.

Parameters:

metadatapython: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:

subscriptionspython: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:

keypython:str

Client private key.

get_public_id()

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

Returns:

idpython: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_keypython:str

Client private key.

sender_idpython:str

Sender public ID.

msg_idpython:str

Message ID received.

messagepython:dict

Received message.

Returns:

confirmationpython: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_keypython:str

Client private key.

sender_idpython:str

Sender public ID.

messagepython:dict

Received message.

Returns:

confirmationpython: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_keypython:str

Client private key.

responder_idpython:str

Responder public ID.

msg_tagpython:str

Response message tag.

responsepython:dict

Received response.

Returns:

confirmationpython: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:

timeoutpython: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:

mtypepython:str

MType to be removed.

declarebool

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:

mtypepython:str

MType to be removed.

declarebool

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_tagpython:str

Message-tag to be removed.

unregister()

Unregister the client from the SAMP Hub.