taba-client 0.3.19rc1__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 ADDED
@@ -0,0 +1,54 @@
1
+ """
2
+ The Python client of Taba (https://github.com/rafaelpontani/taba): the nine operations of the client API,
3
+ `subscribe`, consuming with a handler and the call retries of the common contract. No dependencies.
4
+
5
+ `taba.Client` is synchronous; `taba.aio.AsyncClient` is the `asyncio` one.
6
+ """
7
+
8
+ from ._version import CONTRACT_VERSION, VERSION
9
+ from .cancel import Cancelled, CancelToken
10
+ from .client import Client
11
+ from .errors import TabaError
12
+ from .models import (
13
+ UNSET,
14
+ BatchMessage,
15
+ BatchResult,
16
+ Config,
17
+ ConsumeOptions,
18
+ DistributorDelivery,
19
+ Message,
20
+ MessageContext,
21
+ Page,
22
+ PublishResponse,
23
+ Topic,
24
+ TopicPut,
25
+ TopicRequest,
26
+ TopicUpdate,
27
+ VisibilityResponse,
28
+ )
29
+
30
+ __version__ = VERSION
31
+
32
+ __all__ = [
33
+ "CONTRACT_VERSION",
34
+ "UNSET",
35
+ "VERSION",
36
+ "BatchMessage",
37
+ "BatchResult",
38
+ "Cancelled",
39
+ "CancelToken",
40
+ "Client",
41
+ "Config",
42
+ "ConsumeOptions",
43
+ "DistributorDelivery",
44
+ "Message",
45
+ "MessageContext",
46
+ "Page",
47
+ "PublishResponse",
48
+ "TabaError",
49
+ "Topic",
50
+ "TopicPut",
51
+ "TopicRequest",
52
+ "TopicUpdate",
53
+ "VisibilityResponse",
54
+ ]
taba/_calls.py ADDED
@@ -0,0 +1,232 @@
1
+ """Builds the `ApiCall` of each operation. Shared by the synchronous and the asynchronous client."""
2
+
3
+ import base64
4
+ import json
5
+ from typing import Any, Dict, List, Optional, Union
6
+
7
+ from ._transport import ApiCall, segment
8
+ from .errors import TabaError
9
+ from .models import UNSET, BatchMessage, ConsumeOptions, Message, TopicRequest, TopicUpdate
10
+
11
+ #: `consume` waits `wait_time` plus this slack (seconds), not the `request_timeout`.
12
+ LONG_POLL_SLACK = 10.0
13
+
14
+ HANDLER_MAX_MESSAGES = 1
15
+ HANDLER_VISIBILITY_TIMEOUT = 120
16
+ HANDLER_WAIT_TIME = 20
17
+
18
+
19
+ def create_topic_call(request: TopicRequest) -> ApiCall:
20
+ if request is None:
21
+ raise TabaError.client("client.invalid-request", "request is required")
22
+ body: Dict[str, Any] = {"name": request.name or ""}
23
+ body.update(_topic_fields(request))
24
+ call = ApiCall("POST", "/topics").with_json(json.dumps(body, separators=(",", ":")))
25
+ call.recover.append((409, "topic.already-exists"))
26
+ return call
27
+
28
+
29
+ def put_topic_call(request: TopicRequest, recreate: Optional[str]) -> ApiCall:
30
+ """`PUT /topics/{topic}`: the fields of `POST /topics` without `name` (it goes in the path)."""
31
+ if request is None:
32
+ raise TabaError.client("client.invalid-request", "request is required")
33
+ if recreate not in (None, "if-empty", "always"):
34
+ raise TabaError.client("client.invalid-request", "recreate must be 'if-empty' or 'always'")
35
+ body = _topic_fields(request)
36
+ call = ApiCall("PUT", "/topics/" + segment(request.name or "")).with_json(json.dumps(body, separators=(",", ":")))
37
+ if recreate is not None:
38
+ call.with_query("recreate", recreate)
39
+ return call
40
+
41
+
42
+ def _topic_fields(request: TopicRequest) -> Dict[str, Any]:
43
+ body: Dict[str, Any] = {"type": request.type or ""}
44
+ if request.tags:
45
+ body["tags"] = request.tags
46
+ if request.prefixes:
47
+ body["prefixes"] = request.prefixes
48
+ for attribute, name in (
49
+ ("volatile", "volatile"),
50
+ ("idle_timeout", "idleTimeout"),
51
+ ("fifo", "fifo"),
52
+ ("max_message_bytes", "maxMessageBytes"),
53
+ ("ttl", "ttl"),
54
+ ("max_deliveries", "maxDeliveries"),
55
+ ):
56
+ value = getattr(request, attribute)
57
+ if value is not None:
58
+ body[name] = value
59
+ return body
60
+
61
+
62
+ def get_topic_call(name: str) -> ApiCall:
63
+ return ApiCall("GET", "/topics/" + segment(name))
64
+
65
+
66
+ def list_topics_call(limit: Optional[int], cursor: Optional[str], name: Optional[str]) -> ApiCall:
67
+ call = ApiCall("GET", "/topics")
68
+ if limit is not None:
69
+ call.with_query("limit", limit)
70
+ if cursor is not None:
71
+ call.with_query("cursor", cursor)
72
+ if name is not None:
73
+ call.with_query("name", name)
74
+ return call
75
+
76
+
77
+ def update_topic_call(name: str, update: TopicUpdate) -> ApiCall:
78
+ if update is None:
79
+ raise TabaError.client("client.invalid-request", "update is required")
80
+ body: Dict[str, Any] = {}
81
+ if update.tags is not None:
82
+ body["tags"] = update.tags
83
+ if update.prefixes is not None:
84
+ body["prefixes"] = update.prefixes
85
+ if update.idle_timeout is not None:
86
+ body["idleTimeout"] = update.idle_timeout
87
+ # `UNSET` leaves the field out; `None` sends `null` (back to the server default).
88
+ for value, key in (
89
+ (update.max_message_bytes, "maxMessageBytes"),
90
+ (update.ttl, "ttl"),
91
+ (update.max_deliveries, "maxDeliveries"),
92
+ ):
93
+ if value is not UNSET:
94
+ body[key] = value
95
+ return ApiCall("PATCH", "/topics/" + segment(name)).with_json(json.dumps(body, separators=(",", ":")))
96
+
97
+
98
+ def delete_topic_call(name: str, if_empty: bool = False) -> ApiCall:
99
+ call = ApiCall("DELETE", "/topics/" + segment(name))
100
+ if if_empty:
101
+ call.with_query("ifEmpty", "true")
102
+ call.recover.append((404, "topic.not-found"))
103
+ return call
104
+
105
+
106
+ def publish_call(
107
+ topic: str,
108
+ body: Union[bytes, bytearray, memoryview, str, None],
109
+ content_type: Optional[str] = None,
110
+ group_id: Optional[str] = None,
111
+ deduplication_id: Optional[str] = None,
112
+ request_id: Optional[str] = None,
113
+ traceparent: Optional[str] = None,
114
+ fifo: bool = False,
115
+ ) -> ApiCall:
116
+ if body is None:
117
+ data = b""
118
+ elif isinstance(body, str):
119
+ data = body.encode("utf-8")
120
+ else:
121
+ data = bytes(body)
122
+ call = ApiCall("POST", "/topics/%s/messages" % segment(topic))
123
+ call.body = data
124
+ call.content_type = content_type or "application/json"
125
+ call.request_id = request_id
126
+ call.traceparent = traceparent
127
+ call.retry_gateway = bool(fifo)
128
+ if group_id is not None:
129
+ call.with_query("groupId", group_id)
130
+ if deduplication_id is not None:
131
+ call.with_query("deduplicationId", deduplication_id)
132
+ return call
133
+
134
+
135
+ def publish_batch_call(topic: str, messages: List[BatchMessage]) -> ApiCall:
136
+ items = []
137
+ for m in messages:
138
+ data = m.body.encode("utf-8") if isinstance(m.body, str) else bytes(m.body)
139
+ item: Dict[str, Any] = {"body": base64.b64encode(data).decode("ascii"), "bodyEncoding": "base64"}
140
+ for value, key in (
141
+ (m.content_type, "contentType"),
142
+ (m.group_id, "groupId"),
143
+ (m.deduplication_id, "deduplicationId"),
144
+ ):
145
+ if value is not None:
146
+ item[key] = value
147
+ items.append(item)
148
+ body = json.dumps({"messages": items}, separators=(",", ":"), ensure_ascii=False)
149
+ return ApiCall("POST", "/topics/%s/messages/batch" % segment(topic)).with_json(body)
150
+
151
+
152
+ def receipts_call(topic: str, route: str, messages: List[Message], seconds: Optional[int] = None) -> ApiCall:
153
+ """The ack (`route` `ack`) or the change of invisibility (`visibility`) of many messages in one request."""
154
+ items = []
155
+ for m in messages:
156
+ item: Dict[str, Any] = {"id": m.id, "receiptToken": m.receipt_token}
157
+ if seconds is not None:
158
+ item["visibilityTimeout"] = seconds
159
+ items.append(item)
160
+ body = json.dumps({"messages": items}, separators=(",", ":"), ensure_ascii=False)
161
+ return ApiCall("POST", "/topics/%s/messages/%s" % (segment(topic), route)).with_json(body)
162
+
163
+
164
+ def consume_call(topic: str, options: Optional[ConsumeOptions]) -> ApiCall:
165
+ o = options or ConsumeOptions()
166
+ call = ApiCall("GET", "/topics/%s/messages" % segment(topic))
167
+ if o.max_messages is not None:
168
+ call.with_query("maxMessages", o.max_messages)
169
+ if o.visibility_timeout is not None:
170
+ call.with_query("visibilityTimeout", o.visibility_timeout)
171
+ if o.wait_time is not None:
172
+ call.with_query("waitTime", o.wait_time)
173
+ if o.auto_create:
174
+ call.with_query("autoCreate", True)
175
+ if o.volatile is not None:
176
+ call.with_query("volatile", o.volatile)
177
+ if o.idle_timeout is not None:
178
+ call.with_query("idleTimeout", o.idle_timeout)
179
+ if o.fifo is not None:
180
+ call.with_query("fifo", o.fifo)
181
+ for key, value in (o.tags or {}).items():
182
+ call.with_query("tag." + key, value)
183
+ call.request_id = o.request_id
184
+ call.traceparent = o.traceparent
185
+ call.timeout = float(o.wait_time or 0) + LONG_POLL_SLACK
186
+ return call
187
+
188
+
189
+ def ack_call(topic: str, message_id: str, receipt_token: str) -> ApiCall:
190
+ call = ApiCall("DELETE", "/topics/%s/messages/%s" % (segment(topic), segment(message_id)))
191
+ return call.with_query("receiptToken", receipt_token)
192
+
193
+
194
+ def change_visibility_call(topic: str, message_id: str, receipt_token: str, seconds: int) -> ApiCall:
195
+ call = ApiCall("PUT", "/topics/%s/messages/%s/visibility" % (segment(topic), segment(message_id)))
196
+ call.with_query("receiptToken", receipt_token)
197
+ return call.with_json(json.dumps({"visibilityTimeout": int(seconds)}, separators=(",", ":")))
198
+
199
+
200
+ def reference(message: Union[Message, str], receipt_token: Optional[str]) -> "tuple[str, str]":
201
+ """A message received from `consume`, or its `id` with the `receipt_token`."""
202
+ if isinstance(message, str):
203
+ if receipt_token is None:
204
+ raise TabaError.client("client.invalid-request", "receipt_token is required with a message id")
205
+ return message, receipt_token
206
+ return message.id, message.receipt_token
207
+
208
+
209
+ def handler_defaults(options: Optional[ConsumeOptions]) -> ConsumeOptions:
210
+ """One message at a time, 20 s of long polling and 120 s of invisibility, which the renewal keeps."""
211
+ o = ConsumeOptions(**vars(options)) if options is not None else ConsumeOptions()
212
+ if o.max_messages is None:
213
+ o.max_messages = HANDLER_MAX_MESSAGES
214
+ if o.visibility_timeout is None:
215
+ o.visibility_timeout = HANDLER_VISIBILITY_TIMEOUT
216
+ if o.wait_time is None:
217
+ o.wait_time = HANDLER_WAIT_TIME
218
+ return o
219
+
220
+
221
+ def subscribe_defaults(options: Optional[ConsumeOptions]) -> ConsumeOptions:
222
+ o = ConsumeOptions(**vars(options)) if options is not None else ConsumeOptions()
223
+ if o.wait_time is None:
224
+ o.wait_time = HANDLER_WAIT_TIME
225
+ if o.max_messages is None:
226
+ o.max_messages = HANDLER_MAX_MESSAGES
227
+ return o
228
+
229
+
230
+ def renewal_interval(lease_seconds: int) -> float:
231
+ """A third of the invisibility (and never all of it), so a failed renewal can be tried again in time."""
232
+ return max(1, lease_seconds) / 3.0
taba/_json.py ADDED
@@ -0,0 +1,165 @@
1
+ """
2
+ The minimal JSON reader (doc 21, "No dependencies"): walks the text once and delivers the fields of an object as
3
+ name -> text fragment and the items of an array as text fragments, without interpreting them. That keeps the
4
+ message `body` exactly as the server sent it (`json.loads` would turn `1.0` into a float and reformat the text).
5
+ """
6
+
7
+ import json
8
+ import re
9
+ from typing import Dict, List, Optional
10
+
11
+ _WHITESPACE = " \t\r\n"
12
+
13
+
14
+ class JsonError(ValueError):
15
+ pass
16
+
17
+
18
+ def _skip(s: str, i: int) -> int:
19
+ n = len(s)
20
+ while i < n and s[i] in _WHITESPACE:
21
+ i += 1
22
+ return i
23
+
24
+
25
+ def _scan_string(s: str, i: int) -> int:
26
+ i += 1
27
+ n = len(s)
28
+ while i < n:
29
+ c = s[i]
30
+ if c == "\\":
31
+ i += 1
32
+ elif c == '"':
33
+ return i + 1
34
+ i += 1
35
+ raise JsonError("unterminated string")
36
+
37
+
38
+ def _scan_value(s: str, i: int) -> int:
39
+ """The index right after the value that starts at `i` (iterative: deep nesting does not use the stack)."""
40
+ n = len(s)
41
+ if i >= n:
42
+ raise JsonError("value expected")
43
+ first = s[i]
44
+ if first == '"':
45
+ return _scan_string(s, i)
46
+ if first in "{[":
47
+ depth = 0
48
+ while i < n:
49
+ c = s[i]
50
+ if c == '"':
51
+ i = _scan_string(s, i) - 1
52
+ elif c in "{[":
53
+ depth += 1
54
+ elif c in "}]":
55
+ depth -= 1
56
+ if depth == 0:
57
+ return i + 1
58
+ i += 1
59
+ raise JsonError("unterminated object or array")
60
+ start = i
61
+ while i < n and s[i] not in ",]} \t\r\n":
62
+ i += 1
63
+ if i == start:
64
+ raise JsonError("value expected")
65
+ return i
66
+
67
+
68
+ def decode_string(fragment: str) -> str:
69
+ """Decodes a string fragment (with the quotes) into text."""
70
+ if not fragment.startswith('"'):
71
+ raise JsonError("string expected")
72
+ try:
73
+ return json.loads(fragment)
74
+ except ValueError:
75
+ raise JsonError("invalid string")
76
+
77
+
78
+ def array_items(fragment: str) -> List[str]:
79
+ """The items of an array fragment, each as a text fragment."""
80
+ s = fragment
81
+ i = _skip(s, 0)
82
+ if i >= len(s) or s[i] != "[":
83
+ raise JsonError("array expected")
84
+ items: List[str] = []
85
+ i = _skip(s, i + 1)
86
+ if i < len(s) and s[i] == "]":
87
+ return items
88
+ while True:
89
+ i = _skip(s, i)
90
+ end = _scan_value(s, i)
91
+ items.append(s[i:end])
92
+ i = _skip(s, end)
93
+ if i < len(s) and s[i] == ",":
94
+ i += 1
95
+ elif i < len(s) and s[i] == "]":
96
+ return items
97
+ else:
98
+ raise JsonError('"," or "]" expected')
99
+
100
+
101
+ class JsonFields:
102
+ """The fields of one JSON object."""
103
+
104
+ def __init__(self, fields: Dict[str, str]) -> None:
105
+ self._fields = fields
106
+
107
+ @classmethod
108
+ def parse(cls, text: str) -> "JsonFields":
109
+ s = text
110
+ n = len(s)
111
+ fields: Dict[str, str] = {}
112
+ i = _skip(s, 0)
113
+ if i >= n or s[i] != "{":
114
+ raise JsonError("object expected")
115
+ i = _skip(s, i + 1)
116
+ if i >= n:
117
+ raise JsonError("unterminated object")
118
+ if s[i] != "}":
119
+ while True:
120
+ i = _skip(s, i)
121
+ if i >= n or s[i] != '"':
122
+ raise JsonError("field name expected")
123
+ key_end = _scan_string(s, i)
124
+ key = decode_string(s[i:key_end])
125
+ i = _skip(s, key_end)
126
+ if i >= n or s[i] != ":":
127
+ raise JsonError('":" expected')
128
+ i = _skip(s, i + 1)
129
+ end = _scan_value(s, i)
130
+ fields[key] = s[i:end]
131
+ i = _skip(s, end)
132
+ if i < n and s[i] == ",":
133
+ i += 1
134
+ elif i < n and s[i] == "}":
135
+ break
136
+ else:
137
+ raise JsonError('"," or "}" expected')
138
+ if _skip(s, i + 1) != n:
139
+ raise JsonError("unexpected text after the object")
140
+ return cls(fields)
141
+
142
+ def raw(self, name: str) -> Optional[str]:
143
+ """The field's text fragment, or `None` when absent or `null`."""
144
+ value = self._fields.get(name)
145
+ return None if value is None or value == "null" else value
146
+
147
+ def string(self, name: str) -> Optional[str]:
148
+ value = self.raw(name)
149
+ return None if value is None else decode_string(value)
150
+
151
+ def boolean(self, name: str) -> Optional[bool]:
152
+ value = self.raw(name)
153
+ if value is None:
154
+ return None
155
+ if value in ("true", "false"):
156
+ return value == "true"
157
+ raise JsonError('field "%s" is not a boolean' % name)
158
+
159
+ def integer(self, name: str) -> Optional[int]:
160
+ value = self.raw(name)
161
+ if value is None:
162
+ return None
163
+ if not re.fullmatch(r"-?[0-9]+", value):
164
+ raise JsonError('field "%s" is not an integer' % name)
165
+ return int(value)