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.
@@ -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
+ [![PyPI](https://img.shields.io/pypi/v/databucket-client)](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,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -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.