SAMPClient¶
-
class
astropy.samp.
SAMPClient
(hub, name=None, description=None, metadata=None, addr=None, port=0, callable=True)[source] [edit on github]¶ 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.- 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_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()
andbind_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)[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 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)[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.
-
declare_metadata
(metadata=None)[source] [edit on github]¶ Declare the client application metadata supported.
Parameters: - metadata : 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)[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.
-
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.
-
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.
-
register
()[source] [edit on github]¶ Register the client to the SAMP Hub.
-
start
()[source] [edit on github]¶ Start the client in a separate thread (non-blocking).
This only has an effect if
callable
was set toTrue
when initializing the client.
-
stop
(timeout=10.0)[source] [edit on github]¶ Stop the client.
Parameters: - timeout : float
Timeout after which to give up if the client cannot be cleanly shut down.
-
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.
-
unregister
()[source] [edit on github]¶ Unregister the client from the SAMP Hub.
- hub :