sqlmodel-object-helpers 0.0.5__tar.gz → 0.0.6__tar.gz

{sqlmodel_object_helpers-0.0.5 → sqlmodel_object_helpers-0.0.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlmodel-object-helpers
-Version: 0.0.5
+Version: 0.0.6
 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,7 @@ 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)
+- **Dynamic Table Metadata** - `build_dynamic_meta` derives `TableMeta` + `list[ColumnMeta]` from a SQLModel class by reading PostgreSQL `pg_description` with fallback to `Column(comment=...)`. Supports per-role label/row_link overrides via `||` comment format, TTL-cached
 - **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
 
@@ -619,6 +620,117 @@ order = soh.OrderBy(sorts=[
 result = await soh.get_objects(session, User, order_by=order)
 ```
 
+## Dynamic Table Metadata
+
+`build_dynamic_meta` builds `TableMeta` + `list[ColumnMeta]` from a SQLModel class at runtime, reading PostgreSQL `pg_description` (TTL-cached) with fallback to `Column(comment=...)` model defaults.
+
+```python
+import sqlmodel_object_helpers as soh
+
+# Physical columns — label, type, lookup derived automatically
+table_meta, columns = await soh.build_dynamic_meta(
+    session,
+    EmailMessage,
+    name="email_messages",
+    columns=[
+        "id",                        # physical column — everything derived
+        "email_type_id",             # FK on *_lkp → lookup_dict auto-derived
+        "updated_at",
+        soh.ColumnMeta(              # virtual column — fully specified
+            json_path="last_editor.user_name",
+            label="Редактор",
+            type=soh.ColumnType.STRING,
+        ),
+    ],
+    role_type="operator",            # per-role label/row_link overrides
+)
+
+# Returns (TableMeta, list[ColumnMeta]) ready for GetAllPagination
+return soh.GetAllPagination(
+    table=table_meta,
+    columns=columns,
+    data=items,
+    pagination=pagination_r,
+)
+```
+
+### Type derivation (SA type → ColumnType)
+
+Physical column types are mapped automatically. Unknown types fall back to `string`.
+
+| SQLAlchemy type | ColumnType |
+|---|---|
+| `Boolean` | `boolean` |
+| `DateTime` | `datetime` |
+| `Date` | `date` |
+| `Integer`, `BigInteger`, `SmallInteger` | `integer` |
+| `Numeric`, `Float` | `float` |
+| `String`, `Text`, `Enum`, `Interval`, `ARRAY`, `Uuid` | `string` |
+| Any other type | `string` (fallback) |
+
+### Label precedence (per physical column)
+
+1. `pg_description` — DBA edit via `COMMENT ON COLUMN` (supports per-role `||` overrides)
+2. `Column(comment=...)` — Python-side default in the model
+3. `ValueError` — fail-loud if both are missing
+
+### Per-role overrides via `||` format
+
+DBAs can set role-specific labels and row links in PostgreSQL comments:
+
+```sql
+COMMENT ON COLUMN emails.email_type_id IS 'Тип письма||operator=Категория||buh=Реквизит';
+COMMENT ON TABLE  emails               IS 'Письма||row_link=/email/$id||row_link.operator=/op/email/$id';
+```
+
+### TTL cache
+
+`pg_description` queries are cached per `(schema, table)` with a configurable TTL (default 60s):
+
+```python
+soh.configure_meta_cache_ttl(120)       # change TTL to 120 seconds
+soh.invalidate_meta_cache()             # clear entire cache
+soh.invalidate_meta_cache(schema="lead")  # clear all entries for a schema
+soh.invalidate_meta_cache("lead", "emails")  # clear one entry
+```
+
+### Standalone mode
+
+```python
+import sqlmodel_object_helpers.standalone as soh_sa
+
+table_meta, columns = await soh_sa.build_dynamic_meta(
+    EmailMessage,
+    name="email_messages",
+    columns=["id", "email_type_id"],
+)
+```
+
+### Backward compatibility and migration
+
+`GetAllPagination` is fully backward compatible — `table` and `columns` default to `None`, so existing endpoints continue to work without changes:
+
+```python
+# Before (still works as-is)
+return soh.GetAllPagination(data=items, pagination=pagination_r)
+
+# After (meta added when ready)
+return soh.GetAllPagination(
+    table=table_meta,
+    columns=columns,
+    data=items,
+    pagination=pagination_r,
+)
+```
+
+Endpoints can be migrated one at a time. Three strategies per endpoint:
+
+| Strategy | `table`/`columns` | Use case |
+|---|---|---|
+| **No meta** | Always `None` | Endpoint not yet migrated, frontend uses hardcoded table |
+| **Always meta** | Sent on every request | Simple, no frontend caching logic needed |
+| **Meta on first page** | Sent when `page=1`, `None` on pages 2+ | Saves traffic, frontend caches meta from first response |
+
 ## API Reference
 
 ### Session Management
@@ -629,7 +741,7 @@ result = await soh.get_objects(session, User, order_by=order)
 
 ### Standalone Wrappers
 
-- `import sqlmodel_object_helpers.standalone as soh_sa` -- All 12 query/mutation functions without `session` parameter
+- `import sqlmodel_object_helpers.standalone as soh_sa` -- All 12 query/mutation functions plus `build_dynamic_meta` without `session` parameter
 
 ### Settings
 
@@ -654,6 +766,14 @@ result = await soh.get_objects(session, User, order_by=order)
 - `soh.delete_objects(session, model, filters)` -- Bulk delete via single `DELETE ... WHERE`
 - `soh.check_for_related_records(session, model, pk)` -- Pre-deletion dependency check
 
+### Dynamic Meta
+
+- `soh.build_dynamic_meta(session, model, *, name, columns, header, row_link, role_type)` -- Build `TableMeta` + `list[ColumnMeta]` from model + `pg_description`
+- `soh.load_pg_comments(session, schema, table)` -- Read `(table_comment, {col: comment})` from `pg_description` (TTL-cached)
+- `soh.configure_meta_cache_ttl(seconds)` -- Override default `pg_description` cache TTL (default: 60s)
+- `soh.invalidate_meta_cache(schema, table)` -- Manually invalidate the `pg_description` cache (full, by-schema, or by-table)
+- `soh.ColumnEntry` -- Type alias: `str | ColumnMeta` (element of `columns` list in `build_dynamic_meta`)
+
 ### Filter Builders
 
 - `soh.build_filter(model, filters, ...)` -- Build SQLAlchemy expression from LogicalFilter dict
@@ -762,6 +882,10 @@ This project follows [Semantic Versioning](https://semver.org/) (MAJOR.MINOR.PAT
 
 ## Changelog
 
+### 0.0.6
+
+- **build_dynamic_meta** / **load_pg_comments** / **configure_meta_cache_ttl** / **invalidate_meta_cache** — dynamic UI metadata reader. Builds `TableMeta` and `list[ColumnMeta]` from a SQLModel class by reading PostgreSQL `pg_description` (TTL-cached, default 60s) with fallback to `Column(comment=...)` defaults from the model. Supports per-role label/row_link overrides via extended `||` comment format. For physical columns the label precedence is `pg_description` > `Column(comment=...)` model default. For virtual columns (paths with `.` traversing relationships) and full overrides — pass a fully-specified `ColumnMeta` instance directly in the `columns` list (used as-is, no derivation). Lookup `lookup_dict`/`lookup_path` are derived from FK on `*_lkp` tables by `{schema}_{base}` convention. Type derived from SA column type. DBAs can edit labels via `COMMENT ON COLUMN/TABLE` SQL — frontend reflects changes within cache TTL without redeploy. No sync block, no schema migrations introduced; the application's `db.py` is not touched.
+
 ### 0.0.5
 
 - **FilterDatetimeRange** / **FilterNaiveDatetimeRange** — range filters that parse comma-separated date strings (`"2026-04-01,2026-05-06"`) into `gt`/`lt` operators for SQL filtering

{sqlmodel_object_helpers-0.0.5 → sqlmodel_object_helpers-0.0.6}/README.md

@@ -21,6 +21,7 @@ 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)
+- **Dynamic Table Metadata** - `build_dynamic_meta` derives `TableMeta` + `list[ColumnMeta]` from a SQLModel class by reading PostgreSQL `pg_description` with fallback to `Column(comment=...)`. Supports per-role label/row_link overrides via `||` comment format, TTL-cached
 - **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
 
@@ -585,6 +586,117 @@ order = soh.OrderBy(sorts=[
 result = await soh.get_objects(session, User, order_by=order)
 ```
 
+## Dynamic Table Metadata
+
+`build_dynamic_meta` builds `TableMeta` + `list[ColumnMeta]` from a SQLModel class at runtime, reading PostgreSQL `pg_description` (TTL-cached) with fallback to `Column(comment=...)` model defaults.
+
+```python
+import sqlmodel_object_helpers as soh
+
+# Physical columns — label, type, lookup derived automatically
+table_meta, columns = await soh.build_dynamic_meta(
+    session,
+    EmailMessage,
+    name="email_messages",
+    columns=[
+        "id",                        # physical column — everything derived
+        "email_type_id",             # FK on *_lkp → lookup_dict auto-derived
+        "updated_at",
+        soh.ColumnMeta(              # virtual column — fully specified
+            json_path="last_editor.user_name",
+            label="Редактор",
+            type=soh.ColumnType.STRING,
+        ),
+    ],
+    role_type="operator",            # per-role label/row_link overrides
+)
+
+# Returns (TableMeta, list[ColumnMeta]) ready for GetAllPagination
+return soh.GetAllPagination(
+    table=table_meta,
+    columns=columns,
+    data=items,
+    pagination=pagination_r,
+)
+```
+
+### Type derivation (SA type → ColumnType)
+
+Physical column types are mapped automatically. Unknown types fall back to `string`.
+
+| SQLAlchemy type | ColumnType |
+|---|---|
+| `Boolean` | `boolean` |
+| `DateTime` | `datetime` |
+| `Date` | `date` |
+| `Integer`, `BigInteger`, `SmallInteger` | `integer` |
+| `Numeric`, `Float` | `float` |
+| `String`, `Text`, `Enum`, `Interval`, `ARRAY`, `Uuid` | `string` |
+| Any other type | `string` (fallback) |
+
+### Label precedence (per physical column)
+
+1. `pg_description` — DBA edit via `COMMENT ON COLUMN` (supports per-role `||` overrides)
+2. `Column(comment=...)` — Python-side default in the model
+3. `ValueError` — fail-loud if both are missing
+
+### Per-role overrides via `||` format
+
+DBAs can set role-specific labels and row links in PostgreSQL comments:
+
+```sql
+COMMENT ON COLUMN emails.email_type_id IS 'Тип письма||operator=Категория||buh=Реквизит';
+COMMENT ON TABLE  emails               IS 'Письма||row_link=/email/$id||row_link.operator=/op/email/$id';
+```
+
+### TTL cache
+
+`pg_description` queries are cached per `(schema, table)` with a configurable TTL (default 60s):
+
+```python
+soh.configure_meta_cache_ttl(120)       # change TTL to 120 seconds
+soh.invalidate_meta_cache()             # clear entire cache
+soh.invalidate_meta_cache(schema="lead")  # clear all entries for a schema
+soh.invalidate_meta_cache("lead", "emails")  # clear one entry
+```
+
+### Standalone mode
+
+```python
+import sqlmodel_object_helpers.standalone as soh_sa
+
+table_meta, columns = await soh_sa.build_dynamic_meta(
+    EmailMessage,
+    name="email_messages",
+    columns=["id", "email_type_id"],
+)
+```
+
+### Backward compatibility and migration
+
+`GetAllPagination` is fully backward compatible — `table` and `columns` default to `None`, so existing endpoints continue to work without changes:
+
+```python
+# Before (still works as-is)
+return soh.GetAllPagination(data=items, pagination=pagination_r)
+
+# After (meta added when ready)
+return soh.GetAllPagination(
+    table=table_meta,
+    columns=columns,
+    data=items,
+    pagination=pagination_r,
+)
+```
+
+Endpoints can be migrated one at a time. Three strategies per endpoint:
+
+| Strategy | `table`/`columns` | Use case |
+|---|---|---|
+| **No meta** | Always `None` | Endpoint not yet migrated, frontend uses hardcoded table |
+| **Always meta** | Sent on every request | Simple, no frontend caching logic needed |
+| **Meta on first page** | Sent when `page=1`, `None` on pages 2+ | Saves traffic, frontend caches meta from first response |
+
 ## API Reference
 
 ### Session Management
@@ -595,7 +707,7 @@ result = await soh.get_objects(session, User, order_by=order)
 
 ### Standalone Wrappers
 
-- `import sqlmodel_object_helpers.standalone as soh_sa` -- All 12 query/mutation functions without `session` parameter
+- `import sqlmodel_object_helpers.standalone as soh_sa` -- All 12 query/mutation functions plus `build_dynamic_meta` without `session` parameter
 
 ### Settings
 
@@ -620,6 +732,14 @@ result = await soh.get_objects(session, User, order_by=order)
 - `soh.delete_objects(session, model, filters)` -- Bulk delete via single `DELETE ... WHERE`
 - `soh.check_for_related_records(session, model, pk)` -- Pre-deletion dependency check
 
+### Dynamic Meta
+
+- `soh.build_dynamic_meta(session, model, *, name, columns, header, row_link, role_type)` -- Build `TableMeta` + `list[ColumnMeta]` from model + `pg_description`
+- `soh.load_pg_comments(session, schema, table)` -- Read `(table_comment, {col: comment})` from `pg_description` (TTL-cached)
+- `soh.configure_meta_cache_ttl(seconds)` -- Override default `pg_description` cache TTL (default: 60s)
+- `soh.invalidate_meta_cache(schema, table)` -- Manually invalidate the `pg_description` cache (full, by-schema, or by-table)
+- `soh.ColumnEntry` -- Type alias: `str | ColumnMeta` (element of `columns` list in `build_dynamic_meta`)
+
 ### Filter Builders
 
 - `soh.build_filter(model, filters, ...)` -- Build SQLAlchemy expression from LogicalFilter dict
@@ -728,6 +848,10 @@ This project follows [Semantic Versioning](https://semver.org/) (MAJOR.MINOR.PAT
 
 ## Changelog
 
+### 0.0.6
+
+- **build_dynamic_meta** / **load_pg_comments** / **configure_meta_cache_ttl** / **invalidate_meta_cache** — dynamic UI metadata reader. Builds `TableMeta` and `list[ColumnMeta]` from a SQLModel class by reading PostgreSQL `pg_description` (TTL-cached, default 60s) with fallback to `Column(comment=...)` defaults from the model. Supports per-role label/row_link overrides via extended `||` comment format. For physical columns the label precedence is `pg_description` > `Column(comment=...)` model default. For virtual columns (paths with `.` traversing relationships) and full overrides — pass a fully-specified `ColumnMeta` instance directly in the `columns` list (used as-is, no derivation). Lookup `lookup_dict`/`lookup_path` are derived from FK on `*_lkp` tables by `{schema}_{base}` convention. Type derived from SA column type. DBAs can edit labels via `COMMENT ON COLUMN/TABLE` SQL — frontend reflects changes within cache TTL without redeploy. No sync block, no schema migrations introduced; the application's `db.py` is not touched.
+
 ### 0.0.5
 
 - **FilterDatetimeRange** / **FilterNaiveDatetimeRange** — range filters that parse comma-separated date strings (`"2026-04-01,2026-05-06"`) into `gt`/`lt` operators for SQL filtering

{sqlmodel_object_helpers-0.0.5 → sqlmodel_object_helpers-0.0.6}/src/sqlmodel_object_helpers/__init__.py

@@ -1,8 +1,15 @@
 """sqlmodel-object-helpers — reusable query helpers for SQLModel projects."""
 
-__version__ = "0.0.5"
+__version__ = "0.0.6"
 
 from .constants import QueryHelperSettings, settings
+from .dynamic_meta import (
+    ColumnEntry,
+    build_dynamic_meta,
+    configure_meta_cache_ttl,
+    invalidate_meta_cache,
+    load_pg_comments,
+)
 from .exceptions import (
     DatabaseError,
     InvalidFilterError,
@@ -13,7 +20,6 @@ from .exceptions import (
 )
 from .filters import build_filter, build_flat_filter, flatten_filters
 from .loaders import build_load_chain, build_load_options
-from .operators import SPECIAL_OPERATORS, SUPPORTED_OPERATORS, Operator
 from .mutations import (
     add_object,
     add_objects,
@@ -23,8 +29,10 @@ from .mutations import (
     update_object,
     update_objects,
 )
+from .operators import SPECIAL_OPERATORS, SUPPORTED_OPERATORS, Operator
 from .query import count_objects, exists_object, get_object, get_objects, get_projection
 from .session import auto_session, configure, create_session_dependency
+from .types.columns import BoolLabels, ColumnMeta, ColumnType, TableMeta
 from .types.datetime import UTCDatetime
 from .types.filters import (
     FilterBool,
@@ -43,7 +51,6 @@ from .types.filters import (
     OrderDesc,
     TimeFilter,
 )
-from .types.columns import BoolLabels, ColumnMeta, ColumnType, TableMeta
 from .types.pagination import (
     GetAllPagination,
     LookupMeta,
@@ -57,16 +64,19 @@ __all__ = [
     "add_object",
     "add_objects",
     "auto_session",
+    "build_dynamic_meta",
     "build_filter",
     "build_flat_filter",
     "build_load_chain",
     "build_load_options",
     "check_for_related_records",
     "BoolLabels",
+    "ColumnEntry",
     "ColumnMeta",
     "ColumnSpec",
     "ColumnType",
     "configure",
+    "configure_meta_cache_ttl",
     "count_objects",
     "create_session_dependency",
     "DatabaseError",
@@ -88,8 +98,10 @@ __all__ = [
     "get_objects",
     "get_projection",
     "GetAllPagination",
+    "invalidate_meta_cache",
     "InvalidFilterError",
     "InvalidLoadPathError",
+    "load_pg_comments",
     "LogicalFilter",
     "LookupMeta",
     "LookupResponse",