sqlmodel-object-helpers 0.0.2__tar.gz → 0.0.4__tar.gz

sqlmodel_object_helpers-0.0.4/.gitignore

@@ -0,0 +1,34 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# MCP config (local)
+.mcp.json
+
+# OS
+Thumbs.db
+Desktop.ini
+.DS_Store

{sqlmodel_object_helpers-0.0.2 → sqlmodel_object_helpers-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlmodel-object-helpers
-Version: 0.0.2
+Version: 0.0.4
 Summary: Generic async query helpers for SQLModel: filtering, eager loading, pagination
 Project-URL: Homepage, https://github.com/itstandart/sqlmodel-object-helpers
 Project-URL: Repository, https://github.com/itstandart/sqlmodel-object-helpers
@@ -55,6 +55,8 @@ Generic async query helpers for [SQLModel](https://sqlmodel.tiangolo.com/): filt
 - **Relationship Safety Check** - `check_for_related_records` pre-deletion inspection of ONETOMANY dependencies
 - **Security Limits** - Configurable depth, list size, and pagination caps to prevent abuse
 - **Type Safety** - Full type annotations with PEP 695 generics and `py.typed` marker (PEP 561)
+- **Standalone Mode** - `configure()` + `import sqlmodel_object_helpers.standalone` for auto-session usage without DI
+- **Session Lifecycle Logging** - Transparent session open/commit/rollback logging with hex session IDs and timing
 
 ## Installation
 
@@ -62,13 +64,20 @@ Generic async query helpers for [SQLModel](https://sqlmodel.tiangolo.com/): filt
 pip install sqlmodel-object-helpers
 ```
 
-One import, everything through dot notation:
+Two usage modes:
 
 ```python
+# DI mode — caller provides session (FastAPI Depends, etc.)
 import sqlmodel_object_helpers as soh
 
 soh.get_object(session, ...)
 soh.add_object(session, ...)
+
+# Standalone mode — auto-creates session per call
+import sqlmodel_object_helpers.standalone as soh_sa
+
+soh_sa.get_object(User, pk={"id": 1})
+soh_sa.add_object(User(name="Alice"))
 ```
 
 ## Quick Start
@@ -109,6 +118,107 @@ async def example(session: AsyncSession):
     # page.data -> list[User], page.pagination.total -> int
 ```
 
+## Standalone Mode
+
+For projects that don't use FastAPI DI or need simple one-call-one-transaction semantics.
+
+> **Important:** The session factory **must** use `expire_on_commit=False`.
+> After each standalone call the session commits and closes — with the default `True`,
+> all attributes on returned objects would be expired and inaccessible (`DetachedInstanceError`).
+
+```python
+from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker
+import sqlmodel_object_helpers as soh
+import sqlmodel_object_helpers.standalone as soh_sa
+
+engine = create_async_engine("postgresql+asyncpg://...")
+async_session_factory = async_sessionmaker(engine, expire_on_commit=False)
+
+# 1. Configure the session factory once at startup
+soh.configure(async_session_factory)
+
+# 2. Use standalone wrappers — each call creates its own session and commits
+user = await soh_sa.get_object(User, pk={"id": 1})
+new_user = await soh_sa.add_object(User(name="Alice"))
+await soh_sa.delete_object(User, pk={"id": 5})
+
+# All 12 functions are available:
+# Queries:  get_object, get_objects, count_objects, exists_object, get_projection
+# Mutations: add_object, add_objects, update_object, update_objects,
+#            delete_object, delete_objects, check_for_related_records
+```
+
+Each standalone call creates a session, executes the operation, commits on success, and rolls back on error. No session parameter needed.
+
+### auto_session - multi-operation transactions
+
+When you need multiple operations in a single atomic transaction:
+
+```python
+import sqlmodel_object_helpers as soh
+
+async with soh.auto_session() as session:
+    billing = await soh.add_object(session, Billing(...))
+    payment = await soh.add_object(session, Payment(...))
+    # commit happens automatically on exit
+    # if any operation fails — ALL are rolled back
+```
+
+## Session Management
+
+### DI mode — `create_session_dependency()`
+
+For FastAPI projects with dependency injection:
+
+```python
+import sqlmodel_object_helpers as soh
+from typing import Annotated
+from fastapi import Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+
+get_session = soh.create_session_dependency(async_session_factory)
+DbSession = Annotated[AsyncSession, Depends(get_session)]
+
+@router.get("/users/{user_id}")
+async def get_user(user_id: int, session: DbSession):
+    return await soh.get_object(session, User, pk={"id": user_id})
+```
+
+One session per HTTP request. The dependency commits on success, rolls back on error.
+
+### Standalone mode — `configure()`
+
+For projects without DI or for scripts/CLI:
+
+```python
+import sqlmodel_object_helpers as soh
+
+soh.configure(async_session_factory)
+# Now standalone functions and auto_session() are available
+```
+
+### Session Lifecycle Logging
+
+All session operations are logged via `logging.getLogger("sqlmodel_object_helpers")`:
+
+```
+DEBUG  auto_session[1a2b3c4d] opened
+DEBUG  auto_session[1a2b3c4d] committed (0.015s)
+WARNING auto_session[1a2b3c4d] rollback (0.003s) — MutationError: ...
+```
+
+- **Hex session ID** (`1a2b3c4d`) correlates all log lines for the same session
+- **Prefix** distinguishes mode: `auto_session` (standalone/auto_session) vs `di_session` (DI dependency)
+- **Timing** shows elapsed time from session open to commit/rollback
+- **Level**: `DEBUG` for normal flow, `WARNING` for rollbacks and commit failures
+
+Enable with:
+
+```python
+import logging
+logging.getLogger("sqlmodel_object_helpers").setLevel(logging.DEBUG)
+```
+
 ## Configuration
 
 Override security limits at application startup:
@@ -127,6 +237,7 @@ soh.settings.max_filter_depth = 50
 | `max_load_depth` | `10` | Maximum depth of eager-loading chains |
 | `max_in_list_size` | `1000` | Maximum elements in an IN(...) list |
 | `max_per_page` | `500` | Maximum value for per_page in pagination |
+| `session_factory` | `None` | `async_sessionmaker` instance for standalone mode (set via `soh.configure()`) |
 
 ## Query Operations
 
@@ -194,13 +305,13 @@ users = await soh.get_objects(
 )
 
 # Time filtering
-from datetime import datetime
+from datetime import datetime, timezone
 
 recent = await soh.get_objects(
     session, User,
     time_filter=soh.TimeFilter(
-        created_after=datetime(2026, 1, 1),
-        created_before=datetime(2026, 2, 1),
+        created_after=datetime(2026, 1, 1, tzinfo=timezone.utc),
+        created_before=datetime(2026, 2, 1, tzinfo=timezone.utc),
     ),
 )
 ```
@@ -221,7 +332,7 @@ active = await soh.count_objects(session, User, filters={"is_active": {soh.Opera
 # With time filter
 recent = await soh.count_objects(
     session, User,
-    time_filter=soh.TimeFilter(created_after=datetime(2026, 1, 1)),
+    time_filter=soh.TimeFilter(created_after=datetime(2026, 1, 1, tzinfo=timezone.utc)),
 )
 ```
 
@@ -405,7 +516,7 @@ Used by `get_objects`. Nested dicts are auto-flattened via `flatten_filters`:
 | `Operator.ILIKE` | `ILIKE` | `{soh.Operator.ILIKE: "%test%"}` |
 | `Operator.BETWEEN` | `BETWEEN` | `{soh.Operator.BETWEEN: [1, 10]}` |
 | `Operator.IS` | `IS` | `{soh.Operator.IS: None}` |
-| `Operator.ISNOT` | `IS NOT` | `{soh.Operator.ISNOT: None}` |
+| `Operator.IS_NOT` | `IS NOT` | `{soh.Operator.IS_NOT: None}` |
 | `Operator.MATCH` | `MATCH` | `{soh.Operator.MATCH: "query"}` |
 | `"exists"` | `IS NOT NULL` / `.any()` | `{"exists": True}` |
 
@@ -483,6 +594,16 @@ result = await soh.get_objects(session, User, order_by=order)
 
 ## API Reference
 
+### Session Management
+
+- `soh.configure(factory)` -- Register `async_sessionmaker` for standalone mode
+- `soh.auto_session()` -- Async context manager: creates session, commits on success, rolls back on error
+- `soh.create_session_dependency(factory)` -- Create async generator for FastAPI `Depends`
+
+### Standalone Wrappers
+
+- `import sqlmodel_object_helpers.standalone as soh_sa` -- All 12 query/mutation functions without `session` parameter
+
 ### Settings
 
 - `soh.settings` -- Module-level `QueryHelperSettings` instance (mutable at runtime)
@@ -521,7 +642,7 @@ result = await soh.get_objects(session, User, order_by=order)
 ### Loaders
 
 - `soh.build_load_chain(model, path, ...)` -- Build loader option from string/list path
-- `soh.build_load_options(model, attrs)` -- Build single loader option chain
+- `soh.build_load_options(model, attrs, *, suspend_error=False)` -- Build single loader option chain
 
 ### Exceptions
 
@@ -539,6 +660,10 @@ result = await soh.get_objects(session, User, order_by=order)
 - `soh.LogicalFilter`
 - `soh.TimeFilter` -- `created_after`, `created_before`, `updated_after`, `updated_before` with half-open interval `[after, before)`
 
+### Datetime Types
+
+- `soh.UTCDatetime` -- `Annotated[datetime, AfterValidator]` that rejects naive datetimes and converts aware datetimes to UTC
+
 ### Pagination Types
 
 - `soh.Pagination` -- Request model (page, per\_page)

{sqlmodel_object_helpers-0.0.2 → sqlmodel_object_helpers-0.0.4}/README.md

@@ -21,6 +21,8 @@ Generic async query helpers for [SQLModel](https://sqlmodel.tiangolo.com/): filt
 - **Relationship Safety Check** - `check_for_related_records` pre-deletion inspection of ONETOMANY dependencies
 - **Security Limits** - Configurable depth, list size, and pagination caps to prevent abuse
 - **Type Safety** - Full type annotations with PEP 695 generics and `py.typed` marker (PEP 561)
+- **Standalone Mode** - `configure()` + `import sqlmodel_object_helpers.standalone` for auto-session usage without DI
+- **Session Lifecycle Logging** - Transparent session open/commit/rollback logging with hex session IDs and timing
 
 ## Installation
 
@@ -28,13 +30,20 @@ Generic async query helpers for [SQLModel](https://sqlmodel.tiangolo.com/): filt
 pip install sqlmodel-object-helpers
 ```
 
-One import, everything through dot notation:
+Two usage modes:
 
 ```python
+# DI mode — caller provides session (FastAPI Depends, etc.)
 import sqlmodel_object_helpers as soh
 
 soh.get_object(session, ...)
 soh.add_object(session, ...)
+
+# Standalone mode — auto-creates session per call
+import sqlmodel_object_helpers.standalone as soh_sa
+
+soh_sa.get_object(User, pk={"id": 1})
+soh_sa.add_object(User(name="Alice"))
 ```
 
 ## Quick Start
@@ -75,6 +84,107 @@ async def example(session: AsyncSession):
     # page.data -> list[User], page.pagination.total -> int
 ```
 
+## Standalone Mode
+
+For projects that don't use FastAPI DI or need simple one-call-one-transaction semantics.
+
+> **Important:** The session factory **must** use `expire_on_commit=False`.
+> After each standalone call the session commits and closes — with the default `True`,
+> all attributes on returned objects would be expired and inaccessible (`DetachedInstanceError`).
+
+```python
+from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker
+import sqlmodel_object_helpers as soh
+import sqlmodel_object_helpers.standalone as soh_sa
+
+engine = create_async_engine("postgresql+asyncpg://...")
+async_session_factory = async_sessionmaker(engine, expire_on_commit=False)
+
+# 1. Configure the session factory once at startup
+soh.configure(async_session_factory)
+
+# 2. Use standalone wrappers — each call creates its own session and commits
+user = await soh_sa.get_object(User, pk={"id": 1})
+new_user = await soh_sa.add_object(User(name="Alice"))
+await soh_sa.delete_object(User, pk={"id": 5})
+
+# All 12 functions are available:
+# Queries:  get_object, get_objects, count_objects, exists_object, get_projection
+# Mutations: add_object, add_objects, update_object, update_objects,
+#            delete_object, delete_objects, check_for_related_records
+```
+
+Each standalone call creates a session, executes the operation, commits on success, and rolls back on error. No session parameter needed.
+
+### auto_session - multi-operation transactions
+
+When you need multiple operations in a single atomic transaction:
+
+```python
+import sqlmodel_object_helpers as soh
+
+async with soh.auto_session() as session:
+    billing = await soh.add_object(session, Billing(...))
+    payment = await soh.add_object(session, Payment(...))
+    # commit happens automatically on exit
+    # if any operation fails — ALL are rolled back
+```
+
+## Session Management
+
+### DI mode — `create_session_dependency()`
+
+For FastAPI projects with dependency injection:
+
+```python
+import sqlmodel_object_helpers as soh
+from typing import Annotated
+from fastapi import Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+
+get_session = soh.create_session_dependency(async_session_factory)
+DbSession = Annotated[AsyncSession, Depends(get_session)]
+
+@router.get("/users/{user_id}")
+async def get_user(user_id: int, session: DbSession):
+    return await soh.get_object(session, User, pk={"id": user_id})
+```
+
+One session per HTTP request. The dependency commits on success, rolls back on error.
+
+### Standalone mode — `configure()`
+
+For projects without DI or for scripts/CLI:
+
+```python
+import sqlmodel_object_helpers as soh
+
+soh.configure(async_session_factory)
+# Now standalone functions and auto_session() are available
+```
+
+### Session Lifecycle Logging
+
+All session operations are logged via `logging.getLogger("sqlmodel_object_helpers")`:
+
+```
+DEBUG  auto_session[1a2b3c4d] opened
+DEBUG  auto_session[1a2b3c4d] committed (0.015s)
+WARNING auto_session[1a2b3c4d] rollback (0.003s) — MutationError: ...
+```
+
+- **Hex session ID** (`1a2b3c4d`) correlates all log lines for the same session
+- **Prefix** distinguishes mode: `auto_session` (standalone/auto_session) vs `di_session` (DI dependency)
+- **Timing** shows elapsed time from session open to commit/rollback
+- **Level**: `DEBUG` for normal flow, `WARNING` for rollbacks and commit failures
+
+Enable with:
+
+```python
+import logging
+logging.getLogger("sqlmodel_object_helpers").setLevel(logging.DEBUG)
+```
+
 ## Configuration
 
 Override security limits at application startup:
@@ -93,6 +203,7 @@ soh.settings.max_filter_depth = 50
 | `max_load_depth` | `10` | Maximum depth of eager-loading chains |
 | `max_in_list_size` | `1000` | Maximum elements in an IN(...) list |
 | `max_per_page` | `500` | Maximum value for per_page in pagination |
+| `session_factory` | `None` | `async_sessionmaker` instance for standalone mode (set via `soh.configure()`) |
 
 ## Query Operations
 
@@ -160,13 +271,13 @@ users = await soh.get_objects(
 )
 
 # Time filtering
-from datetime import datetime
+from datetime import datetime, timezone
 
 recent = await soh.get_objects(
     session, User,
     time_filter=soh.TimeFilter(
-        created_after=datetime(2026, 1, 1),
-        created_before=datetime(2026, 2, 1),
+        created_after=datetime(2026, 1, 1, tzinfo=timezone.utc),
+        created_before=datetime(2026, 2, 1, tzinfo=timezone.utc),
     ),
 )
 ```
@@ -187,7 +298,7 @@ active = await soh.count_objects(session, User, filters={"is_active": {soh.Opera
 # With time filter
 recent = await soh.count_objects(
     session, User,
-    time_filter=soh.TimeFilter(created_after=datetime(2026, 1, 1)),
+    time_filter=soh.TimeFilter(created_after=datetime(2026, 1, 1, tzinfo=timezone.utc)),
 )
 ```
 
@@ -371,7 +482,7 @@ Used by `get_objects`. Nested dicts are auto-flattened via `flatten_filters`:
 | `Operator.ILIKE` | `ILIKE` | `{soh.Operator.ILIKE: "%test%"}` |
 | `Operator.BETWEEN` | `BETWEEN` | `{soh.Operator.BETWEEN: [1, 10]}` |
 | `Operator.IS` | `IS` | `{soh.Operator.IS: None}` |
-| `Operator.ISNOT` | `IS NOT` | `{soh.Operator.ISNOT: None}` |
+| `Operator.IS_NOT` | `IS NOT` | `{soh.Operator.IS_NOT: None}` |
 | `Operator.MATCH` | `MATCH` | `{soh.Operator.MATCH: "query"}` |
 | `"exists"` | `IS NOT NULL` / `.any()` | `{"exists": True}` |
 
@@ -449,6 +560,16 @@ result = await soh.get_objects(session, User, order_by=order)
 
 ## API Reference
 
+### Session Management
+
+- `soh.configure(factory)` -- Register `async_sessionmaker` for standalone mode
+- `soh.auto_session()` -- Async context manager: creates session, commits on success, rolls back on error
+- `soh.create_session_dependency(factory)` -- Create async generator for FastAPI `Depends`
+
+### Standalone Wrappers
+
+- `import sqlmodel_object_helpers.standalone as soh_sa` -- All 12 query/mutation functions without `session` parameter
+
 ### Settings
 
 - `soh.settings` -- Module-level `QueryHelperSettings` instance (mutable at runtime)
@@ -487,7 +608,7 @@ result = await soh.get_objects(session, User, order_by=order)
 ### Loaders
 
 - `soh.build_load_chain(model, path, ...)` -- Build loader option from string/list path
-- `soh.build_load_options(model, attrs)` -- Build single loader option chain
+- `soh.build_load_options(model, attrs, *, suspend_error=False)` -- Build single loader option chain
 
 ### Exceptions
 
@@ -505,6 +626,10 @@ result = await soh.get_objects(session, User, order_by=order)
 - `soh.LogicalFilter`
 - `soh.TimeFilter` -- `created_after`, `created_before`, `updated_after`, `updated_before` with half-open interval `[after, before)`
 
+### Datetime Types
+
+- `soh.UTCDatetime` -- `Annotated[datetime, AfterValidator]` that rejects naive datetimes and converts aware datetimes to UTC
+
 ### Pagination Types
 
 - `soh.Pagination` -- Request model (page, per\_page)

{sqlmodel_object_helpers-0.0.2 → sqlmodel_object_helpers-0.0.4}/src/sqlmodel_object_helpers/__init__.py

@@ -1,6 +1,6 @@
 """sqlmodel-object-helpers — reusable query helpers for SQLModel projects."""
 
-__version__ = "0.0.2"
+__version__ = "0.0.4"
 
 from .constants import QueryHelperSettings, settings
 from .exceptions import (
@@ -24,13 +24,15 @@ from .mutations import (
     update_objects,
 )
 from .query import count_objects, exists_object, get_object, get_objects, get_projection
-from .session import create_session_dependency
+from .session import auto_session, configure, create_session_dependency
+from .types.datetime import UTCDatetime
 from .types.filters import (
     FilterBool,
     FilterDate,
     FilterDatetime,
     FilterExists,
     FilterInt,
+    FilterNaiveDatetime,
     FilterStr,
     FilterTimedelta,
     LogicalFilter,
@@ -47,59 +49,53 @@ from .types.pagination import (
 from .types.projections import ColumnSpec
 
 __all__ = [
-    # Settings
-    "settings",
-    "QueryHelperSettings",
-    # Query functions (read)
-    "get_object",
-    "get_objects",
-    "get_projection",
-    "count_objects",
-    "exists_object",
-    # Mutation functions (create / update / delete)
     "add_object",
     "add_objects",
-    "update_object",
-    "update_objects",
-    "delete_object",
-    "delete_objects",
-    "check_for_related_records",
-    # Filters
+    "auto_session",
     "build_filter",
     "build_flat_filter",
-    "flatten_filters",
-    "SUPPORTED_OPERATORS",
-    "SPECIAL_OPERATORS",
-    "Operator",
-    # Loaders
-    "build_load_options",
     "build_load_chain",
-    # Exceptions
-    "QueryError",
-    "ObjectNotFoundError",
-    "InvalidFilterError",
-    "InvalidLoadPathError",
+    "build_load_options",
+    "check_for_related_records",
+    "ColumnSpec",
+    "configure",
+    "count_objects",
+    "create_session_dependency",
     "DatabaseError",
-    "MutationError",
-    # Filter types
-    "FilterInt",
-    "FilterStr",
+    "delete_object",
+    "delete_objects",
+    "exists_object",
+    "FilterBool",
     "FilterDate",
     "FilterDatetime",
-    "FilterTimedelta",
-    "FilterBool",
     "FilterExists",
+    "FilterInt",
+    "FilterNaiveDatetime",
+    "FilterStr",
+    "FilterTimedelta",
+    "flatten_filters",
+    "get_object",
+    "get_objects",
+    "get_projection",
+    "GetAllPagination",
+    "InvalidFilterError",
+    "InvalidLoadPathError",
+    "LogicalFilter",
+    "MutationError",
+    "ObjectNotFoundError",
+    "Operator",
     "OrderAsc",
-    "OrderDesc",
     "OrderBy",
-    "LogicalFilter",
-    "TimeFilter",
-    # Pagination types
+    "OrderDesc",
     "Pagination",
     "PaginationR",
-    "GetAllPagination",
-    # Projection types
-    "ColumnSpec",
-    # Session
-    "create_session_dependency",
+    "QueryError",
+    "QueryHelperSettings",
+    "settings",
+    "SPECIAL_OPERATORS",
+    "SUPPORTED_OPERATORS",
+    "TimeFilter",
+    "update_object",
+    "update_objects",
+    "UTCDatetime",
 ]

{sqlmodel_object_helpers-0.0.2 → sqlmodel_object_helpers-0.0.4}/src/sqlmodel_object_helpers/constants.py

@@ -1,4 +1,5 @@
-"""Security and performance limits for query building.
+"""
+Security and performance limits for query building.
 
 All values have sensible defaults. Override at application startup:
 
@@ -7,11 +8,14 @@ All values have sensible defaults. Override at application startup:
     settings.max_filter_depth = 50
 """
 
+from typing import Any
+
 from pydantic import BaseModel
 
 
 class QueryHelperSettings(BaseModel):
-    """Mutable settings for query-helper limits.
+    """
+    Mutable settings for query-helper limits.
 
     Attributes:
         max_filter_depth: Maximum recursion depth for build_filter (AND/OR nesting).
@@ -22,6 +26,9 @@ class QueryHelperSettings(BaseModel):
             (e.g. "application.applicant.educations" = 3).
         max_in_list_size: Maximum number of elements in an IN(...) list.
         max_per_page: Maximum value for per_page in pagination.
+        session_factory: async_sessionmaker instance for standalone mode.
+            Set via ``soh.configure(factory)``.
+
     """
 
     max_filter_depth: int = 100
@@ -29,6 +36,7 @@ class QueryHelperSettings(BaseModel):
     max_load_depth: int = 10
     max_in_list_size: int = 1000
     max_per_page: int = 500
+    session_factory: Any = None
 
 
 settings = QueryHelperSettings()

{sqlmodel_object_helpers-0.0.2 → sqlmodel_object_helpers-0.0.4}/src/sqlmodel_object_helpers/exceptions.py

@@ -42,7 +42,8 @@ class DatabaseError(QueryError):
 
 
 class MutationError(QueryError):
-    """Raised when a create/update/delete operation fails.
+    """
+    Raised when a create/update/delete operation fails.
 
     Covers constraint violations, invalid field names in update data,
     and other mutation-specific errors.