Skip to main content
`Ctrl`+`K`

# SAMPIntegratedClient

class astropy.samp.SAMPIntegratedClient(name=None, description=None, metadata=None, addr=None, port=0, 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 `python:str`, optional

      Client name (corresponding to `samp.name` metadata keyword).

    description `python:str`, optional

      Client description (corresponding to `samp.description.text` metadata keyword).

    metadata `python:dict`, optional

      Client application metadata in the standard SAMP format.

    addr `python: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 `python: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_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, pool_size]) | 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 `python:str`

        MType to be caught.

      function `python: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 `python: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 `python:str`

        MType to be caught.

      function `python: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 `python: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 `python:str`

        MType to be caught.

      function `python: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 `python: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 `python:str`

        Message-tag to be caught.

      function `python: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, 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 `python: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>, ...}`.

      pool_size `python: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 `python: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 `python:str`

        Recipient ID

      msg_tag `python:str`

        Message tag to use

      mtype `python:str`

        MType to be sent

      params `python:dict` of `set` of `python:str`

        Variable keyword set which contains the list of parameters for the specified MType.

    Examples

        >>> from astropy.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 `python:str`

        Message tag to use

      mtype `python:str`

        MType to be sent

      params `python:dict` of `set` of `python:str`

        Variable keyword set which contains the list of parameters for the specified MType.

    Examples

        >>> from astropy.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 `python:str`

        Recipient ID

      mtype `python:str`

        MType to be sent

      timeout `python:str`

        Call timeout in seconds

      params `python:dict` of `set` of `python:str`

        Variable keyword set which contains the list of parameters for the specified MType.

    Examples

        >>> from astropy.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 `python:str`

        Recipient ID

      mtype `python:str`

        the MType to be notified

      params `python:dict` or `set` of `python:str`

        Variable keyword set which contains the list of parameters for the specified MType.

    Examples

        >>> from astropy.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 `python:str`

        MType to be notified.

      params `python:dict` or `set` of `python:str`

        Variable keyword set which contains the list of parameters for the specified MType.

    Examples

        >>> from astropy.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 `python:str`

        Message ID to which reply.

      status `python:str`

        Content of the `samp.status` response keyword.

      result `python:dict`

        Content of the `samp.result` response keyword.

      error `python:dict`

        Content of the `samp.error` response keyword.

    Examples

        >>> from astropy.samp import SAMPIntegratedClient, SAMP_STATUS_ERROR
        >>> cli = SAMPIntegratedClient()
        >>> ...
        >>> cli.ereply("message_id", 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 `python:str`

        Client private key.

  get_public_id()

    Return public client ID obtained at registration time (`samp.self-id`).

    Returns:
      id `python: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 `python:str`

        Client private key.

      sender_id `python:str`

        Sender public ID.

      msg_id `python:str`

        Message ID received.

      message `python:dict`

        Received message.

    Returns:
      confirmation `python: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 `python:str`

        Client private key.

      sender_id `python:str`

        Sender public ID.

      message `python:dict`

        Received message.

    Returns:
      confirmation `python: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 `python:str`

        Client private key.

      responder_id `python:str`

        Responder public ID.

      msg_tag `python:str`

        Response message tag.

      response `python:dict`

        Received response.

    Returns:
      confirmation `python: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 `python: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 `python: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 `python:str`

        Message-tag to be removed.