.. doctest-skip-all

.. _vo-samp:

*************************************************************
SAMP (Simple Application Messaging Protocol) (`pyvo.samp`)
*************************************************************

`pyvo.samp` is a Python implementation of the SAMP messaging system.

Simple Application Messaging Protocol (SAMP) is an inter-process communication
system that allows different client programs, usually running on the same
computer, to communicate with each other by exchanging short messages that may
reference external data files. The protocol has been developed within the
International Virtual Observatory Alliance (IVOA) and is understood by many
desktop astronomy tools, including `TOPCAT <https://www.star.bristol.ac.uk/mbt/topcat>`_, `SAO DS9 <http://ds9.si.edu/>`_,
and `Aladin <https://aladin.unistra.fr>`_.

So by using the classes in `pyvo.samp`, Python code can interact with
other running desktop clients, for instance displaying a named FITS file in DS9,
prompting Aladin to recenter on a given sky position, or receiving a message
identifying the row when a user highlights a plotted point in TOPCAT.

The way the protocol works is that a SAMP "Hub" process must be running on the
local host, and then various client programs can connect to it. Once connected,
these clients can send messages to each other via the hub. The details are
described in the `SAMP standard <http://www.ivoa.net/documents/SAMP/>`_.

`pyvo.samp` provides classes both to set up such a hub process, and to
help implement a client that can send and receive messages.
Note that setting up the hub from Python is not always necessary, since
various other SAMP-aware applications may start up a hub independently; in most
cases, only one running hub is used during a SAMP session.

The following classes are available in `pyvo.samp`:

* `pyvo.samp.SAMPHubServer`, which is used to instantiate a hub server that clients can
  then connect to.
* `pyvo.samp.SAMPHubProxy`, which is used to connect to an existing hub (including hubs
  started from other applications such as `TOPCAT <https://www.star.bristol.ac.uk/mbt/topcat>`_).
* `pyvo.samp.SAMPClient`, which is used to create a SAMP client.
* `pyvo.samp.SAMPIntegratedClient`, which is the same as `pyvo.samp.SAMPClient` except that it has
  a self-contained `pyvo.samp.SAMPHubProxy` to provide a simpler user interface.

`pyvo.samp` is a full implementation of `SAMP V1.3
<http://www.ivoa.net/documents/SAMP/20120411/>`_. As well as the Standard
Profile, it supports the Web Profile, which means that it can be used to also
communicate with web SAMP clients; see the `sampjs
<http://astrojs.github.io/sampjs/>`_ library examples for more details.

.. _IVOA Simple Application Messaging Protocol: http://www.ivoa.net/documents/latest/SAMP.html

Using `pyvo.samp`
====================

.. toctree::
   :maxdepth: 2

   example_hub
   example_table_image
   example_clients
   advanced_embed_samp_hub

Reference/API
=============

.. toctree::
   :maxdepth: 2

   ref_api

Acknowledgments
===============

Some of this code was adapted from the `SAMPy <https://pypi.org/project/sampy>`__
package written by Luigi Paioro, who has granted the Astropy Project permission
to use the code under a BSD license.