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