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/fields.py
ADDED
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
class Field:
|
|
5
|
+
"""Fields of a data row that can be used in rules and sorting (besides properties such as ``$.address.city``)."""
|
|
6
|
+
|
|
7
|
+
ID = "id"
|
|
8
|
+
TAG_ID = "tagId"
|
|
9
|
+
OWNER = "owner"
|
|
10
|
+
RESERVED = "reserved"
|
|
11
|
+
CREATED_BY = "createdBy"
|
|
12
|
+
CREATED_AT = "createdAt"
|
|
13
|
+
MODIFIED_BY = "modifiedBy"
|
|
14
|
+
MODIFIED_AT = "modifiedAt"
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
class HistoryField:
|
|
18
|
+
"""Fields of a history entry, for :meth:`HistorySearch.where` and sorting the history."""
|
|
19
|
+
|
|
20
|
+
#: Id of the history entry.
|
|
21
|
+
ID = "id"
|
|
22
|
+
#: Id of the data row.
|
|
23
|
+
DATA_ID = "dataId"
|
|
24
|
+
TAG_ID = "tagId"
|
|
25
|
+
RESERVED = "reserved"
|
|
26
|
+
MODIFIED_BY = "modifiedBy"
|
|
27
|
+
MODIFIED_AT = "modifiedAt"
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
class Sort:
|
|
31
|
+
"""Sort orders for ``Query.sort``, ``Reserve.sort`` and ``HistorySearch.sort``: a field or a property.
|
|
32
|
+
|
|
33
|
+
::
|
|
34
|
+
|
|
35
|
+
Sort.asc("$.name"), Sort.desc(Field.ID), Sort.RANDOM
|
|
36
|
+
"""
|
|
37
|
+
|
|
38
|
+
#: Random order, e.g. to reserve a random row.
|
|
39
|
+
RANDOM = "random"
|
|
40
|
+
|
|
41
|
+
@staticmethod
|
|
42
|
+
def asc(field_or_property: str) -> str:
|
|
43
|
+
return f"asc({field_or_property})"
|
|
44
|
+
|
|
45
|
+
@staticmethod
|
|
46
|
+
def desc(field_or_property: str) -> str:
|
|
47
|
+
return f"desc({field_or_property})"
|
databucket/model.py
ADDED
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
from dataclasses import dataclass
|
|
4
|
+
from datetime import datetime
|
|
5
|
+
from typing import Generic, TypeVar
|
|
6
|
+
|
|
7
|
+
T = TypeVar("T")
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
@dataclass(frozen=True)
|
|
11
|
+
class DataRow(Generic[T]):
|
|
12
|
+
"""A data row. ``T`` is the type of the properties."""
|
|
13
|
+
|
|
14
|
+
id: int
|
|
15
|
+
tag_id: int | None
|
|
16
|
+
reserved: bool
|
|
17
|
+
#: The user who reserved the row.
|
|
18
|
+
owner: str | None
|
|
19
|
+
properties: T
|
|
20
|
+
created_by: str | None
|
|
21
|
+
created_at: datetime | None
|
|
22
|
+
modified_by: str | None
|
|
23
|
+
modified_at: datetime | None
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
@dataclass(frozen=True)
|
|
27
|
+
class Page(Generic[T]):
|
|
28
|
+
"""A page of rows found by :meth:`Query.fetch`."""
|
|
29
|
+
|
|
30
|
+
rows: list[DataRow[T]]
|
|
31
|
+
#: Page number, starting from 1.
|
|
32
|
+
page: int
|
|
33
|
+
limit: int
|
|
34
|
+
#: Number of all matching rows.
|
|
35
|
+
total: int
|
|
36
|
+
total_pages: int
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
@dataclass(frozen=True)
|
|
40
|
+
class Reservation(Generic[T]):
|
|
41
|
+
"""The result of :meth:`Reserve.fetch`."""
|
|
42
|
+
|
|
43
|
+
#: The reserved rows (fewer than the limit when not enough free rows match).
|
|
44
|
+
rows: list[DataRow[T]]
|
|
45
|
+
#: Number of free rows matching the rules left after this reservation.
|
|
46
|
+
available: int
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
@dataclass(frozen=True)
|
|
50
|
+
class HistoryEntry(Generic[T]):
|
|
51
|
+
"""One change of a data row."""
|
|
52
|
+
|
|
53
|
+
#: Id of the history entry.
|
|
54
|
+
id: int
|
|
55
|
+
#: Id of the data row.
|
|
56
|
+
data_id: int
|
|
57
|
+
#: The new tag, when it changed.
|
|
58
|
+
tag_id: int | None
|
|
59
|
+
#: The new reserved state, when it changed.
|
|
60
|
+
reserved: bool | None
|
|
61
|
+
properties_changed: bool
|
|
62
|
+
#: The properties of this version (only with :meth:`HistorySearch.with_properties`, when they changed).
|
|
63
|
+
properties: T | None
|
|
64
|
+
modified_at: datetime | None
|
|
65
|
+
modified_by: str | None
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
@dataclass(frozen=True)
|
|
69
|
+
class HistoryPage(Generic[T]):
|
|
70
|
+
"""A page of history entries found by :meth:`HistorySearch.fetch`."""
|
|
71
|
+
|
|
72
|
+
entries: list[HistoryEntry[T]]
|
|
73
|
+
page: int
|
|
74
|
+
limit: int
|
|
75
|
+
total: int
|
|
76
|
+
total_pages: int
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
@dataclass(frozen=True)
|
|
80
|
+
class Project:
|
|
81
|
+
"""The project the client is signed in to."""
|
|
82
|
+
|
|
83
|
+
id: int
|
|
84
|
+
name: str
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
class DatabucketError(Exception):
|
|
88
|
+
"""An error returned by Databucket (HTTP status 4xx/5xx) or a failure to reach it."""
|
|
89
|
+
|
|
90
|
+
def __init__(self, status: int, message: str, body: str | None = None) -> None:
|
|
91
|
+
super().__init__(f"{status}: {message}" if status > 0 else message)
|
|
92
|
+
#: HTTP status code, or 0 when there was no response (connection error, timeout) or the sign-in gave no token.
|
|
93
|
+
self.status = status
|
|
94
|
+
#: Raw response body, if any.
|
|
95
|
+
self.body = body
|
databucket/py.typed
ADDED
|
File without changes
|
databucket/rules.py
ADDED
|
@@ -0,0 +1,272 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import json
|
|
4
|
+
from collections.abc import Iterable, Sequence
|
|
5
|
+
from datetime import date, datetime, timezone
|
|
6
|
+
from typing import Any
|
|
7
|
+
|
|
8
|
+
#: A JsonLogic expression, e.g. ``{"==": [{"var": "$.city"}, "Paris"]}``.
|
|
9
|
+
JsonLogic = dict[str, Any]
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class Rule:
|
|
13
|
+
"""A condition on data rows, built in code and sent to Databucket as JsonLogic (API version 2).
|
|
14
|
+
|
|
15
|
+
::
|
|
16
|
+
|
|
17
|
+
Rule.property("$.address.city").eq("Paris")
|
|
18
|
+
Rule.tag_id().in_(1, 2)
|
|
19
|
+
Rule.or_(Rule.owner().is_null(), Rule.owner().eq(Rule.CURRENT_USER))
|
|
20
|
+
Rule.property("$.orders").length().gt(2)
|
|
21
|
+
|
|
22
|
+
Rules can also be combined with ``&``, ``|`` and ``~`` (and, or, not).
|
|
23
|
+
"""
|
|
24
|
+
|
|
25
|
+
#: As a value: the signed-in user, e.g. ``Rule.owner().eq(Rule.CURRENT_USER)``.
|
|
26
|
+
CURRENT_USER = "@currentUser"
|
|
27
|
+
|
|
28
|
+
def __init__(self, logic: Any) -> None:
|
|
29
|
+
self._logic = logic
|
|
30
|
+
|
|
31
|
+
def to_logic(self) -> Any:
|
|
32
|
+
"""The JsonLogic expression of this rule."""
|
|
33
|
+
return self._logic
|
|
34
|
+
|
|
35
|
+
@staticmethod
|
|
36
|
+
def property(path: str) -> Operand:
|
|
37
|
+
"""A property of the data, e.g. ``$.address.city`` (the ``$.`` prefix may be left out)."""
|
|
38
|
+
return Operand(_property_path(path), is_property=True)
|
|
39
|
+
|
|
40
|
+
@staticmethod
|
|
41
|
+
def field(field: str) -> Operand:
|
|
42
|
+
"""A field of a data row (:class:`Field`) or of a history entry (:class:`HistoryField`)."""
|
|
43
|
+
return Operand(field, is_property=False)
|
|
44
|
+
|
|
45
|
+
@staticmethod
|
|
46
|
+
def id() -> Operand:
|
|
47
|
+
return Rule.field("id")
|
|
48
|
+
|
|
49
|
+
@staticmethod
|
|
50
|
+
def tag_id() -> Operand:
|
|
51
|
+
return Rule.field("tagId")
|
|
52
|
+
|
|
53
|
+
@staticmethod
|
|
54
|
+
def owner() -> Operand:
|
|
55
|
+
return Rule.field("owner")
|
|
56
|
+
|
|
57
|
+
@staticmethod
|
|
58
|
+
def reserved() -> Operand:
|
|
59
|
+
return Rule.field("reserved")
|
|
60
|
+
|
|
61
|
+
@staticmethod
|
|
62
|
+
def and_(*rules: Rule | Iterable[Rule]) -> Rule:
|
|
63
|
+
return Rule({"and": [r._logic for r in _flat(rules)]})
|
|
64
|
+
|
|
65
|
+
@staticmethod
|
|
66
|
+
def or_(*rules: Rule | Iterable[Rule]) -> Rule:
|
|
67
|
+
return Rule({"or": [r._logic for r in _flat(rules)]})
|
|
68
|
+
|
|
69
|
+
@staticmethod
|
|
70
|
+
def not_(rule: Rule) -> Rule:
|
|
71
|
+
return Rule({"!": rule._logic})
|
|
72
|
+
|
|
73
|
+
@staticmethod
|
|
74
|
+
def logic(json_logic: JsonLogic) -> Rule:
|
|
75
|
+
"""Any JsonLogic expression, e.g. copied from the rich filter."""
|
|
76
|
+
return Rule(json_logic)
|
|
77
|
+
|
|
78
|
+
def __and__(self, other: Rule) -> Rule:
|
|
79
|
+
return Rule.and_(self, other)
|
|
80
|
+
|
|
81
|
+
def __or__(self, other: Rule) -> Rule:
|
|
82
|
+
return Rule.or_(self, other)
|
|
83
|
+
|
|
84
|
+
def __invert__(self) -> Rule:
|
|
85
|
+
return Rule.not_(self)
|
|
86
|
+
|
|
87
|
+
def __repr__(self) -> str:
|
|
88
|
+
return f"Rule({json.dumps(self._logic)})"
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
class Operand:
|
|
92
|
+
"""The left side of a rule: a field, a property or a property function."""
|
|
93
|
+
|
|
94
|
+
def __init__(self, name: str, is_property: bool) -> None:
|
|
95
|
+
self._name = name
|
|
96
|
+
self._is_property = is_property
|
|
97
|
+
|
|
98
|
+
def _variable(self) -> dict[str, str]:
|
|
99
|
+
return {"var": self._name}
|
|
100
|
+
|
|
101
|
+
def _op(self, operator: str, *args: Any) -> Rule:
|
|
102
|
+
return Rule({operator: [self._variable(), *(_value(a) for a in args)]})
|
|
103
|
+
|
|
104
|
+
def eq(self, value: Any) -> Rule:
|
|
105
|
+
return self._op("==", value)
|
|
106
|
+
|
|
107
|
+
def ne(self, value: Any) -> Rule:
|
|
108
|
+
return self._op("!=", value)
|
|
109
|
+
|
|
110
|
+
def gt(self, value: Any) -> Rule:
|
|
111
|
+
return self._op(">", value)
|
|
112
|
+
|
|
113
|
+
def ge(self, value: Any) -> Rule:
|
|
114
|
+
return self._op(">=", value)
|
|
115
|
+
|
|
116
|
+
def lt(self, value: Any) -> Rule:
|
|
117
|
+
return self._op("<", value)
|
|
118
|
+
|
|
119
|
+
def le(self, value: Any) -> Rule:
|
|
120
|
+
return self._op("<=", value)
|
|
121
|
+
|
|
122
|
+
def between(self, start: Any, end: Any) -> Rule:
|
|
123
|
+
"""start <= value <= end"""
|
|
124
|
+
return Rule({"<=": [_value(start), self._variable(), _value(end)]})
|
|
125
|
+
|
|
126
|
+
def in_(self, *values: Any) -> Rule:
|
|
127
|
+
"""One of the values: ``in_(1, 2)`` or ``in_([1, 2])``."""
|
|
128
|
+
return self._op("in", _flat_values(values))
|
|
129
|
+
|
|
130
|
+
def not_in(self, *values: Any) -> Rule:
|
|
131
|
+
return self._op("!in", _flat_values(values))
|
|
132
|
+
|
|
133
|
+
def like(self, pattern: str) -> Rule:
|
|
134
|
+
"""SQL LIKE pattern: ``%`` any text, ``_`` one character."""
|
|
135
|
+
return self._op("like", pattern)
|
|
136
|
+
|
|
137
|
+
def not_like(self, pattern: str) -> Rule:
|
|
138
|
+
return self._op("!like", pattern)
|
|
139
|
+
|
|
140
|
+
def matches(self, regex: str) -> Rule:
|
|
141
|
+
"""POSIX regular expression, case sensitive."""
|
|
142
|
+
return self._op("~", regex)
|
|
143
|
+
|
|
144
|
+
def matches_ignore_case(self, regex: str) -> Rule:
|
|
145
|
+
"""POSIX regular expression, case insensitive."""
|
|
146
|
+
return self._op("~*", regex)
|
|
147
|
+
|
|
148
|
+
def not_matches(self, regex: str) -> Rule:
|
|
149
|
+
return self._op("!~", regex)
|
|
150
|
+
|
|
151
|
+
def is_null(self) -> Rule:
|
|
152
|
+
return self._op("is", None)
|
|
153
|
+
|
|
154
|
+
def is_not_null(self) -> Rule:
|
|
155
|
+
return self._op("is not", None)
|
|
156
|
+
|
|
157
|
+
def is_empty(self) -> Rule:
|
|
158
|
+
"""No value: null, missing or (for a property) an empty text."""
|
|
159
|
+
return Rule({"!": self._variable()})
|
|
160
|
+
|
|
161
|
+
def is_not_empty(self) -> Rule:
|
|
162
|
+
return Rule({"!!": self._variable()})
|
|
163
|
+
|
|
164
|
+
def exists(self) -> Rule:
|
|
165
|
+
"""The property is present in the data (also when its value is null)."""
|
|
166
|
+
return self._fn("exists()").eq(True)
|
|
167
|
+
|
|
168
|
+
def not_exists(self) -> Rule:
|
|
169
|
+
return self._fn("notExists()").eq(True)
|
|
170
|
+
|
|
171
|
+
def length(self) -> Operand:
|
|
172
|
+
"""Number of items of an array property (0 when it is not an array)."""
|
|
173
|
+
return self._fn("length()")
|
|
174
|
+
|
|
175
|
+
def _fn(self, fn: str) -> Operand:
|
|
176
|
+
if not self._is_property:
|
|
177
|
+
raise ValueError(f"{fn} works only on a property, not on the field {self._name}")
|
|
178
|
+
return Operand(f"{self._name}.{fn}", is_property=False)
|
|
179
|
+
|
|
180
|
+
|
|
181
|
+
class Rules:
|
|
182
|
+
"""Which data rows a call works on.
|
|
183
|
+
|
|
184
|
+
::
|
|
185
|
+
|
|
186
|
+
Rules.where(Rule.property("$.status").eq("active"), Rule.reserved().eq(False)) # all must match
|
|
187
|
+
Rules.ALL # every row
|
|
188
|
+
Rules.from_rules([["$.status", "==", "active"]]) # the API "rules" format
|
|
189
|
+
Rules.from_logic(json_logic) # JsonLogic
|
|
190
|
+
"""
|
|
191
|
+
|
|
192
|
+
#: No conditions: every row (not accepted when modifying or removing data).
|
|
193
|
+
ALL: Rules
|
|
194
|
+
|
|
195
|
+
def __init__(self, logic: Any = None, rules: list[Any] | None = None) -> None:
|
|
196
|
+
self._logic = logic
|
|
197
|
+
self._rules = rules
|
|
198
|
+
|
|
199
|
+
@staticmethod
|
|
200
|
+
def where(*rules: Rule | Iterable[Rule]) -> Rules:
|
|
201
|
+
"""Rows matching all the rules: ``where(r1, r2)`` or ``where([r1, r2])``."""
|
|
202
|
+
flat = _flat(rules)
|
|
203
|
+
if not flat:
|
|
204
|
+
return Rules.ALL
|
|
205
|
+
if len(flat) == 1:
|
|
206
|
+
return Rules(flat[0].to_logic())
|
|
207
|
+
return Rules(Rule.and_(flat).to_logic())
|
|
208
|
+
|
|
209
|
+
@staticmethod
|
|
210
|
+
def from_rules(rules: Sequence[Any]) -> Rules:
|
|
211
|
+
"""Rules in the API "rules" format, e.g. copied from the "API request" tab of the rich filter:
|
|
212
|
+
``[["$.city", "==", "Paris"], {"or": [["tagId", "in", [1, 2]], ["$.age", ">", 30]]}]``.
|
|
213
|
+
|
|
214
|
+
Note: in this format a value that starts with ``$`` or equals a field name (e.g. "owner") is read as
|
|
215
|
+
a property or field, not as text. :meth:`Rules.where` has no such ambiguity.
|
|
216
|
+
"""
|
|
217
|
+
return Rules(rules=list(rules))
|
|
218
|
+
|
|
219
|
+
@staticmethod
|
|
220
|
+
def from_logic(logic: JsonLogic) -> Rules:
|
|
221
|
+
"""A JsonLogic expression, e.g. ``{"==": [{"var": "$.city"}, "Paris"]}``."""
|
|
222
|
+
return Rules(logic)
|
|
223
|
+
|
|
224
|
+
def is_empty(self) -> bool:
|
|
225
|
+
"""True when there are no conditions (every row)."""
|
|
226
|
+
return self._logic is None and not self._rules
|
|
227
|
+
|
|
228
|
+
def to_body(self) -> dict[str, Any]:
|
|
229
|
+
"""The request body items: ``logic`` or ``rules``."""
|
|
230
|
+
if self._logic is not None:
|
|
231
|
+
return {"logic": self._logic}
|
|
232
|
+
if self._rules is not None:
|
|
233
|
+
return {"rules": self._rules}
|
|
234
|
+
return {}
|
|
235
|
+
|
|
236
|
+
def __repr__(self) -> str:
|
|
237
|
+
return "Rules.ALL" if self.is_empty() else f"Rules({json.dumps(self.to_body())})"
|
|
238
|
+
|
|
239
|
+
|
|
240
|
+
Rules.ALL = Rules()
|
|
241
|
+
|
|
242
|
+
|
|
243
|
+
def _flat(rules: Iterable[Rule | Iterable[Rule]]) -> list[Rule]:
|
|
244
|
+
result: list[Rule] = []
|
|
245
|
+
for item in rules:
|
|
246
|
+
if isinstance(item, Rule):
|
|
247
|
+
result.append(item)
|
|
248
|
+
else:
|
|
249
|
+
result.extend(item)
|
|
250
|
+
return result
|
|
251
|
+
|
|
252
|
+
|
|
253
|
+
def _flat_values(values: tuple[Any, ...]) -> list[Any]:
|
|
254
|
+
if len(values) == 1 and isinstance(values[0], (list, tuple, set, frozenset)):
|
|
255
|
+
return [_value(v) for v in values[0]]
|
|
256
|
+
return [_value(v) for v in values]
|
|
257
|
+
|
|
258
|
+
|
|
259
|
+
def _value(value: Any) -> Any:
|
|
260
|
+
"""Dates are sent as ISO text (UTC); a datetime without a time zone is local time."""
|
|
261
|
+
if isinstance(value, datetime):
|
|
262
|
+
utc = value.astimezone(timezone.utc)
|
|
263
|
+
return utc.strftime("%Y-%m-%dT%H:%M:%S.") + f"{utc.microsecond // 1000:03d}Z"
|
|
264
|
+
if isinstance(value, date):
|
|
265
|
+
return value.isoformat()
|
|
266
|
+
return value
|
|
267
|
+
|
|
268
|
+
|
|
269
|
+
def _property_path(path: str) -> str:
|
|
270
|
+
if not path or not path.strip():
|
|
271
|
+
raise ValueError("The property path is empty")
|
|
272
|
+
return path if path.startswith("$") else f"$.{path}"
|
databucket/search.py
ADDED
|
@@ -0,0 +1,185 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
from collections.abc import Iterable
|
|
4
|
+
from typing import TYPE_CHECKING, Generic, TypeVar
|
|
5
|
+
|
|
6
|
+
from .model import DataRow, HistoryEntry, HistoryPage, Page, Reservation
|
|
7
|
+
from .rules import Rule, Rules
|
|
8
|
+
|
|
9
|
+
if TYPE_CHECKING:
|
|
10
|
+
from .bucket import Bucket
|
|
11
|
+
|
|
12
|
+
T = TypeVar("T")
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
class Query(Generic[T]):
|
|
16
|
+
"""A search for data rows; create it with :meth:`Bucket.find`.
|
|
17
|
+
|
|
18
|
+
::
|
|
19
|
+
|
|
20
|
+
page = users.find(rules).sort(Sort.desc(Field.ID)).limit(20).page(2).fetch()
|
|
21
|
+
rows = users.find(rules).limit(100).list()
|
|
22
|
+
row = users.find(rules).first()
|
|
23
|
+
count = users.find(rules).count()
|
|
24
|
+
"""
|
|
25
|
+
|
|
26
|
+
def __init__(self, bucket: Bucket[T], rules: Rules) -> None:
|
|
27
|
+
self._bucket = bucket
|
|
28
|
+
self._rules = rules
|
|
29
|
+
self._page = 1
|
|
30
|
+
self._limit = 1
|
|
31
|
+
self._sort = "id"
|
|
32
|
+
|
|
33
|
+
def page(self, page: int) -> Query[T]:
|
|
34
|
+
"""Page number, starting from 1 (default 1)."""
|
|
35
|
+
if page < 1:
|
|
36
|
+
raise ValueError("The page starts from 1")
|
|
37
|
+
self._page = page
|
|
38
|
+
return self
|
|
39
|
+
|
|
40
|
+
def limit(self, limit: int) -> Query[T]:
|
|
41
|
+
"""Rows per page (default 1)."""
|
|
42
|
+
if limit < 1:
|
|
43
|
+
raise ValueError("The limit must be at least 1; use count() to only count rows")
|
|
44
|
+
self._limit = limit
|
|
45
|
+
return self
|
|
46
|
+
|
|
47
|
+
def sort(self, sort: str) -> Query[T]:
|
|
48
|
+
"""Sort order, see :class:`Sort` (default: by id)."""
|
|
49
|
+
self._sort = sort
|
|
50
|
+
return self
|
|
51
|
+
|
|
52
|
+
def fetch(self) -> Page[T]:
|
|
53
|
+
return self._bucket._fetch_page(self._rules, self._page, self._limit, self._sort)
|
|
54
|
+
|
|
55
|
+
def list(self) -> list[DataRow[T]]:
|
|
56
|
+
"""The rows of the page."""
|
|
57
|
+
return self.fetch().rows
|
|
58
|
+
|
|
59
|
+
def first(self) -> DataRow[T] | None:
|
|
60
|
+
"""The first matching row; None when none matches."""
|
|
61
|
+
rows = self._bucket._fetch_page(self._rules, 1, 1, self._sort).rows
|
|
62
|
+
return rows[0] if rows else None
|
|
63
|
+
|
|
64
|
+
def count(self) -> int:
|
|
65
|
+
"""Number of matching rows (no rows are transferred)."""
|
|
66
|
+
return self._bucket.count(self._rules)
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
class Reserve(Generic[T]):
|
|
70
|
+
"""A reservation of free data rows; create it with :meth:`Bucket.reserve`. Rows taken at the same moment by
|
|
71
|
+
another client are skipped, so parallel tests never get the same row.
|
|
72
|
+
|
|
73
|
+
::
|
|
74
|
+
|
|
75
|
+
user = users.reserve(rules).one()
|
|
76
|
+
r = users.reserve(rules).limit(3).sort(Sort.RANDOM).fetch()
|
|
77
|
+
free = users.reserve(rules).available()
|
|
78
|
+
"""
|
|
79
|
+
|
|
80
|
+
def __init__(self, bucket: Bucket[T], rules: Rules) -> None:
|
|
81
|
+
self._bucket = bucket
|
|
82
|
+
self._rules = rules
|
|
83
|
+
self._limit = 1
|
|
84
|
+
self._sort = "id"
|
|
85
|
+
self._for_user: str | None = None
|
|
86
|
+
|
|
87
|
+
def limit(self, limit: int) -> Reserve[T]:
|
|
88
|
+
"""Number of rows to reserve (default 1)."""
|
|
89
|
+
if limit < 1:
|
|
90
|
+
raise ValueError("The limit must be at least 1; use available() to only count free rows")
|
|
91
|
+
self._limit = limit
|
|
92
|
+
return self
|
|
93
|
+
|
|
94
|
+
def sort(self, sort: str) -> Reserve[T]:
|
|
95
|
+
"""Which free rows are taken first, see :class:`Sort` (default: by id)."""
|
|
96
|
+
self._sort = sort
|
|
97
|
+
return self
|
|
98
|
+
|
|
99
|
+
def for_user(self, username: str) -> Reserve[T]:
|
|
100
|
+
"""Reserve for another user (ADMIN only; ignored for other roles)."""
|
|
101
|
+
self._for_user = username
|
|
102
|
+
return self
|
|
103
|
+
|
|
104
|
+
def fetch(self) -> Reservation[T]:
|
|
105
|
+
return self._bucket._reserve_rows(self._rules, self._limit, self._sort, self._for_user)
|
|
106
|
+
|
|
107
|
+
def one(self) -> DataRow[T] | None:
|
|
108
|
+
"""Reserves one row; None when no free row matches."""
|
|
109
|
+
rows = self._bucket._reserve_rows(self._rules, 1, self._sort, self._for_user).rows
|
|
110
|
+
return rows[0] if rows else None
|
|
111
|
+
|
|
112
|
+
def available(self) -> int:
|
|
113
|
+
"""Number of free rows matching the rules; nothing is reserved."""
|
|
114
|
+
return self._bucket._reserve_rows(self._rules, 0, self._sort, self._for_user).available
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
class HistorySearch(Generic[T]):
|
|
118
|
+
"""A search of the history of a bucket; create it with :meth:`Bucket.search_history` (Databucket 3.14.0+).
|
|
119
|
+
|
|
120
|
+
::
|
|
121
|
+
|
|
122
|
+
# changes made by the nightly robot since yesterday, on the rows that are now in GB, newest first
|
|
123
|
+
page = (users.search_history(Rules.where(Rule.property("$.address.country").eq("GB")))
|
|
124
|
+
.where(Rule.field(HistoryField.MODIFIED_BY).eq("nightly-robot"),
|
|
125
|
+
Rule.field(HistoryField.MODIFIED_AT).ge(datetime.now(timezone.utc) - timedelta(days=1)))
|
|
126
|
+
.sort(Sort.desc(HistoryField.MODIFIED_AT))
|
|
127
|
+
.limit(50)
|
|
128
|
+
.fetch())
|
|
129
|
+
"""
|
|
130
|
+
|
|
131
|
+
def __init__(self, bucket: Bucket[T], rows: Rules) -> None:
|
|
132
|
+
self._bucket = bucket
|
|
133
|
+
self._rows = rows
|
|
134
|
+
self._entries: list[Rule] = []
|
|
135
|
+
self._page = 1
|
|
136
|
+
self._limit = 20
|
|
137
|
+
self._sort = "id"
|
|
138
|
+
self._properties = False
|
|
139
|
+
|
|
140
|
+
def where(self, *rules: Rule | Iterable[Rule]) -> HistorySearch[T]:
|
|
141
|
+
"""Which history entries (all must match): rules on :class:`HistoryField` s, e.g.
|
|
142
|
+
``Rule.field(HistoryField.MODIFIED_BY).eq("john")``. The properties of the versions can't be searched."""
|
|
143
|
+
for item in rules:
|
|
144
|
+
if isinstance(item, Rule):
|
|
145
|
+
self._entries.append(item)
|
|
146
|
+
else:
|
|
147
|
+
self._entries.extend(item)
|
|
148
|
+
return self
|
|
149
|
+
|
|
150
|
+
def page(self, page: int) -> HistorySearch[T]:
|
|
151
|
+
"""Page number, starting from 1 (default 1)."""
|
|
152
|
+
if page < 1:
|
|
153
|
+
raise ValueError("The page starts from 1")
|
|
154
|
+
self._page = page
|
|
155
|
+
return self
|
|
156
|
+
|
|
157
|
+
def limit(self, limit: int) -> HistorySearch[T]:
|
|
158
|
+
"""Entries per page, 1..1000 (default 20)."""
|
|
159
|
+
if limit < 1 or limit > 1000:
|
|
160
|
+
raise ValueError("The limit is 1..1000; use count() to only count entries")
|
|
161
|
+
self._limit = limit
|
|
162
|
+
return self
|
|
163
|
+
|
|
164
|
+
def sort(self, sort: str) -> HistorySearch[T]:
|
|
165
|
+
"""Sort order by a history field, e.g. ``Sort.desc(HistoryField.MODIFIED_AT)`` (default: by id)."""
|
|
166
|
+
self._sort = sort
|
|
167
|
+
return self
|
|
168
|
+
|
|
169
|
+
def with_properties(self) -> HistorySearch[T]:
|
|
170
|
+
"""Also the properties of each version (when they changed)."""
|
|
171
|
+
self._properties = True
|
|
172
|
+
return self
|
|
173
|
+
|
|
174
|
+
def fetch(self) -> HistoryPage[T]:
|
|
175
|
+
return self._bucket._search_history_page(
|
|
176
|
+
self._rows, Rules.where(self._entries), self._page, self._limit, self._sort, self._properties
|
|
177
|
+
)
|
|
178
|
+
|
|
179
|
+
def list(self) -> list[HistoryEntry[T]]:
|
|
180
|
+
"""The entries of the page."""
|
|
181
|
+
return self.fetch().entries
|
|
182
|
+
|
|
183
|
+
def count(self) -> int:
|
|
184
|
+
"""Number of matching history entries."""
|
|
185
|
+
return self._bucket._search_history_page(self._rows, Rules.where(self._entries), 1, 0, self._sort, False).total
|