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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlmodel-object-helpers
-Version: 0.0.4
+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
 
@@ -539,7 +540,34 @@ class UserFilter(BaseModel):
     posts: soh.FilterExists | None = None  # exists: bool
 ```
 
-Available: `FilterInt`, `FilterStr`, `FilterDate`, `FilterDatetime`, `FilterTimedelta`, `FilterBool`, `FilterExists`.
+Available: `FilterInt`, `FilterStr`, `FilterDate`, `FilterDatetime`, `FilterNaiveDatetime`, `FilterTimedelta`, `FilterBool`, `FilterExists`.
+
+#### Range Filters
+
+`FilterDatetimeRange` and `FilterNaiveDatetimeRange` parse a comma-separated date string into `gt`/`lt` operators:
+
+```python
+import sqlmodel_object_helpers as soh
+
+# Full range: "FROM,TO" → gt + lt
+f = soh.FilterDatetimeRange.model_validate("2026-04-01,2026-05-06")
+f.model_dump(exclude_none=True)
+# {"gt": datetime(2026, 4, 1, tzinfo=UTC), "lt": datetime(2026, 5, 6, tzinfo=UTC)}
+# SQL: WHERE field > '2026-04-01' AND field < '2026-05-06'
+
+# Open end: "FROM," → gt only
+f = soh.FilterDatetimeRange.model_validate("2026-04-01,")
+# SQL: WHERE field > '2026-04-01'
+
+# Open start: ",TO" → lt only
+f = soh.FilterDatetimeRange.model_validate(",2026-05-06")
+# SQL: WHERE field < '2026-05-06'
+```
+
+Each date part accepts ISO (`2026-04-01`, `2026-04-01T00:00:00Z`) and display format (`01.04.2026 00:00`).
+
+- `FilterDatetimeRange` — produces UTC-aware datetimes
+- `FilterNaiveDatetimeRange` — produces naive (timezone-unaware) datetimes
 
 ## Eager Loading
 
@@ -592,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
@@ -602,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
 
@@ -627,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
@@ -655,7 +802,8 @@ result = await soh.get_objects(session, User, order_by=order)
 
 ### Filter Types
 
-- `soh.FilterInt`, `soh.FilterStr`, `soh.FilterDate`, `soh.FilterDatetime`, `soh.FilterTimedelta`, `soh.FilterBool`, `soh.FilterExists`
+- `soh.FilterInt`, `soh.FilterStr`, `soh.FilterDate`, `soh.FilterDatetime`, `soh.FilterNaiveDatetime`, `soh.FilterTimedelta`, `soh.FilterBool`, `soh.FilterExists`
+- `soh.FilterDatetimeRange`, `soh.FilterNaiveDatetimeRange` -- Range filters that parse `"FROM,TO"` strings into `gt`/`lt` operators
 - `soh.OrderAsc`, `soh.OrderDesc`, `soh.OrderBy`
 - `soh.LogicalFilter`
 - `soh.TimeFilter` -- `created_after`, `created_before`, `updated_after`, `updated_before` with half-open interval `[after, before)`
@@ -668,7 +816,19 @@ result = await soh.get_objects(session, User, order_by=order)
 
 - `soh.Pagination` -- Request model (page, per\_page)
 - `soh.PaginationR` -- Response model (page, per\_page, total)
-- `soh.GetAllPagination[T]` -- Generic wrapper (data: list[T], pagination: PaginationR | None)
+- `soh.GetAllPagination[T]` -- Generic wrapper (table: TableMeta | None, columns: list[ColumnMeta] | None, data: list[T], pagination: PaginationR | None)
+
+### Table Metadata Types
+
+- `soh.TableMeta` -- Table-level metadata (name, header, row_link)
+- `soh.ColumnMeta` -- Column metadata (json_path, label, type, lookup_dict, lookup_path, bool_labels)
+- `soh.ColumnType` -- StrEnum of column data types (string, integer, float, boolean, date, datetime)
+- `soh.BoolLabels` -- Display labels for boolean columns (true_label, false_label)
+
+### Lookup Types
+
+- `soh.LookupMeta` -- Lookup metadata (name used as cache key, matches `ColumnMeta.lookup_dict`)
+- `soh.LookupResponse[T]` -- Generic wrapper for lookup endpoints (meta: LookupMeta, data: list[T])
 
 ### Projection Types
 
@@ -720,6 +880,23 @@ This project follows [Semantic Versioning](https://semver.org/) (MAJOR.MINOR.PAT
 - **MINOR** — new features (backwards compatible)
 - **MAJOR** — breaking changes
 
+## 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
+- **ColumnMeta** / **TableMeta** / **ColumnType** / **BoolLabels** — dynamic table metadata: backend describes columns, types, labels, lookups, and row navigation so the frontend renders any table without hardcoding
+- **GetAllPagination** — now includes optional `table` and `columns` fields for delivering table metadata alongside paginated data
+- **LookupMeta** / **LookupResponse** — standard `{meta, data}` wrapper for lookup (`_lkp`) endpoints, enabling unified frontend caching of dictionaries with `meta.name` as cache key
+
+### 0.0.4
+
+- Initial public release
+
 ## License
 
 This project is licensed under the **PolyForm Noncommercial License 1.0.0**.

{sqlmodel_object_helpers-0.0.4 → 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
 
@@ -505,7 +506,34 @@ class UserFilter(BaseModel):
     posts: soh.FilterExists | None = None  # exists: bool
 ```
 
-Available: `FilterInt`, `FilterStr`, `FilterDate`, `FilterDatetime`, `FilterTimedelta`, `FilterBool`, `FilterExists`.
+Available: `FilterInt`, `FilterStr`, `FilterDate`, `FilterDatetime`, `FilterNaiveDatetime`, `FilterTimedelta`, `FilterBool`, `FilterExists`.
+
+#### Range Filters
+
+`FilterDatetimeRange` and `FilterNaiveDatetimeRange` parse a comma-separated date string into `gt`/`lt` operators:
+
+```python
+import sqlmodel_object_helpers as soh
+
+# Full range: "FROM,TO" → gt + lt
+f = soh.FilterDatetimeRange.model_validate("2026-04-01,2026-05-06")
+f.model_dump(exclude_none=True)
+# {"gt": datetime(2026, 4, 1, tzinfo=UTC), "lt": datetime(2026, 5, 6, tzinfo=UTC)}
+# SQL: WHERE field > '2026-04-01' AND field < '2026-05-06'
+
+# Open end: "FROM," → gt only
+f = soh.FilterDatetimeRange.model_validate("2026-04-01,")
+# SQL: WHERE field > '2026-04-01'
+
+# Open start: ",TO" → lt only
+f = soh.FilterDatetimeRange.model_validate(",2026-05-06")
+# SQL: WHERE field < '2026-05-06'
+```
+
+Each date part accepts ISO (`2026-04-01`, `2026-04-01T00:00:00Z`) and display format (`01.04.2026 00:00`).
+
+- `FilterDatetimeRange` — produces UTC-aware datetimes
+- `FilterNaiveDatetimeRange` — produces naive (timezone-unaware) datetimes
 
 ## Eager Loading
 
@@ -558,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
@@ -568,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
 
@@ -593,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
@@ -621,7 +768,8 @@ result = await soh.get_objects(session, User, order_by=order)
 
 ### Filter Types
 
-- `soh.FilterInt`, `soh.FilterStr`, `soh.FilterDate`, `soh.FilterDatetime`, `soh.FilterTimedelta`, `soh.FilterBool`, `soh.FilterExists`
+- `soh.FilterInt`, `soh.FilterStr`, `soh.FilterDate`, `soh.FilterDatetime`, `soh.FilterNaiveDatetime`, `soh.FilterTimedelta`, `soh.FilterBool`, `soh.FilterExists`
+- `soh.FilterDatetimeRange`, `soh.FilterNaiveDatetimeRange` -- Range filters that parse `"FROM,TO"` strings into `gt`/`lt` operators
 - `soh.OrderAsc`, `soh.OrderDesc`, `soh.OrderBy`
 - `soh.LogicalFilter`
 - `soh.TimeFilter` -- `created_after`, `created_before`, `updated_after`, `updated_before` with half-open interval `[after, before)`
@@ -634,7 +782,19 @@ result = await soh.get_objects(session, User, order_by=order)
 
 - `soh.Pagination` -- Request model (page, per\_page)
 - `soh.PaginationR` -- Response model (page, per\_page, total)
-- `soh.GetAllPagination[T]` -- Generic wrapper (data: list[T], pagination: PaginationR | None)
+- `soh.GetAllPagination[T]` -- Generic wrapper (table: TableMeta | None, columns: list[ColumnMeta] | None, data: list[T], pagination: PaginationR | None)
+
+### Table Metadata Types
+
+- `soh.TableMeta` -- Table-level metadata (name, header, row_link)
+- `soh.ColumnMeta` -- Column metadata (json_path, label, type, lookup_dict, lookup_path, bool_labels)
+- `soh.ColumnType` -- StrEnum of column data types (string, integer, float, boolean, date, datetime)
+- `soh.BoolLabels` -- Display labels for boolean columns (true_label, false_label)
+
+### Lookup Types
+
+- `soh.LookupMeta` -- Lookup metadata (name used as cache key, matches `ColumnMeta.lookup_dict`)
+- `soh.LookupResponse[T]` -- Generic wrapper for lookup endpoints (meta: LookupMeta, data: list[T])
 
 ### Projection Types
 
@@ -686,6 +846,23 @@ This project follows [Semantic Versioning](https://semver.org/) (MAJOR.MINOR.PAT
 - **MINOR** — new features (backwards compatible)
 - **MAJOR** — breaking changes
 
+## 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
+- **ColumnMeta** / **TableMeta** / **ColumnType** / **BoolLabels** — dynamic table metadata: backend describes columns, types, labels, lookups, and row navigation so the frontend renders any table without hardcoding
+- **GetAllPagination** — now includes optional `table` and `columns` fields for delivering table metadata alongside paginated data
+- **LookupMeta** / **LookupResponse** — standard `{meta, data}` wrapper for lookup (`_lkp`) endpoints, enabling unified frontend caching of dictionaries with `meta.name` as cache key
+
+### 0.0.4
+
+- Initial public release
+
 ## License
 
 This project is licensed under the **PolyForm Noncommercial License 1.0.0**.

{sqlmodel_object_helpers-0.0.4 → 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.4"
+__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,16 +29,20 @@ 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,
     FilterDate,
     FilterDatetime,
+    FilterDatetimeRange,
     FilterExists,
     FilterInt,
     FilterNaiveDatetime,
+    FilterNaiveDatetimeRange,
     FilterStr,
     FilterTimedelta,
     LogicalFilter,
@@ -43,6 +53,8 @@ from .types.filters import (
 )
 from .types.pagination import (
     GetAllPagination,
+    LookupMeta,
+    LookupResponse,
     Pagination,
     PaginationR,
 )
@@ -52,13 +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",
@@ -68,9 +86,11 @@ __all__ = [
     "FilterBool",
     "FilterDate",
     "FilterDatetime",
+    "FilterDatetimeRange",
     "FilterExists",
     "FilterInt",
     "FilterNaiveDatetime",
+    "FilterNaiveDatetimeRange",
     "FilterStr",
     "FilterTimedelta",
     "flatten_filters",
@@ -78,9 +98,13 @@ __all__ = [
     "get_objects",
     "get_projection",
     "GetAllPagination",
+    "invalidate_meta_cache",
     "InvalidFilterError",
     "InvalidLoadPathError",
+    "load_pg_comments",
     "LogicalFilter",
+    "LookupMeta",
+    "LookupResponse",
     "MutationError",
     "ObjectNotFoundError",
     "Operator",
@@ -94,6 +118,7 @@ __all__ = [
     "settings",
     "SPECIAL_OPERATORS",
     "SUPPORTED_OPERATORS",
+    "TableMeta",
     "TimeFilter",
     "update_object",
     "update_objects",