0
# SAMP (Simple Application Messaging Protocol)
1
2
SAMP client and hub functionality for interoperability with other astronomical software applications.
3
4
## Core Imports
5
6
```python
7
from astropy.samp import SAMPHubServer, SAMPIntegratedClient
8
from astropy.samp import SAMPClient
9
```
10
11
## Capabilities
12
13
### SAMP Hub Server
14
15
SAMP hub server for coordinating communication between astronomical applications.
16
17
```python { .api }
18
class SAMPHubServer:
19
"""
20
SAMP hub server implementation.
21
22
Parameters:
23
- secret: hub secret key
24
- addr: server address
25
- port: server port (0 for automatic)
26
- lockfile: path to lockfile
27
- timeout: client timeout
28
- client_timeout: timeout for client operations
29
- mode: hub mode ('single' or 'multiple')
30
"""
31
def __init__(self, secret=None, addr=None, port=0, lockfile=None, timeout=10, client_timeout=120, mode='single'): ...
32
33
def start(self, wait=False):
34
"""
35
Start the hub server.
36
37
Parameters:
38
- wait: whether to wait for hub to be ready
39
"""
40
41
def stop(self):
42
"""Stop the hub server."""
43
44
def is_running(self):
45
"""Check if hub is running."""
46
47
@property
48
def clients(self):
49
"""Dictionary of connected clients."""
50
51
class SAMPHubProxy:
52
"""
53
Proxy for communicating with SAMP hub.
54
55
Parameters:
56
- hub_params: hub connection parameters
57
"""
58
def __init__(self, hub_params=None): ...
59
60
def connect(self):
61
"""Connect to hub."""
62
63
def disconnect(self):
64
"""Disconnect from hub."""
65
66
def is_connected(self):
67
"""Check if connected to hub."""
68
```
69
70
### SAMP Clients
71
72
Client classes for connecting applications to SAMP hubs.
73
74
```python { .api }
75
class SAMPClient:
76
"""
77
Basic SAMP client.
78
79
Parameters:
80
- hub: hub proxy instance
81
- name: client name
82
- description: client description
83
- metadata: client metadata dictionary
84
"""
85
def __init__(self, hub=None, name=None, description=None, metadata=None): ...
86
87
def connect(self, hub=None, pool_size=20):
88
"""
89
Connect to SAMP hub.
90
91
Parameters:
92
- hub: hub proxy to connect to
93
- pool_size: thread pool size
94
"""
95
96
def disconnect(self):
97
"""Disconnect from hub."""
98
99
def is_connected(self):
100
"""Check if connected."""
101
102
def bind_receive_message(self, mtype, function):
103
"""
104
Bind function to receive messages of given type.
105
106
Parameters:
107
- mtype: message type to bind
108
- function: callback function
109
"""
110
111
def bind_receive_call(self, mtype, function):
112
"""
113
Bind function to receive calls of given type.
114
115
Parameters:
116
- mtype: message type to bind
117
- function: callback function
118
"""
119
120
def bind_receive_notification(self, mtype, function):
121
"""
122
Bind function to receive notifications of given type.
123
124
Parameters:
125
- mtype: message type to bind
126
- function: callback function
127
"""
128
129
class SAMPIntegratedClient(SAMPClient):
130
"""
131
SAMP client with integrated hub functionality.
132
133
This client can start its own hub if none is available.
134
135
Parameters:
136
- name: client name
137
- description: client description
138
- metadata: client metadata
139
"""
140
def __init__(self, name=None, description=None, metadata=None): ...
141
142
def connect(self, hub=None, pool_size=20):
143
"""Connect to hub, starting one if necessary."""
144
```
145
146
### Message Operations
147
148
Functions for sending and receiving SAMP messages.
149
150
```python { .api }
151
def notify(client_id, message):
152
"""
153
Send notification message.
154
155
Parameters:
156
- client_id: target client ID
157
- message: message dictionary
158
"""
159
160
def notify_all(message):
161
"""
162
Send notification to all clients.
163
164
Parameters:
165
- message: message dictionary
166
"""
167
168
def call(client_id, message, timeout=10):
169
"""
170
Send synchronous call message.
171
172
Parameters:
173
- client_id: target client ID
174
- message: message dictionary
175
- timeout: response timeout
176
177
Returns:
178
dict: response message
179
"""
180
181
def call_all(message, timeout=10):
182
"""
183
Send call to all clients.
184
185
Parameters:
186
- message: message dictionary
187
- timeout: response timeout
188
189
Returns:
190
dict: responses from all clients
191
"""
192
193
def call_and_wait(client_id, message, timeout=10):
194
"""
195
Send asynchronous call and wait for response.
196
197
Parameters:
198
- client_id: target client ID
199
- message: message dictionary
200
- timeout: response timeout
201
202
Returns:
203
dict: response message
204
"""
205
```
206
207
## Usage Examples
208
209
### Starting a SAMP Hub
210
211
```python
212
from astropy.samp import SAMPHubServer
213
214
# Start a SAMP hub
215
hub = SAMPHubServer()
216
hub.start(wait=True)
217
218
print(f"Hub running on port {hub.port}")
219
print(f"Hub secret: {hub.secret}")
220
221
# Hub will run until stopped
222
# hub.stop()
223
```
224
225
### Connecting a Client
226
227
```python
228
from astropy.samp import SAMPIntegratedClient
229
230
# Create and connect client
231
client = SAMPIntegratedClient(
232
name="My Astronomy App",
233
description="Example SAMP client",
234
metadata={
235
"samp.name": "My App",
236
"samp.description.text": "Example application",
237
"author.name": "Astronomer"
238
}
239
)
240
241
# Connect to hub (will start one if needed)
242
client.connect()
243
244
print(f"Connected as client ID: {client.get_public_id()}")
245
print(f"Connected clients: {list(client.get_subscribed_clients('*').keys())}")
246
```
247
248
### Sending Messages
249
250
```python
251
# Send table to all clients that can receive tables
252
message = {
253
"samp.mtype": "table.load.votable",
254
"samp.params": {
255
"url": "file:///path/to/table.xml",
256
"table-id": "example-table",
257
"name": "Example Data"
258
}
259
}
260
261
# Send to all subscribed clients
262
responses = client.call_all(message, timeout=30)
263
print(f"Sent table to {len(responses)} clients")
264
```
265
266
### Receiving Messages
267
268
```python
269
def receive_table(private_key, sender_id, msg_id, mtype, params, extra):
270
"""Handle incoming table load requests."""
271
print(f"Received table from {sender_id}: {params['name']}")
272
print(f"Table URL: {params['url']}")
273
274
# Return success response
275
return {"samp.status": "samp.ok"}
276
277
# Bind handler for table messages
278
client.bind_receive_call("table.load.*", receive_table)
279
280
print("Client ready to receive table messages")
281
```
282
283
### Hub Discovery
284
285
```python
286
from astropy.samp import SAMPHubProxy
287
288
# Find existing hub
289
try:
290
hub = SAMPHubProxy()
291
hub.connect()
292
print("Connected to existing hub")
293
except:
294
print("No hub found")
295
```
296
297
## Types
298
299
```python { .api }
300
# SAMP types
301
SAMPHubServer = astropy.samp.SAMPHubServer
302
SAMPClient = astropy.samp.SAMPClient
303
SAMPIntegratedClient = astropy.samp.SAMPIntegratedClient
304
SAMPHubProxy = astropy.samp.SAMPHubProxy
305
```