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