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/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