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

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

@@ -5,6 +5,72 @@ 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
+
+- **Model Signals**: Django-style event system for model lifecycle
+  - `Signal` class for pre/post event handlers
+  - `AroundSignal` class for context manager-style wrapping signals with `yield`
+  - `pre_save` / `post_save` - Fired before/after `save()` operations
+  - `pre_update` / `post_update` - Fired before/after `update()` and `merge()` operations
+  - `pre_delete` / `post_delete` - Fired before/after `delete()` operations
+  - `around_save` / `around_update` / `around_delete` - Wrap operations for timing, logging, etc.
+  - `connect(model_class)` decorator for registering handlers
+  - `disconnect(handler, model_class)` for removing handlers
+  - `clear()` for removing all handlers
+  - `has_handlers()` for checking if handlers are registered
+
+- `post_save` signal includes `created` flag to distinguish new records
+- `pre_update` / `post_update` signals include `update_fields` list
+- New test file `tests/test_signals.py` with unit and e2e tests
+
+### Changed
+
+- `save()`, `update()`, `merge()`, `delete()` now emit signals when handlers are registered
+- Internal `_do_save()` method extracted from `save()` for signal integration
+
 ## [0.3.0] - 2026-02-05
 
 ### Added

surreal_orm_lite-0.5.0/PKG-INFO

@@ -0,0 +1,451 @@
+Metadata-Version: 2.4
+Name: surreal-orm-lite
+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
+Project-URL: Repository, https://github.com/EulogySnowfall/SurrealDB-ORM-lite.git
+Project-URL: Issues, https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues
+Project-URL: Changelog, https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/CHANGELOG.md
+Author-email: Yannick Croteau <croteau.yannick@gmail.com>
+License: # MIT License
+        
+        Copyright (c) 2024-2026 Yannick Croteau
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: async,database,orm,pydantic,surrealdb
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pydantic :: 2
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: surrealdb>=1.0.8
+Description-Content-Type: text/markdown
+
+# Surreal ORM Lite
+
+![Python](https://img.shields.io/badge/python-3.11%2B-blue)
+![SurrealDB](https://img.shields.io/badge/SurrealDB-2.6.0-purple)
+![SDK](https://img.shields.io/badge/SDK-Official%201.0.8-green)
+![License](https://img.shields.io/badge/license-MIT-blue)
+[![codecov](https://codecov.io/gh/EulogySnowfall/SurrealDB-ORM-lite/graph/badge.svg)](https://codecov.io/gh/EulogySnowfall/SurrealDB-ORM-lite)
+
+**Surreal ORM Lite** is a lightweight, Django-style ORM for [SurrealDB](https://surrealdb.com/) that uses the **official SurrealDB Python SDK**. It provides a simple and intuitive interface for database operations with full async support and Pydantic validation.
+
+## Why This Project?
+
+This ORM is designed to:
+
+- Use the **official SurrealDB SDK** (`surrealdb>=1.0.8`) for maximum compatibility
+- Stay **lightweight** with minimal dependencies
+- Keep **up-to-date** with SurrealDB and SDK releases
+- Provide **Django-style** query syntax that developers love
+
+---
+
+## Requirements
+
+| Dependency   | Version          |
+| ------------ | ---------------- |
+| Python       | 3.11+            |
+| SurrealDB    | 2.6.0+           |
+| Official SDK | surrealdb>=1.0.8 |
+| Pydantic     | >=2.12.5         |
+
+---
+
+## Installation
+
+```bash
+pip install surreal-orm-lite
+```
+
+Or with uv:
+
+```bash
+uv add surreal-orm-lite
+```
+
+---
+
+## Quick Start
+
+### 1. Configure the Connection
+
+```python
+from surreal_orm_lite import SurrealDBConnectionManager
+
+SurrealDBConnectionManager.set_connection(
+    url="http://localhost:8000",
+    user="root",
+    password="root",
+    namespace="my_namespace",
+    database="my_database",
+)
+```
+
+### 2. Define a Model
+
+```python
+from surreal_orm_lite import BaseSurrealModel
+from pydantic import Field
+
+class User(BaseSurrealModel):
+    id: str | None = None
+    name: str = Field(..., max_length=100)
+    email: str
+    age: int = Field(..., ge=0)
+```
+
+### 3. CRUD Operations
+
+```python
+# Create
+user = User(name="Alice", email="alice@example.com", age=30)
+await user.save()
+
+# Read
+user = await User.objects().get("alice_id")
+users = await User.objects().filter(age__gte=18).exec()
+
+# Update
+user.age = 31
+await user.update()
+
+# Or partial update
+await user.merge(age=31)
+
+# Delete
+await user.delete()
+```
+
+### 4. QuerySet Methods
+
+```python
+# Filter with Django-style lookups
+users = await User.objects().filter(
+    age__gte=18,
+    name__startswith="A"
+).exec()
+
+# Ordering (with -field shorthand for DESC)
+users = await User.objects().order_by("name").exec()
+users = await User.objects().order_by("-age", "name").exec()
+
+# Pagination
+users = await User.objects().limit(10).offset(20).exec()
+
+# Select specific fields
+results = await User.objects().select("name", "email").exec()
+
+# Get first result
+user = await User.objects().filter(name="Alice").first()
+
+# Get all records
+all_users = await User.objects().all()
+
+# Custom query
+results = await User.objects().query(
+    "SELECT * FROM User WHERE age > $min_age",
+    {"min_age": 21}
+)
+```
+
+---
+
+## 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          | ✅     |
+| Raw SurrealQL queries  | ✅     |
+| Q Objects (OR/AND/NOT) | ✅     |
+| Parameterized filters  | ✅     |
+| Bulk operations        | ✅     |
+| `-field` ordering      | ✅     |
+
+### Supported Filter Lookups
+
+- `exact` (default)
+- `gt`, `gte`, `lt`, `lte`
+- `in`, `not_in`
+- `contains`, `icontains`, `not_contains`
+- `containsall`, `containsany`
+- `startswith`, `istartswith`
+- `endswith`, `iendswith`
+- `like`, `ilike`
+- `match`, `regex`, `iregex`
+- `isnull`
+
+### 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
+
+# Simple aggregations
+count = await User.objects().count()
+total = await Order.objects().sum("amount")
+avg_age = await User.objects().avg("age")
+max_price = await Product.objects().max("price")
+min_price = await Product.objects().min("price")
+
+# Check existence
+has_admins = await User.objects().filter(role="admin").exists()
+
+# GROUP BY with annotations
+results = await User.objects().values("status").annotate(count=Count()).exec()
+# [{"status": "active", "count": 42}, {"status": "inactive", "count": 8}]
+
+# Raw SurrealQL queries
+results = await User.raw_query(
+    "SELECT * FROM User WHERE age > $min_age",
+    variables={"min_age": 18}
+)
+```
+
+### 8. Model Signals
+
+```python
+from surreal_orm_lite import pre_save, post_save, pre_delete, post_delete
+
+@post_save.connect(User)
+async def on_user_saved(sender, instance, created, **kwargs):
+    """Called after every User save."""
+    if created:
+        await send_welcome_email(instance.email)
+    await invalidate_cache(f"user:{instance.id}")
+
+@pre_delete.connect(User)
+async def on_user_deleting(sender, instance, **kwargs):
+    """Called before User deletion."""
+    await archive_user_data(instance.id)
+```
+
+**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()`            |                 |
+
+**Around signals** use async generators to wrap operations:
+
+```python
+from surreal_orm_lite import around_save
+
+@around_save.connect(User)
+async def time_user_save(sender, instance, **kwargs):
+    import time
+    start = time.time()
+    yield  # save() executes here
+    duration = time.time() - start
+    print(f"Save took {duration:.3f}s")
+```
+
+---
+
+## Configuration Options
+
+### Custom Primary Key
+
+```python
+from surreal_orm_lite import BaseSurrealModel, SurrealConfigDict
+
+class Product(BaseSurrealModel):
+    model_config = SurrealConfigDict(primary_key="sku")
+
+    sku: str
+    name: str
+    price: float
+```
+
+### Context Manager
+
+```python
+async with SurrealDBConnectionManager():
+    users = await User.objects().all()
+# Connection automatically closed
+```
+
+---
+
+## Compatibility
+
+This ORM is tested and compatible with:
+
+| SurrealDB Version | SDK Version | Status        |
+| ----------------- | ----------- | ------------- |
+| 2.6.0             | 1.0.8       | ✅ Tested     |
+| 2.5.x             | 1.0.8       | ✅ Compatible |
+
+---
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m "Add amazing feature"`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+---
+
+## Roadmap
+
+| 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  |
+
+See [docs/ROADMAP.md](docs/ROADMAP.md) for full details.
+
+---
+
+## 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/)
+
+---
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+---
+
+## Author
+
+**Yannick Croteau**
+GitHub: [@EulogySnowfall](https://github.com/EulogySnowfall)
+
+---
+
+## Related Projects
+
+- [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