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.- namestr, optional
Client name (corresponding to
samp.name
metadata keyword).- descriptionstr, optional
Client description (corresponding to
samp.description.text
metadata keyword).- metadatadict, optional
Client application metadata in the standard SAMP format.
- addrstr, 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.
- portint, 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.
- hub
Attributes Summary
Whether the client is currently registered.
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()
andbind_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"
) andextra
is a dictionary containing any extra message map entry. The client is automatically declared subscribed to the MType by default.- Parameters
- mtypestr
MType to be caught.
- functioncallable
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()
).- metadatadict, 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 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
- mtypestr
MType to be caught.
- functioncallable
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()
).- metadatadict, 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"
) andextra
is a dictionary containing any extra message map entry. The client is automatically declared subscribed to the MType by default.- Parameters
- mtypestr
MType to be caught.
- functioncallable
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()
).- metadatadict, 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 andresponse
is the response received.- Parameters
- msg_tagstr
Message-tag to be caught.
- functioncallable
Application function to be used when
msg_tag
is received.
-
declare_metadata
(self, metadata=None)[source]¶ Declare the client application metadata supported.
- Parameters
- metadatadict, 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()
andbind_receive_call()
.An optional
subscriptions
map can be added to the final map passed to thedeclare_subscriptions()
method.- Parameters
- subscriptionsdict, optional
Dictionary containing the list of MTypes to subscribe to, with the same format of the
subscriptions
map passed to thedeclare_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
- keystr
Client private key.
-
get_public_id
(self)[source]¶ Return public client ID obtained at registration time (
samp.self-id
).- Returns
- idstr
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 theSAMPClient
class this method should be overwritten.Note
When overwritten, this method must always return a string result (even empty).
- Parameters
- private_keystr
Client private key.
- sender_idstr
Sender public ID.
- msg_idstr
Message ID received.
- messagedict
Received message.
- Returns
- confirmationstr
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 theSAMPClient
class this method should be overwritten.Note
When overwritten, this method must always return a string result (even empty).
- Parameters
- private_keystr
Client private key.
- sender_idstr
Sender public ID.
- messagedict
Received message.
- Returns
- confirmationstr
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 theSAMPClient
class this method should be overwritten.Note
When overwritten, this method must always return a string result (even empty).
- Parameters
- private_keystr
Client private key.
- responder_idstr
Responder public ID.
- msg_tagstr
Response message tag.
- responsedict
Received response.
- Returns
- confirmationstr
Any confirmation string.
-
start
(self)[source]¶ Start the client in a separate thread (non-blocking).
This only has an effect if
callable
was set toTrue
when initializing the client.
-
stop
(self, timeout=10.0)[source]¶ Stop the client.
- Parameters
- timeoutfloat
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
- mtypestr
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
(self, mtype, declare=True)[source]¶ Remove from the notifications binding table the specified MType and unsubscribe the client from it (if required).
- Parameters
- mtypestr
MType to be removed.
- declarebool
Specify whether the client must be automatically declared as unsubscribed from the MType (see also
declare_subscriptions()
).