surreal-orm-lite 0.4.0__tar.gz → 0.5.0__tar.gz

{surreal_orm_lite-0.4.0 → surreal_orm_lite-0.5.0}/CHANGELOG.md

@@ -5,6 +5,47 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-02-11
+
+### Added
+
+- **Q Objects**: Django-style composable query expressions for complex filters
+  - `Q(field=value)` for basic conditions
+  - `Q(...) | Q(...)` for OR queries
+  - `Q(...) & Q(...)` for AND queries
+  - `~Q(...)` for NOT queries
+  - Nested combinations: `Q(age__gte=18) & (Q(role="admin") | Q(role="mod"))`
+
+- **Parameterized Filters**: All filter values now use parameterized variables (`$_fN`) instead of string interpolation, preventing SQL injection
+
+- **New Lookup Operators**:
+  - `not_in` - NOT IN operator
+  - `not_contains` - CONTAINSNOT operator
+  - `containsall` - CONTAINSALL operator
+  - `containsany` - CONTAINSANY operator
+
+- **`-field` Ordering Shorthand**: Prefix field with `-` for descending order
+  - `order_by("-created_at")` instead of `order_by("created_at", OrderBy.DESC)`
+  - Multi-field ordering: `order_by("-age", "name")`
+
+- **Bulk Operations**:
+  - `bulk_create(models)` - Create multiple records via SDK's `insert()`
+  - `bulk_update(**kwargs)` - Update all matching records with parameterized SET clause
+  - `bulk_delete()` - Delete all matching records, returns count
+
+- New `Q` class exported from `surreal_orm_lite`
+- New test file `tests/test_v050.py` for all v0.5.0 features
+
+### Changed
+
+- `_compile_query()`, `_compile_aggregation_query()`, `_compile_group_by_query()` now return `tuple[str, dict]` with parameterized variables
+- `_execute_query()` now accepts optional `variables` parameter
+- `filter()` now accepts `*args: Q` positional arguments alongside keyword filters
+- `order_by()` now accepts multiple fields with `-field` prefix support
+- `_build_where()` replaces `_build_where_clauses()` and returns parameterized WHERE clause
+- Shared `parse_lookup()` and `build_filter_condition()` functions moved to `utils.py`
+- Fixed `isnull` lookup: now correctly generates `IS NULL`/`IS NOT NULL`
+
 ## [0.4.0] - 2026-02-07
 
 ### Added

{surreal_orm_lite-0.4.0 → surreal_orm_lite-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: surreal-orm-lite
-Version: 0.4.0
+Version: 0.5.0
 Summary: Lightweight Django-style ORM for SurrealDB using the official Python SDK. Async support with Pydantic validation.
 Project-URL: Homepage, https://github.com/EulogySnowfall/SurrealDB-ORM-lite
 Project-URL: Documentation, https://github.com/EulogySnowfall/SurrealDB-ORM-lite
@@ -31,7 +31,7 @@ License: # MIT License
         SOFTWARE.
 License-File: LICENSE
 Keywords: async,database,orm,pydantic,surrealdb
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 3 - Alpha
 Classifier: Framework :: Pydantic :: 2
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
@@ -154,9 +154,9 @@ users = await User.objects().filter(
     name__startswith="A"
 ).exec()
 
-# Ordering
+# Ordering (with -field shorthand for DESC)
 users = await User.objects().order_by("name").exec()
-users = await User.objects().order_by("age", OrderBy.DESC).exec()
+users = await User.objects().order_by("-age", "name").exec()
 
 # Pagination
 users = await User.objects().limit(10).offset(20).exec()
@@ -181,30 +181,76 @@ results = await User.objects().query(
 
 ## Features
 
-| Feature               | Status |
-| --------------------- | ------ |
-| Async/await support   | ✅     |
-| Pydantic validation   | ✅     |
-| CRUD operations       | ✅     |
-| QuerySet with filters | ✅     |
-| Django-style lookups  | ✅     |
-| Custom primary keys   | ✅     |
-| HTTP connections      | ✅     |
-| WebSocket connections | ✅     |
-| Aggregations          | ✅     |
-| GROUP BY              | ✅     |
-| Model Signals         | ✅     |
+| Feature                | Status |
+| ---------------------- | ------ |
+| Async/await support    | ✅     |
+| Pydantic validation    | ✅     |
+| CRUD operations        | ✅     |
+| QuerySet with filters  | ✅     |
+| Django-style lookups   | ✅     |
+| Custom primary keys    | ✅     |
+| HTTP connections       | ✅     |
+| WebSocket connections  | ✅     |
+| Aggregations           | ✅     |
+| GROUP BY               | ✅     |
+| Model Signals          | ✅     |
+| Raw SurrealQL queries  | ✅     |
+| Q Objects (OR/AND/NOT) | ✅     |
+| Parameterized filters  | ✅     |
+| Bulk operations        | ✅     |
+| `-field` ordering      | ✅     |
 
 ### Supported Filter Lookups
 
 - `exact` (default)
 - `gt`, `gte`, `lt`, `lte`
-- `in`
-- `contains`, `icontains`
+- `in`, `not_in`
+- `contains`, `icontains`, `not_contains`
+- `containsall`, `containsany`
 - `startswith`, `istartswith`
 - `endswith`, `iendswith`
+- `like`, `ilike`
+- `match`, `regex`, `iregex`
+- `isnull`
 
-### 5. Aggregations
+### 5. Q Objects (Complex Queries)
+
+```python
+from surreal_orm_lite import Q
+
+# OR queries
+users = await User.objects().filter(Q(name="Alice") | Q(name="Bob")).exec()
+
+# NOT queries
+active = await User.objects().filter(~Q(status="banned")).exec()
+
+# Complex combinations
+results = await User.objects().filter(
+    Q(age__gte=18) & (Q(role="admin") | Q(role="mod"))
+).exec()
+
+# Mix Q objects with keyword filters
+results = await User.objects().filter(
+    Q(role="admin") | Q(role="mod"),
+    age__gte=25
+).exec()
+```
+
+### 6. Bulk Operations
+
+```python
+# Bulk create
+users = [User(name="Alice", age=30), User(name="Bob", age=25)]
+created = await User.objects().bulk_create(users)
+
+# Bulk update (returns count of updated records)
+count = await User.objects().filter(status="pending").bulk_update(status="active")
+
+# Bulk delete (returns count of deleted records)
+count = await User.objects().filter(status="inactive").bulk_delete()
+```
+
+### 7. Aggregations
 
 ```python
 from surreal_orm_lite import Count, Sum, Avg, Min, Max
@@ -230,7 +276,7 @@ results = await User.raw_query(
 )
 ```
 
-### 6. Model Signals
+### 8. Model Signals
 
 ```python
 from surreal_orm_lite import pre_save, post_save, pre_delete, post_delete
@@ -250,17 +296,17 @@ async def on_user_deleting(sender, instance, **kwargs):
 
 **Available signals:**
 
-| Signal          | When                        | Extra kwargs     |
-| --------------- | --------------------------- | ---------------- |
-| `pre_save`      | Before `save()`             |                  |
-| `post_save`     | After `save()`              | `created`        |
-| `pre_update`    | Before `update()`/`merge()` | `update_fields`  |
-| `post_update`   | After `update()`/`merge()`  | `update_fields`  |
-| `pre_delete`    | Before `delete()`           |                  |
-| `post_delete`   | After `delete()`            |                  |
-| `around_save`   | Wraps `save()`              |                  |
-| `around_update` | Wraps `update()`/`merge()`  | `update_fields`  |
-| `around_delete` | Wraps `delete()`            |                  |
+| Signal          | When                        | Extra kwargs    |
+| --------------- | --------------------------- | --------------- |
+| `pre_save`      | Before `save()`             |                 |
+| `post_save`     | After `save()`              | `created`       |
+| `pre_update`    | Before `update()`/`merge()` | `update_fields` |
+| `post_update`   | After `update()`/`merge()`  | `update_fields` |
+| `pre_delete`    | Before `delete()`           |                 |
+| `post_delete`   | After `delete()`            |                 |
+| `around_save`   | Wraps `save()`              |                 |
+| `around_update` | Wraps `update()`/`merge()`  | `update_fields` |
+| `around_delete` | Wraps `delete()`            |                 |
 
 **Around signals** use async generators to wrap operations:
 
@@ -326,16 +372,62 @@ Contributions are welcome! Please:
 
 ---
 
-## Advanced Features?
+## Roadmap
 
-This project prioritizes **stability and compatibility** with the official SurrealDB Python SDK. Due to current SDK limitations, some advanced features cannot be implemented here.
+| Version | Theme                         | Status      |
+| ------- | ----------------------------- | ----------- |
+| v0.2.x  | Core ORM (CRUD, QuerySet)     | ✅ Released |
+| v0.3.0  | Aggregations & Utilities      | ✅ Released |
+| v0.4.0  | Model Signals                 | ✅ Released |
+| v0.5.0  | Bulk Operations & Q Objects   | ✅ Released |
+| v0.6.0  | Relations & Graph             | 📋 Next     |
+| v0.7.0  | Transactions ORM              | 📋 Planned  |
+| v0.8.0  | SurrealFunc & Computed Fields | 📋 Planned  |
+| v0.9.0  | Field Aliases & DX            | 📋 Planned  |
+| v1.0.0  | Production Ready              | 📋 Planned  |
 
-For a feature-rich ORM with relations, transactions, and more, see:
+See [docs/ROADMAP.md](docs/ROADMAP.md) for full details.
 
-- **GitHub**: [SurrealDB-ORM](https://github.com/EulogySnowfall/SurrealDB-ORM/)
-- **PyPI**: [surrealdb-orm](https://pypi.org/project/surrealdb-orm/)
+---
 
-When the official SDK supports additional features, they will be incorporated into this lite version.
+## SurrealDB-ORM-lite vs SurrealDB-ORM
+
+This project prioritizes **stability and compatibility** with the official SurrealDB Python SDK. The full [SurrealDB-ORM](https://github.com/EulogySnowfall/SurrealDB-ORM/) uses a custom SDK for advanced features.
+
+| Feature                   | ORM-lite (official SDK) | ORM (custom SDK) |
+| ------------------------- | ----------------------- | ---------------- |
+| CRUD & QuerySet           | ✅                      | ✅               |
+| Aggregations & GROUP BY   | ✅                      | ✅               |
+| Model Signals             | ✅                      | ✅               |
+| Bulk Operations           | ✅                      | ✅               |
+| Q Objects (OR/AND/NOT)    | ✅                      | ✅               |
+| Parameterized Filters     | ✅                      | ✅               |
+| Relations & Graph         | v0.6.0                  | ✅               |
+| FETCH clause              | v0.6.0                  | ✅               |
+| Transactions (tx=)        | v0.7.0                  | ✅               |
+| SurrealFunc & Computed    | v0.8.0                  | ✅               |
+| Field Aliases             | v0.9.0                  | ✅               |
+| Retry, Logging, Metrics   | v0.10.0                 | ✅               |
+| Live Models / CDC         | ❌                      | ✅               |
+| Vector / Full-Text Search | ❌                      | ✅               |
+| Hybrid Search (RRF)       | ❌                      | ✅               |
+| Migrations & CLI          | ❌                      | ✅               |
+| JWT Authentication        | ❌                      | ✅               |
+| Schema Introspection      | ❌                      | ✅               |
+| Connection Pool           | ❌                      | ✅               |
+| CBOR Protocol             | ❌                      | ✅               |
+| Subqueries & Query Cache  | ❌                      | ✅               |
+| Geospatial Fields         | ❌                      | ✅               |
+| DEFINE EVENT              | ❌                      | ✅               |
+| Test Fixtures & Factories | ❌                      | ✅               |
+| Atomic Array Operations   | ❌                      | ✅               |
+
+**Choose ORM-lite** if you want the official SDK, minimal dependencies, and core ORM features.
+
+**Choose ORM** if you need live queries, migrations, authentication, vector search, or advanced features.
+
+- **SurrealDB-ORM GitHub**: [github.com/EulogySnowfall/SurrealDB-ORM](https://github.com/EulogySnowfall/SurrealDB-ORM/)
+- **SurrealDB-ORM PyPI**: [surrealdb-orm](https://pypi.org/project/surrealdb-orm/)
 
 ---
 
@@ -356,3 +448,4 @@ GitHub: [@EulogySnowfall](https://github.com/EulogySnowfall)
 
 - [SurrealDB](https://surrealdb.com/) - The database
 - [surrealdb.py](https://github.com/surrealdb/surrealdb.py) - Official Python SDK
+- [SurrealDB-ORM](https://github.com/EulogySnowfall/SurrealDB-ORM/) - Full-featured ORM with custom SDK

{surreal_orm_lite-0.4.0 → surreal_orm_lite-0.5.0}/README.md

@@ -104,9 +104,9 @@ users = await User.objects().filter(
     name__startswith="A"
 ).exec()
 
-# Ordering
+# Ordering (with -field shorthand for DESC)
 users = await User.objects().order_by("name").exec()
-users = await User.objects().order_by("age", OrderBy.DESC).exec()
+users = await User.objects().order_by("-age", "name").exec()
 
 # Pagination
 users = await User.objects().limit(10).offset(20).exec()
@@ -131,30 +131,76 @@ results = await User.objects().query(
 
 ## Features
 
-| Feature               | Status |
-| --------------------- | ------ |
-| Async/await support   | ✅     |
-| Pydantic validation   | ✅     |
-| CRUD operations       | ✅     |
-| QuerySet with filters | ✅     |
-| Django-style lookups  | ✅     |
-| Custom primary keys   | ✅     |
-| HTTP connections      | ✅     |
-| WebSocket connections | ✅     |
-| Aggregations          | ✅     |
-| GROUP BY              | ✅     |
-| Model Signals         | ✅     |
+| Feature                | Status |
+| ---------------------- | ------ |
+| Async/await support    | ✅     |
+| Pydantic validation    | ✅     |
+| CRUD operations        | ✅     |
+| QuerySet with filters  | ✅     |
+| Django-style lookups   | ✅     |
+| Custom primary keys    | ✅     |
+| HTTP connections       | ✅     |
+| WebSocket connections  | ✅     |
+| Aggregations           | ✅     |
+| GROUP BY               | ✅     |
+| Model Signals          | ✅     |
+| Raw SurrealQL queries  | ✅     |
+| Q Objects (OR/AND/NOT) | ✅     |
+| Parameterized filters  | ✅     |
+| Bulk operations        | ✅     |
+| `-field` ordering      | ✅     |
 
 ### Supported Filter Lookups
 
 - `exact` (default)
 - `gt`, `gte`, `lt`, `lte`
-- `in`
-- `contains`, `icontains`
+- `in`, `not_in`
+- `contains`, `icontains`, `not_contains`
+- `containsall`, `containsany`
 - `startswith`, `istartswith`
 - `endswith`, `iendswith`
+- `like`, `ilike`
+- `match`, `regex`, `iregex`
+- `isnull`
 
-### 5. Aggregations
+### 5. Q Objects (Complex Queries)
+
+```python
+from surreal_orm_lite import Q
+
+# OR queries
+users = await User.objects().filter(Q(name="Alice") | Q(name="Bob")).exec()
+
+# NOT queries
+active = await User.objects().filter(~Q(status="banned")).exec()
+
+# Complex combinations
+results = await User.objects().filter(
+    Q(age__gte=18) & (Q(role="admin") | Q(role="mod"))
+).exec()
+
+# Mix Q objects with keyword filters
+results = await User.objects().filter(
+    Q(role="admin") | Q(role="mod"),
+    age__gte=25
+).exec()
+```
+
+### 6. Bulk Operations
+
+```python
+# Bulk create
+users = [User(name="Alice", age=30), User(name="Bob", age=25)]
+created = await User.objects().bulk_create(users)
+
+# Bulk update (returns count of updated records)
+count = await User.objects().filter(status="pending").bulk_update(status="active")
+
+# Bulk delete (returns count of deleted records)
+count = await User.objects().filter(status="inactive").bulk_delete()
+```
+
+### 7. Aggregations
 
 ```python
 from surreal_orm_lite import Count, Sum, Avg, Min, Max
@@ -180,7 +226,7 @@ results = await User.raw_query(
 )
 ```
 
-### 6. Model Signals
+### 8. Model Signals
 
 ```python
 from surreal_orm_lite import pre_save, post_save, pre_delete, post_delete
@@ -200,17 +246,17 @@ async def on_user_deleting(sender, instance, **kwargs):
 
 **Available signals:**
 
-| Signal          | When                        | Extra kwargs     |
-| --------------- | --------------------------- | ---------------- |
-| `pre_save`      | Before `save()`             |                  |
-| `post_save`     | After `save()`              | `created`        |
-| `pre_update`    | Before `update()`/`merge()` | `update_fields`  |
-| `post_update`   | After `update()`/`merge()`  | `update_fields`  |
-| `pre_delete`    | Before `delete()`           |                  |
-| `post_delete`   | After `delete()`            |                  |
-| `around_save`   | Wraps `save()`              |                  |
-| `around_update` | Wraps `update()`/`merge()`  | `update_fields`  |
-| `around_delete` | Wraps `delete()`            |                  |
+| Signal          | When                        | Extra kwargs    |
+| --------------- | --------------------------- | --------------- |
+| `pre_save`      | Before `save()`             |                 |
+| `post_save`     | After `save()`              | `created`       |
+| `pre_update`    | Before `update()`/`merge()` | `update_fields` |
+| `post_update`   | After `update()`/`merge()`  | `update_fields` |
+| `pre_delete`    | Before `delete()`           |                 |
+| `post_delete`   | After `delete()`            |                 |
+| `around_save`   | Wraps `save()`              |                 |
+| `around_update` | Wraps `update()`/`merge()`  | `update_fields` |
+| `around_delete` | Wraps `delete()`            |                 |
 
 **Around signals** use async generators to wrap operations:
 
@@ -276,16 +322,62 @@ Contributions are welcome! Please:
 
 ---
 
-## Advanced Features?
+## Roadmap
 
-This project prioritizes **stability and compatibility** with the official SurrealDB Python SDK. Due to current SDK limitations, some advanced features cannot be implemented here.
+| Version | Theme                         | Status      |
+| ------- | ----------------------------- | ----------- |
+| v0.2.x  | Core ORM (CRUD, QuerySet)     | ✅ Released |
+| v0.3.0  | Aggregations & Utilities      | ✅ Released |
+| v0.4.0  | Model Signals                 | ✅ Released |
+| v0.5.0  | Bulk Operations & Q Objects   | ✅ Released |
+| v0.6.0  | Relations & Graph             | 📋 Next     |
+| v0.7.0  | Transactions ORM              | 📋 Planned  |
+| v0.8.0  | SurrealFunc & Computed Fields | 📋 Planned  |
+| v0.9.0  | Field Aliases & DX            | 📋 Planned  |
+| v1.0.0  | Production Ready              | 📋 Planned  |
 
-For a feature-rich ORM with relations, transactions, and more, see:
+See [docs/ROADMAP.md](docs/ROADMAP.md) for full details.
 
-- **GitHub**: [SurrealDB-ORM](https://github.com/EulogySnowfall/SurrealDB-ORM/)
-- **PyPI**: [surrealdb-orm](https://pypi.org/project/surrealdb-orm/)
+---
 
-When the official SDK supports additional features, they will be incorporated into this lite version.
+## SurrealDB-ORM-lite vs SurrealDB-ORM
+
+This project prioritizes **stability and compatibility** with the official SurrealDB Python SDK. The full [SurrealDB-ORM](https://github.com/EulogySnowfall/SurrealDB-ORM/) uses a custom SDK for advanced features.
+
+| Feature                   | ORM-lite (official SDK) | ORM (custom SDK) |
+| ------------------------- | ----------------------- | ---------------- |
+| CRUD & QuerySet           | ✅                      | ✅               |
+| Aggregations & GROUP BY   | ✅                      | ✅               |
+| Model Signals             | ✅                      | ✅               |
+| Bulk Operations           | ✅                      | ✅               |
+| Q Objects (OR/AND/NOT)    | ✅                      | ✅               |
+| Parameterized Filters     | ✅                      | ✅               |
+| Relations & Graph         | v0.6.0                  | ✅               |
+| FETCH clause              | v0.6.0                  | ✅               |
+| Transactions (tx=)        | v0.7.0                  | ✅               |
+| SurrealFunc & Computed    | v0.8.0                  | ✅               |
+| Field Aliases             | v0.9.0                  | ✅               |
+| Retry, Logging, Metrics   | v0.10.0                 | ✅               |
+| Live Models / CDC         | ❌                      | ✅               |
+| Vector / Full-Text Search | ❌                      | ✅               |
+| Hybrid Search (RRF)       | ❌                      | ✅               |
+| Migrations & CLI          | ❌                      | ✅               |
+| JWT Authentication        | ❌                      | ✅               |
+| Schema Introspection      | ❌                      | ✅               |
+| Connection Pool           | ❌                      | ✅               |
+| CBOR Protocol             | ❌                      | ✅               |
+| Subqueries & Query Cache  | ❌                      | ✅               |
+| Geospatial Fields         | ❌                      | ✅               |
+| DEFINE EVENT              | ❌                      | ✅               |
+| Test Fixtures & Factories | ❌                      | ✅               |
+| Atomic Array Operations   | ❌                      | ✅               |
+
+**Choose ORM-lite** if you want the official SDK, minimal dependencies, and core ORM features.
+
+**Choose ORM** if you need live queries, migrations, authentication, vector search, or advanced features.
+
+- **SurrealDB-ORM GitHub**: [github.com/EulogySnowfall/SurrealDB-ORM](https://github.com/EulogySnowfall/SurrealDB-ORM/)
+- **SurrealDB-ORM PyPI**: [surrealdb-orm](https://pypi.org/project/surrealdb-orm/)
 
 ---
 
@@ -306,3 +398,4 @@ GitHub: [@EulogySnowfall](https://github.com/EulogySnowfall)
 
 - [SurrealDB](https://surrealdb.com/) - The database
 - [surrealdb.py](https://github.com/surrealdb/surrealdb.py) - Official Python SDK
+- [SurrealDB-ORM](https://github.com/EulogySnowfall/SurrealDB-ORM/) - Full-featured ORM with custom SDK

{surreal_orm_lite-0.4.0 → surreal_orm_lite-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "surreal-orm-lite"
-version = "0.4.0"
+version = "0.5.0"
 description = "Lightweight Django-style ORM for SurrealDB using the official Python SDK. Async support with Pydantic validation."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -10,7 +10,7 @@ authors = [
 ]
 keywords = ["surrealdb", "orm", "database", "async", "pydantic"]
 classifiers = [
-    "Development Status :: 4 - Beta",
+    "Development Status :: 3 - Alpha",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",

{surreal_orm_lite-0.4.0 → surreal_orm_lite-0.5.0}/src/surreal_orm_lite/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.4.0"
+__version__ = "0.5.0"
 
 from .aggregations import Aggregation, Avg, Count, Max, Min, Sum
 from .connection_manager import SurrealDBConnectionManager
@@ -11,6 +11,7 @@ from .exceptions import (
     SurrealORMError,
 )
 from .model_base import BaseSurrealModel, SurrealConfigDict
+from .q import Q
 from .query_set import QuerySet
 from .signals import (
     AroundSignal,
@@ -35,6 +36,7 @@ __all__ = [
     "SurrealConfigDict",
     # QuerySet
     "QuerySet",
+    "Q",
     "OrderBy",
     # Aggregations
     "Aggregation",

{surreal_orm_lite-0.4.0 → surreal_orm_lite-0.5.0}/src/surreal_orm_lite/constants.py

@@ -5,10 +5,14 @@ LOOKUP_OPERATORS = {
     "lt": "<",
     "lte": "<=",
     "in": "IN",
+    "not_in": "NOT IN",
     "like": "LIKE",
     "ilike": "ILIKE",
     "contains": "CONTAINS",
     "icontains": "CONTAINS",
+    "not_contains": "CONTAINSNOT",
+    "containsall": "CONTAINSALL",
+    "containsany": "CONTAINSANY",
     "startswith": "STARTSWITH",
     "istartswith": "STARTSWITH",
     "endswith": "ENDSWITH",

surreal_orm_lite-0.5.0/src/surreal_orm_lite/q.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .utils import build_filter_condition, parse_lookup
+
+
+class Q:
+    """
+    Composable query expression for building complex filters with OR, AND, and NOT operators.
+
+    Q objects can be combined using ``|`` (OR), ``&`` (AND), and ``~`` (NOT) operators
+    to create complex query filters that go beyond simple AND-joined kwargs.
+
+    Example::
+
+        # OR query
+        Q(name="alice") | Q(email__contains="alice")
+
+        # NOT query
+        ~Q(status="banned")
+
+        # Complex combination
+        Q(age__gte=18) & Q(age__lte=65) & (Q(role="admin") | Q(role="mod"))
+    """
+
+    AND = "AND"
+    OR = "OR"
+
+    def __init__(self, **kwargs: Any) -> None:
+        self.filters: dict[str, Any] = kwargs
+        self.children: list[Q] = []
+        self.connector: str = self.AND
+        self.negated: bool = False
+
+    def __or__(self, other: Q) -> Q:
+        if not isinstance(other, Q):
+            return NotImplemented
+        node = Q()
+        node.children = [self, other]
+        node.connector = self.OR
+        return node
+
+    def __and__(self, other: Q) -> Q:
+        if not isinstance(other, Q):
+            return NotImplemented
+        node = Q()
+        node.children = [self, other]
+        node.connector = self.AND
+        return node
+
+    def __invert__(self) -> Q:
+        clone = Q(**self.filters)
+        clone.children = list(self.children)
+        clone.connector = self.connector
+        clone.negated = not self.negated
+        return clone
+
+    def __repr__(self) -> str:
+        parts = []
+        if self.filters:
+            parts.append(f"filters={self.filters}")
+        if self.children:
+            parts.append(f"children={self.children}")
+        if self.connector != self.AND:
+            parts.append(f"connector={self.connector}")
+        if self.negated:
+            parts.append("negated=True")
+        return f"Q({', '.join(parts)})"
+
+    def to_sql(self, counter: int = 0) -> tuple[str, dict[str, Any], int]:
+        """
+        Generate a parameterized SQL WHERE fragment.
+
+        Args:
+            counter: The starting variable counter for unique naming.
+
+        Returns:
+            A tuple of (sql_fragment, variables_dict, next_counter).
+        """
+        all_parts: list[str] = []
+        all_variables: dict[str, Any] = {}
+
+        # Own filters (always AND-joined within a single Q)
+        if self.filters:
+            filter_parts: list[str] = []
+            for key, value in self.filters.items():
+                field, lookup = parse_lookup(key)
+                sql, vars_, counter = build_filter_condition(field, lookup, value, counter)
+                filter_parts.append(sql)
+                all_variables.update(vars_)
+            if len(filter_parts) == 1:
+                all_parts.append(filter_parts[0])
+            else:
+                all_parts.append(f"({' AND '.join(filter_parts)})")
+
+        # Child Q objects
+        for child in self.children:
+            sql, vars_, counter = child.to_sql(counter)
+            if sql:
+                all_parts.append(sql)
+                all_variables.update(vars_)
+
+        if not all_parts:
+            return "", {}, counter
+
+        result = all_parts[0] if len(all_parts) == 1 else f"({' {conn} '.join(all_parts)})".format(conn=self.connector)
+
+        if self.negated:
+            result = f"NOT ({result})"
+
+        return result, all_variables, counter