SAMPIntegratedClient

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

Bases: object

A Simple SAMP client.

This class is meant to simplify the client usage providing a proxy class that merges the SAMPClient and SAMPHubProxy functionalities in a simplified API.

Parameters:
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_connected Testing method to verify the client connection with a running Hub.

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.
call(self, recipient_id, msg_tag, message) Proxy to call SAMP Hub method.
call_all(self, msg_tag, message) Proxy to callAll SAMP Hub method.
call_and_wait(self, recipient_id, message, …) Proxy to callAndWait SAMP Hub method.
connect(self[, hub, hub_params, pool_size]) Connect with the current or specified SAMP Hub, start and register the client.
declare_metadata(self, metadata) Proxy to declareMetadata SAMP Hub method.
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().
disconnect(self) Unregister the client from the current SAMP Hub, stop the client and disconnect from the Hub.
ecall(self, recipient_id, msg_tag, mtype, …) Easy to use version of call().
ecall_all(self, msg_tag, mtype, \*\*params) Easy to use version of call_all().
ecall_and_wait(self, recipient_id, mtype, …) Easy to use version of call_and_wait().
enotify(self, recipient_id, mtype, \*\*params) Easy to use version of notify().
enotify_all(self, mtype, \*\*params) Easy to use version of notify_all().
ereply(self, msg_id, status[, result, error]) Easy to use version of reply().
get_metadata(self, client_id) Proxy to getMetadata SAMP Hub method.
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).
get_registered_clients(self) Proxy to getRegisteredClients SAMP Hub method.
get_subscribed_clients(self, mtype) Proxy to getSubscribedClients SAMP Hub method.
get_subscriptions(self, client_id) Proxy to getSubscriptions SAMP Hub method.
notify(self, recipient_id, message) Proxy to notify SAMP Hub method.
notify_all(self, message) Proxy to notifyAll SAMP Hub method.
ping(self) Proxy to ping SAMP Hub method (Standard Profile only).
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.
reply(self, msg_id, response) Proxy to reply SAMP Hub method.
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.

Attributes Documentation

is_connected

Testing method to verify the client connection with a running Hub.

Returns:
is_connected : bool

True if the client is connected to a Hub, False otherwise.

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.

call(self, recipient_id, msg_tag, message)[source]

Proxy to call SAMP Hub method.

call_all(self, msg_tag, message)[source]

Proxy to callAll SAMP Hub method.

call_and_wait(self, recipient_id, message, timeout)[source]

Proxy to callAndWait SAMP Hub method.

connect(self, hub=None, hub_params=None, pool_size=20)[source]

Connect with the current or specified SAMP Hub, start and register the client.

Parameters:
hub : SAMPHubServer, optional

The hub to connect to.

hub_params : dict, optional

Optional dictionary containing the lock-file content of the Hub with which to connect. This dictionary has the form {<token-name>: <token-string>, ...}.

pool_size : int, optional

The number of socket connections opened to communicate with the Hub.

declare_metadata(self, metadata)[source]

Proxy to declareMetadata SAMP Hub method.

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.

disconnect(self)[source]

Unregister the client from the current SAMP Hub, stop the client and disconnect from the Hub.

ecall(self, recipient_id, msg_tag, mtype, **params)[source]

Easy to use version of call().

This is a proxy to call method that allows to send a call message in a simplified way.

Note that reserved extra_kws keyword is a dictionary with the special meaning of being used to add extra keywords, in addition to the standard samp.mtype and samp.params, to the message sent.

Parameters:
recipient_id : str

Recipient ID

msg_tag : str

Message tag to use

mtype : str

MType to be sent

params : dict of set of keywords

Variable keyword set which contains the list of parameters for the specified MType.

Examples

>>> from astropy.samp import SAMPIntegratedClient
>>> cli = SAMPIntegratedClient()
>>> ...
>>> msgid = cli.ecall("abc", "xyz", "samp.msg.progress",
...                   txt = "initialization", percent = "10",
...                   extra_kws = {"my.extra.info": "just an example"})
ecall_all(self, msg_tag, mtype, **params)[source]

Easy to use version of call_all().

This is a proxy to callAll method that allows to send the call message in a simplified way.

Note that reserved extra_kws keyword is a dictionary with the special meaning of being used to add extra keywords, in addition to the standard samp.mtype and samp.params, to the message sent.

Parameters:
msg_tag : str

Message tag to use

mtype : str

MType to be sent

params : dict of set of keywords

Variable keyword set which contains the list of parameters for the specified MType.

Examples

>>> from astropy.samp import SAMPIntegratedClient
>>> cli = SAMPIntegratedClient()
>>> ...
>>> msgid = cli.ecall_all("xyz", "samp.msg.progress",
...                       txt = "initialization", percent = "10",
...                       extra_kws = {"my.extra.info": "just an example"})
ecall_and_wait(self, recipient_id, mtype, timeout, **params)[source]

Easy to use version of call_and_wait().

This is a proxy to callAndWait method that allows to send the call message in a simplified way.

Note that reserved extra_kws keyword is a dictionary with the special meaning of being used to add extra keywords, in addition to the standard samp.mtype and samp.params, to the message sent.

Parameters:
recipient_id : str

Recipient ID

mtype : str

MType to be sent

timeout : str

Call timeout in seconds

params : dict of set of keywords

Variable keyword set which contains the list of parameters for the specified MType.

Examples

>>> from astropy.samp import SAMPIntegratedClient
>>> cli = SAMPIntegratedClient()
>>> ...
>>> cli.ecall_and_wait("xyz", "samp.msg.progress", "5",
...                    txt = "initialization", percent = "10",
...                    extra_kws = {"my.extra.info": "just an example"})
enotify(self, recipient_id, mtype, **params)[source]

Easy to use version of notify().

This is a proxy to notify method that allows to send the notification message in a simplified way.

Note that reserved extra_kws keyword is a dictionary with the special meaning of being used to add extra keywords, in addition to the standard samp.mtype and samp.params, to the message sent.

Parameters:
recipient_id : str

Recipient ID

mtype : str

the MType to be notified

params : dict or set of keywords

Variable keyword set which contains the list of parameters for the specified MType.

Examples

>>> from astropy.samp import SAMPIntegratedClient
>>> cli = SAMPIntegratedClient()
>>> ...
>>> cli.enotify("samp.msg.progress", msgid = "xyz", txt = "initialization",
...             percent = "10", extra_kws = {"my.extra.info": "just an example"})
enotify_all(self, mtype, **params)[source]

Easy to use version of notify_all().

This is a proxy to notifyAll method that allows to send the notification message in a simplified way.

Note that reserved extra_kws keyword is a dictionary with the special meaning of being used to add extra keywords, in addition to the standard samp.mtype and samp.params, to the message sent.

Parameters:
mtype : str

MType to be notified.

params : dict or set of keywords

Variable keyword set which contains the list of parameters for the specified MType.

Examples

>>> from astropy.samp import SAMPIntegratedClient
>>> cli = SAMPIntegratedClient()
>>> ...
>>> cli.enotify_all("samp.msg.progress", txt = "initialization",
...                 percent = "10",
...                 extra_kws = {"my.extra.info": "just an example"})
ereply(self, msg_id, status, result=None, error=None)[source]

Easy to use version of reply().

This is a proxy to reply method that allows to send a reply message in a simplified way.

Parameters:
msg_id : str

Message ID to which reply.

status : str

Content of the samp.status response keyword.

result : dict

Content of the samp.result response keyword.

error : dict

Content of the samp.error response keyword.

Examples

>>> from astropy.samp import SAMPIntegratedClient, SAMP_STATUS_ERROR
>>> cli = SAMPIntegratedClient()
>>> ...
>>> cli.ereply("abd", SAMP_STATUS_ERROR, result={},
...            error={"samp.errortxt": "Test error message"})
get_metadata(self, client_id)[source]

Proxy to getMetadata SAMP Hub 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.

get_registered_clients(self)[source]

Proxy to getRegisteredClients SAMP Hub method.

This returns all the registered clients, excluding the current client.

get_subscribed_clients(self, mtype)[source]

Proxy to getSubscribedClients SAMP Hub method.

get_subscriptions(self, client_id)[source]

Proxy to getSubscriptions SAMP Hub method.

notify(self, recipient_id, message)[source]

Proxy to notify SAMP Hub method.

notify_all(self, message)[source]

Proxy to notifyAll SAMP Hub method.

ping(self)[source]

Proxy to ping SAMP Hub method (Standard Profile only).

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.

reply(self, msg_id, response)[source]

Proxy to reply SAMP Hub method.

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.