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.
Files changed (84) hide show
  1. {sqlobjects-2.1.0/sqlobjects.egg-info → sqlobjects-2.2.0}/PKG-INFO +9 -7
  2. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/README.md +7 -5
  3. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/docs/rules/01-database-session-guide.md +12 -4
  4. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/docs/rules/03-query-operations-guide.md +14 -9
  5. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/docs/rules/04-crud-operations-guide.md +1 -1
  6. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/docs/rules/05-relationships-guide.md +11 -8
  7. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/docs/rules/06-validation-signals-guide.md +15 -12
  8. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/docs/rules/07-performance-guide.md +3 -3
  9. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/pyproject.toml +8 -2
  10. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/__init__.py +1 -1
  11. sqlobjects-2.2.0/sqlobjects/_compat.py +108 -0
  12. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/expressions/aggregate.py +6 -3
  13. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/expressions/subquery.py +5 -23
  14. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/fields/core.py +2 -2
  15. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/metadata.py +5 -20
  16. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/queries/builder.py +5 -1
  17. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/queries/dialect.py +7 -2
  18. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/queries/executor.py +5 -17
  19. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/session.py +2 -1
  20. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/sql_logging.py +9 -2
  21. {sqlobjects-2.1.0 → sqlobjects-2.2.0/sqlobjects.egg-info}/PKG-INFO +9 -7
  22. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects.egg-info/SOURCES.txt +1 -1
  23. sqlobjects-2.2.0/sqlobjects.egg-info/requires.txt +4 -0
  24. sqlobjects-2.1.0/CHANGELOG.md +0 -314
  25. sqlobjects-2.1.0/sqlobjects.egg-info/requires.txt +0 -4
  26. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/LICENSE +0 -0
  27. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/docs/rules/02-model-definition-guide.md +0 -0
  28. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/docs/rules/README.md +0 -0
  29. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/setup.cfg +0 -0
  30. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/_install_rules.py +0 -0
  31. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/cascade.py +0 -0
  32. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/contrib/__init__.py +0 -0
  33. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/contrib/asgi.py +0 -0
  34. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/contrib/fastapi.py +0 -0
  35. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/database/__init__.py +0 -0
  36. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/database/config.py +0 -0
  37. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/database/manager.py +0 -0
  38. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/exceptions.py +0 -0
  39. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/expressions/__init__.py +0 -0
  40. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/expressions/base.py +0 -0
  41. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/expressions/cte.py +0 -0
  42. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/expressions/explain.py +0 -0
  43. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/expressions/function.py +0 -0
  44. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/expressions/mixins.py +0 -0
  45. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/expressions/scalar.py +0 -0
  46. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/expressions/terminal.py +0 -0
  47. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/expressions/window.py +0 -0
  48. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/fields/__init__.py +0 -0
  49. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/fields/functions.py +0 -0
  50. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/fields/proxies.py +0 -0
  51. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/fields/relations/__init__.py +0 -0
  52. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/fields/relations/descriptors.py +0 -0
  53. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/fields/relations/managers.py +0 -0
  54. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/fields/relations/prefetch.py +0 -0
  55. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/fields/relations/strategies.py +0 -0
  56. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/fields/relations/utils.py +0 -0
  57. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/fields/shortcuts.py +0 -0
  58. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/fields/types/__init__.py +0 -0
  59. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/fields/types/base.py +0 -0
  60. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/fields/types/comparators.py +0 -0
  61. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/fields/types/registry.py +0 -0
  62. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/fields/utils.py +0 -0
  63. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/internal/__init__.py +0 -0
  64. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/internal/operations.py +0 -0
  65. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/internal/results.py +0 -0
  66. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/mixins.py +0 -0
  67. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/model.py +0 -0
  68. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/objects/__init__.py +0 -0
  69. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/objects/bulk.py +0 -0
  70. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/objects/core.py +0 -0
  71. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/objects/upsert.py +0 -0
  72. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/py.typed +0 -0
  73. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/queries/__init__.py +0 -0
  74. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/queryset.py +0 -0
  75. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/signals.py +0 -0
  76. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/utils/__init__.py +0 -0
  77. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/utils/inspect.py +0 -0
  78. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/utils/naming.py +0 -0
  79. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/utils/pattern.py +0 -0
  80. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects/validators.py +0 -0
  81. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects.egg-info/dependency_links.txt +0 -0
  82. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects.egg-info/entry_points.txt +0 -0
  83. {sqlobjects-2.1.0 → sqlobjects-2.2.0}/sqlobjects.egg-info/top_level.txt +0 -0
  84. {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.1.0
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]>=2.0.44
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 user.posts.using(session).all()
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
- posts = await Post.objects.join(
306
- User, # Using Model class (recommended)
307
- Post.author_id == User.id
308
- ).select_for_update(nowait=True).all()
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 user.posts.using(session).all()
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
- posts = await Post.objects.join(
275
- User, # Using Model class (recommended)
276
- Post.author_id == User.id
277
- ).select_for_update(nowait=True).all()
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.using(session).all()
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.using(session).all()
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`, and `error_type`. Parameters may
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 the exception class, not its message.
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
- # Pessimistic locking (FOR UPDATE)
318
- user = await User.objects.filter(
319
- User.id == 1
320
- ).select_for_update(nowait=True).first()
321
-
322
- # Shared locking (FOR SHARE)
323
- users = await User.objects.filter(
324
- User.department == "sales"
325
- ).select_for_share(skip_locked=True).all()
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 user.posts.using(session).create(title="Post")
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.fetch() # No N+1 queries
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 fetch()** lazy-loaded relationships
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.fetch()
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.fetch()
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').limit(10)
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 fetch() for lazy-loaded relationships
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.fetch() # Explicit load
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
- asyncio.create_task(self.process_large_file()) # Background task
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
- # Group related operations
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 asyncio.gather(
329
- self.send_welcome_email(),
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
- # Background tasks for non-critical operations
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
- asyncio.create_task(self.update_search_index())
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.fetch() # No N+1 queries
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.using(session).all()
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.fetch()
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.1.0"
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
- "sqlalchemy[asyncio]>=2.0.44",
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
+ ]
@@ -19,7 +19,7 @@ from .queryset import Q, QuerySet
19
19
  from .sql_logging import ObjectLogger, get_caller_frame
20
20
 
21
21
 
22
- __version__ = "2.1.0"
22
+ __version__ = "2.2.0"
23
23
 
24
24
  __all__ = [
25
25
  # Core classes
@@ -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._is_singleton_constant
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) or expression._is_singleton_constant:
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, aggregate functions,
63
- and LIMIT clauses to determine the most suitable subquery type.
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: Clear scalar query characteristics
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 3: Multi-column queries default to table subquery
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 4: Single column non-aggregate query (e.g., ID lists)
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._colspec, # noqa # Use original string reference
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 getattr(idx, "_ddl_if", None) is not None:
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(_colspec="User.id")。
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
- schema, tname, colname = fk._column_tokens
967
+ _, tname, _ = foreign_key_target_tokens(fk)
979
968
  if tname != actual_table:
980
- if schema:
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
- query = query.distinct(*(table.c[field] for field in self.distinct_fields))
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: