taba-client 0.3.19__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
taba/client.py ADDED
@@ -0,0 +1,387 @@
1
+ """The synchronous Taba client."""
2
+
3
+ import json
4
+ import threading
5
+ from typing import Any, Callable, Dict, Iterator, List, Optional, Union
6
+
7
+ from . import _calls
8
+ from ._transport import Sleep, Transport
9
+ from .cancel import Cancelled, CancelToken
10
+ from .errors import TabaError
11
+ from .models import (
12
+ BatchMessage,
13
+ BatchResult,
14
+ Config,
15
+ ConsumeOptions,
16
+ Message,
17
+ MessageContext,
18
+ Page,
19
+ PublishResponse,
20
+ Topic,
21
+ TopicPut,
22
+ TopicRequest,
23
+ TopicUpdate,
24
+ VisibilityResponse,
25
+ parse_batch_results,
26
+ parse_messages,
27
+ parse_page,
28
+ parse_publish_response,
29
+ parse_topic,
30
+ parse_visibility_response,
31
+ )
32
+
33
+
34
+ def make_config(config: Union[Config, str, None], options: Dict[str, Any]) -> Config:
35
+ if isinstance(config, Config):
36
+ if options:
37
+ raise TypeError("pass either a Config or keyword options, not both")
38
+ return config
39
+ if isinstance(config, str):
40
+ options = dict(options, base_url=config)
41
+ return Config(**options)
42
+
43
+
44
+ def _lost_or_gone(error: TabaError) -> bool:
45
+ """The message already went back to the queue (deadline expired) or is already gone."""
46
+ return error.status in (409, 404)
47
+
48
+
49
+ class Client:
50
+ """
51
+ The Taba client API client (doc 21): the nine operations, `subscribe` and the consume with a handler.
52
+ It is safe for concurrent use: each thread has its own connection. For `asyncio`, use `taba.aio.AsyncClient`.
53
+
54
+ >>> client = Client("http://localhost:8080", token="...")
55
+ >>> client.publish_json("orders", {"order": 9001})
56
+ >>> for message in client.consume("orders", wait_time=20):
57
+ ... client.ack("orders", message)
58
+ """
59
+
60
+ def __init__(self, config: Union[Config, str, None] = None, *, _sleep: Optional[Sleep] = None, **options: Any) -> None:
61
+ self._config = make_config(config, options)
62
+ self._transport = Transport(self._config, _sleep)
63
+ self._serializer = self._config.serializer or json
64
+
65
+ @property
66
+ def config(self) -> Config:
67
+ return self._config
68
+
69
+ def close(self) -> None:
70
+ """Closes the calling thread's connection. The client can be used again afterwards."""
71
+ self._transport.close()
72
+
73
+ def __enter__(self) -> "Client":
74
+ return self
75
+
76
+ def __exit__(self, *exc_info: Any) -> None:
77
+ self.close()
78
+
79
+ def _send(self, call: Any, cancel: Optional[CancelToken]) -> Any:
80
+ return self._transport.send(call, cancel)
81
+
82
+ # -- topics --------------------------------------------------------------------------------------------
83
+
84
+ def create_topic(self, request: TopicRequest, *, cancel: Optional[CancelToken] = None) -> Topic:
85
+ reply = self._send(_calls.create_topic_call(request), cancel)
86
+ if reply.recovered:
87
+ return self.get_topic(request.name, cancel=cancel)
88
+ return parse_topic(reply.text)
89
+
90
+ def get_topic(self, name: str, *, cancel: Optional[CancelToken] = None) -> Topic:
91
+ return parse_topic(self._send(_calls.get_topic_call(name), cancel).text)
92
+
93
+ def list_topics(
94
+ self,
95
+ limit: Optional[int] = None,
96
+ cursor: Optional[str] = None,
97
+ name: Optional[str] = None,
98
+ *,
99
+ cancel: Optional[CancelToken] = None,
100
+ ) -> Page:
101
+ """`GET /topics`. Parameters left `None` do not go in the query."""
102
+ return parse_page(self._send(_calls.list_topics_call(limit, cursor, name), cancel).text)
103
+
104
+ def iter_topics(self, name: Optional[str] = None, *, cancel: Optional[CancelToken] = None) -> Iterator[Topic]:
105
+ """All topics, page by page, as a generator."""
106
+ cursor = None
107
+ while True:
108
+ page = self.list_topics(cursor=cursor, name=name, cancel=cancel)
109
+ yield from page.items
110
+ cursor = page.next_cursor
111
+ if cursor is None:
112
+ return
113
+
114
+ def list_all_topics(self, name: Optional[str] = None, *, cancel: Optional[CancelToken] = None) -> List[Topic]:
115
+ return list(self.iter_topics(name, cancel=cancel))
116
+
117
+ def update_topic(self, name: str, update: TopicUpdate, *, cancel: Optional[CancelToken] = None) -> Topic:
118
+ """A real `PATCH`, with no verb-override header."""
119
+ return parse_topic(self._send(_calls.update_topic_call(name, update), cancel).text)
120
+
121
+ def create_or_update_topic(
122
+ self, request: TopicRequest, *, recreate: Optional[str] = None, cancel: Optional[CancelToken] = None
123
+ ) -> TopicPut:
124
+ """
125
+ `PUT /topics/{topic}`: brings the topic to the declared state, creating it if it does not exist. What is left
126
+ out goes back to the server default (a full replacement, unlike `update_topic`); `request.name` is the topic
127
+ of the path. Another `type`, `fifo` or `volatile` is `409 topic.immutable-mismatch` unless `recreate`
128
+ (`"if-empty"` or `"always"`) says otherwise. Repeated after a 503 like the other calls: the route is
129
+ idempotent.
130
+ """
131
+ reply = self._send(_calls.put_topic_call(request, recreate), cancel)
132
+ if reply.status == 201:
133
+ outcome = "recreated" if reply.recreated else "created"
134
+ else:
135
+ outcome = "updated"
136
+ return TopicPut(parse_topic(reply.text), outcome)
137
+
138
+ def delete_topic(self, name: str, *, if_empty: bool = False, cancel: Optional[CancelToken] = None) -> None:
139
+ """
140
+ `DELETE /topics/{topic}`. With `if_empty=True`, removes the queue only if it and its dead-letter hold no
141
+ message on any node (`409 topic.not-empty` otherwise; a distributor holds none).
142
+ """
143
+ self._send(_calls.delete_topic_call(name, if_empty), cancel)
144
+
145
+ # -- publishing ----------------------------------------------------------------------------------------
146
+
147
+ def publish(
148
+ self,
149
+ topic: str,
150
+ body: Union[bytes, bytearray, memoryview, str, None],
151
+ *,
152
+ content_type: Optional[str] = None,
153
+ group_id: Optional[str] = None,
154
+ deduplication_id: Optional[str] = None,
155
+ request_id: Optional[str] = None,
156
+ traceparent: Optional[str] = None,
157
+ fifo: bool = False,
158
+ cancel: Optional[CancelToken] = None,
159
+ ) -> PublishResponse:
160
+ """
161
+ `POST /topics/{topic}/messages`. The body goes as bytes (a `str` is sent as UTF-8), without validation.
162
+ Set `fifo=True` when the topic is a FIFO queue: only there can a 502/504 be repeated.
163
+ """
164
+ call = _calls.publish_call(
165
+ topic, body, content_type, group_id, deduplication_id, request_id, traceparent, fifo
166
+ )
167
+ return parse_publish_response(self._send(call, cancel).text)
168
+
169
+ def publish_json(self, topic: str, value: Any, **options: Any) -> PublishResponse:
170
+ """Serializes the value (with the configured `serializer`, or `json`) and publishes as `application/json`."""
171
+ if value is None:
172
+ raise TabaError.client("client.invalid-request", "value is required")
173
+ try:
174
+ text = self._serializer.dumps(value)
175
+ except (TypeError, ValueError) as e:
176
+ raise TabaError.client("client.invalid-request", "cannot serialize the value: %s" % e)
177
+ options["content_type"] = "application/json"
178
+ return self.publish(topic, text.encode("utf-8"), **options)
179
+
180
+ def publish_raw_json(self, topic: str, text: str, **options: Any) -> PublishResponse:
181
+ """Publishes a JSON text the application already built, without serializing."""
182
+ options["content_type"] = "application/json"
183
+ return self.publish(topic, text.encode("utf-8"), **options)
184
+
185
+ def publish_text(self, topic: str, text: str, **options: Any) -> PublishResponse:
186
+ """Publishes a text (`Content-Type: text/plain; charset=utf-8`)."""
187
+ options["content_type"] = "text/plain; charset=utf-8"
188
+ return self.publish(topic, text.encode("utf-8"), **options)
189
+
190
+ def publish_batch(
191
+ self, topic: str, messages: List[BatchMessage], *, cancel: Optional[CancelToken] = None
192
+ ) -> List[BatchResult]:
193
+ """
194
+ `POST /topics/{topic}/messages/batch`: publishes many messages in one request (1 to the server's
195
+ `api.batch.max-messages`, 1000 by default). Each item is answered as its single publication and one that
196
+ fails does not undo the others (look at `ok`). On a FIFO queue the items of a group are published in the
197
+ order of the list. A failure of the network is not repeated (it could duplicate).
198
+ """
199
+ return parse_batch_results(self._send(_calls.publish_batch_call(topic, messages), cancel).text)
200
+
201
+ # -- consuming -----------------------------------------------------------------------------------------
202
+
203
+ def consume(self, topic: str, *, cancel: Optional[CancelToken] = None, **options: Any) -> List[Message]:
204
+ """
205
+ `GET /topics/{topic}/messages`. The read time is `wait_time + 10` seconds, not the `request_timeout`.
206
+ A timeout is not repeated (the node may have captured messages, which come back by themselves at the end
207
+ of the `visibility_timeout`). Returns an empty list if there are no messages. Options: `max_messages`,
208
+ `visibility_timeout`, `wait_time`, `auto_create`, `volatile`, `idle_timeout`, `fifo`, `tags`,
209
+ `request_id`, `traceparent`.
210
+ """
211
+ return self._consume(topic, ConsumeOptions(**options), cancel)
212
+
213
+ def _consume(self, topic: str, options: ConsumeOptions, cancel: Optional[CancelToken]) -> List[Message]:
214
+ return parse_messages(self._send(_calls.consume_call(topic, options), cancel).text)
215
+
216
+ def ack(
217
+ self,
218
+ topic: str,
219
+ message: Union[Message, str],
220
+ receipt_token: Optional[str] = None,
221
+ *,
222
+ cancel: Optional[CancelToken] = None,
223
+ ) -> None:
224
+ """`DELETE /topics/{topic}/messages/{id}?receiptToken=`. `message` is what `consume` returned, or its id."""
225
+ message_id, token = _calls.reference(message, receipt_token)
226
+ self._send(_calls.ack_call(topic, message_id, token), cancel)
227
+
228
+ def change_visibility(
229
+ self,
230
+ topic: str,
231
+ message: Union[Message, str],
232
+ seconds: int,
233
+ receipt_token: Optional[str] = None,
234
+ *,
235
+ cancel: Optional[CancelToken] = None,
236
+ ) -> VisibilityResponse:
237
+ """`PUT /topics/{topic}/messages/{id}/visibility?receiptToken=`."""
238
+ message_id, token = _calls.reference(message, receipt_token)
239
+ reply = self._send(_calls.change_visibility_call(topic, message_id, token, seconds), cancel)
240
+ return parse_visibility_response(reply.text)
241
+
242
+ def ack_batch(
243
+ self, topic: str, messages: List[Message], *, cancel: Optional[CancelToken] = None
244
+ ) -> List[BatchResult]:
245
+ """`POST /topics/{topic}/messages/ack`: acknowledges many messages `consume` returned, in one request."""
246
+ return parse_batch_results(self._send(_calls.receipts_call(topic, "ack", messages), cancel).text)
247
+
248
+ def change_visibility_batch(
249
+ self, topic: str, messages: List[Message], seconds: int, *, cancel: Optional[CancelToken] = None
250
+ ) -> List[BatchResult]:
251
+ """`POST /topics/{topic}/messages/visibility`: the invisibility of each message, `seconds` from now."""
252
+ call = _calls.receipts_call(topic, "visibility", messages, seconds)
253
+ return parse_batch_results(self._send(call, cancel).text)
254
+
255
+ def consume_with(
256
+ self,
257
+ topic: str,
258
+ handler: Callable[[MessageContext], None],
259
+ *,
260
+ cancel: Optional[CancelToken] = None,
261
+ **options: Any,
262
+ ) -> int:
263
+ """
264
+ Reads from the queue and hands each message to `handler(context)`. The message is deleted if the handler
265
+ returns without raising (`context.delete = False` keeps it). While the handler runs, the invisibility is
266
+ renewed every third of it, by another thread. Defaults: one message at a time, 20 s of long polling,
267
+ 120 s of invisibility. If the handler raises, the message is not deleted and the exception propagates.
268
+ Returns how many messages were handled.
269
+ """
270
+ opts = _calls.handler_defaults(ConsumeOptions(**options))
271
+ handled = 0
272
+ for message in self._consume(topic, opts, cancel):
273
+ context = self._context(topic, opts, message, cancel)
274
+ self._handle(topic, context, lambda c=context: handler(c))
275
+ handled += 1
276
+ return handled
277
+
278
+ def consume_json(
279
+ self,
280
+ topic: str,
281
+ handler: Callable[[MessageContext], None],
282
+ *,
283
+ cancel: Optional[CancelToken] = None,
284
+ **options: Any,
285
+ ) -> int:
286
+ """
287
+ `consume_with` with the body already parsed (with the configured `serializer`, or `json`) in
288
+ `context.body`. A body that does not parse gives `client.invalid-response` before the handler is called,
289
+ and the message is not deleted.
290
+ """
291
+ opts = _calls.handler_defaults(ConsumeOptions(**options))
292
+ handled = 0
293
+ for message in self._consume(topic, opts, cancel):
294
+ try:
295
+ body = self._serializer.loads(message.body_text)
296
+ except ValueError as e:
297
+ raise TabaError.client(
298
+ "client.invalid-response", "body of message %s is not valid JSON: %s" % (message.id, e)
299
+ )
300
+ context = self._context(topic, opts, message, cancel)
301
+ context.body = body
302
+ self._handle(topic, context, lambda c=context: handler(c))
303
+ handled += 1
304
+ return handled
305
+
306
+ def _context(self, topic: str, options: ConsumeOptions, message: Message, cancel: Optional[CancelToken]) -> MessageContext:
307
+ return MessageContext(
308
+ message,
309
+ options.visibility_timeout or _calls.HANDLER_VISIBILITY_TIMEOUT,
310
+ lambda seconds: self.change_visibility(topic, message, seconds, cancel=cancel),
311
+ )
312
+
313
+ def _handle(self, topic: str, context: MessageContext, run: Callable[[], None]) -> None:
314
+ stop = CancelToken()
315
+ renewal = threading.Thread(target=self._keep_alive, args=(topic, context, stop), daemon=True, name="taba-renewal")
316
+ renewal.start()
317
+ try:
318
+ run()
319
+ finally:
320
+ stop.cancel()
321
+ renewal.join()
322
+ if context.delete:
323
+ try:
324
+ # Without the token: the message was already handled, and acknowledging it must not be cut short.
325
+ self.ack(topic, context.message)
326
+ except TabaError as e:
327
+ if not _lost_or_gone(e):
328
+ raise
329
+
330
+ def _keep_alive(self, topic: str, context: MessageContext, stop: CancelToken) -> None:
331
+ """The second thread: renews the invisibility until the handler finishes. Never raises."""
332
+ try:
333
+ while not stop.is_set():
334
+ self._transport.sleep(_calls.renewal_interval(context.lease_seconds), stop)
335
+ try:
336
+ self.change_visibility(topic, context.message, context.lease_seconds, cancel=stop)
337
+ except TabaError as e:
338
+ if _lost_or_gone(e):
339
+ # The message already went back to the queue or was deleted: renewing is no longer of any use.
340
+ context._lost = True
341
+ return
342
+ # Transient failure (network, 5xx): tries again on the next round, before the deadline expires.
343
+ except Cancelled:
344
+ pass
345
+ finally:
346
+ self._transport.close() # this thread's own connection
347
+
348
+ def subscribe(
349
+ self,
350
+ topic: str,
351
+ handler: Callable[[Message], None],
352
+ *,
353
+ cancel: Optional[CancelToken] = None,
354
+ on_error: Optional[Callable[[Message, Exception], None]] = None,
355
+ **options: Any,
356
+ ) -> None:
357
+ """
358
+ The consume loop: long polling (`wait_time` 20 and one message at a time, if not set), calls
359
+ `handler(message)` and acknowledges by itself only if it returns without raising (a message that fails
360
+ goes back to the queue at the end of the `visibility_timeout`, and the error goes to
361
+ `on_error(message, error)`). Blocks until `cancel` is cancelled and then returns without an exception
362
+ (a `KeyboardInterrupt` propagates). A server error while consuming propagates.
363
+ """
364
+ cancel = cancel or CancelToken()
365
+ poll = _calls.subscribe_defaults(ConsumeOptions(**options))
366
+ while not cancel.is_set():
367
+ try:
368
+ messages = self._consume(topic, poll, cancel)
369
+ except Cancelled:
370
+ return
371
+ for message in messages:
372
+ handled = False
373
+ try:
374
+ handler(message)
375
+ handled = True
376
+ except Exception as e: # noqa: BLE001 - the handler is the application's code
377
+ if on_error is not None:
378
+ on_error(message, e)
379
+ if handled:
380
+ try:
381
+ # Without the token: the message was already handled.
382
+ self.ack(topic, message)
383
+ except TabaError as e:
384
+ if not _lost_or_gone(e):
385
+ raise
386
+ if cancel.is_set():
387
+ return
taba/errors.py ADDED
@@ -0,0 +1,49 @@
1
+ """The only kind of error of the connector (doc 21, "The common contract")."""
2
+
3
+ from typing import Optional
4
+
5
+
6
+ class TabaError(Exception):
7
+ """
8
+ The API `ErrorResponse`, or a failure of the client itself (`status` 0 and `code` `client.network`,
9
+ `client.timeout`, `client.invalid-config`, `client.invalid-response` or `client.invalid-request`).
10
+ Test the `code`, never the `message`.
11
+ """
12
+
13
+ def __init__(
14
+ self,
15
+ status: int,
16
+ code: str,
17
+ message: str,
18
+ request_id: Optional[str] = None,
19
+ retry_after: Optional[int] = None,
20
+ details: Optional[str] = None,
21
+ body: bytes = b"",
22
+ ) -> None:
23
+ super().__init__(message)
24
+ #: The HTTP status, or zero on a failure of the client itself.
25
+ self.status = status
26
+ #: The `group.reason` code of the error.
27
+ self.code = code or ""
28
+ self.message = message
29
+ #: The `requestId` of the `ErrorResponse`, or the `X-Request-Id` header.
30
+ self.request_id = request_id
31
+ #: The seconds of the `Retry-After`, if the response carried it.
32
+ self.retry_after = retry_after
33
+ #: The `details` of the `ErrorResponse`, as JSON text.
34
+ self.details = details
35
+ #: The response body, as it came (empty on a client failure).
36
+ self.body = body
37
+
38
+ @property
39
+ def is_client_side(self) -> bool:
40
+ """A failure of the client itself, not a server response."""
41
+ return self.status == 0
42
+
43
+ def __str__(self) -> str:
44
+ suffix = "" if self.request_id is None else " (requestId %s)" % self.request_id
45
+ return "%s: %s%s" % (self.code, self.message, suffix)
46
+
47
+ @classmethod
48
+ def client(cls, code: str, message: str) -> "TabaError":
49
+ return cls(0, code, message)