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 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")