Skip to main content
`Ctrl`+`K`

# SAMPClient

class astropy.samp.SAMPClient(hub, name=None, description=None, metadata=None, addr=None, port=0, callable=True)

  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 `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_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()` and `bind_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)

    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.

  declare_metadata(metadata=None)

    Declare the client application metadata supported.

    Parameters:
      metadata `python: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)

    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.

  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.

  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.

  register()

    Register the client to the SAMP Hub.

  start()

    Start the client in a separate thread (non-blocking).

    This only has an effect if `callable` was set to `True` when initializing the client.

  stop(timeout=10.0)

    Stop the client.

    Parameters:
      timeout `python:float`

        Timeout after which to give up if the client cannot be cleanly shut down.

  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.

  unregister()

    Unregister the client from the SAMP Hub.