databucket-client 2.0.0__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.
- databucket/__init__.py +37 -0
- databucket/bucket.py +296 -0
- databucket/change.py +100 -0
- databucket/client.py +226 -0
- databucket/fields.py +47 -0
- databucket/model.py +95 -0
- databucket/py.typed +0 -0
- databucket/rules.py +272 -0
- databucket/search.py +185 -0
- databucket_client-2.0.0.dist-info/METADATA +219 -0
- databucket_client-2.0.0.dist-info/RECORD +13 -0
- databucket_client-2.0.0.dist-info/WHEEL +4 -0
- databucket_client-2.0.0.dist-info/licenses/LICENSE +21 -0
databucket/__init__.py
ADDED
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
"""Client for Databucket (test data management): find, reserve, change and remove test data from your automated
|
|
2
|
+
tests. See https://github.com/databucket/databucket-python-client"""
|
|
3
|
+
|
|
4
|
+
from .bucket import Bucket
|
|
5
|
+
from .change import Change, NewData
|
|
6
|
+
from .client import API_VERSION_HEADER, Databucket
|
|
7
|
+
from .fields import Field, HistoryField, Sort
|
|
8
|
+
from .model import DatabucketError, DataRow, HistoryEntry, HistoryPage, Page, Project, Reservation
|
|
9
|
+
from .rules import JsonLogic, Operand, Rule, Rules
|
|
10
|
+
from .search import HistorySearch, Query, Reserve
|
|
11
|
+
|
|
12
|
+
__version__ = "2.0.0"
|
|
13
|
+
|
|
14
|
+
__all__ = [
|
|
15
|
+
"API_VERSION_HEADER",
|
|
16
|
+
"Bucket",
|
|
17
|
+
"Change",
|
|
18
|
+
"DataRow",
|
|
19
|
+
"Databucket",
|
|
20
|
+
"DatabucketError",
|
|
21
|
+
"Field",
|
|
22
|
+
"HistoryEntry",
|
|
23
|
+
"HistoryField",
|
|
24
|
+
"HistoryPage",
|
|
25
|
+
"HistorySearch",
|
|
26
|
+
"JsonLogic",
|
|
27
|
+
"NewData",
|
|
28
|
+
"Operand",
|
|
29
|
+
"Page",
|
|
30
|
+
"Project",
|
|
31
|
+
"Query",
|
|
32
|
+
"Reservation",
|
|
33
|
+
"Reserve",
|
|
34
|
+
"Rule",
|
|
35
|
+
"Rules",
|
|
36
|
+
"Sort",
|
|
37
|
+
]
|
databucket/bucket.py
ADDED
|
@@ -0,0 +1,296 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import json
|
|
4
|
+
import re
|
|
5
|
+
from collections.abc import Iterable
|
|
6
|
+
from datetime import datetime
|
|
7
|
+
from typing import TYPE_CHECKING, Any, Generic, TypeVar, overload
|
|
8
|
+
from urllib.parse import quote
|
|
9
|
+
|
|
10
|
+
from .change import Change, NewData
|
|
11
|
+
from .model import DatabucketError, DataRow, HistoryEntry, HistoryPage, Page, Reservation
|
|
12
|
+
from .rules import Rules
|
|
13
|
+
from .search import HistorySearch, Query, Reserve
|
|
14
|
+
|
|
15
|
+
if TYPE_CHECKING:
|
|
16
|
+
from .client import Databucket
|
|
17
|
+
|
|
18
|
+
T = TypeVar("T")
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
class Bucket(Generic[T]):
|
|
22
|
+
"""The data of one bucket. Get it with :meth:`Databucket.bucket`. ``T`` is the type of the properties."""
|
|
23
|
+
|
|
24
|
+
def __init__(self, databucket: Databucket, name: str) -> None:
|
|
25
|
+
if not name or not name.strip():
|
|
26
|
+
raise ValueError("The bucket name is empty")
|
|
27
|
+
self._databucket = databucket
|
|
28
|
+
self.name = name
|
|
29
|
+
self._path = f"/api/bucket/{quote(name, safe='')}"
|
|
30
|
+
|
|
31
|
+
# ------------------------------------------------------------------ insert
|
|
32
|
+
|
|
33
|
+
def insert(self, data: T | NewData[T]) -> DataRow[T]:
|
|
34
|
+
"""Inserts a row (properties, or :class:`NewData` with a tag or reserved) and returns it with its id."""
|
|
35
|
+
return self._row(self._databucket._call("POST", self._path, _new_data(data).to_body()))
|
|
36
|
+
|
|
37
|
+
def insert_all(self, data: Iterable[T | NewData[T]]) -> None:
|
|
38
|
+
"""Inserts many rows in one call (the rows are not returned; find them by rules)."""
|
|
39
|
+
bodies = [_new_data(d).to_body() for d in data]
|
|
40
|
+
if bodies:
|
|
41
|
+
self._databucket._call("POST", f"{self._path}/multi", bodies)
|
|
42
|
+
|
|
43
|
+
# ------------------------------------------------------------------ read
|
|
44
|
+
|
|
45
|
+
@overload
|
|
46
|
+
def get(self, id: int) -> DataRow[T] | None: ...
|
|
47
|
+
|
|
48
|
+
@overload
|
|
49
|
+
def get(self, id: Iterable[int]) -> list[DataRow[T]]: ...
|
|
50
|
+
|
|
51
|
+
def get(self, id: int | Iterable[int]) -> DataRow[T] | None | list[DataRow[T]]:
|
|
52
|
+
"""The row with the given id (None when it doesn't exist or is not visible to the user), or the rows with
|
|
53
|
+
the given ids (missing ids are skipped)."""
|
|
54
|
+
if isinstance(id, int):
|
|
55
|
+
rows = self.get([id])
|
|
56
|
+
return rows[0] if rows else None
|
|
57
|
+
ids = list(id)
|
|
58
|
+
if not ids:
|
|
59
|
+
return []
|
|
60
|
+
# one existing row comes as an object, otherwise a list
|
|
61
|
+
result = self._databucket._call("GET", f"{self._path}/{_ids(ids)}")
|
|
62
|
+
if isinstance(result, list):
|
|
63
|
+
return self._rows(result)
|
|
64
|
+
return [self._row(result)] if isinstance(result, dict) else []
|
|
65
|
+
|
|
66
|
+
def find(self, rules: Rules) -> Query[T]:
|
|
67
|
+
"""A search for rows matching the rules; see :class:`Query`."""
|
|
68
|
+
return Query(self, rules)
|
|
69
|
+
|
|
70
|
+
def count(self, rules: Rules) -> int:
|
|
71
|
+
"""Number of rows matching the rules."""
|
|
72
|
+
result = self._databucket._call("POST", f"{self._path}/get?limit=0", rules.to_body())
|
|
73
|
+
return int((result or {}).get("total", 0))
|
|
74
|
+
|
|
75
|
+
def _fetch_page(self, rules: Rules, page: int, limit: int, sort: str) -> Page[T]:
|
|
76
|
+
result = (
|
|
77
|
+
self._databucket._call(
|
|
78
|
+
"POST", f"{self._path}/get?page={page}&limit={limit}&sort={quote(sort, safe='')}", rules.to_body()
|
|
79
|
+
)
|
|
80
|
+
or {}
|
|
81
|
+
)
|
|
82
|
+
return Page(
|
|
83
|
+
rows=self._rows(result.get("data")),
|
|
84
|
+
page=result.get("page", page),
|
|
85
|
+
limit=result.get("limit", limit),
|
|
86
|
+
total=int(result.get("total", 0)),
|
|
87
|
+
total_pages=result.get("totalPages", 0),
|
|
88
|
+
)
|
|
89
|
+
|
|
90
|
+
# ------------------------------------------------------------------ reserve
|
|
91
|
+
|
|
92
|
+
def reserve(self, rules: Rules) -> Reserve[T]:
|
|
93
|
+
"""A reservation of free rows matching the rules; see :class:`Reserve`."""
|
|
94
|
+
return Reserve(self, rules)
|
|
95
|
+
|
|
96
|
+
def _reserve_rows(self, rules: Rules, limit: int, sort: str, for_user: str | None) -> Reservation[T]:
|
|
97
|
+
body = dict(rules.to_body())
|
|
98
|
+
if for_user is not None:
|
|
99
|
+
body["targetOwnerUsername"] = for_user
|
|
100
|
+
result = (
|
|
101
|
+
self._databucket._call("POST", f"{self._path}/reserve?limit={limit}&sort={quote(sort, safe='')}", body)
|
|
102
|
+
or {}
|
|
103
|
+
)
|
|
104
|
+
return Reservation(rows=self._rows(result.get("data")), available=int(result.get("available", 0)))
|
|
105
|
+
|
|
106
|
+
def release(self, *ids: int) -> int:
|
|
107
|
+
"""Releases the rows (reserved = False); returns the number of changed rows."""
|
|
108
|
+
return self.update(Change().reserved(False), *ids)
|
|
109
|
+
|
|
110
|
+
# ------------------------------------------------------------------ modify and remove
|
|
111
|
+
|
|
112
|
+
@overload
|
|
113
|
+
def update(self, change: Change, /, *ids: int) -> int: ...
|
|
114
|
+
|
|
115
|
+
@overload
|
|
116
|
+
def update(self, rules: Rules, change: Change, /) -> int: ...
|
|
117
|
+
|
|
118
|
+
def update(self, first: Change | Rules, *rest: Any) -> int:
|
|
119
|
+
"""``update(change, *ids)``: applies the change to the rows with the given ids;
|
|
120
|
+
``update(rules, change)``: to all rows matching the rules (at least one rule).
|
|
121
|
+
Returns the number of changed rows."""
|
|
122
|
+
if isinstance(first, Rules):
|
|
123
|
+
self._require_rules(first, "modify")
|
|
124
|
+
if len(rest) != 1 or not isinstance(rest[0], Change):
|
|
125
|
+
raise TypeError("update(rules, change): the change is missing")
|
|
126
|
+
body = {**rest[0].to_body(), **first.to_body()}
|
|
127
|
+
return _count(self._databucket._call("PUT", self._path, body))
|
|
128
|
+
if not rest:
|
|
129
|
+
return 0
|
|
130
|
+
return _count(self._databucket._call("PUT", f"{self._path}/{_ids(rest)}", first.to_body()))
|
|
131
|
+
|
|
132
|
+
@overload
|
|
133
|
+
def delete(self, *ids: int) -> int: ...
|
|
134
|
+
|
|
135
|
+
@overload
|
|
136
|
+
def delete(self, rules: Rules, /) -> int: ...
|
|
137
|
+
|
|
138
|
+
def delete(self, *args: Any) -> int:
|
|
139
|
+
"""``delete(*ids)``: removes the rows with the given ids together with their history;
|
|
140
|
+
``delete(rules)``: all rows matching the rules (at least one rule). Returns the number of removed rows."""
|
|
141
|
+
if args and isinstance(args[0], Rules):
|
|
142
|
+
self._require_rules(args[0], "remove")
|
|
143
|
+
return _count(self._databucket._call("DELETE", self._path, args[0].to_body()))
|
|
144
|
+
if not args:
|
|
145
|
+
return 0
|
|
146
|
+
return _count(self._databucket._call("DELETE", f"{self._path}/{_ids(args)}"))
|
|
147
|
+
|
|
148
|
+
# ------------------------------------------------------------------ history (buckets with history enabled)
|
|
149
|
+
|
|
150
|
+
def history(self, id: int) -> list[HistoryEntry[T]]:
|
|
151
|
+
"""The changes of a row, oldest first."""
|
|
152
|
+
result = self._databucket._call("GET", f"{self._path}/{id}/history")
|
|
153
|
+
return [
|
|
154
|
+
HistoryEntry(
|
|
155
|
+
id=int(e["id"]),
|
|
156
|
+
data_id=id,
|
|
157
|
+
tag_id=_int_or_none(e.get("tag_id")),
|
|
158
|
+
reserved=e.get("reserved"),
|
|
159
|
+
properties_changed=e.get("properties") is True,
|
|
160
|
+
properties=None,
|
|
161
|
+
modified_at=_date(e.get("modified_at")),
|
|
162
|
+
modified_by=e.get("modified_by"),
|
|
163
|
+
)
|
|
164
|
+
for e in (result if isinstance(result, list) else [])
|
|
165
|
+
]
|
|
166
|
+
|
|
167
|
+
def search_history(self, rows: Rules) -> HistorySearch[T]:
|
|
168
|
+
"""A search of the history of the rows matching the rules (by their current state; ``Rules.ALL`` for all
|
|
169
|
+
rows); see :class:`HistorySearch`. Databucket 3.14.0+."""
|
|
170
|
+
return HistorySearch(self, rows)
|
|
171
|
+
|
|
172
|
+
def _search_history_page(
|
|
173
|
+
self, rows: Rules, entries: Rules, page: int, limit: int, sort: str, with_properties: bool
|
|
174
|
+
) -> HistoryPage[T]:
|
|
175
|
+
body = dict(rows.to_body())
|
|
176
|
+
entry_body = entries.to_body()
|
|
177
|
+
if "logic" in entry_body:
|
|
178
|
+
body["historyLogic"] = entry_body["logic"]
|
|
179
|
+
if "rules" in entry_body:
|
|
180
|
+
body["historyRules"] = entry_body["rules"]
|
|
181
|
+
path = f"{self._path}/history/get?page={page}&limit={limit}&sort={quote(sort, safe='')}"
|
|
182
|
+
if with_properties:
|
|
183
|
+
path += "&properties=true"
|
|
184
|
+
result = self._databucket._call("POST", path, body) or {}
|
|
185
|
+
history = result.get("history")
|
|
186
|
+
return HistoryPage(
|
|
187
|
+
entries=[
|
|
188
|
+
HistoryEntry(
|
|
189
|
+
id=int(h["id"]),
|
|
190
|
+
data_id=int(h["dataId"]),
|
|
191
|
+
tag_id=_int_or_none(h.get("tagId")),
|
|
192
|
+
reserved=h.get("reserved"),
|
|
193
|
+
properties_changed=h.get("propertiesChanged") is True,
|
|
194
|
+
properties=self._properties(h.get("properties")),
|
|
195
|
+
modified_at=_date(h.get("modifiedAt")),
|
|
196
|
+
modified_by=h.get("modifiedBy"),
|
|
197
|
+
)
|
|
198
|
+
for h in (history if isinstance(history, list) else [])
|
|
199
|
+
],
|
|
200
|
+
page=result.get("page", page),
|
|
201
|
+
limit=result.get("limit", limit),
|
|
202
|
+
total=int(result.get("total", 0)),
|
|
203
|
+
total_pages=result.get("totalPages", 0),
|
|
204
|
+
)
|
|
205
|
+
|
|
206
|
+
def history_properties(self, id: int, *history_ids: int) -> dict[int, T]:
|
|
207
|
+
"""The properties of a row as they were in the given history entries (by history entry id)."""
|
|
208
|
+
if not history_ids:
|
|
209
|
+
return {}
|
|
210
|
+
result = self._databucket._call("GET", f"{self._path}/{id}/history/{_ids(history_ids)}")
|
|
211
|
+
return {
|
|
212
|
+
int(e["id"]): self._properties(e.get("properties")) # type: ignore[misc]
|
|
213
|
+
for e in (result if isinstance(result, list) else [])
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
@overload
|
|
217
|
+
def clear_history(self, id: int, /) -> int: ...
|
|
218
|
+
|
|
219
|
+
@overload
|
|
220
|
+
def clear_history(self, rules: Rules, /) -> int: ...
|
|
221
|
+
|
|
222
|
+
def clear_history(self, id_or_rules: int | Rules) -> int:
|
|
223
|
+
"""``clear_history(id)``: removes the history of a row (the row itself stays), returns the number of removed
|
|
224
|
+
history entries; ``clear_history(rules)``: of all rows matching the rules (at least one rule), returns the
|
|
225
|
+
number of rows."""
|
|
226
|
+
if isinstance(id_or_rules, Rules):
|
|
227
|
+
self._require_rules(id_or_rules, "clear the history of")
|
|
228
|
+
return _count(self._databucket._call("DELETE", f"{self._path}/history/clear", id_or_rules.to_body()))
|
|
229
|
+
return _count(self._databucket._call("DELETE", f"{self._path}/{id_or_rules}/history/clear"))
|
|
230
|
+
|
|
231
|
+
# ------------------------------------------------------------------ mapping
|
|
232
|
+
|
|
233
|
+
def _rows(self, items: Any) -> list[DataRow[T]]:
|
|
234
|
+
return [self._row(item) for item in items] if isinstance(items, list) else []
|
|
235
|
+
|
|
236
|
+
def _row(self, item: dict[str, Any]) -> DataRow[T]:
|
|
237
|
+
return DataRow(
|
|
238
|
+
id=int(item["id"]),
|
|
239
|
+
tag_id=_int_or_none(item.get("tagId")),
|
|
240
|
+
reserved=item.get("reserved") is True,
|
|
241
|
+
owner=item.get("owner"),
|
|
242
|
+
properties=self._properties(item.get("properties")), # type: ignore[arg-type]
|
|
243
|
+
created_by=item.get("createdBy"),
|
|
244
|
+
created_at=_date(item.get("createdAt")),
|
|
245
|
+
modified_by=item.get("modifiedBy"),
|
|
246
|
+
modified_at=_date(item.get("modifiedAt")),
|
|
247
|
+
)
|
|
248
|
+
|
|
249
|
+
def _properties(self, value: Any) -> T | None:
|
|
250
|
+
if value is None:
|
|
251
|
+
return None
|
|
252
|
+
if isinstance(value, str):
|
|
253
|
+
# stored as text by some endpoints
|
|
254
|
+
try:
|
|
255
|
+
return json.loads(value) # type: ignore[no-any-return]
|
|
256
|
+
except ValueError as e:
|
|
257
|
+
raise DatabucketError(0, f"Can not read the properties: {e}", value) from e
|
|
258
|
+
return value # type: ignore[no-any-return]
|
|
259
|
+
|
|
260
|
+
def _require_rules(self, rules: Rules, action: str) -> None:
|
|
261
|
+
if rules is None or rules.is_empty():
|
|
262
|
+
raise ValueError(f"Can not {action} data without rules (bucket {self.name})")
|
|
263
|
+
|
|
264
|
+
def __repr__(self) -> str:
|
|
265
|
+
return f"Bucket({self.name!r})"
|
|
266
|
+
|
|
267
|
+
|
|
268
|
+
def _new_data(data: Any) -> NewData[Any]:
|
|
269
|
+
return data if isinstance(data, NewData) else NewData(data)
|
|
270
|
+
|
|
271
|
+
|
|
272
|
+
def _ids(ids: Iterable[Any]) -> str:
|
|
273
|
+
return ",".join(str(int(i)) for i in ids)
|
|
274
|
+
|
|
275
|
+
|
|
276
|
+
def _int_or_none(value: Any) -> int | None:
|
|
277
|
+
return None if value is None else int(value)
|
|
278
|
+
|
|
279
|
+
|
|
280
|
+
def _date(value: Any) -> datetime | None:
|
|
281
|
+
if value is None:
|
|
282
|
+
return None
|
|
283
|
+
if isinstance(value, (int, float)):
|
|
284
|
+
return datetime.fromtimestamp(value / 1000).astimezone()
|
|
285
|
+
text = str(value)
|
|
286
|
+
if text.endswith("Z"):
|
|
287
|
+
text = text[:-1] + "+00:00"
|
|
288
|
+
# Python 3.10 reads only 3 or 6 digits of a fraction of a second
|
|
289
|
+
text = re.sub(r"\.(\d{1,6})\d*", lambda m: "." + m.group(1).ljust(6, "0"), text, count=1)
|
|
290
|
+
return datetime.fromisoformat(text)
|
|
291
|
+
|
|
292
|
+
|
|
293
|
+
def _count(result: Any) -> int:
|
|
294
|
+
"""The number in a message such as "Modified 3 data row(s)"."""
|
|
295
|
+
match = re.search(r"\d+", str((result or {}).get("message", "")) if isinstance(result, dict) else "")
|
|
296
|
+
return int(match.group(0)) if match else 0
|
databucket/change.py
ADDED
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
from typing import Any, Generic, TypeVar
|
|
4
|
+
|
|
5
|
+
from .rules import _property_path
|
|
6
|
+
|
|
7
|
+
T = TypeVar("T")
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
class Change:
|
|
11
|
+
"""Changes to apply to data rows; items left out stay unchanged.
|
|
12
|
+
|
|
13
|
+
::
|
|
14
|
+
|
|
15
|
+
Change().set("$.status", "used").remove("$.tmp").tag_id(4)
|
|
16
|
+
Change().reserved(False) # release
|
|
17
|
+
Change().properties(new_user) # replace all properties
|
|
18
|
+
"""
|
|
19
|
+
|
|
20
|
+
def __init__(self) -> None:
|
|
21
|
+
self._tag_id: int | None = None
|
|
22
|
+
self._reserved: bool | None = None
|
|
23
|
+
self._properties: Any = None
|
|
24
|
+
self._has_properties = False
|
|
25
|
+
self._to_set: dict[str, Any] = {}
|
|
26
|
+
self._to_remove: list[str] = []
|
|
27
|
+
|
|
28
|
+
def tag_id(self, tag_id: int) -> Change:
|
|
29
|
+
self._tag_id = tag_id
|
|
30
|
+
return self
|
|
31
|
+
|
|
32
|
+
def reserved(self, reserved: bool) -> Change:
|
|
33
|
+
"""True reserves the rows for the signed-in user (only rows that are not reserved yet are changed),
|
|
34
|
+
False releases them."""
|
|
35
|
+
self._reserved = reserved
|
|
36
|
+
return self
|
|
37
|
+
|
|
38
|
+
def properties(self, properties: Any) -> Change:
|
|
39
|
+
"""Replaces all properties."""
|
|
40
|
+
self._properties = properties
|
|
41
|
+
self._has_properties = True
|
|
42
|
+
return self
|
|
43
|
+
|
|
44
|
+
def set(self, path: str, value: Any) -> Change:
|
|
45
|
+
"""Sets one property, e.g. ``set("$.address.city", "Paris")`` (the ``$.`` prefix may be left out)."""
|
|
46
|
+
self._to_set[_property_path(path)] = value
|
|
47
|
+
return self
|
|
48
|
+
|
|
49
|
+
def remove(self, path: str) -> Change:
|
|
50
|
+
"""Removes one property, e.g. ``remove("$.tmp")``."""
|
|
51
|
+
self._to_remove.append(_property_path(path))
|
|
52
|
+
return self
|
|
53
|
+
|
|
54
|
+
def to_body(self) -> dict[str, Any]:
|
|
55
|
+
"""The request body."""
|
|
56
|
+
body: dict[str, Any] = {}
|
|
57
|
+
if self._tag_id is not None:
|
|
58
|
+
body["tagId"] = self._tag_id
|
|
59
|
+
if self._reserved is not None:
|
|
60
|
+
body["reserved"] = self._reserved
|
|
61
|
+
if self._has_properties:
|
|
62
|
+
body["properties"] = self._properties
|
|
63
|
+
if self._to_set:
|
|
64
|
+
body["propertiesToSet"] = self._to_set
|
|
65
|
+
if self._to_remove:
|
|
66
|
+
body["propertiesToRemove"] = self._to_remove
|
|
67
|
+
return body
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
class NewData(Generic[T]):
|
|
71
|
+
"""A new row with a tag or reserved, for :meth:`Bucket.insert` and :meth:`Bucket.insert_all`.
|
|
72
|
+
|
|
73
|
+
::
|
|
74
|
+
|
|
75
|
+
NewData(user).tag_id(3).reserved(True)
|
|
76
|
+
"""
|
|
77
|
+
|
|
78
|
+
def __init__(self, properties: T) -> None:
|
|
79
|
+
self.properties = properties
|
|
80
|
+
self._tag_id: int | None = None
|
|
81
|
+
self._reserved: bool | None = None
|
|
82
|
+
|
|
83
|
+
def tag_id(self, tag_id: int) -> NewData[T]:
|
|
84
|
+
self._tag_id = tag_id
|
|
85
|
+
return self
|
|
86
|
+
|
|
87
|
+
def reserved(self, reserved: bool) -> NewData[T]:
|
|
88
|
+
"""True: the row is reserved for the signed-in user."""
|
|
89
|
+
self._reserved = reserved
|
|
90
|
+
return self
|
|
91
|
+
|
|
92
|
+
def to_body(self) -> dict[str, Any]:
|
|
93
|
+
"""The request body."""
|
|
94
|
+
body: dict[str, Any] = {}
|
|
95
|
+
if self._tag_id is not None:
|
|
96
|
+
body["tagId"] = self._tag_id
|
|
97
|
+
if self._reserved is not None:
|
|
98
|
+
body["reserved"] = self._reserved
|
|
99
|
+
body["properties"] = self.properties
|
|
100
|
+
return body
|
databucket/client.py
ADDED
|
@@ -0,0 +1,226 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import json
|
|
4
|
+
import logging
|
|
5
|
+
import threading
|
|
6
|
+
import time
|
|
7
|
+
from collections.abc import Callable
|
|
8
|
+
from datetime import date
|
|
9
|
+
from typing import Any, TypeVar
|
|
10
|
+
|
|
11
|
+
import requests
|
|
12
|
+
|
|
13
|
+
from .bucket import Bucket
|
|
14
|
+
from .model import DatabucketError, Project
|
|
15
|
+
from .rules import _value
|
|
16
|
+
|
|
17
|
+
#: The header selecting the version of the data API.
|
|
18
|
+
API_VERSION_HEADER = "Databucket-Api-Version"
|
|
19
|
+
_API_VERSION = "2"
|
|
20
|
+
_USER_AGENT = "databucket-python-client/2"
|
|
21
|
+
|
|
22
|
+
T = TypeVar("T")
|
|
23
|
+
|
|
24
|
+
log = logging.getLogger("databucket")
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
class Databucket:
|
|
28
|
+
"""Client for one Databucket project, signed in as one user (typically a ROBOT account).
|
|
29
|
+
|
|
30
|
+
::
|
|
31
|
+
|
|
32
|
+
databucket = Databucket(
|
|
33
|
+
"https://databucket.example.com",
|
|
34
|
+
username="tests-robot",
|
|
35
|
+
password=os.environ["DATABUCKET_PASSWORD"],
|
|
36
|
+
project="Acme Shop",
|
|
37
|
+
)
|
|
38
|
+
users = databucket.bucket("dev-users")
|
|
39
|
+
user = users.reserve(Rules.where(Rule.property("$.status").eq("active"))).one()
|
|
40
|
+
|
|
41
|
+
The client signs in on the first call and again when the token expires. One client can be shared by threads.
|
|
42
|
+
All data calls use API version 2 (header ``Databucket-Api-Version: 2``). Each request is logged at DEBUG level
|
|
43
|
+
by the logger ``databucket``.
|
|
44
|
+
|
|
45
|
+
:param url: the address of Databucket, e.g. ``https://databucket.example.com`` or ``http://localhost:8080``
|
|
46
|
+
:param username: sign in with a username and password (``POST /api/public/signin``), together with ``password``
|
|
47
|
+
:param password: the password of ``username``
|
|
48
|
+
:param sso_token: sign in with an access token of the identity provider (OAuth2 client credentials of a ROBOT
|
|
49
|
+
account), exchanged for a Databucket token (``POST /api/public/sso/token-exchange``); called on every
|
|
50
|
+
sign-in, so it can fetch a fresh token
|
|
51
|
+
:param token: a Databucket token you already have (no sign-in; it is not renewed)
|
|
52
|
+
:param project: the project by id or by name (needed only when the user has several projects)
|
|
53
|
+
:param timeout: timeout of each request in seconds (default 30)
|
|
54
|
+
:param session: your own ``requests.Session``, e.g. with a proxy or certificates
|
|
55
|
+
"""
|
|
56
|
+
|
|
57
|
+
def __init__(
|
|
58
|
+
self,
|
|
59
|
+
url: str,
|
|
60
|
+
*,
|
|
61
|
+
username: str | None = None,
|
|
62
|
+
password: str | None = None,
|
|
63
|
+
sso_token: Callable[[], str] | None = None,
|
|
64
|
+
token: str | None = None,
|
|
65
|
+
project: int | str | None = None,
|
|
66
|
+
timeout: float = 30.0,
|
|
67
|
+
session: requests.Session | None = None,
|
|
68
|
+
) -> None:
|
|
69
|
+
if not url or not url.strip():
|
|
70
|
+
raise ValueError("The Databucket url is empty")
|
|
71
|
+
self._base_url = url.rstrip("/")
|
|
72
|
+
self._timeout = timeout
|
|
73
|
+
self._session = session or requests.Session()
|
|
74
|
+
self._project_id = project if isinstance(project, int) else None
|
|
75
|
+
self._project_name = project if isinstance(project, str) else None
|
|
76
|
+
self._current_token = token
|
|
77
|
+
self._current_project: Project | None = None
|
|
78
|
+
self._lock = threading.Lock()
|
|
79
|
+
|
|
80
|
+
self._sign_in_fn: Callable[[int | None], Any] | None = None
|
|
81
|
+
if username is not None or password is not None:
|
|
82
|
+
if not username or password is None:
|
|
83
|
+
raise ValueError("Sign-in with a password needs both username and password")
|
|
84
|
+
self._sign_in_fn = lambda project_id: self._sign_in_call(
|
|
85
|
+
"/api/public/signin",
|
|
86
|
+
{"username": username, "password": password, **_project(project_id)},
|
|
87
|
+
)
|
|
88
|
+
elif sso_token is not None:
|
|
89
|
+
self._sign_in_fn = lambda project_id: self._sign_in_call(
|
|
90
|
+
"/api/public/sso/token-exchange", {"token": sso_token(), **_project(project_id)}
|
|
91
|
+
)
|
|
92
|
+
if self._sign_in_fn is None and not self._current_token:
|
|
93
|
+
raise ValueError("No credentials: give username and password, sso_token or token")
|
|
94
|
+
|
|
95
|
+
def bucket(self, name: str) -> Bucket[Any]:
|
|
96
|
+
"""A bucket. For typed properties: ``users: Bucket[User] = databucket.bucket("dev-users")``."""
|
|
97
|
+
return Bucket(self, name)
|
|
98
|
+
|
|
99
|
+
def project(self) -> Project | None:
|
|
100
|
+
"""The project the client works in (signs in if not done yet); None when only a token was given."""
|
|
101
|
+
self.token()
|
|
102
|
+
return self._current_project
|
|
103
|
+
|
|
104
|
+
def token(self) -> str:
|
|
105
|
+
"""The current access token (signs in if needed)."""
|
|
106
|
+
token = self._current_token
|
|
107
|
+
if token:
|
|
108
|
+
return token
|
|
109
|
+
with self._lock:
|
|
110
|
+
# another thread may have signed in meanwhile
|
|
111
|
+
if self._current_token:
|
|
112
|
+
return self._current_token
|
|
113
|
+
return self._sign_in()
|
|
114
|
+
|
|
115
|
+
# ------------------------------------------------------------------ sign-in
|
|
116
|
+
|
|
117
|
+
def _sign_in(self) -> str:
|
|
118
|
+
if self._sign_in_fn is None:
|
|
119
|
+
raise DatabucketError(0, "No credentials: give username and password, sso_token or token")
|
|
120
|
+
|
|
121
|
+
project_id = self._project_id
|
|
122
|
+
response = self._sign_in_fn(project_id) or {}
|
|
123
|
+
if project_id is None and not response.get("token") and isinstance(response.get("projects"), list):
|
|
124
|
+
# the user has several projects: pick one by name
|
|
125
|
+
project_id = self._pick_project(response["projects"])
|
|
126
|
+
response = self._sign_in_fn(project_id) or {}
|
|
127
|
+
signed_in = response.get("project")
|
|
128
|
+
if (
|
|
129
|
+
self._project_name is not None
|
|
130
|
+
and project_id is None
|
|
131
|
+
and signed_in
|
|
132
|
+
and signed_in.get("name") != self._project_name
|
|
133
|
+
):
|
|
134
|
+
raise DatabucketError(0, f"The user is not assigned to the project '{self._project_name}'")
|
|
135
|
+
|
|
136
|
+
if not response.get("token") or response.get("changePassword"):
|
|
137
|
+
reason = ": the user has to change the password first" if response.get("changePassword") else ""
|
|
138
|
+
raise DatabucketError(0, f"Sign-in gave no token for a project{reason}", json.dumps(response))
|
|
139
|
+
|
|
140
|
+
self._current_project = Project(int(signed_in["id"]), signed_in["name"]) if signed_in else None
|
|
141
|
+
self._current_token = str(response["token"])
|
|
142
|
+
project = self._current_project
|
|
143
|
+
log.debug("Signed in to project %s (%s)", project.name if project else None, project.id if project else None)
|
|
144
|
+
return self._current_token
|
|
145
|
+
|
|
146
|
+
def _pick_project(self, projects: list[dict[str, Any]]) -> int:
|
|
147
|
+
for p in projects:
|
|
148
|
+
if p.get("name") == self._project_name:
|
|
149
|
+
return int(p["id"])
|
|
150
|
+
names = ", ".join(str(p.get("name")) for p in projects)
|
|
151
|
+
if self._project_name is None:
|
|
152
|
+
raise DatabucketError(0, f"The user has several projects, choose one with the 'project' option: [{names}]")
|
|
153
|
+
raise DatabucketError(0, f"The user is not assigned to the project '{self._project_name}'; projects: [{names}]")
|
|
154
|
+
|
|
155
|
+
def _sign_in_call(self, path: str, body: dict[str, Any]) -> Any:
|
|
156
|
+
status, text = self._send("POST", path, {"Content-Type": "application/json"}, json.dumps(body))
|
|
157
|
+
return self._handle("POST", path, status, text)
|
|
158
|
+
|
|
159
|
+
# ------------------------------------------------------------------ HTTP
|
|
160
|
+
|
|
161
|
+
def _call(self, method: str, path: str, body: Any = None, retry: bool = True) -> Any:
|
|
162
|
+
"""A call of the data API (version 2) with the token; signs in again once on 401."""
|
|
163
|
+
token = self.token()
|
|
164
|
+
headers = {"Authorization": f"Bearer {token}", API_VERSION_HEADER: _API_VERSION}
|
|
165
|
+
data = None
|
|
166
|
+
if body is not None:
|
|
167
|
+
headers["Content-Type"] = "application/json"
|
|
168
|
+
data = json.dumps(body, default=_json_default)
|
|
169
|
+
status, text = self._send(method, path, headers, data)
|
|
170
|
+
|
|
171
|
+
if status == 401 and retry and self._sign_in_fn is not None:
|
|
172
|
+
# the token expired: sign in again once
|
|
173
|
+
with self._lock:
|
|
174
|
+
if self._current_token == token:
|
|
175
|
+
self._current_token = None
|
|
176
|
+
return self._call(method, path, body, retry=False)
|
|
177
|
+
return self._handle(method, path, status, text)
|
|
178
|
+
|
|
179
|
+
def _send(self, method: str, path: str, headers: dict[str, str], data: str | None) -> tuple[int, str]:
|
|
180
|
+
url = self._base_url + path
|
|
181
|
+
start = time.monotonic()
|
|
182
|
+
try:
|
|
183
|
+
response = self._session.request(
|
|
184
|
+
method,
|
|
185
|
+
url,
|
|
186
|
+
headers={"Accept": "application/json", "User-Agent": _USER_AGENT, **headers},
|
|
187
|
+
data=data.encode("utf-8") if data is not None else None,
|
|
188
|
+
timeout=self._timeout,
|
|
189
|
+
)
|
|
190
|
+
except requests.Timeout as e:
|
|
191
|
+
raise DatabucketError(0, f"{method} {url} failed: timeout after {self._timeout} s") from e
|
|
192
|
+
except requests.RequestException as e:
|
|
193
|
+
raise DatabucketError(0, f"{method} {url} failed: {e}") from e
|
|
194
|
+
log.debug("%s %s -> %s (%d ms)", method, url, response.status_code, (time.monotonic() - start) * 1000)
|
|
195
|
+
response.encoding = response.encoding or "utf-8"
|
|
196
|
+
return response.status_code, response.text
|
|
197
|
+
|
|
198
|
+
def _handle(self, method: str, path: str, status: int, text: str) -> Any:
|
|
199
|
+
parsed = _parse(text)
|
|
200
|
+
if status >= 400:
|
|
201
|
+
message = None
|
|
202
|
+
if isinstance(parsed, dict):
|
|
203
|
+
message = parsed.get("message") or parsed.get("error")
|
|
204
|
+
if not message:
|
|
205
|
+
message = text if text.strip() else "no response body"
|
|
206
|
+
raise DatabucketError(status, f"{message} ({method} {path.split('?')[0]})", text)
|
|
207
|
+
return parsed
|
|
208
|
+
|
|
209
|
+
|
|
210
|
+
def _project(project_id: int | None) -> dict[str, int]:
|
|
211
|
+
return {} if project_id is None else {"projectId": project_id}
|
|
212
|
+
|
|
213
|
+
|
|
214
|
+
def _parse(text: str) -> Any:
|
|
215
|
+
if not text or not text.strip():
|
|
216
|
+
return None
|
|
217
|
+
try:
|
|
218
|
+
return json.loads(text)
|
|
219
|
+
except ValueError:
|
|
220
|
+
return None
|
|
221
|
+
|
|
222
|
+
|
|
223
|
+
def _json_default(value: Any) -> Any:
|
|
224
|
+
if isinstance(value, date):
|
|
225
|
+
return _value(value)
|
|
226
|
+
raise TypeError(f"Object of type {type(value).__name__} is not JSON serializable")
|