dray 0.0.0__tar.gz → 0.2__tar.gz

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.
dray-0.2/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Rodney Haywood
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.
dray-0.2/PKG-INFO ADDED
@@ -0,0 +1,450 @@
1
+ Metadata-Version: 2.4
2
+ Name: dray
3
+ Version: 0.2
4
+ Summary: A Python record layer for Amazon Aurora DSQL
5
+ Author: Rodos
6
+ License-Expression: MIT
7
+ License-File: LICENSE
8
+ Classifier: Development Status :: 3 - Alpha
9
+ Classifier: Intended Audience :: Developers
10
+ Classifier: Programming Language :: Python :: 3.12
11
+ Classifier: Programming Language :: Python :: 3.13
12
+ Classifier: Programming Language :: Python :: 3.14
13
+ Classifier: Topic :: Database
14
+ Classifier: Topic :: Database :: Front-Ends
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Typing :: Typed
17
+ Requires-Dist: psycopg>=3.3.4,<4
18
+ Requires-Dist: cachetools>=5.3
19
+ Requires-Dist: aurora-dsql-python-connector[psycopg]>=0.2.7,<0.3 ; extra == 'dsql'
20
+ Requires-Dist: psycopg-pool>=3.3.1 ; extra == 'dsql'
21
+ Requires-Python: >=3.12
22
+ Project-URL: Homepage, https://github.com/draylabs/dray
23
+ Project-URL: Documentation, https://github.com/draylabs/dray/blob/main/docs/manual.md
24
+ Project-URL: Source, https://github.com/draylabs/dray
25
+ Project-URL: Issues, https://github.com/draylabs/dray/issues
26
+ Provides-Extra: dsql
27
+ Description-Content-Type: text/markdown
28
+
29
+ # dray
30
+
31
+ **A Python record layer for Amazon Aurora DSQL.**
32
+
33
+ dray is built out of how DSQL works. No savepoints, no locks to take, three
34
+ thousand rows to a transaction, and a commit that can be refused. The limits
35
+ are the design rather than obstacles to route around.
36
+
37
+ You can already run SQLAlchemy or Django against DSQL — AWS ships adapters for
38
+ both — but you spend the time talking them out of savepoints, pessimistic
39
+ locking and heap storage. dray assumes none of those to begin with.
40
+
41
+ ## Install
42
+
43
+ ```bash
44
+ uv add dray # or: pip install dray
45
+ ```
46
+
47
+ Python 3.12 or newer. `Store.connect` authenticates against a cluster and so
48
+ needs AWS's own connector, which is an extra:
49
+
50
+ ```bash
51
+ uv add "dray[dsql]"
52
+ ```
53
+
54
+ A store handed a connection you already have needs none of that — psycopg is
55
+ the driver underneath either way, and the connector installs no driver of its
56
+ own.
57
+
58
+ **dray is not at 1.0.** 0.1 is the first release meant to be depended on, and
59
+ a version before 1.0 may still change what a call does. [The manual][manual] is
60
+ the promise; anything not on that page is not one yet.
61
+
62
+ The smallest thing that works:
63
+
64
+ ```python
65
+ from dray import Store, record
66
+
67
+
68
+ @record(table="person", collection="people")
69
+ class Person:
70
+ family_name: str
71
+
72
+
73
+ store = Store.connect(host="ab12cd.dsql.ap-southeast-2.on.aws")
74
+ store.create(Person) # the table it implies, once
75
+
76
+ person = store.people.add(Person(family_name="Hemingway"))
77
+ print(store.people.by_id(person.id).family_name)
78
+ # Hemingway
79
+ ```
80
+
81
+ With dray you get:
82
+
83
+ - **DSQL's limits handled for you.** A transaction there holds 3,000 rows, so a
84
+ big write is split to fit; a commit it refuses under contention is replayed
85
+ rather than raised at you; a save that meets somebody's migration rides it
86
+ out; and a delete reaches the records underneath.
87
+ - **Records that are plain dataclasses**, declared with a decorator. No base
88
+ class, no metaclass, and no connection — you can build one, hand it to a
89
+ function and test it with the database nowhere in sight.
90
+ - **A column or a JSON document, decided per field.** Give a field its own
91
+ column, or keep it in a `jsonb` document beside the others — adding one of
92
+ those is a write rather than a migration, and a filter and an index are
93
+ written the same way either side.
94
+ - **Indexes said on the class, down to which rows.** `index("family_name",
95
+ where={"status": "volunteer"})` covers the few anybody asks about, and with
96
+ `unique=True` it is a rule about those alone: one open signup per person,
97
+ any number of cancelled ones.
98
+ - **Somewhere for your queries to live.** A collection is a class you own, with
99
+ `find` for matching on values and SQL you wrote for everything else. Both
100
+ hand back records rather than rows.
101
+ - **A read cache, per record, off until you ask for it.** Put `cached_for=10`
102
+ on a record and reading the same one again comes out of memory instead of
103
+ the database. Other reads fill that cache too, a write drops what it
104
+ changed, and nothing lives long enough to go far wrong.
105
+ - **Made to be used from many threads.** A store each out of a pool and
106
+ one cache between them, so a page wanting six answers asks for all six at
107
+ once and costs the longest rather than the sum — then reads on sequentially,
108
+ out of the cache they filled.
109
+ - **Sub-records that travel with their parent.** Notes on a person, lines in an
110
+ order: queued up, written in the same transaction as the change they explain,
111
+ and deleted when it is. One child table serves every kind of parent, which
112
+ no foreign key could, so dray does the cascade for you.
113
+ - **A field that names another record, held to it.** Say `references=Person`
114
+ on an `organiser_id` and DSQL refuses an id that resolves to nobody, and
115
+ refuses to delete a person an event still names. dray tells you which field,
116
+ and changes nothing behind your back.
117
+ - **Business rules that live on the field, not at the call site.** What a value
118
+ will accept, what it tidies on the way in, what to fill in on a write, and
119
+ what to run when it changes. Said once on the class and applied at every door
120
+ a value arrives through — a constructor, a form, an importer, a filter — so
121
+ there is no route into your data that quietly goes around them, and nobody
122
+ has to remember to call anything.
123
+ - **Optimistic concurrency, already wired up.** Two people open the same record
124
+ and both save it: the first one lands, and the second is told rather than
125
+ quietly painting over it. Every record carries an `etag` dray mints and
126
+ checks on the way back in, so you get a `RecordHasChanged` to handle rather
127
+ than a mystery change to account for weeks later.
128
+ - **Two answers when DSQL is briefly not there, rather than one error.**
129
+ `Unavailable` where nothing was committed and the work can be run again,
130
+ and `CommitUncertain` where the commit went unanswered and the rows may have
131
+ landed — with the keys of the records to go and look for.
132
+ - **The `create table` your classes imply**, as statements to paste into a
133
+ migration — and a way to ask a live database where it has drifted from
134
+ them.
135
+ - **Somewhere to look when it is slow.** Every trip dray made to DSQL and every
136
+ one the cache saved you — the connection, the transaction, the statement, the
137
+ hit — with what asked for it and what it cost, as a tree you can print or
138
+ assert on. A test can pin *this page makes one read and not six*, and against
139
+ a cluster you can hang DSQL's own query plan under each read.
140
+
141
+ ## Documentation
142
+
143
+ **[The manual][manual]** is the whole of it, and is meant to be read from
144
+ the top rather than searched: a record, a store to reach it through, a collection
145
+ to ask, children hanging off it, and — throughout — what the database is doing
146
+ underneath and why the shape above it is what it is.
147
+
148
+ It is one page on purpose. The story builds, so it is read in order the first
149
+ time, and after that a browser's own search reaches every word of it at once.
150
+
151
+ **[The reference][reference]** is the other half of that, and is
152
+ meant to be looked at rather than read: what the pieces are and how you reach
153
+ one from another, what each of them offers, which door runs which rule, and
154
+ where the transaction is. All of it in one screen, which is the one thing a
155
+ page read from the top cannot do. Open it in a browser — it is generated by
156
+ `scripts/reference.py`, half of it read out of the library itself.
157
+
158
+ **Building with an agent?** Hand it [the manual][manual]. The page is one page
159
+ for this reason as much as for reading: the whole promise fits in a single
160
+ fetch, in order, with the reasoning attached — so an agent is not guessing at
161
+ what a call takes, or reaching for a savepoint or a lock that is not there. Pointing at it from whatever file your agent reads for project
162
+ context is enough, and [the reference][reference] is worth adding where the
163
+ work is mostly about which door runs which rule.
164
+
165
+ The page is also written *against* agents building blind — handed a domain to
166
+ build and this page, with dray's source barred — and a good many of its
167
+ sentences are there because one of those builds got something wrong. The
168
+ nuance is on the page rather than waiting to be discovered, and yours will not
169
+ be the first agent to meet it.
170
+
171
+ ## A fuller example
172
+
173
+ The manual is where all of this is actually taught, in order and with the
174
+ reasoning. What follows is only a feel for it — the same register with the
175
+ rules it needs, the history it keeps and the questions it gets asked:
176
+
177
+ ```python
178
+ from datetime import datetime
179
+
180
+ import dray
181
+ from dray import (
182
+ Store, child, clock, collection, field, index, record, records_change
183
+ )
184
+
185
+ STATUSES = ("enquiry", "volunteer", "lapsed")
186
+
187
+
188
+ def enqueue(what, who): # yours — a queue, a mail, a webhook
189
+ ...
190
+
191
+
192
+ def tidied(email):
193
+ return email.strip().lower() if email else None
194
+
195
+
196
+ def whoever(write):
197
+ """Whoever the save was told about, in `save(given={"whom": ...})`."""
198
+ return write.given.get("whom")
199
+
200
+
201
+ # Define it
202
+
203
+ @record(
204
+ table="person", # where the rows live
205
+ collection="people", # what the store calls them
206
+ order_by="family_name", # the order a read gets if nobody asks
207
+ indexes=[index("status", "family_name")],
208
+ cached_for=10, # seconds a row may be served from memory
209
+ )
210
+ class Person:
211
+ family_name: str # a plain annotation is a text column
212
+ given_names: str = ""
213
+
214
+ status: str = field(
215
+ default="enquiry",
216
+ # Limit what this will accept, no matter how it is assigned.
217
+ choices=STATUSES,
218
+ # React when the value moves, wherever the edit came from, with any
219
+ # function of yours. `records_change` is one dray ships: it queues a
220
+ # line into the child named, filling that child's first field.
221
+ on_change=records_change(into="logs"),
222
+ )
223
+
224
+ email: str | None = field(
225
+ # Runs wherever a value reaches the field: the constructor, an
226
+ # assignment, `parse`, and the value a filter is asked to match. So a
227
+ # row stored tidied is found by any spelling of it.
228
+ converter=tidied,
229
+ )
230
+
231
+ suburb: str | None = field(
232
+ stored_in="blob", # jsonb — no migration, no column spent
233
+ )
234
+
235
+ added_on: datetime | None = field(
236
+ # Fill this on the insert, with any function of yours. `clock` is one
237
+ # dray ships, and asks the database for the time rather than Python.
238
+ on_add=clock,
239
+ )
240
+
241
+ changed_on: datetime | None = field(
242
+ # Fill it again on every write after that, so a null here means
243
+ # nobody has edited this record yet.
244
+ on_save=clock,
245
+ )
246
+
247
+ # Ordinary Python. A record is your class, and dray has no opinion about
248
+ # anything it did not put there — this is not a field, not stored, and
249
+ # not in `as_dict()`.
250
+ @property
251
+ def full_name(self) -> str:
252
+ return f"{self.given_names} {self.family_name}".strip()
253
+
254
+ # Refuse a record that does not hang together. Where a rule needs the
255
+ # whole record rather than one value, and it runs at every door one comes
256
+ # in by, before any transaction is open.
257
+ @dray.check
258
+ def a_volunteer_is_somewhere(self):
259
+ if self.status == "volunteer" and not self.suburb:
260
+ raise ValueError("a volunteer is rostered out of a suburb")
261
+
262
+ # Act inside the write's own transaction. For a rule that has to write, or
263
+ # to read another record with it already open. `write.adding` is true only
264
+ # on the write that creates the record, `write.was` is what it held before
265
+ # this one, and `write.given` is who is asking.
266
+ @dray.before_save
267
+ def log_the_arrival(self, write):
268
+ if write.adding:
269
+ self.logs.add("enquiry received")
270
+
271
+ # Act once the rows are durable, and not at all if they never are. Where
272
+ # the work leaves the database — a job, a mail, a webhook.
273
+ @dray.after_commit
274
+ def tell_the_roster(self):
275
+ enqueue("person-changed", self.id)
276
+
277
+
278
+ @child(of=Person, name="notes", table="note", order_by="at")
279
+ class Note:
280
+ body: str # what `notes.add("...")` fills
281
+ at: datetime | None = field(on_add=clock)
282
+
283
+
284
+ @child(of=Person, name="logs", table="person_log", order_by="at")
285
+ class Log:
286
+ message: str # what `records_change` writes into
287
+ at: datetime | None = field(on_add=clock)
288
+ whom: str | None = field(on_add=whoever)
289
+
290
+
291
+ @collection(of=Person)
292
+ class People:
293
+ """Questions of your own, in SQL, answered in records."""
294
+
295
+ def changed_since(self, when: datetime) -> list[Person]:
296
+ # `sql_for` is how a field is named in SQL: the column where it has
297
+ # one, the expression that reads it out of the blob where it does
298
+ # not. So this keeps working if the field ever moves, and a name the
299
+ # class never declared is refused here rather than by the database.
300
+ changed = self.sql_for("changed_on")
301
+ return self.select_many(
302
+ f"select {self.columns} from {self.table}"
303
+ f" where {changed} >= %s order by {changed} desc",
304
+ [when],
305
+ )
306
+
307
+
308
+ # Use it
309
+
310
+ store = Store.connect(host="ab12cd.dsql.ap-southeast-2.on.aws")
311
+ store.create(Person, Note, Log) # the three tables these imply
312
+
313
+ # An enquiry, typed in.
314
+ person = store.people.add( # inserted, and handed back filled in
315
+ Person(family_name="Hemingway", given_names="Ernest", suburb="Leura",
316
+ email=" Ernest@Example.COM "),
317
+ given={"whom": "rod"}, # who is asking, for the rules to use
318
+ )
319
+
320
+ # And one from outside — a form, a spreadsheet, an API. `parse` runs the
321
+ # converters and the rules, so what it accepts is what a write will take.
322
+ other = store.people.add(
323
+ Person.parse({"family_name": "Stein", "given_names": "Gertrude",
324
+ "suburb": "Katoomba", "email": "GStein@Example.com"}),
325
+ given={"whom": "rod"},
326
+ )
327
+
328
+ # Both of them signed up at the same open day. One transaction, so the
329
+ # register cannot end up holding half of it — and `after_commit` waits for
330
+ # the outermost block, so the roster hears once rather than twice.
331
+ with store.transaction():
332
+ for one in (person, other):
333
+ one.status = "volunteer" # queues a line for `logs`
334
+ one.notes.add("Signed up at the Katoomba open day.")
335
+ one.save(given={"whom": "rod"})
336
+
337
+ # A name of your own in the tree, so a watcher can say what the whole page
338
+ # cost as well as what each read in it cost. Free when nobody is watching.
339
+ with store.span("the roster page"):
340
+ store.people.find() # both, by family_name — the class said
341
+ store.people.find(equals={"status": "volunteer", "suburb": "Leura"})
342
+ store.people.find(equals={"email": "ERNEST@example.com"}) # stored tidied
343
+ store.people.changed_since(datetime(2026, 1, 1))
344
+ store.people.by_id(person.id) # seeded by the find — no round trip
345
+
346
+ person.full_name # 'Ernest Hemingway' — yours, not dray's
347
+
348
+ person.as_dict() # every field the class declares
349
+ # {'family_name': 'Hemingway', 'given_names': 'Ernest', 'status': 'volunteer',
350
+ # 'email': 'ernest@example.com', 'suburb': 'Leura', 'added_on': datetime(…),
351
+ # 'changed_on': datetime(…), 'id': UUID(…), 'etag': '…'}
352
+
353
+ # Two kinds of child, put in one order here rather than by the database.
354
+ # They are ordinary objects once they have arrived, so this is a `sorted`.
355
+ for one in sorted([*person.notes, *person.logs], key=lambda one: one.at):
356
+ print(f"{one.at:%H:%M}", getattr(one, "message", None) or one.body)
357
+ # 15:25 enquiry received
358
+ # 15:25 status changed from 'enquiry' to 'volunteer'.
359
+ # 15:25 Signed up at the Katoomba open day.
360
+ ```
361
+
362
+ Six of those fields get columns of their own and `suburb` lives in a jsonb
363
+ document, and the filter at the end reads the same across both. `status` takes
364
+ no word outside `STATUSES` and writes a line into `logs` every time it moves,
365
+ whether it was moved by your code, by a form or by an importer. The check runs
366
+ at every door a record comes in by, so a volunteer with nowhere to be rostered
367
+ is refused before a statement is written.
368
+
369
+ Each person and their notes and logs go in one transaction, and the block puts
370
+ both people in one more: all of it lands or none of it does, and
371
+ `tell_the_roster` waits for the outermost block rather than firing per save.
372
+ `changed_since` is the shape `find` will not do — equality is the whole of what
373
+ it takes, so a range is SQL you wrote, handed back as records rather than rows.
374
+ And the last read in the page costs nothing: the `find` above it left its rows
375
+ where `by_id` looks, for the ten seconds the class asked for.
376
+
377
+ And because every trip to DSQL is a span, that run draws itself. This is the
378
+ page above, against a real cluster:
379
+
380
+ ```
381
+ ├─ caller the roster page··············· 191.74ms █████████████████████▉
382
+ │ ├─ statement Person·················· 61.38ms 2 rows ███████
383
+ │ │ ├─ execute Person················· 60.58ms ██████▉
384
+ │ │ ╰─ hydrate Person················· 0.13ms 2 rows ▏
385
+ │ ├─ statement Person·················· 33.90ms 1 rows ███▉
386
+ │ │ ├─ execute Person················· 33.35ms ███▊
387
+ │ │ ╰─ hydrate Person················· 0.08ms 1 rows ▏
388
+ │ ├─ statement Person·················· 35.36ms 1 rows ████
389
+ │ │ ├─ execute Person················· 34.92ms ████
390
+ │ │ ╰─ hydrate Person················· 0.05ms 1 rows ▏
391
+ │ ├─ statement Person·················· 60.02ms 2 rows ██████▉
392
+ │ │ ├─ execute Person················· 59.17ms ██████▊
393
+ │ │ ╰─ hydrate Person················· 0.14ms 2 rows ▏
394
+ │ ╰─ cache Person······················ 0.19ms 1 rows ▏
395
+ │ ╰─ hydrate Person················· 0.04ms 1 rows ▏
396
+ ```
397
+
398
+ Four reads at thirty to sixty milliseconds each, and the fifth — the `by_id`
399
+ the `find` had already filled — at **0.19ms**. `just flow` hangs DSQL's own
400
+ query plan under each read as well, which is where you find out that the slow
401
+ one was a scan.
402
+
403
+ ## Contributing
404
+
405
+ **Everything is in issues.** A finding becomes an issue, a decision becomes a
406
+ comment on one, and what a change did is in its pull request — there is no
407
+ design document and no notes file anywhere. Which means an obvious-sounding
408
+ proposal may be one that has already been argued down, so search the closed
409
+ issues before writing a new one.
410
+
411
+ The suite needs no configuration — `pytest-postgresql` starts a PostgreSQL and
412
+ throws it away — but it does want [`just`](https://just.systems) and
413
+ [`uv`](https://docs.astral.sh/uv/) on your machine:
414
+
415
+ ```bash
416
+ just test
417
+ ```
418
+
419
+ Run it that way rather than by hand. Both `--group test` and `--extra dsql`
420
+ have to be named, and a shorter command does not fail — `uv run pytest`
421
+ resolves a pytest that has never heard of dray and passes having run nothing.
422
+ `just --list` has the others: `just fresh` builds the environment from scratch
423
+ when a pass needs to be provably honest, and `just cluster` runs the half local
424
+ PostgreSQL cannot answer.
425
+
426
+ **Open an issue first, and wait for the decision in it to be settled.** Not as
427
+ a formality: `docs/manual.md` is written first, so a change to what a caller
428
+ can call is a change to that page and usually a decision as well. A pull
429
+ request that arrives without one is often work somebody has to turn down for a
430
+ reason that would have been two lines in a comment. An issue is welcome on its
431
+ own and obliges you to write nothing — a finding, reproduced, is worth as much
432
+ as a fix.
433
+
434
+ A pull request branches from `main` and is named for the change. Commit
435
+ subjects are a short declarative sentence in the present tense, and carry no
436
+ trailers — no `Co-Authored-By`, no tool or session links. The author field
437
+ already says, and this history will outlive every tool that touched it. Put
438
+ `Closes #N` in the body where the change finishes the issue.
439
+
440
+ The body carries the thinking, because the diff carries the change: before and
441
+ after as a handful of lines of real code, first and before any argument, then
442
+ what was wrong, the decisions you made that the issue did not settle, and what
443
+ you tested and deliberately did not. Tests come with the change rather than
444
+ after it, and are named for the behaviour rather than the function.
445
+
446
+ `docs/manual.md` is written first and the API follows it. If a change makes a
447
+ sentence on that page untrue, the sentence is part of the change.
448
+
449
+ [manual]: https://github.com/draylabs/dray/blob/main/docs/manual.md
450
+ [reference]: https://github.com/draylabs/dray/blob/main/docs/reference.html