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/__init__.py +54 -0
- taba/_calls.py +232 -0
- taba/_json.py +165 -0
- taba/_transport.py +310 -0
- taba/_version.py +5 -0
- taba/aio.py +236 -0
- taba/cancel.py +62 -0
- taba/client.py +387 -0
- taba/errors.py +49 -0
- taba/models.py +409 -0
- taba/py.typed +0 -0
- taba_client-0.3.19.dist-info/METADATA +106 -0
- taba_client-0.3.19.dist-info/RECORD +15 -0
- taba_client-0.3.19.dist-info/WHEEL +5 -0
- taba_client-0.3.19.dist-info/top_level.txt +1 -0
taba/models.py
ADDED
|
@@ -0,0 +1,409 @@
|
|
|
1
|
+
"""The models of the client API and the reading of its JSON responses."""
|
|
2
|
+
|
|
3
|
+
import base64
|
|
4
|
+
import binascii
|
|
5
|
+
import json
|
|
6
|
+
import ssl
|
|
7
|
+
from dataclasses import dataclass, field
|
|
8
|
+
from typing import Any, Dict, List, Optional, Union
|
|
9
|
+
|
|
10
|
+
from ._json import JsonError, JsonFields, array_items, decode_string
|
|
11
|
+
from ._version import VERSION
|
|
12
|
+
from .errors import TabaError
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
@dataclass
|
|
16
|
+
class Config:
|
|
17
|
+
"""
|
|
18
|
+
The client configuration (doc 21). It does not read environment variables: `TABA_*` is the prefix of the
|
|
19
|
+
server configuration; whoever uses the connector reads their own and fills this object.
|
|
20
|
+
"""
|
|
21
|
+
|
|
22
|
+
#: Address of the client API load balancer (`http://host:port` or `https://...`). Required.
|
|
23
|
+
base_url: str = ""
|
|
24
|
+
#: Goes in `Authorization: Bearer`. Without it, the call goes without the header.
|
|
25
|
+
token: Optional[str] = None
|
|
26
|
+
#: Seconds to open the connection.
|
|
27
|
+
connect_timeout: float = 5.0
|
|
28
|
+
#: Seconds of an ordinary call. `consume` uses `wait_time + 10`.
|
|
29
|
+
request_timeout: float = 30.0
|
|
30
|
+
#: Attempts, counting the first.
|
|
31
|
+
max_attempts: int = 3
|
|
32
|
+
#: Goes in `User-Agent`. Add the application name.
|
|
33
|
+
user_agent: str = "taba-python/" + VERSION
|
|
34
|
+
#: Who serializes `publish_json` and parses `consume_json`: an object with `dumps` and `loads` (default: `json`).
|
|
35
|
+
serializer: Any = None
|
|
36
|
+
#: An own `ssl.SSLContext` (a private CA, for example). Default: the system's, TLS 1.2 or later.
|
|
37
|
+
ssl_context: Optional[ssl.SSLContext] = None
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
@dataclass(frozen=True)
|
|
41
|
+
class Topic:
|
|
42
|
+
id: str
|
|
43
|
+
name: str
|
|
44
|
+
#: `queue` or `distributor`.
|
|
45
|
+
type: str
|
|
46
|
+
#: Creation date, as RFC 3339 text.
|
|
47
|
+
created_at: str
|
|
48
|
+
fifo: Optional[bool] = None
|
|
49
|
+
volatile: Optional[bool] = None
|
|
50
|
+
#: The topic JSON, as the server returned it.
|
|
51
|
+
raw: str = ""
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
@dataclass(frozen=True)
|
|
55
|
+
class Page:
|
|
56
|
+
items: List[Topic]
|
|
57
|
+
#: The cursor of the next page, or `None` on the last one.
|
|
58
|
+
next_cursor: Optional[str]
|
|
59
|
+
raw: str = ""
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
@dataclass
|
|
63
|
+
class TopicRequest:
|
|
64
|
+
"""`POST /topics`. Only what was filled in is sent."""
|
|
65
|
+
|
|
66
|
+
name: str
|
|
67
|
+
#: `queue` or `distributor`.
|
|
68
|
+
type: str
|
|
69
|
+
tags: Optional[Dict[str, str]] = None
|
|
70
|
+
#: Distributor only: the name prefixes of the queues each publication is copied to.
|
|
71
|
+
prefixes: Optional[List[str]] = None
|
|
72
|
+
volatile: Optional[bool] = None
|
|
73
|
+
idle_timeout: Optional[int] = None
|
|
74
|
+
fifo: Optional[bool] = None
|
|
75
|
+
max_message_bytes: Optional[int] = None
|
|
76
|
+
ttl: Optional[int] = None
|
|
77
|
+
max_deliveries: Optional[int] = None
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
@dataclass(frozen=True)
|
|
81
|
+
class TopicPut:
|
|
82
|
+
"""What `create_or_update_topic` did and the topic as it is now."""
|
|
83
|
+
|
|
84
|
+
topic: Topic
|
|
85
|
+
#: `created` (`201`), `updated` (`200`: changed, or already as declared) or `recreated` (a new `id`).
|
|
86
|
+
outcome: str
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
class _Unset:
|
|
90
|
+
def __repr__(self) -> str:
|
|
91
|
+
return "UNSET"
|
|
92
|
+
|
|
93
|
+
def __bool__(self) -> bool:
|
|
94
|
+
return False
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
#: A `TopicUpdate` field left out of the request. `None` sends `null`: goes back to the server default.
|
|
98
|
+
UNSET: Any = _Unset()
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
@dataclass
|
|
102
|
+
class TopicUpdate:
|
|
103
|
+
"""`PATCH /topics/{topic}`: only what was filled in is sent."""
|
|
104
|
+
|
|
105
|
+
#: Replaces the whole map (an empty map clears the tags).
|
|
106
|
+
tags: Optional[Dict[str, str]] = None
|
|
107
|
+
prefixes: Optional[List[str]] = None
|
|
108
|
+
idle_timeout: Optional[int] = None
|
|
109
|
+
max_message_bytes: Any = UNSET
|
|
110
|
+
ttl: Any = UNSET
|
|
111
|
+
max_deliveries: Any = UNSET
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
@dataclass
|
|
115
|
+
class ConsumeOptions:
|
|
116
|
+
"""The `consume` options. The connector sends only what was set: whatever is missing takes the server default."""
|
|
117
|
+
|
|
118
|
+
max_messages: Optional[int] = None
|
|
119
|
+
#: Seconds of invisibility for the delivered messages.
|
|
120
|
+
visibility_timeout: Optional[int] = None
|
|
121
|
+
#: Seconds of long polling.
|
|
122
|
+
wait_time: Optional[int] = None
|
|
123
|
+
auto_create: bool = False
|
|
124
|
+
#: The next four only apply with `auto_create`.
|
|
125
|
+
volatile: Optional[bool] = None
|
|
126
|
+
idle_timeout: Optional[int] = None
|
|
127
|
+
fifo: Optional[bool] = None
|
|
128
|
+
tags: Optional[Dict[str, str]] = None
|
|
129
|
+
request_id: Optional[str] = None
|
|
130
|
+
traceparent: Optional[str] = None
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
@dataclass(frozen=True)
|
|
134
|
+
class Message:
|
|
135
|
+
"""A delivered message. The `body` always comes out as bytes (doc 21, "The delivered message")."""
|
|
136
|
+
|
|
137
|
+
id: str
|
|
138
|
+
#: JSON: the JSON text as it came. `text/*`: the UTF-8 text. base64: the bytes already decoded.
|
|
139
|
+
body: bytes
|
|
140
|
+
content_type: str
|
|
141
|
+
receipt_token: str
|
|
142
|
+
delivery_count: int = 0
|
|
143
|
+
#: As RFC 3339 text.
|
|
144
|
+
published_at: str = ""
|
|
145
|
+
invisible_until: str = ""
|
|
146
|
+
group_id: Optional[str] = None
|
|
147
|
+
deduplication_id: Optional[str] = None
|
|
148
|
+
dead_lettered_at: Optional[str] = None
|
|
149
|
+
dead_letter_reason: Optional[str] = None
|
|
150
|
+
#: The message JSON, as the server returned it.
|
|
151
|
+
raw: str = ""
|
|
152
|
+
|
|
153
|
+
@property
|
|
154
|
+
def body_text(self) -> str:
|
|
155
|
+
"""The `body` as UTF-8 text."""
|
|
156
|
+
return self.body.decode("utf-8")
|
|
157
|
+
|
|
158
|
+
def json(self) -> Any:
|
|
159
|
+
"""The `body` read as JSON."""
|
|
160
|
+
return json.loads(self.body_text)
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
@dataclass(frozen=True)
|
|
164
|
+
class DistributorDelivery:
|
|
165
|
+
"""The copy of a publication made by a distributor to a queue."""
|
|
166
|
+
|
|
167
|
+
topic: str
|
|
168
|
+
id: Optional[str] = None
|
|
169
|
+
error_code: Optional[str] = None
|
|
170
|
+
error_message: Optional[str] = None
|
|
171
|
+
|
|
172
|
+
@property
|
|
173
|
+
def succeeded(self) -> bool:
|
|
174
|
+
return self.error_code is None
|
|
175
|
+
|
|
176
|
+
|
|
177
|
+
@dataclass(frozen=True)
|
|
178
|
+
class PublishResponse:
|
|
179
|
+
#: The message `id` (queue). `None` in a distributor's response.
|
|
180
|
+
id: Optional[str] = None
|
|
181
|
+
#: FIFO queue only: `True` when it repeated a publication within the deduplication window.
|
|
182
|
+
duplicate: Optional[bool] = None
|
|
183
|
+
#: Distributor only: how many queues matched.
|
|
184
|
+
matched: Optional[int] = None
|
|
185
|
+
deliveries: List[DistributorDelivery] = field(default_factory=list)
|
|
186
|
+
raw: str = ""
|
|
187
|
+
|
|
188
|
+
|
|
189
|
+
@dataclass(frozen=True)
|
|
190
|
+
class VisibilityResponse:
|
|
191
|
+
id: str
|
|
192
|
+
invisible_until: str
|
|
193
|
+
raw: str = ""
|
|
194
|
+
|
|
195
|
+
|
|
196
|
+
@dataclass
|
|
197
|
+
class BatchMessage:
|
|
198
|
+
"""One message of `publish_batch`: the same fields as `publish`. The bytes travel in base64."""
|
|
199
|
+
|
|
200
|
+
body: Union[bytes, bytearray, memoryview, str]
|
|
201
|
+
#: Default `application/json`.
|
|
202
|
+
content_type: Optional[str] = None
|
|
203
|
+
group_id: Optional[str] = None
|
|
204
|
+
deduplication_id: Optional[str] = None
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
@dataclass(frozen=True)
|
|
208
|
+
class BatchResult:
|
|
209
|
+
"""
|
|
210
|
+
The result of one item of a batch, in the order of the request: the `status` the single call would have
|
|
211
|
+
answered and what it would have returned. An item that failed does not raise: `ok` is `False`.
|
|
212
|
+
"""
|
|
213
|
+
|
|
214
|
+
#: `201` published, `200` a FIFO duplicate, a distributor or a new invisibility, `204` acked, or the error's.
|
|
215
|
+
status: int
|
|
216
|
+
id: Optional[str] = None
|
|
217
|
+
duplicate: Optional[bool] = None
|
|
218
|
+
matched: Optional[int] = None
|
|
219
|
+
invisible_until: Optional[str] = None
|
|
220
|
+
error_code: Optional[str] = None
|
|
221
|
+
error_message: Optional[str] = None
|
|
222
|
+
raw: str = ""
|
|
223
|
+
|
|
224
|
+
@property
|
|
225
|
+
def ok(self) -> bool:
|
|
226
|
+
return self.error_code is None and self.status < 300
|
|
227
|
+
|
|
228
|
+
|
|
229
|
+
class MessageContext:
|
|
230
|
+
"""
|
|
231
|
+
What the `consume_with` handler receives: the `message`, the `delete` flag (the message is deleted at the end
|
|
232
|
+
if the handler returns without raising; the default is `True`) and `change_visibility`. While the handler
|
|
233
|
+
runs, the connector renews the invisibility by itself, so no other consumer takes the message.
|
|
234
|
+
"""
|
|
235
|
+
|
|
236
|
+
def __init__(self, message: Message, lease_seconds: int, change: Any) -> None:
|
|
237
|
+
self.message = message
|
|
238
|
+
self.delete = True
|
|
239
|
+
#: `consume_json` only: the parsed body.
|
|
240
|
+
self.body: Any = None
|
|
241
|
+
self._lease_seconds = lease_seconds
|
|
242
|
+
self._lost = False
|
|
243
|
+
self._change = change
|
|
244
|
+
|
|
245
|
+
@property
|
|
246
|
+
def lease_seconds(self) -> int:
|
|
247
|
+
"""The seconds of invisibility the automatic renewal requests on each round."""
|
|
248
|
+
return self._lease_seconds
|
|
249
|
+
|
|
250
|
+
@property
|
|
251
|
+
def lease_lost(self) -> bool:
|
|
252
|
+
"""`True` when the server refused the renewal (the message already went back to the queue or was deleted)."""
|
|
253
|
+
return self._lost
|
|
254
|
+
|
|
255
|
+
def change_visibility(self, seconds: int) -> None:
|
|
256
|
+
"""Changes the invisibility to `seconds` from now on. The value becomes the one of the automatic renewal."""
|
|
257
|
+
self._change(seconds)
|
|
258
|
+
self._lease_seconds = seconds
|
|
259
|
+
|
|
260
|
+
|
|
261
|
+
# -- reading the responses ---------------------------------------------------------------------------------
|
|
262
|
+
|
|
263
|
+
|
|
264
|
+
def _invalid(what: str, error: JsonError) -> TabaError:
|
|
265
|
+
return TabaError.client("client.invalid-response", "%s: %s" % (what, error))
|
|
266
|
+
|
|
267
|
+
|
|
268
|
+
def _fields(raw: str, what: str) -> JsonFields:
|
|
269
|
+
try:
|
|
270
|
+
return JsonFields.parse(raw)
|
|
271
|
+
except JsonError as e:
|
|
272
|
+
raise _invalid(what, e)
|
|
273
|
+
|
|
274
|
+
|
|
275
|
+
def _is_json_type(content_type: str) -> bool:
|
|
276
|
+
media = content_type.split(";")[0].strip().lower()
|
|
277
|
+
return media == "application/json" or media.endswith("+json")
|
|
278
|
+
|
|
279
|
+
|
|
280
|
+
def parse_topic(raw: str) -> Topic:
|
|
281
|
+
f = _fields(raw, "topic")
|
|
282
|
+
try:
|
|
283
|
+
return Topic(
|
|
284
|
+
id=f.string("id") or "",
|
|
285
|
+
name=f.string("name") or "",
|
|
286
|
+
type=f.string("type") or "",
|
|
287
|
+
created_at=f.string("createdAt") or "",
|
|
288
|
+
fifo=f.boolean("fifo"),
|
|
289
|
+
volatile=f.boolean("volatile"),
|
|
290
|
+
raw=raw,
|
|
291
|
+
)
|
|
292
|
+
except JsonError as e:
|
|
293
|
+
raise _invalid("topic", e)
|
|
294
|
+
|
|
295
|
+
|
|
296
|
+
def parse_message(raw: str) -> Message:
|
|
297
|
+
f = _fields(raw, "message")
|
|
298
|
+
try:
|
|
299
|
+
content_type = f.string("contentType") or "application/json"
|
|
300
|
+
body = f.raw("body")
|
|
301
|
+
if body is None:
|
|
302
|
+
data = b""
|
|
303
|
+
elif f.string("bodyEncoding") == "base64":
|
|
304
|
+
try:
|
|
305
|
+
data = base64.b64decode(decode_string(body), validate=True)
|
|
306
|
+
except (binascii.Error, ValueError):
|
|
307
|
+
raise TabaError.client("client.invalid-response", "invalid base64 body")
|
|
308
|
+
elif _is_json_type(content_type):
|
|
309
|
+
data = body.encode("utf-8")
|
|
310
|
+
else:
|
|
311
|
+
data = decode_string(body).encode("utf-8")
|
|
312
|
+
return Message(
|
|
313
|
+
id=f.string("id") or "",
|
|
314
|
+
body=data,
|
|
315
|
+
content_type=content_type,
|
|
316
|
+
receipt_token=f.string("receiptToken") or "",
|
|
317
|
+
delivery_count=f.integer("deliveryCount") or 0,
|
|
318
|
+
published_at=f.string("publishedAt") or "",
|
|
319
|
+
invisible_until=f.string("invisibleUntil") or "",
|
|
320
|
+
group_id=f.string("groupId"),
|
|
321
|
+
deduplication_id=f.string("deduplicationId"),
|
|
322
|
+
dead_lettered_at=f.string("deadLetteredAt"),
|
|
323
|
+
dead_letter_reason=f.string("deadLetterReason"),
|
|
324
|
+
raw=raw,
|
|
325
|
+
)
|
|
326
|
+
except JsonError as e:
|
|
327
|
+
raise _invalid("message", e)
|
|
328
|
+
|
|
329
|
+
|
|
330
|
+
def parse_messages(raw: str) -> List[Message]:
|
|
331
|
+
f = _fields(raw, "consume")
|
|
332
|
+
try:
|
|
333
|
+
return [parse_message(item) for item in array_items(f.raw("messages") or "[]")]
|
|
334
|
+
except JsonError as e:
|
|
335
|
+
raise _invalid("messages", e)
|
|
336
|
+
|
|
337
|
+
|
|
338
|
+
def parse_page(raw: str) -> Page:
|
|
339
|
+
f = _fields(raw, "page")
|
|
340
|
+
try:
|
|
341
|
+
items = [parse_topic(item) for item in array_items(f.raw("items") or "[]")]
|
|
342
|
+
return Page(items=items, next_cursor=f.string("nextCursor"), raw=raw)
|
|
343
|
+
except JsonError as e:
|
|
344
|
+
raise _invalid("page items", e)
|
|
345
|
+
|
|
346
|
+
|
|
347
|
+
def parse_publish_response(raw: str) -> PublishResponse:
|
|
348
|
+
f = _fields(raw, "publication")
|
|
349
|
+
try:
|
|
350
|
+
deliveries: List[DistributorDelivery] = []
|
|
351
|
+
listing = f.raw("deliveries")
|
|
352
|
+
if listing is not None:
|
|
353
|
+
for item in array_items(listing):
|
|
354
|
+
d = JsonFields.parse(item)
|
|
355
|
+
error = d.raw("error")
|
|
356
|
+
e = JsonFields.parse(error) if error is not None and error.startswith("{") else None
|
|
357
|
+
deliveries.append(
|
|
358
|
+
DistributorDelivery(
|
|
359
|
+
topic=d.string("topic") or "",
|
|
360
|
+
id=d.string("id"),
|
|
361
|
+
error_code=None if e is None else (e.string("code") or ""),
|
|
362
|
+
error_message=None if e is None else e.string("message"),
|
|
363
|
+
)
|
|
364
|
+
)
|
|
365
|
+
return PublishResponse(
|
|
366
|
+
id=f.string("id"),
|
|
367
|
+
duplicate=f.boolean("duplicate"),
|
|
368
|
+
matched=f.integer("matched"),
|
|
369
|
+
deliveries=deliveries,
|
|
370
|
+
raw=raw,
|
|
371
|
+
)
|
|
372
|
+
except JsonError as e:
|
|
373
|
+
raise _invalid("publication", e)
|
|
374
|
+
|
|
375
|
+
|
|
376
|
+
def parse_batch_results(raw: str) -> List[BatchResult]:
|
|
377
|
+
"""The `results` of a batch, one per item in the order of the request."""
|
|
378
|
+
f = _fields(raw, "batch")
|
|
379
|
+
try:
|
|
380
|
+
results: List[BatchResult] = []
|
|
381
|
+
for item in array_items(f.raw("results") or "[]"):
|
|
382
|
+
r = JsonFields.parse(item)
|
|
383
|
+
error = r.raw("error")
|
|
384
|
+
e = JsonFields.parse(error) if error is not None and error.startswith("{") else None
|
|
385
|
+
results.append(
|
|
386
|
+
BatchResult(
|
|
387
|
+
status=r.integer("status") or 0,
|
|
388
|
+
id=r.string("id"),
|
|
389
|
+
duplicate=r.boolean("duplicate"),
|
|
390
|
+
matched=r.integer("matched"),
|
|
391
|
+
invisible_until=r.string("invisibleUntil"),
|
|
392
|
+
error_code=None if e is None else (e.string("code") or ""),
|
|
393
|
+
error_message=None if e is None else e.string("message"),
|
|
394
|
+
raw=item,
|
|
395
|
+
)
|
|
396
|
+
)
|
|
397
|
+
return results
|
|
398
|
+
except JsonError as e:
|
|
399
|
+
raise _invalid("batch results", e)
|
|
400
|
+
|
|
401
|
+
|
|
402
|
+
def parse_visibility_response(raw: str) -> VisibilityResponse:
|
|
403
|
+
f = _fields(raw, "visibility")
|
|
404
|
+
try:
|
|
405
|
+
return VisibilityResponse(
|
|
406
|
+
id=f.string("id") or "", invisible_until=f.string("invisibleUntil") or "", raw=raw
|
|
407
|
+
)
|
|
408
|
+
except JsonError as e:
|
|
409
|
+
raise _invalid("visibility", e)
|
taba/py.typed
ADDED
|
File without changes
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: taba-client
|
|
3
|
+
Version: 0.3.19
|
|
4
|
+
Summary: Taba messaging system client: the nine operations, subscribe, call retries. No dependencies.
|
|
5
|
+
License: Apache-2.0
|
|
6
|
+
Project-URL: Repository, https://github.com/rafaelpontani/taba
|
|
7
|
+
Keywords: taba,queue,messaging,client
|
|
8
|
+
Classifier: License :: OSI Approved :: Apache Software License
|
|
9
|
+
Classifier: Programming Language :: Python :: 3
|
|
10
|
+
Classifier: Typing :: Typed
|
|
11
|
+
Requires-Python: >=3.9
|
|
12
|
+
Description-Content-Type: text/markdown
|
|
13
|
+
|
|
14
|
+
# taba-client (Python)
|
|
15
|
+
|
|
16
|
+
The Python client of [Taba](https://github.com/rafaelpontani/taba): the nine operations of the client API, `subscribe`, consuming with a handler (with automatic renewal of the invisibility) and the call retries of the common contract. **No dependencies** (only the standard library); typed.
|
|
17
|
+
|
|
18
|
+
> Other languages: [Português (Brasil)](https://github.com/rafaelpontani/taba/blob/main/doc/pt-BR/21-conectores.md) · [all languages](https://github.com/rafaelpontani/taba/blob/main/doc/README.md)
|
|
19
|
+
|
|
20
|
+
- **Python 3.9 or later.**
|
|
21
|
+
- `taba.Client` is synchronous and safe for concurrent use (each thread has its own connection); `taba.aio.AsyncClient` is the `asyncio` one.
|
|
22
|
+
|
|
23
|
+
```python
|
|
24
|
+
from taba import Client, TopicRequest
|
|
25
|
+
|
|
26
|
+
with Client("http://localhost:8080", token="...") as client:
|
|
27
|
+
client.create_topic(TopicRequest("orders", "queue"))
|
|
28
|
+
client.publish_json("orders", {"order": 9001})
|
|
29
|
+
|
|
30
|
+
# Consume with a handler: the message is deleted if the handler does not raise.
|
|
31
|
+
def handle(context):
|
|
32
|
+
print(context.message.body_text)
|
|
33
|
+
|
|
34
|
+
client.consume_with("orders", handle, wait_time=20)
|
|
35
|
+
|
|
36
|
+
# Or the whole loop, until the token is cancelled.
|
|
37
|
+
# client.subscribe("orders", lambda message: print(message.json()), cancel=token)
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
```python
|
|
41
|
+
import asyncio
|
|
42
|
+
from taba.aio import AsyncClient
|
|
43
|
+
|
|
44
|
+
async def main():
|
|
45
|
+
async with AsyncClient("http://localhost:8080") as client:
|
|
46
|
+
for message in await client.consume("orders", wait_time=20):
|
|
47
|
+
await client.ack("orders", message)
|
|
48
|
+
|
|
49
|
+
asyncio.run(main())
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Installing
|
|
53
|
+
|
|
54
|
+
```
|
|
55
|
+
pip install taba-client
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
The package has the version of the Taba release it came with and is published from the release workflow of this repository with PyPI Trusted Publishing. A release candidate is published in the PEP 440 form (`0.3.19rc1`), which `pip` only installs when asked (`pip install --pre taba-client`). Each [Release](https://github.com/rafaelpontani/taba/releases) also has the same wheel, `taba_client-<release>-py3-none-any.whl`, with its checksum in `SHA256SUMS` and its provenance (`gh attestation verify <file> -R rafaelpontani/taba`).
|
|
59
|
+
|
|
60
|
+
Straight from the source, with no Release (a branch, a tag or a commit after the `@`):
|
|
61
|
+
|
|
62
|
+
```
|
|
63
|
+
pip install "git+https://github.com/rafaelpontani/taba.git@release#subdirectory=connectors/python"
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
## Declaring a topic
|
|
67
|
+
|
|
68
|
+
`create_or_update_topic(request, recreate=None)` (`PUT /topics/{topic}`, also on `AsyncClient`) creates the topic or brings it to the declared state, and returns a `TopicPut` with the `topic` and the `outcome` (`created`, `updated` or `recreated`). What is left out goes back to the server default (a full replacement, unlike the update); another type, `fifo` or `volatile` is the error `409 topic.immutable-mismatch` unless `recreate` is `if-empty` (only when the queue and its dead-letter are empty, `409 topic.not-empty` otherwise) or `always` (drops the messages; new `id`). After a `503` the call is repeated like the others. `delete_topic(name, if_empty=True)` only removes a queue with no message. `create_topic` does not change (`409` when it exists). Details: [Create or update a topic](https://github.com/rafaelpontani/taba/blob/main/doc/en-US/16-client-api.md#create-or-update-a-topic-put-topicstopic).
|
|
69
|
+
|
|
70
|
+
## Batches
|
|
71
|
+
|
|
72
|
+
Many messages in one request, next to the single calls (optional): `publish_batch(topic, [BatchMessage(body, content_type=...)])`, `ack_batch(topic, messages)` and `change_visibility_batch(topic, messages, seconds)` (also on `AsyncClient`) return one `BatchResult` per item (`ok`, `status`, `id`, `error_code`). Each item is answered as its single call, in order, and an item that failed comes back with its `status` and error code instead of throwing. The bodies go in base64, so any type fits. Details: [Messages in batch](https://github.com/rafaelpontani/taba/blob/main/doc/en-US/16-client-api.md#messages-in-batch-post-messagesbatch-ack-and-visibility).
|
|
73
|
+
|
|
74
|
+
## Configuration
|
|
75
|
+
|
|
76
|
+
`Client(Config(...))`, or `Client(base_url, **options)` with the same fields. The client does not read environment variables: `TABA_*` belongs to the server.
|
|
77
|
+
|
|
78
|
+
| Field | Default | |
|
|
79
|
+
|---|---|---|
|
|
80
|
+
| `base_url` | required | `http://host:port` or `https://...` |
|
|
81
|
+
| `token` | none | `Authorization: Bearer` |
|
|
82
|
+
| `connect_timeout` | `5.0` | seconds |
|
|
83
|
+
| `request_timeout` | `30.0` | seconds; `consume` uses `wait_time + 10` |
|
|
84
|
+
| `max_attempts` | `3` | counting the first |
|
|
85
|
+
| `user_agent` | `taba-python/<version>` | |
|
|
86
|
+
| `serializer` | `json` | an object with `dumps` and `loads`, for `publish_json` and `consume_json` |
|
|
87
|
+
| `ssl_context` | system's, TLS 1.2+ | an own `ssl.SSLContext` (a private CA, for example) |
|
|
88
|
+
|
|
89
|
+
## What differs from the other connectors
|
|
90
|
+
|
|
91
|
+
- Names are `snake_case`; options are keyword arguments (`client.consume("q", max_messages=5, wait_time=20)`), and `ack`/`change_visibility` take the `Message` you received or its id plus `receipt_token`.
|
|
92
|
+
- A `TopicUpdate` field left at its default is not sent; `None` sends `null` (back to the server default) for `max_message_bytes`, `ttl` and `max_deliveries`.
|
|
93
|
+
- Cancelling: the synchronous client takes a `CancelToken` (`cancel=token`; it closes the connection in flight, so a long polling does not wait for its timeout) and raises `taba.Cancelled`; `subscribe` returns without an exception. The `asyncio` client is cancelled the `asyncio` way (`task.cancel()`), which raises `asyncio.CancelledError`.
|
|
94
|
+
- `iter_topics()` is a generator over all the pages; `list_all_topics()` returns the list.
|
|
95
|
+
- Errors are always a `TabaError` with `status`, `code`, `message`, `request_id`, `retry_after`, `details`. Test the `code`, never the `message`.
|
|
96
|
+
- The standard library has no asynchronous HTTP client, so the `asyncio` client runs the synchronous transport in worker threads (`asyncio.to_thread`).
|
|
97
|
+
- TLS is Python's own, with TLS 1.2 as the minimum; the certificate is always verified.
|
|
98
|
+
|
|
99
|
+
## Tests
|
|
100
|
+
|
|
101
|
+
```
|
|
102
|
+
cd connectors/python
|
|
103
|
+
python -m unittest discover -s tests -t .
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
The tests start a local HTTP server that records every request and answers from a script (the equivalent of the C# `ScriptedHandler`). The **contract tests** run the same scenario against a real Taba (one node in Docker), on the oldest supported version: `contract/run.sh` (`../contract/run.sh` for all the connectors; [how it works](https://github.com/rafaelpontani/taba/blob/main/connectors/contract/README.md)).
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
taba/__init__.py,sha256=K228ook9zDLQscsYNsWdyL8a48Khbq84QijKsbXEaFs,1139
|
|
2
|
+
taba/_calls.py,sha256=tMTe2vR9qXj5XOXBGiKYRjau8372mbtP7WLLHbjBINc,9208
|
|
3
|
+
taba/_json.py,sha256=ODJEegI_EKLrXSylTHqM0xwJaUGeFQzktHOzAbOvDbA,4943
|
|
4
|
+
taba/_transport.py,sha256=ENbdGZRpSayMbpdzYNjBCtm-Ray5aRoUH-phWseyJnc,12704
|
|
5
|
+
taba/_version.py,sha256=GE7eD8TCptRzSISdGwcWTC2UTcjhDFgol_EWO2xLsNI,139
|
|
6
|
+
taba/aio.py,sha256=k2o1ya1fP26WgYXjZ9HvUv_QUyoZRO0dJGwCg7Zhcik,10570
|
|
7
|
+
taba/cancel.py,sha256=hKoyEHd1vNm4nzD0tNRXceqlec9BTT4Ga5Nld_DyoZ8,1980
|
|
8
|
+
taba/client.py,sha256=vw9_j2OzZUHgUcAGfp9t08Vk1Dq_mDF78ahlcYJrVyw,17292
|
|
9
|
+
taba/errors.py,sha256=8Cb_CIC4gjF-xR64PlzfRcbSiZj1EGlvNplpTqtB_D4,1779
|
|
10
|
+
taba/models.py,sha256=zTrZGabl_pPIPXQAwaU--5yP461ukujMmNeVbQoQToQ,13615
|
|
11
|
+
taba/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
12
|
+
taba_client-0.3.19.dist-info/METADATA,sha256=j4iJAyCBv4HxIBTQascyE5nUh2g_H1uxVeYy-yilwUo,6856
|
|
13
|
+
taba_client-0.3.19.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
14
|
+
taba_client-0.3.19.dist-info/top_level.txt,sha256=LX5dolNzVxAFLapQQNus4RpNt2xwtt6q4HiUqAEgjgk,5
|
|
15
|
+
taba_client-0.3.19.dist-info/RECORD,,
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
taba
|