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
|
@@ -0,0 +1,219 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: databucket-client
|
|
3
|
+
Version: 2.0.0
|
|
4
|
+
Summary: Client for Databucket (test data management): find, reserve, change and remove test data from your automated tests
|
|
5
|
+
Project-URL: Homepage, https://github.com/databucket/databucket-python-client
|
|
6
|
+
Project-URL: Issues, https://github.com/databucket/databucket-python-client/issues
|
|
7
|
+
Project-URL: Databucket, https://github.com/databucket/databucket-server
|
|
8
|
+
Author: Krzysztof Słysz
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: databucket,pytest,test data,test data management,testing
|
|
12
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Operating System :: OS Independent
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
17
|
+
Classifier: Topic :: Software Development :: Testing
|
|
18
|
+
Classifier: Typing :: Typed
|
|
19
|
+
Requires-Python: >=3.10
|
|
20
|
+
Requires-Dist: requests>=2.32
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
|
|
23
|
+
# databucket-python-client
|
|
24
|
+
|
|
25
|
+
[](https://pypi.org/project/databucket-client/)
|
|
26
|
+
|
|
27
|
+
Python client for [Databucket](https://github.com/databucket/databucket-server): find, reserve, change and remove test
|
|
28
|
+
data from your automated tests (pytest, Robot Framework libraries, Behave, scripts).
|
|
29
|
+
|
|
30
|
+
- Python 3.10+, one dependency (`requests`), type hints included
|
|
31
|
+
- API version 2 of Databucket (3.13.0 or newer; history search and history for ROBOT accounts: 3.14.0)
|
|
32
|
+
- Sign-in with a password or with a token of your identity provider (SSO robot accounts, Databucket 3.10.0+);
|
|
33
|
+
the token is renewed when it expires
|
|
34
|
+
- Parallel tests never reserve the same row; one client can be shared by threads
|
|
35
|
+
|
|
36
|
+
```
|
|
37
|
+
pip install databucket-client
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
The same features and version numbers as the [Java client](https://github.com/databucket/databucket-java-client) and
|
|
41
|
+
the [JavaScript client](https://github.com/databucket/databucket-js-client).
|
|
42
|
+
|
|
43
|
+
## Quick start
|
|
44
|
+
|
|
45
|
+
```python
|
|
46
|
+
import os
|
|
47
|
+
from databucket import Change, Databucket, Rule, Rules
|
|
48
|
+
|
|
49
|
+
databucket = Databucket(
|
|
50
|
+
"https://databucket.example.com",
|
|
51
|
+
username="tests-robot",
|
|
52
|
+
password=os.environ["DATABUCKET_PASSWORD"],
|
|
53
|
+
project="Acme Shop", # by name or id; needed when the user has several projects
|
|
54
|
+
)
|
|
55
|
+
|
|
56
|
+
users = databucket.bucket("dev-users")
|
|
57
|
+
|
|
58
|
+
# reserve one free active user for this test
|
|
59
|
+
user = users.reserve(
|
|
60
|
+
Rules.where(
|
|
61
|
+
Rule.property("$.account.status").eq("active"),
|
|
62
|
+
Rule.property("$.address.country").in_("GB", "PL"),
|
|
63
|
+
)
|
|
64
|
+
).one()
|
|
65
|
+
assert user, "No free active user"
|
|
66
|
+
|
|
67
|
+
# ... the test ...
|
|
68
|
+
|
|
69
|
+
users.update(Change().set("$.account.status", "suspended"), user.id)
|
|
70
|
+
users.release(user.id)
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Rows are `DataRow` objects: `id`, `tag_id`, `reserved`, `owner`, `properties` (a dict by default), `created_by`,
|
|
74
|
+
`created_at`, `modified_by`, `modified_at` (`datetime`). For typed properties, e.g. a `TypedDict`:
|
|
75
|
+
`users: Bucket[User] = databucket.bucket("dev-users")`.
|
|
76
|
+
|
|
77
|
+
## pytest
|
|
78
|
+
|
|
79
|
+
A fixture that gives each test its own user and releases it afterwards, also when the test fails:
|
|
80
|
+
|
|
81
|
+
```python
|
|
82
|
+
# conftest.py
|
|
83
|
+
import os
|
|
84
|
+
import pytest
|
|
85
|
+
from databucket import Databucket, Rule, Rules
|
|
86
|
+
|
|
87
|
+
databucket = Databucket(
|
|
88
|
+
os.environ["DATABUCKET_URL"],
|
|
89
|
+
username="tests-robot",
|
|
90
|
+
password=os.environ["DATABUCKET_PASSWORD"],
|
|
91
|
+
project="Acme Shop",
|
|
92
|
+
)
|
|
93
|
+
users = databucket.bucket("dev-users")
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
@pytest.fixture
|
|
97
|
+
def user():
|
|
98
|
+
row = users.reserve(Rules.where(Rule.property("$.account.status").eq("active"))).one()
|
|
99
|
+
if row is None:
|
|
100
|
+
pytest.fail("No free active user in dev-users")
|
|
101
|
+
yield row
|
|
102
|
+
users.release(row.id)
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
# test_login.py
|
|
106
|
+
def test_signs_in(page, user):
|
|
107
|
+
page.goto("/login")
|
|
108
|
+
page.get_by_label("Email").fill(user.properties["email"])
|
|
109
|
+
# ...
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Works with `pytest-xdist` too: parallel workers never get the same row.
|
|
113
|
+
|
|
114
|
+
## Rules
|
|
115
|
+
|
|
116
|
+
Rules are written in code and sent as JsonLogic, so values are never mistaken for fields or properties.
|
|
117
|
+
|
|
118
|
+
```python
|
|
119
|
+
Rule.property("$.address.city").eq("Paris") # also: ne, gt, ge, lt, le
|
|
120
|
+
Rule.property("$.age").between(18, 65)
|
|
121
|
+
Rule.tag_id().in_(1, 2) # or in_([1, 2]); also: not_in
|
|
122
|
+
Rule.property("$.email").like("%@example.com") # also: not_like, matches, matches_ignore_case, not_matches
|
|
123
|
+
Rule.owner().is_null() # also: is_not_null
|
|
124
|
+
Rule.property("$.phone").is_empty() # None, missing or ""; also: is_not_empty
|
|
125
|
+
Rule.property("$.tmp").exists() # also: not_exists
|
|
126
|
+
Rule.property("$.orders").length().gt(2) # items of an array
|
|
127
|
+
Rule.field(Field.CREATED_BY).eq(Rule.CURRENT_USER) # the signed-in user
|
|
128
|
+
Rule.or_(rule1, rule2), Rule.and_(...), Rule.not_(rule)
|
|
129
|
+
rule1 | rule2, rule1 & rule2, ~rule # the same with operators
|
|
130
|
+
|
|
131
|
+
Rules.where(rule1, rule2) # all must match; also Rules.where([rule1, rule2])
|
|
132
|
+
Rules.ALL # every row (not accepted for update / delete)
|
|
133
|
+
Rules.from_rules(list) # the API "rules" format, e.g. copied from the "API request" tab of the rich filter
|
|
134
|
+
Rules.from_logic(dict) # JsonLogic
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
Fields: `id`, `tagId`, `owner`, `reserved`, `createdBy`, `createdAt`, `modifiedBy`, `modifiedAt` (`Field`).
|
|
138
|
+
Dates can be given as `datetime`; they are sent as ISO text in UTC (a `datetime` without a time zone is local time).
|
|
139
|
+
|
|
140
|
+
## Operations
|
|
141
|
+
|
|
142
|
+
| Call | API |
|
|
143
|
+
|---|---|
|
|
144
|
+
| `insert(properties)`, `insert(NewData(p).tag_id(3).reserved(True))` | `POST /api/bucket/{bucket}` |
|
|
145
|
+
| `insert_all([p1, p2, NewData(p3).tag_id(3)])` | `POST /api/bucket/{bucket}/multi` |
|
|
146
|
+
| `get(id)` (`None` when missing), `get([id1, id2])` | `GET /api/bucket/{bucket}/{ids}` |
|
|
147
|
+
| `find(rules).sort(Sort.desc("$.name")).limit(20).page(2).fetch()` / `.list()` / `.first()` / `.count()`, `count(rules)` | `POST /api/bucket/{bucket}/get` |
|
|
148
|
+
| `reserve(rules).one()`, `.limit(3).sort(Sort.RANDOM).fetch()`, `.available()`, `.for_user("john")` (ADMIN) | `POST /api/bucket/{bucket}/reserve` |
|
|
149
|
+
| `update(change, *ids)`, `update(rules, change)`, `release(*ids)` | `PUT /api/bucket/{bucket}[/{ids}]` |
|
|
150
|
+
| `delete(*ids)`, `delete(rules)` | `DELETE /api/bucket/{bucket}[/{ids}]` |
|
|
151
|
+
| `history(id)`, `history_properties(id, *history_ids)`, `clear_history(id)`, `clear_history(rules)` | `/api/bucket/{bucket}/{id}/history...` |
|
|
152
|
+
| `search_history(rows).where(...).sort(...).limit(50).with_properties().fetch()` / `.list()` / `.count()` | `POST /api/bucket/{bucket}/history/get` |
|
|
153
|
+
|
|
154
|
+
`update`, `release`, `delete` and `clear_history` return the number of changed rows (or removed history entries).
|
|
155
|
+
|
|
156
|
+
`Change()` sets, removes or replaces properties, the tag and the reservation:
|
|
157
|
+
`Change().set("$.status", "used").remove("$.tmp").tag_id(4)`, `Change().properties(new_user)`.
|
|
158
|
+
|
|
159
|
+
## History
|
|
160
|
+
|
|
161
|
+
```python
|
|
162
|
+
from datetime import datetime, timedelta, timezone
|
|
163
|
+
from databucket import HistoryField, Rule, Rules, Sort
|
|
164
|
+
|
|
165
|
+
# changes made by the nightly robot since yesterday, on the rows that are now in GB, newest first
|
|
166
|
+
page = (
|
|
167
|
+
users.search_history(Rules.where(Rule.property("$.address.country").eq("GB")))
|
|
168
|
+
.where(
|
|
169
|
+
Rule.field(HistoryField.MODIFIED_BY).eq("nightly-robot"),
|
|
170
|
+
Rule.field(HistoryField.MODIFIED_AT).ge(datetime.now(timezone.utc) - timedelta(days=1)),
|
|
171
|
+
)
|
|
172
|
+
.sort(Sort.desc(HistoryField.MODIFIED_AT))
|
|
173
|
+
.limit(50)
|
|
174
|
+
.with_properties() # the properties of each version
|
|
175
|
+
.fetch()
|
|
176
|
+
)
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
The rows are chosen by their current state (`Rules`), the entries by the fields of the history (`HistoryField`:
|
|
180
|
+
`ID`, `DATA_ID`, `TAG_ID`, `RESERVED`, `MODIFIED_BY`, `MODIFIED_AT`); the properties of past versions can't be searched.
|
|
181
|
+
|
|
182
|
+
Errors are raised as `DatabucketError` with `status` (the HTTP status, 0 when there was no response) and the server's
|
|
183
|
+
message; `body` holds the raw response. Wrong arguments (e.g. `update(Rules.ALL, ...)`) raise `ValueError`.
|
|
184
|
+
|
|
185
|
+
## Options
|
|
186
|
+
|
|
187
|
+
```python
|
|
188
|
+
Databucket(
|
|
189
|
+
"https://databucket.example.com",
|
|
190
|
+
username="tests-robot", password=password, # POST /api/public/signin
|
|
191
|
+
# or: sso_token=fetch_token_from_idp, # POST /api/public/sso/token-exchange (client credentials of a ROBOT)
|
|
192
|
+
# or: token=databucket_token, # a token you already have (not renewed)
|
|
193
|
+
project=15, # or "Acme Shop"
|
|
194
|
+
timeout=10, # per request, seconds (default 30)
|
|
195
|
+
session=my_session, # your requests.Session, e.g. with a proxy or certificates
|
|
196
|
+
)
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
Each request is logged at DEBUG level by the logger `databucket`
|
|
200
|
+
(`logging.getLogger("databucket").setLevel(logging.DEBUG)`).
|
|
201
|
+
|
|
202
|
+
## Build
|
|
203
|
+
|
|
204
|
+
```
|
|
205
|
+
python -m venv .venv
|
|
206
|
+
.venv/Scripts/activate # Windows; Linux / macOS: source .venv/bin/activate
|
|
207
|
+
pip install -e . --group dev # pip 25.1+
|
|
208
|
+
pytest # unit tests
|
|
209
|
+
pytest tests/it # integration tests
|
|
210
|
+
ruff check . && ruff format --check . && mypy
|
|
211
|
+
python -m build # dist/
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
The integration tests need Databucket with the DEMO dataset, e.g. the docker compose of databucket-server
|
|
215
|
+
(http://databucket.localhost, project "Acme Shop", users `demo-robot` and `demo-member`); the history tests need
|
|
216
|
+
Databucket 3.14.0+. Change it with `DATABUCKET_URL`, `DATABUCKET_PROJECT`, `DATABUCKET_BUCKET`. They work only on rows
|
|
217
|
+
they create and remove them at the end.
|
|
218
|
+
|
|
219
|
+
Release to PyPI: `python -m build` and `twine upload dist/*` (with an API token of pypi.org).
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
databucket/__init__.py,sha256=C37Wa4A68xBHB2Ep9gQFOceh_gKR-Mxqp96cS2Sa8ms,978
|
|
2
|
+
databucket/bucket.py,sha256=q3ls3qjWyOKkrlq1jVePyF3IPT_w2TJXYrD10M7TcLM,12860
|
|
3
|
+
databucket/change.py,sha256=igc9mBKS3pQG8rlMkmoGOKjX3dREH6rRt0d3fuKIIxU,3230
|
|
4
|
+
databucket/client.py,sha256=bU8dESJVOR-csHvcejDEnsobvTXJ-fueeAubuKegRK8,10158
|
|
5
|
+
databucket/fields.py,sha256=nnNgxRHS3ON4oRhpzliIIfHB4MS7dcZ-N5_aVkzoAEc,1226
|
|
6
|
+
databucket/model.py,sha256=YpDUAm6Hm5rjnVy-HyQw25fqRF5-OWyHBkcCFmQnfQY,2580
|
|
7
|
+
databucket/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
8
|
+
databucket/rules.py,sha256=0PYhgeFH7dl3FCMXzDGMk1wbHgwrHG9yiTwahztTq_0,9182
|
|
9
|
+
databucket/search.py,sha256=-HY92zuSp00rc7aVdNt_ww7k-Y_kCGsFkdB-xyXDUao,6866
|
|
10
|
+
databucket_client-2.0.0.dist-info/METADATA,sha256=GWFWB-T0429CtJnxLqzGssHG3XSJ7zRT17Thp2ArITM,9401
|
|
11
|
+
databucket_client-2.0.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
12
|
+
databucket_client-2.0.0.dist-info/licenses/LICENSE,sha256=inUkQ5xzA4ATLVMOTRRwjnuJXcvFIVisPm6GYqnkaGQ,1088
|
|
13
|
+
databucket_client-2.0.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2021 Databucket
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|