astro py:docs

- Index
- Modules

### Navigation

- next »
- « previous |
- Astropy v1.1.1 »
- Virtual Observatory Access (`astropy.vo`) »
- SAMP (Simple Application Messaging Protocol (`astropy.vo.samp`) »
- SAMPIntegratedClient

# 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)

  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.

  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, then `key_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), or `ssl.CERT_REQUIRED` (required and validated). If the value of this parameter is not `ssl.CERT_NONE`, then the `ca_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 the `ssl` 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()` 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 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)

    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, key_file=None, cert_file=None, cert_reqs=0, ca_certs=None, ssl_version=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>, ...}`.

    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, then `key_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), or `ssl.CERT_REQUIRED` (required and validated). If the value of this parameter is not `ssl.CERT_NONE`, then the `ca_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 the `ssl` documentation for more information.

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

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

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

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

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

    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)

    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.