SAMPIntegratedClient¶
-
class
astropy.vo.samp.
SAMPIntegratedClient
(name=None, description=None, metadata=None, addr=None, port=0, https=False, key_file=None, cert_file=None, cert_reqs=0, ca_certs=None, ssl_version=None, callable=True)[source] [edit on github]¶ Bases:
object
A Simple SAMP client.
This class is meant to simplify the client usage providing a proxy class that merges the
SAMPClient
andSAMPHubProxy
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.
https : bool, optional
If
True
, set the callable client running on a Secure Sockets Layer (SSL) connection (HTTPS). By default SSL is disabled.key_file : str, optional
The path to a file containing the private key for SSL connections. If the certificate file (
cert_file
) contains the private key, thenkey_file
can be omitted.cert_file : str, optional
The path to a file which contains a certificate to be used to identify the local side of the secure connection.
cert_reqs : int, optional
Whether a certificate is required from the server side of the connection, and whether it will be validated if provided. It must be one of the three values
ssl.CERT_NONE
(certificates ignored),ssl.CERT_OPTIONAL
(not required, but validated if provided), orssl.CERT_REQUIRED
(required and validated). If the value of this parameter is notssl.CERT_NONE
, then theca_certs
parameter must point to a file of CA certificates.ca_certs : str, optional
The path to a file containing a set of concatenated “Certification Authority” certificates, which are used to validate the certificate passed from the Hub end of the connection.
ssl_version : int, optional
Which version of the SSL protocol to use. Typically, the server chooses a particular protocol version, and the client must adapt to the server’s choice. Most of the versions are not interoperable with the other versions. If not specified, the default SSL version is taken from the default in the installed version of the Python standard
ssl
library. See thessl
documentation for more information.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, key_file, ...])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()
andbind_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)[source] [edit on github]¶ 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"
) andextra
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)[source] [edit on github]¶ 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 isNone
),mtype
is the message MType,params
is the message parameter set (content of"samp.params"
) andextra
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 catched.
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)[source] [edit on github]¶ 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"
) andextra
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)[source] [edit on github]¶ 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 andresponse
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)[source] [edit on github]¶ Proxy to
call
SAMP Hub method.
-
call_all
(msg_tag, message)[source] [edit on github]¶ Proxy to
callAll
SAMP Hub method.
-
call_and_wait
(recipient_id, message, timeout)[source] [edit on github]¶ Proxy to
callAndWait
SAMP Hub method.
-
connect
(hub=None, hub_params=None, key_file=None, cert_file=None, cert_reqs=0, ca_certs=None, ssl_version=None, pool_size=20)[source] [edit on github]¶ Connect with the current or specified SAMP Hub, start and register the client.
Parameters: hub :
SAMPHubServer
, optionalThe 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>, ...}
.key_file : str, optional
The path to a file containing the private key for SSL connections. If the certificate file (
cert_file
) contains the private key, thenkey_file
can be omitted.cert_file : str, optional
The path to a file which contains a certificate to be used to identify the local side of the secure connection.
cert_reqs : int, optional
Whether a certificate is required from the server side of the connection, and whether it will be validated if provided. It must be one of the three values
ssl.CERT_NONE
(certificates ignored),ssl.CERT_OPTIONAL
(not required, but validated if provided), orssl.CERT_REQUIRED
(required and validated). If the value of this parameter is notssl.CERT_NONE
, then theca_certs
parameter must point to a file of CA certificates.ca_certs : str, optional
The path to a file containing a set of concatenated “Certification Authority” certificates, which are used to validate the certificate passed from the Hub end of the connection.
ssl_version : int, optional
Which version of the SSL protocol to use. Typically, the server chooses a particular protocol version, and the client must adapt to the server’s choice. Most of the versions are not interoperable with the other versions. If not specified, the default SSL version is taken from the default in the installed version of the Python standard
ssl
library. See thessl
documentation for more information.pool_size : int, optional
The number of socket connections opened to communicate with the Hub.
-
declare_metadata
(metadata)[source] [edit on github]¶ Proxy to
declareMetadata
SAMP Hub method.
-
declare_subscriptions
(subscriptions=None)[source] [edit on github]¶ Declares the MTypes the client wishes to subscribe to, implicitly defined with the MType binding methods
bind_receive_notification()
andbind_receive_call()
.An optional
subscriptions
map can be added to the final map passed to thedeclare_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 thedeclare_subscriptions()
method.
-
disconnect
()[source] [edit on github]¶ Unregister the client from the current SAMP Hub, stop the client and disconnect from the Hub.
-
ecall
(recipient_id, msg_tag, mtype, **params)[source] [edit on github]¶ 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 standardsamp.mtype
andsamp.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.vo.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)[source] [edit on github]¶ 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 standardsamp.mtype
andsamp.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.vo.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)[source] [edit on github]¶ 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 standardsamp.mtype
andsamp.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.vo.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)[source] [edit on github]¶ 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 standardsamp.mtype
andsamp.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.vo.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)[source] [edit on github]¶ 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 standardsamp.mtype
andsamp.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.vo.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)[source] [edit on github]¶ 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.vo.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)[source] [edit on github]¶ Proxy to
getMetadata
SAMP Hub method.
-
get_private_key
()[source] [edit on github]¶ 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
()[source] [edit on github]¶ Return public client ID obtained at registration time (
samp.self-id
).Returns: id : str
Client public ID.
-
get_registered_clients
()[source] [edit on github]¶ Proxy to
getRegisteredClients
SAMP Hub method.This returns all the registered clients, excluding the current client.
-
get_subscribed_clients
(mtype)[source] [edit on github]¶ Proxy to
getSubscribedClients
SAMP Hub method.
-
get_subscriptions
(client_id)[source] [edit on github]¶ Proxy to
getSubscriptions
SAMP Hub method.
-
notify
(recipient_id, message)[source] [edit on github]¶ Proxy to
notify
SAMP Hub method.
-
notify_all
(message)[source] [edit on github]¶ Proxy to
notifyAll
SAMP Hub method.
-
ping
()[source] [edit on github]¶ Proxy to
ping
SAMP Hub method (Standard Profile only).
-
receive_call
(private_key, sender_id, msg_id, message)[source] [edit on github]¶ 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 theSAMPClient
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)[source] [edit on github]¶ 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 theSAMPClient
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)[source] [edit on github]¶ 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 theSAMPClient
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)[source] [edit on github]¶ Proxy to
reply
SAMP Hub method.
-
unbind_receive_call
(mtype, declare=True)[source] [edit on github]¶ 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)[source] [edit on github]¶ 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)[source] [edit on github]¶ Remove from the responses binding table the specified message-tag.
Parameters: msg_tag : str
Message-tag to be removed.
-