sqlobjects 2.1.0__tar.gz → 2.2.0__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.
- {sqlobjects-2.1.0/sqlobjects.egg-info → sqlobjects-2.2.0}/PKG-INFO +9 -7
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/README.md +7 -5
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/docs/rules/01-database-session-guide.md +12 -4
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/docs/rules/03-query-operations-guide.md +14 -9
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/docs/rules/04-crud-operations-guide.md +1 -1
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/docs/rules/05-relationships-guide.md +11 -8
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/docs/rules/06-validation-signals-guide.md +15 -12
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/docs/rules/07-performance-guide.md +3 -3
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/pyproject.toml +8 -2
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/__init__.py +1 -1
- sqlobjects-2.2.0/sqlobjects/_compat.py +108 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/expressions/aggregate.py +6 -3
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/expressions/subquery.py +5 -23
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/fields/core.py +2 -2
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/metadata.py +5 -20
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/queries/builder.py +5 -1
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/queries/dialect.py +7 -2
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/queries/executor.py +5 -17
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/session.py +2 -1
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/sql_logging.py +9 -2
- {sqlobjects-2.1.0 → sqlobjects-2.2.0/sqlobjects.egg-info}/PKG-INFO +9 -7
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects.egg-info/SOURCES.txt +1 -1
- sqlobjects-2.2.0/sqlobjects.egg-info/requires.txt +4 -0
- sqlobjects-2.1.0/CHANGELOG.md +0 -314
- sqlobjects-2.1.0/sqlobjects.egg-info/requires.txt +0 -4
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/LICENSE +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/docs/rules/02-model-definition-guide.md +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/docs/rules/README.md +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/setup.cfg +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/_install_rules.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/cascade.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/contrib/__init__.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/contrib/asgi.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/contrib/fastapi.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/database/__init__.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/database/config.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/database/manager.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/exceptions.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/expressions/__init__.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/expressions/base.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/expressions/cte.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/expressions/explain.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/expressions/function.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/expressions/mixins.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/expressions/scalar.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/expressions/terminal.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/expressions/window.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/fields/__init__.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/fields/functions.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/fields/proxies.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/fields/relations/__init__.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/fields/relations/descriptors.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/fields/relations/managers.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/fields/relations/prefetch.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/fields/relations/strategies.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/fields/relations/utils.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/fields/shortcuts.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/fields/types/__init__.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/fields/types/base.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/fields/types/comparators.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/fields/types/registry.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/fields/utils.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/internal/__init__.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/internal/operations.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/internal/results.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/mixins.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/model.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/objects/__init__.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/objects/bulk.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/objects/core.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/objects/upsert.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/py.typed +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/queries/__init__.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/queryset.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/signals.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/utils/__init__.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/utils/inspect.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/utils/naming.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/utils/pattern.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/validators.py +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects.egg-info/dependency_links.txt +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects.egg-info/entry_points.txt +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects.egg-info/top_level.txt +0 -0
- {sqlobjects-2.1.0 → sqlobjects-2.2.0}/tests/test_config.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: sqlobjects
|
|
3
|
-
Version: 2.
|
|
3
|
+
Version: 2.2.0
|
|
4
4
|
Summary: Django-style async ORM library based on SQLAlchemy with chainable queries, Q objects, and relationship loading
|
|
5
5
|
Author-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>
|
|
6
6
|
Maintainer-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>
|
|
@@ -24,7 +24,7 @@ Classifier: Typing :: Typed
|
|
|
24
24
|
Requires-Python: >=3.12
|
|
25
25
|
Description-Content-Type: text/markdown
|
|
26
26
|
License-File: LICENSE
|
|
27
|
-
Requires-Dist: sqlalchemy[asyncio]
|
|
27
|
+
Requires-Dist: sqlalchemy[asyncio]<2.2,>=2.0.45
|
|
28
28
|
Provides-Extra: migrations
|
|
29
29
|
Requires-Dist: alembic>=1.16.5; extra == "migrations"
|
|
30
30
|
Dynamic: license-file
|
|
@@ -178,7 +178,7 @@ from sqlobjects.session import ctx_session, ctx_sessions
|
|
|
178
178
|
# Single database transaction
|
|
179
179
|
async with ctx_session() as session:
|
|
180
180
|
user = await User.objects.using(session).create(username="bob")
|
|
181
|
-
posts = await
|
|
181
|
+
posts = await Post.objects.using(session).filter(author_id=user.id).all()
|
|
182
182
|
# Automatic commit on success, rollback on error
|
|
183
183
|
|
|
184
184
|
# Multi-database transactions
|
|
@@ -302,10 +302,12 @@ avg_age = User.objects.aggregate(avg_age=func.avg(User.age)).subquery(query_type
|
|
|
302
302
|
older_users = await User.objects.filter(User.age > avg_age).all()
|
|
303
303
|
|
|
304
304
|
# Manual joins and locking
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
305
|
+
# Row locks need an explicit transaction on PostgreSQL/MySQL
|
|
306
|
+
async with ctx_session():
|
|
307
|
+
posts = await Post.objects.join(
|
|
308
|
+
User, # Using Model class (recommended)
|
|
309
|
+
Post.author_id == User.id
|
|
310
|
+
).select_for_update(nowait=True).all()
|
|
309
311
|
|
|
310
312
|
# Raw SQL when needed
|
|
311
313
|
users = await User.objects.raw(
|
|
@@ -147,7 +147,7 @@ from sqlobjects.session import ctx_session, ctx_sessions
|
|
|
147
147
|
# Single database transaction
|
|
148
148
|
async with ctx_session() as session:
|
|
149
149
|
user = await User.objects.using(session).create(username="bob")
|
|
150
|
-
posts = await
|
|
150
|
+
posts = await Post.objects.using(session).filter(author_id=user.id).all()
|
|
151
151
|
# Automatic commit on success, rollback on error
|
|
152
152
|
|
|
153
153
|
# Multi-database transactions
|
|
@@ -271,10 +271,12 @@ avg_age = User.objects.aggregate(avg_age=func.avg(User.age)).subquery(query_type
|
|
|
271
271
|
older_users = await User.objects.filter(User.age > avg_age).all()
|
|
272
272
|
|
|
273
273
|
# Manual joins and locking
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
274
|
+
# Row locks need an explicit transaction on PostgreSQL/MySQL
|
|
275
|
+
async with ctx_session():
|
|
276
|
+
posts = await Post.objects.join(
|
|
277
|
+
User, # Using Model class (recommended)
|
|
278
|
+
Post.author_id == User.id
|
|
279
|
+
).select_for_update(nowait=True).all()
|
|
278
280
|
|
|
279
281
|
# Raw SQL when needed
|
|
280
282
|
users = await User.objects.raw(
|
|
@@ -48,7 +48,7 @@ from sqlobjects.session import ctx_session, ctx_sessions
|
|
|
48
48
|
# Single database transaction
|
|
49
49
|
async with ctx_session() as session:
|
|
50
50
|
user = await User.objects.using(session).create(username="bob")
|
|
51
|
-
posts = await user.posts
|
|
51
|
+
posts = await user.load_relation("posts")
|
|
52
52
|
# Auto-commit on success, rollback on exception
|
|
53
53
|
|
|
54
54
|
# Multi-database transaction
|
|
@@ -114,6 +114,11 @@ if has_session("analytics"):
|
|
|
114
114
|
- `has_session()` reports only an open session usable by the current task.
|
|
115
115
|
- A closed session cannot be reused. Background work must open a new context.
|
|
116
116
|
- Cancellation rolls back request/context transactions and releases their connections.
|
|
117
|
+
- After an SQL error in an explicit transaction, call `rollback()` or wrap the
|
|
118
|
+
risky statement in `async with await session.begin_nested():`; otherwise later
|
|
119
|
+
statements raise `TransactionError`. Readonly sessions are unaffected by a failed
|
|
120
|
+
query. On an implicit (auto-commit) session the transaction opened by
|
|
121
|
+
`begin_nested()` commits when its outermost savepoint ends.
|
|
117
122
|
|
|
118
123
|
### ✅ Do
|
|
119
124
|
|
|
@@ -198,7 +203,7 @@ async with ctx_session() as session:
|
|
|
198
203
|
# All operations share the same connection
|
|
199
204
|
users = await User.objects.using(session).all()
|
|
200
205
|
for user in users:
|
|
201
|
-
await user.posts
|
|
206
|
+
await user.load_relation("posts") # Uses the loading session
|
|
202
207
|
```
|
|
203
208
|
|
|
204
209
|
### Read/Write Separation
|
|
@@ -414,10 +419,13 @@ skips timing and frame inspection; enabled logging resolves the user frame
|
|
|
414
419
|
across the async greenlet bridge.
|
|
415
420
|
|
|
416
421
|
Each record carries `sql`, driver-format `params`, `duration_ms`, `db_name`,
|
|
417
|
-
`dialect`, `executemany`, `rowcount`, `success`,
|
|
422
|
+
`dialect`, `executemany`, `rowcount`, `success`, `error_type`, and
|
|
423
|
+
`driver_error_type`. Parameters may
|
|
418
424
|
be a dictionary, tuple or a sequence of parameter sets. `hide_parameters=True`
|
|
419
425
|
in `init_db()` makes `params` null, including on failure; raw SQL literals are
|
|
420
|
-
not redacted. Errors include only
|
|
426
|
+
not redacted. Errors include only exception classes, not messages: `error_type` is the
|
|
427
|
+
SQLAlchemy class and is stable across drivers, `driver_error_type` is the
|
|
428
|
+
driver's own class and is not.
|
|
421
429
|
|
|
422
430
|
Records count driver calls, not ORM methods or returned rows. Timing excludes
|
|
423
431
|
pool checkout, compilation, later fetching, hydration and commit. `rowcount` can
|
|
@@ -314,17 +314,22 @@ posts = await Post.objects.outerjoin(
|
|
|
314
314
|
### Row Locking
|
|
315
315
|
|
|
316
316
|
```python
|
|
317
|
-
#
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
317
|
+
# Row locks require an explicit transaction on PostgreSQL/MySQL
|
|
318
|
+
async with ctx_session():
|
|
319
|
+
# Pessimistic locking (FOR UPDATE)
|
|
320
|
+
user = await User.objects.filter(
|
|
321
|
+
User.id == 1
|
|
322
|
+
).select_for_update(nowait=True).first()
|
|
323
|
+
|
|
324
|
+
# Shared locking (FOR SHARE)
|
|
325
|
+
users = await User.objects.filter(
|
|
326
|
+
User.department == "sales"
|
|
327
|
+
).select_for_share(skip_locked=True).all()
|
|
326
328
|
```
|
|
327
329
|
|
|
330
|
+
Outside SQLite, `select_for_update()` / `select_for_share()` must run inside an
|
|
331
|
+
explicit transaction; the lock is held until that transaction ends.
|
|
332
|
+
|
|
328
333
|
### Date/Time Extraction
|
|
329
334
|
|
|
330
335
|
```python
|
|
@@ -337,7 +337,7 @@ await User.objects.bulk_create(data, batch_size=100) # SQLite
|
|
|
337
337
|
async with ctx_session() as session:
|
|
338
338
|
# Quick database operations only
|
|
339
339
|
user = await User.objects.using(session).create(username="alice")
|
|
340
|
-
await
|
|
340
|
+
await Post.objects.using(session).create(title="Post", author_id=user.id)
|
|
341
341
|
# Transaction commits here
|
|
342
342
|
|
|
343
343
|
# Don't hold transactions during I/O
|
|
@@ -58,7 +58,7 @@ for post in posts:
|
|
|
58
58
|
# prefetch_related (separate query) - for reverse relationships
|
|
59
59
|
users = await User.objects.prefetch_related("posts").all()
|
|
60
60
|
for user in users:
|
|
61
|
-
posts = await user.posts
|
|
61
|
+
posts = await user.load_relation("posts") # Prefetched list, no query
|
|
62
62
|
|
|
63
63
|
# Combined loading
|
|
64
64
|
posts = await Post.objects.select_related("author").prefetch_related("comments").all()
|
|
@@ -162,7 +162,9 @@ users = await User.objects.prefetch_related(
|
|
|
162
162
|
### ❌ Don't
|
|
163
163
|
|
|
164
164
|
- **Don't use select_related** for reverse relationships (use prefetch_related)
|
|
165
|
-
- **Don't forget to
|
|
165
|
+
- **Don't forget to load** lazy relationships with `load_relation()`; after
|
|
166
|
+
`select_related`/`prefetch_related` the attribute is already an entity or list and
|
|
167
|
+
has no `.fetch()`
|
|
166
168
|
- **Don't cause N+1 queries** by not using loading strategies
|
|
167
169
|
- **Don't mix loading strategies** incorrectly
|
|
168
170
|
|
|
@@ -200,7 +202,7 @@ class Book(ObjectModel):
|
|
|
200
202
|
|
|
201
203
|
# Usage
|
|
202
204
|
author = await Author.objects.prefetch_related("books").get(Author.id == 1)
|
|
203
|
-
books = await author.books
|
|
205
|
+
books = await author.load_relation("books") # Prefetched list, no extra query
|
|
204
206
|
```
|
|
205
207
|
|
|
206
208
|
### One-to-One
|
|
@@ -233,7 +235,7 @@ class Course(ObjectModel):
|
|
|
233
235
|
|
|
234
236
|
# Usage
|
|
235
237
|
student = await Student.objects.prefetch_related("courses").get(Student.id == 1)
|
|
236
|
-
courses = await student.courses
|
|
238
|
+
courses = await student.load_relation("courses") # Prefetched list, no extra query
|
|
237
239
|
```
|
|
238
240
|
|
|
239
241
|
### Self-Referential
|
|
@@ -369,11 +371,11 @@ posts = await Post.objects.select_related("author").defer(
|
|
|
369
371
|
"author__bio" # Heavy field from related model
|
|
370
372
|
).all()
|
|
371
373
|
|
|
372
|
-
# Filter prefetched relationships
|
|
374
|
+
# Filter prefetched relationships (slicing the prefetch queryset is rejected)
|
|
373
375
|
users = await User.objects.prefetch_related(
|
|
374
376
|
posts=Post.objects.filter(
|
|
375
377
|
Post.created_at >= datetime.now(timezone.utc) - timedelta(days=7)
|
|
376
|
-
).order_by('-created_at')
|
|
378
|
+
).order_by('-created_at')
|
|
377
379
|
).all()
|
|
378
380
|
```
|
|
379
381
|
|
|
@@ -416,9 +418,10 @@ users = await User.objects.prefetch_related("posts").all()
|
|
|
416
418
|
|
|
417
419
|
**Solution**:
|
|
418
420
|
```python
|
|
419
|
-
# Use
|
|
421
|
+
# Use load_relation() for lazy relationships (works whether or not the
|
|
422
|
+
# relationship was eagerly loaded; .fetch() exists only on the lazy proxy)
|
|
420
423
|
post = await Post.objects.get(Post.id == 1)
|
|
421
|
-
author = await post.author
|
|
424
|
+
author = await post.load_relation("author") # Explicit load
|
|
422
425
|
|
|
423
426
|
# Or use select_related
|
|
424
427
|
post = await Post.objects.select_related("author").get(Post.id == 1)
|
|
@@ -233,7 +233,9 @@ async def before_save(self, context: SignalContext):
|
|
|
233
233
|
self.updated_at = datetime.now(timezone.utc) # Fast
|
|
234
234
|
|
|
235
235
|
async def after_save(self, context: SignalContext):
|
|
236
|
-
|
|
236
|
+
# after_* hooks run before the transaction commits; defer external side
|
|
237
|
+
# effects until the commit succeeds
|
|
238
|
+
await context.on_commit(self.process_large_file)
|
|
237
239
|
```
|
|
238
240
|
|
|
239
241
|
## Signal Execution Flow
|
|
@@ -323,22 +325,23 @@ class User(ObjectModel):
|
|
|
323
325
|
### Signal Performance
|
|
324
326
|
|
|
325
327
|
```python
|
|
326
|
-
#
|
|
328
|
+
# ORM writes that belong to the same transaction: await them sequentially.
|
|
329
|
+
# Hooks run inside the operation's session, which belongs to the current task;
|
|
330
|
+
# asyncio.create_task()/gather() would run them in other tasks and raise
|
|
331
|
+
# TransactionError.
|
|
327
332
|
async def after_create(self, context: SignalContext):
|
|
328
|
-
await
|
|
329
|
-
|
|
330
|
-
self.create_default_preferences(),
|
|
331
|
-
self.log_user_creation()
|
|
332
|
-
)
|
|
333
|
+
await self.create_default_preferences()
|
|
334
|
+
await self.log_user_creation()
|
|
333
335
|
|
|
334
|
-
#
|
|
336
|
+
# External side effects: defer until the transaction has committed.
|
|
337
|
+
# after_* hooks fire before commit, so a rollback would otherwise leave
|
|
338
|
+
# emails sent or indexes updated for data that never persisted.
|
|
335
339
|
async def after_save(self, context: SignalContext):
|
|
336
|
-
# Critical operations (blocking)
|
|
337
340
|
self.updated_at = datetime.now(timezone.utc)
|
|
338
|
-
|
|
339
|
-
# Non-critical operations (background)
|
|
341
|
+
|
|
340
342
|
if not context.is_bulk:
|
|
341
|
-
|
|
343
|
+
await context.on_commit(self.update_search_index)
|
|
344
|
+
await context.on_commit(self.send_welcome_email)
|
|
342
345
|
```
|
|
343
346
|
|
|
344
347
|
### Validation Performance
|
|
@@ -66,7 +66,7 @@ for post in posts:
|
|
|
66
66
|
# prefetch_related for reverse relationships (fast - 2 queries)
|
|
67
67
|
users = await User.objects.prefetch_related("posts").all()
|
|
68
68
|
for user in users:
|
|
69
|
-
posts = await user.posts
|
|
69
|
+
posts = await user.load_relation("posts") # Returns the prefetched list, no query
|
|
70
70
|
```
|
|
71
71
|
|
|
72
72
|
### Query Optimization
|
|
@@ -106,7 +106,7 @@ async with ctx_session() as session:
|
|
|
106
106
|
# All operations share the same connection
|
|
107
107
|
users = await User.objects.using(session).all()
|
|
108
108
|
for user in users:
|
|
109
|
-
await user.posts
|
|
109
|
+
await user.load_relation("posts") # Uses the loading session
|
|
110
110
|
```
|
|
111
111
|
|
|
112
112
|
## Best Practices
|
|
@@ -297,7 +297,7 @@ print(f"Query took {duration:.3f} seconds")
|
|
|
297
297
|
start = time.time()
|
|
298
298
|
posts = await Post.objects.all()
|
|
299
299
|
for post in posts[:10]:
|
|
300
|
-
author = await post.author
|
|
300
|
+
author = await post.load_relation("author")
|
|
301
301
|
time_without = time.time() - start
|
|
302
302
|
|
|
303
303
|
# With select_related
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "sqlobjects"
|
|
3
|
-
version = "2.
|
|
3
|
+
version = "2.2.0"
|
|
4
4
|
description = "Django-style async ORM library based on SQLAlchemy with chainable queries, Q objects, and relationship loading"
|
|
5
5
|
readme = "README.md"
|
|
6
6
|
license = "MIT"
|
|
@@ -34,7 +34,9 @@ classifiers = [
|
|
|
34
34
|
]
|
|
35
35
|
requires-python = ">=3.12"
|
|
36
36
|
dependencies = [
|
|
37
|
-
|
|
37
|
+
# 2.0.45 is the first release that emits FOR SHARE on MySQL 8; before it,
|
|
38
|
+
# select_for_share(nowait/skip_locked) is a syntax error there.
|
|
39
|
+
"sqlalchemy[asyncio]>=2.0.45,<2.2",
|
|
38
40
|
]
|
|
39
41
|
|
|
40
42
|
[project.optional-dependencies]
|
|
@@ -149,3 +151,7 @@ addopts = [
|
|
|
149
151
|
"--strict-markers",
|
|
150
152
|
"-v"
|
|
151
153
|
]
|
|
154
|
+
# A SQLAlchemy deprecation is the early warning for the next release series.
|
|
155
|
+
filterwarnings = [
|
|
156
|
+
"error::sqlalchemy.exc.SADeprecationWarning",
|
|
157
|
+
]
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
"""SQLAlchemy version compatibility helpers.
|
|
2
|
+
|
|
3
|
+
Everything that depends on SQLAlchemy internals differing between supported
|
|
4
|
+
release series lives here, so that an upgrade breaks in one tested place
|
|
5
|
+
instead of at import time in user code.
|
|
6
|
+
|
|
7
|
+
Supported series: 2.0 (>= 2.0.44) and 2.1.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from typing import Any
|
|
11
|
+
|
|
12
|
+
from sqlalchemy import ForeignKey, Index
|
|
13
|
+
from sqlalchemy.dialects.postgresql import ext as _postgresql_ext
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
# Added in 2.1 as the replacement for ``select.distinct(*columns)``; absent on 2.0.
|
|
17
|
+
_distinct_on: Any = getattr(_postgresql_ext, "distinct_on", None)
|
|
18
|
+
_DistinctOnClause: Any = getattr(_postgresql_ext, "DistinctOnClause", None)
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
__all__ = [
|
|
22
|
+
"apply_distinct_on",
|
|
23
|
+
"foreign_key_copy_target",
|
|
24
|
+
"foreign_key_target_tokens",
|
|
25
|
+
"has_distinct_on",
|
|
26
|
+
"index_has_ddl_if",
|
|
27
|
+
"retarget_foreign_key",
|
|
28
|
+
"select_has_for_update",
|
|
29
|
+
]
|
|
30
|
+
|
|
31
|
+
# SQLAlchemy 2.1 stores a name-based foreign key target as a
|
|
32
|
+
# ``ForeignKeyTarget(schema, table_name, column_name)`` tuple exposed through
|
|
33
|
+
# the public ``ForeignKey.target_tokens``; ``_colspec`` became a read-only
|
|
34
|
+
# legacy accessor. 2.0 stores the dotted string in a writable ``_colspec``.
|
|
35
|
+
_HAS_TARGET_TOKENS = hasattr(ForeignKey, "target_tokens")
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def foreign_key_target_tokens(fk: ForeignKey) -> tuple[str | None, str, str | None]:
|
|
39
|
+
"""Return the ``(schema, table_name, column_name)`` target of a foreign key."""
|
|
40
|
+
raw: Any = fk # version-specific attributes; see _HAS_TARGET_TOKENS
|
|
41
|
+
schema, table_name, column_name = raw.target_tokens if _HAS_TARGET_TOKENS else raw._column_tokens # noqa: SLF001
|
|
42
|
+
return schema, table_name, column_name
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def foreign_key_copy_target(fk: ForeignKey) -> Any:
|
|
46
|
+
"""Return a value that builds an equivalent ``ForeignKey`` when passed to its constructor.
|
|
47
|
+
|
|
48
|
+
A target given as a ``Column`` is returned as that column; a target given
|
|
49
|
+
by name is returned in the form the running SQLAlchemy version stores it,
|
|
50
|
+
so names containing dots survive the copy on 2.1.
|
|
51
|
+
"""
|
|
52
|
+
raw: Any = fk
|
|
53
|
+
if _HAS_TARGET_TOKENS:
|
|
54
|
+
column = raw.target_column
|
|
55
|
+
return raw.target_tokens if column is None else column
|
|
56
|
+
return raw._colspec # noqa: SLF001
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
def retarget_foreign_key(fk: ForeignKey, table_name: str) -> None:
|
|
60
|
+
"""Point a name-based foreign key at another table, keeping schema and column.
|
|
61
|
+
|
|
62
|
+
Used to replace a model class name with the model's actual table name once
|
|
63
|
+
the referenced model is registered. SQLAlchemy has no public API for
|
|
64
|
+
changing the target of an existing ``ForeignKey``, so this is the single
|
|
65
|
+
place allowed to rewrite its private state.
|
|
66
|
+
"""
|
|
67
|
+
raw: Any = fk
|
|
68
|
+
if _HAS_TARGET_TOKENS:
|
|
69
|
+
raw._given_tokens = raw.target_tokens._replace(table_name=table_name) # noqa: SLF001
|
|
70
|
+
else:
|
|
71
|
+
schema, _, column_name = raw._column_tokens # noqa: SLF001
|
|
72
|
+
prefix = f"{schema}." if schema else ""
|
|
73
|
+
raw._colspec = f"{prefix}{table_name}.{column_name}" # noqa: SLF001
|
|
74
|
+
# Memoized on 2.0; drop it so the new target is parsed again.
|
|
75
|
+
raw.__dict__.pop("_column_tokens", None)
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
def apply_distinct_on(query: Any, columns: list[Any]) -> Any:
|
|
79
|
+
"""Apply PostgreSQL ``DISTINCT ON (columns)`` to a SELECT.
|
|
80
|
+
|
|
81
|
+
2.1 deprecates ``select.distinct(*columns)`` in favour of the
|
|
82
|
+
``postgresql.distinct_on`` extension; 2.0 only has the former.
|
|
83
|
+
"""
|
|
84
|
+
if _distinct_on is not None:
|
|
85
|
+
return query.ext(_distinct_on(*columns))
|
|
86
|
+
return query.distinct(*columns)
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def has_distinct_on(element: Any) -> bool:
|
|
90
|
+
"""Whether a statement element is, or directly carries, a ``DISTINCT ON`` clause.
|
|
91
|
+
|
|
92
|
+
Covers both spellings: ``select.distinct(*columns)`` stores the columns on
|
|
93
|
+
the SELECT, the 2.1 extension is a separate element inside the statement.
|
|
94
|
+
Call it for every element of ``visitors.iterate(statement)``.
|
|
95
|
+
"""
|
|
96
|
+
if _DistinctOnClause is not None and isinstance(element, _DistinctOnClause):
|
|
97
|
+
return True
|
|
98
|
+
return bool(getattr(element, "_distinct_on", ()))
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def select_has_for_update(query: Any) -> bool:
|
|
102
|
+
"""Whether a SELECT was built with ``with_for_update()``; there is no public accessor."""
|
|
103
|
+
return getattr(query, "_for_update_arg", None) is not None
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
def index_has_ddl_if(index: Index) -> bool:
|
|
107
|
+
"""Whether an index has conditional DDL set through ``Index.ddl_if()``; there is no public accessor."""
|
|
108
|
+
return getattr(index, "_ddl_if", None) is not None
|
|
@@ -4,7 +4,7 @@ from typing import TYPE_CHECKING, Any
|
|
|
4
4
|
|
|
5
5
|
from sqlalchemy import false, select
|
|
6
6
|
from sqlalchemy.sql import visitors
|
|
7
|
-
from sqlalchemy.sql.elements import BindParameter, ColumnClause, ColumnElement
|
|
7
|
+
from sqlalchemy.sql.elements import BindParameter, ColumnClause, ColumnElement, False_, Null, True_
|
|
8
8
|
from sqlalchemy.sql.selectable import ScalarSelect
|
|
9
9
|
|
|
10
10
|
from ..exceptions import QueryError
|
|
@@ -14,6 +14,9 @@ from .base import QueryExpression
|
|
|
14
14
|
if TYPE_CHECKING:
|
|
15
15
|
from ..queries import QueryBuilder
|
|
16
16
|
|
|
17
|
+
# NULL, TRUE and FALSE: constants that are not bind parameters.
|
|
18
|
+
_SINGLETON_CONSTANTS = (Null, True_, False_)
|
|
19
|
+
|
|
17
20
|
|
|
18
21
|
class AggregateExpression(QueryExpression[dict[str, Any]]):
|
|
19
22
|
"""Aggregate matching rows, with one statement shared by all evaluation paths."""
|
|
@@ -64,7 +67,7 @@ class AggregateExpression(QueryExpression[dict[str, Any]]):
|
|
|
64
67
|
grouped
|
|
65
68
|
and isinstance(element, ColumnElement)
|
|
66
69
|
and not isinstance(element, BindParameter)
|
|
67
|
-
and not element
|
|
70
|
+
and not isinstance(element, _SINGLETON_CONSTANTS)
|
|
68
71
|
):
|
|
69
72
|
for key, alias in grouping_keys:
|
|
70
73
|
if element.compare(key):
|
|
@@ -147,7 +150,7 @@ class AggregateExpression(QueryExpression[dict[str, Any]]):
|
|
|
147
150
|
builder.annotations[alias] = expression
|
|
148
151
|
fields.append(alias)
|
|
149
152
|
grouping_keys.append((expression, alias))
|
|
150
|
-
if isinstance(expression, BindParameter)
|
|
153
|
+
if isinstance(expression, (BindParameter, *_SINGLETON_CONSTANTS)):
|
|
151
154
|
# MySQL interprets GROUP BY 1 as a select-list ordinal. Refer to
|
|
152
155
|
# the projected constant by alias to preserve one constant group.
|
|
153
156
|
builder.group_clauses[index] = alias
|
|
@@ -59,8 +59,8 @@ class SubqueryExpression(ColumnElement):
|
|
|
59
59
|
def _infer_type(self) -> str:
|
|
60
60
|
"""Automatically infer the appropriate subquery type based on query structure.
|
|
61
61
|
|
|
62
|
-
Analyzes query characteristics including column count
|
|
63
|
-
|
|
62
|
+
Analyzes query characteristics including column count and aggregate
|
|
63
|
+
functions to determine the most suitable subquery type.
|
|
64
64
|
|
|
65
65
|
Returns:
|
|
66
66
|
Inferred subquery type ('scalar', 'table', or 'exists')
|
|
@@ -68,23 +68,15 @@ class SubqueryExpression(ColumnElement):
|
|
|
68
68
|
try:
|
|
69
69
|
structure = self._analyze_query_structure()
|
|
70
70
|
|
|
71
|
-
# Rule 1:
|
|
72
|
-
if (
|
|
73
|
-
structure["has_single_column"]
|
|
74
|
-
and structure["has_aggregates"]
|
|
75
|
-
and (structure["has_limit_one"] or structure["is_count_query"])
|
|
76
|
-
):
|
|
77
|
-
return "scalar"
|
|
78
|
-
|
|
79
|
-
# Rule 2: Single column aggregate query (commonly used for comparisons)
|
|
71
|
+
# Rule 1: Single column aggregate query (commonly used for comparisons)
|
|
80
72
|
if structure["has_single_column"] and structure["has_aggregates"]:
|
|
81
73
|
return "scalar"
|
|
82
74
|
|
|
83
|
-
# Rule
|
|
75
|
+
# Rule 2: Multi-column queries default to table subquery
|
|
84
76
|
if structure["column_count"] > 1:
|
|
85
77
|
return "table"
|
|
86
78
|
|
|
87
|
-
# Rule
|
|
79
|
+
# Rule 3: Single column non-aggregate query (e.g., ID lists)
|
|
88
80
|
if structure["has_single_column"] and not structure["has_aggregates"]:
|
|
89
81
|
return "table" # For IN conditions
|
|
90
82
|
|
|
@@ -109,10 +101,8 @@ class SubqueryExpression(ColumnElement):
|
|
|
109
101
|
"select_columns": [],
|
|
110
102
|
"has_aggregates": False,
|
|
111
103
|
"has_single_column": False,
|
|
112
|
-
"has_limit_one": False,
|
|
113
104
|
"has_annotations": False,
|
|
114
105
|
"column_count": 0,
|
|
115
|
-
"is_count_query": False,
|
|
116
106
|
}
|
|
117
107
|
|
|
118
108
|
try:
|
|
@@ -127,14 +117,6 @@ class SubqueryExpression(ColumnElement):
|
|
|
127
117
|
aggregate_keywords = ["count(", "sum(", "avg(", "max(", "min("]
|
|
128
118
|
analysis["has_aggregates"] = any(keyword in query_str for keyword in aggregate_keywords)
|
|
129
119
|
|
|
130
|
-
# Analyze LIMIT clause
|
|
131
|
-
analysis["has_limit_one"] = (
|
|
132
|
-
hasattr(self.query, "_limit") and self.query._limit is not None and self.query._limit == 1 # noqa
|
|
133
|
-
)
|
|
134
|
-
|
|
135
|
-
# Detect count queries
|
|
136
|
-
analysis["is_count_query"] = "count(" in query_str
|
|
137
|
-
|
|
138
120
|
except Exception: # noqa
|
|
139
121
|
# Return safe defaults when analysis fails
|
|
140
122
|
pass
|
|
@@ -10,6 +10,7 @@ from sqlalchemy.sql.elements import ColumnElement
|
|
|
10
10
|
|
|
11
11
|
from sqlobjects.fields.proxies import RelatedCollection, RelatedObject
|
|
12
12
|
|
|
13
|
+
from .._compat import foreign_key_copy_target
|
|
13
14
|
from ..cascade import OnDelete
|
|
14
15
|
from ..expressions.mixins import ColumnAttributeFunctionMixin
|
|
15
16
|
from .types import create_type_instance
|
|
@@ -514,9 +515,8 @@ class ColumnAttribute(ColumnAttributeFunctionMixin, Generic[T]):
|
|
|
514
515
|
foreign_keys = []
|
|
515
516
|
if self.__column__.foreign_keys:
|
|
516
517
|
for fk in self.__column__.foreign_keys:
|
|
517
|
-
# Use original string reference instead of column attribute
|
|
518
518
|
new_fk = ForeignKey(
|
|
519
|
-
fk
|
|
519
|
+
foreign_key_copy_target(fk),
|
|
520
520
|
name=fk.name,
|
|
521
521
|
onupdate=fk.onupdate,
|
|
522
522
|
ondelete=fk.ondelete,
|
|
@@ -8,6 +8,7 @@ from sqlalchemy import MetaData as SqlAlchemyMetaData
|
|
|
8
8
|
from sqlalchemy.exc import CompileError
|
|
9
9
|
from sqlalchemy.sql.elements import conv
|
|
10
10
|
|
|
11
|
+
from ._compat import foreign_key_target_tokens, index_has_ddl_if, retarget_foreign_key
|
|
11
12
|
from .fields import ColumnAttribute
|
|
12
13
|
from .fields.relations import M2MTable, RelationshipDescriptor, RelationshipResolver
|
|
13
14
|
from .fields.utils import get_column_from_field, is_field_definition
|
|
@@ -551,14 +552,6 @@ class ModelProcessor(type):
|
|
|
551
552
|
"""
|
|
552
553
|
from sqlalchemy import Table
|
|
553
554
|
|
|
554
|
-
# Collect fields with explicit indexes to avoid duplicates
|
|
555
|
-
indexed_fields = set()
|
|
556
|
-
for idx in config.indexes:
|
|
557
|
-
if hasattr(idx, "_columns"):
|
|
558
|
-
for col in idx._columns:
|
|
559
|
-
if isinstance(col, str):
|
|
560
|
-
indexed_fields.add(col.split(".")[-1])
|
|
561
|
-
|
|
562
555
|
# Collect column definitions and relationship fields
|
|
563
556
|
columns = []
|
|
564
557
|
relationships = {}
|
|
@@ -576,10 +569,6 @@ class ModelProcessor(type):
|
|
|
576
569
|
# Use create_table_column method to get independent Column instance
|
|
577
570
|
if hasattr(column_attr, "create_table_column"):
|
|
578
571
|
column = column_attr.create_table_column(name)
|
|
579
|
-
# Clear index attributes if field has explicit index
|
|
580
|
-
if name in indexed_fields:
|
|
581
|
-
column.index = False
|
|
582
|
-
column.unique = False
|
|
583
572
|
else:
|
|
584
573
|
# Fallback for non-ColumnAttribute fields
|
|
585
574
|
column = column_attr
|
|
@@ -656,7 +645,7 @@ class ModelProcessor(type):
|
|
|
656
645
|
for idx in list(table.indexes):
|
|
657
646
|
# Conditional DDL can produce different schemas per dialect or
|
|
658
647
|
# callback result. Keep it intact instead of evaluating callbacks.
|
|
659
|
-
if
|
|
648
|
+
if index_has_ddl_if(idx):
|
|
660
649
|
continue
|
|
661
650
|
try:
|
|
662
651
|
expressions, options = expression_sig(idx), dialect_sig(idx)
|
|
@@ -954,7 +943,7 @@ class ModelProcessor(type):
|
|
|
954
943
|
def _resolve_class_foreign_keys(mcs, registry):
|
|
955
944
|
"""延迟解析外键引用:优先按类名匹配,匹配不到则视为表名。
|
|
956
945
|
|
|
957
|
-
foreign_key("User.id") 传入时原样交给 SQLAlchemy
|
|
946
|
+
foreign_key("User.id") 传入时原样交给 SQLAlchemy(目标为 "User.id")。
|
|
958
947
|
每次新模型注册后,此方法遍历所有 FK:
|
|
959
948
|
1. 取出 info["_fk_ref"](即 "." 前的那段,如 "User")
|
|
960
949
|
2. 尝试在 registry 中按类名查找模型
|
|
@@ -975,13 +964,9 @@ class ModelProcessor(type):
|
|
|
975
964
|
continue
|
|
976
965
|
# Found matching model — rewrite _colspec to actual table name
|
|
977
966
|
actual_table = model.__table__.name
|
|
978
|
-
|
|
967
|
+
_, tname, _ = foreign_key_target_tokens(fk)
|
|
979
968
|
if tname != actual_table:
|
|
980
|
-
|
|
981
|
-
fk._colspec = f"{schema}.{actual_table}.{colname}"
|
|
982
|
-
else:
|
|
983
|
-
fk._colspec = f"{actual_table}.{colname}"
|
|
984
|
-
fk.__dict__.pop("_column_tokens", None)
|
|
969
|
+
retarget_foreign_key(fk, actual_table)
|
|
985
970
|
fk_info["_fk_resolved"] = True
|
|
986
971
|
|
|
987
972
|
@classmethod
|
|
@@ -11,6 +11,7 @@ from sqlalchemy import (
|
|
|
11
11
|
)
|
|
12
12
|
from sqlalchemy.sql.selectable import Subquery
|
|
13
13
|
|
|
14
|
+
from .._compat import apply_distinct_on
|
|
14
15
|
from ..exceptions import QueryError
|
|
15
16
|
|
|
16
17
|
|
|
@@ -517,7 +518,10 @@ class QueryBuilder:
|
|
|
517
518
|
unknown = [field for field in self.distinct_fields if field not in table.c]
|
|
518
519
|
if unknown:
|
|
519
520
|
raise QueryError(f"Unknown DISTINCT field(s): {unknown}")
|
|
520
|
-
|
|
521
|
+
if self.distinct_fields:
|
|
522
|
+
query = apply_distinct_on(query, [table.c[field] for field in self.distinct_fields])
|
|
523
|
+
else:
|
|
524
|
+
query = query.distinct()
|
|
521
525
|
|
|
522
526
|
# Apply annotations (values mode already selected the requested ones)
|
|
523
527
|
if self.annotations and values_fields is None:
|