SAMPIntegratedClient

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

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

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

call(recipient_id, msg_tag, message)

Proxy to call SAMP Hub method.

call_all(msg_tag, message)

Proxy to callAll SAMP Hub method.

call_and_wait(recipient_id, message, timeout)

Proxy to callAndWait SAMP Hub method.

connect(hub=None, hub_params=None, pool_size=20)

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

Proxy to declareMetadata SAMP Hub method.

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.

disconnect()

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

ecall(recipient_id, msg_tag, mtype, **params)

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(msg_tag, mtype, **params)

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(recipient_id, mtype, timeout, **params)

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(recipient_id, mtype, **params)

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(mtype, **params)

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(msg_id, status, result=None, error=None)

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

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

get_registered_clients()

Proxy to getRegisteredClients SAMP Hub method.

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

get_subscribed_clients(mtype)

Proxy to getSubscribedClients SAMP Hub method.

get_subscriptions(client_id)

Proxy to getSubscriptions SAMP Hub method.

notify(recipient_id, message)

Proxy to notify SAMP Hub method.

notify_all(message)

Proxy to notifyAll SAMP Hub method.

ping()

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

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.

reply(msg_id, response)

Proxy to reply SAMP Hub method.

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.