simple-module-db 0.0.37__tar.gz → 0.0.38__tar.gz

{simple_module_db-0.0.37 → simple_module_db-0.0.38}/.gitignore

@@ -7,8 +7,6 @@ build/
 .venv/
 *.egg
 
-# UV
-uv.lock
 
 # Node
 node_modules/
@@ -65,3 +63,4 @@ host/client_app/.playwright-cli/*
 .qa/
 .verify/
 /openapi.json
+qa-shots/

{simple_module_db-0.0.37 → simple_module_db-0.0.38}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simple_module_db
-Version: 0.0.37
+Version: 0.0.38
 Summary: Per-module SQLModel Base, async session, standard mixins (Audit, SoftDelete, MultiTenant, Versioned) for simple_module
 Project-URL: Homepage, https://github.com/antosubash/simple_module_python
 Project-URL: Repository, https://github.com/antosubash/simple_module_python
@@ -25,7 +25,7 @@ Requires-Dist: aiosqlite>=0.20
 Requires-Dist: alembic>=1.14
 Requires-Dist: asyncpg>=0.30
 Requires-Dist: psycopg2-binary>=2.9
-Requires-Dist: simple-module-core==0.0.37
+Requires-Dist: simple-module-core==0.0.38
 Requires-Dist: sqlalchemy[asyncio]>=2.0
 Requires-Dist: sqlmodel>=0.0.22
 Description-Content-Type: text/markdown

{simple_module_db-0.0.37 → simple_module_db-0.0.38}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_db"
-version = "0.0.37"
+version = "0.0.38"
 description = "Per-module SQLModel Base, async session, standard mixins (Audit, SoftDelete, MultiTenant, Versioned) for simple_module"
 readme = "README.md"
 license = "MIT"
@@ -28,7 +28,7 @@ dependencies = [
     # The async app code goes through asyncpg; migration env.py rewrites the
     # URL to +psycopg2 because Alembic's online migrations are sync-only.
     "psycopg2-binary>=2.9",
-    "simple_module_core==0.0.37",
+    "simple_module_core==0.0.38",
     "sqlalchemy[asyncio]>=2.0",
     "sqlmodel>=0.0.22",
 ]

{simple_module_db-0.0.37 → simple_module_db-0.0.38}/simple_module_db/__init__.py

@@ -2,9 +2,11 @@
 
 from simple_module_db.audit import AuditRecord
 from simple_module_db.base import create_module_base
+from simple_module_db.bulk_audit import UnauditedWriteError, record_bulk_audit
 from simple_module_db.callbacks import OnCommitCallback
 from simple_module_db.deps import get_db
 from simple_module_db.extensions import UnsupportedDatabaseError, ensure_db_extensions
+from simple_module_db.independent import independent_session
 from simple_module_db.migration_portability import drop_enums_if_postgres
 from simple_module_db.migrations import (
     build_module_metadata,
@@ -13,6 +15,13 @@ from simple_module_db.migrations import (
     render_item,
 )
 from simple_module_db.mixins import AuditMixin, MultiTenantMixin, SoftDeleteMixin, VersionedMixin
+from simple_module_db.pagination import (
+    Page,
+    PageParams,
+    clamp_page,
+    paginate,
+    total_pages,
+)
 from simple_module_db.provider import DatabaseProvider, detect_provider
 from simple_module_db.search import LIKE_ESCAPE_CHAR, like_contains_pattern, like_prefix_pattern
 from simple_module_db.session import DatabaseState, RequestSession, init_db
@@ -50,15 +59,19 @@ __all__ = [
     "MissingTenantError",
     "MultiTenantMixin",
     "OnCommitCallback",
+    "Page",
+    "PageParams",
     "RequestSession",
     "SoftDeleteMixin",
     "TSVector",
     "TenantIsolationError",
+    "UnauditedWriteError",
     "UnsupportedDatabaseError",
     "VersionedMixin",
     "all_tenants",
     "bind_current_tenant",
     "build_module_metadata",
+    "clamp_page",
     "create_module_base",
     "current_tenant_id",
     "detect_provider",
@@ -67,6 +80,7 @@ __all__ = [
     "finalize_session",
     "get_db",
     "hard_delete",
+    "independent_session",
     "init_db",
     "is_valid_tenant_id",
     "like_contains_pattern",
@@ -75,6 +89,9 @@ __all__ = [
     "make_process_revision_directives",
     "mark_written",
     "no_tenant",
+    "paginate",
+    "record_bulk_audit",
     "render_item",
     "tenant_context",
+    "total_pages",
 ]

simple_module_db-0.0.38/simple_module_db/_bulk_audit_records.py

@@ -0,0 +1,129 @@
+"""Audit record building and delivery shared by the bulk-audit hook and its manual entry point."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Iterable
+from typing import Any, Final
+
+from simple_module_core.correlation import correlation_id
+from sqlalchemy import inspect as sa_inspect
+from sqlalchemy.orm import ORMExecuteState, Session
+from sqlalchemy.sql.elements import BindParameter
+from sqlalchemy.sql.visitors import iterate
+
+from simple_module_db.audit import AuditRecord, _serialize, format_pk
+from simple_module_db.query_filter import engine_policy
+
+logger = logging.getLogger("simple_module_db.bulk_audit")
+
+ACTION_BULK_INSERTED: Final = "bulk_inserted"
+ACTION_BULK_UPDATED: Final = "bulk_updated"
+ACTION_BULK_DELETED: Final = "bulk_deleted"
+ACTION_BULK_SOFT_DELETED: Final = "bulk_soft_deleted"
+ACTION_BULK_RESTORED: Final = "bulk_restored"
+SUMMARY_ENTITY_ID: Final = "*"
+
+_SOFT_DELETE_FLAG: Final = "is_deleted"
+_ACTIVE_KEY: Final = "_sm_bulk_audit_active"
+
+
+class _Ctx:
+    """What one audited statement records, built before it runs."""
+
+    def __init__(self, entity_type: str, action: str, changes: list[dict[str, Any]]) -> None:
+        self.entity_type = entity_type
+        self.action = action
+        self.row_actions = [action]
+        self.changes = changes
+        self.user_id = _current_user()
+        self.correlation_id = correlation_id.get("") or None
+
+    def record(
+        self,
+        entity_id: str,
+        changes: list[dict[str, Any]] | None = None,
+        action: str | None = None,
+    ) -> AuditRecord:
+        return AuditRecord(
+            entity_type=self.entity_type,
+            entity_id=entity_id,
+            action=action or self.action,
+            changes=self.changes if changes is None else changes,
+            user_id=self.user_id,
+            correlation_id=self.correlation_id,
+        )
+
+
+def _current_user() -> str | None:
+    from simple_module_db.listeners import current_user_id
+
+    return current_user_id.get()
+
+
+def _where_params(stmt: Any, params: Any) -> dict[str, Any] | None:
+    """The execute params the ``WHERE`` clause binds, so the prefetch can run it."""
+    where = getattr(stmt, "whereclause", None)
+    if where is None or not isinstance(params, dict):
+        return None
+    keys = {e.key for e in iterate(where) if isinstance(e, BindParameter)}
+    return {k: v for k, v in params.items() if k in keys} or None
+
+
+def _bulk_by_pk_ids(execute_state: ORMExecuteState, cls: type) -> list[str] | None:
+    """``session.execute(update(Model), [{pk..., col...}, ...])``: ids from the rows."""
+    params = execute_state.parameters
+    if not (execute_state.is_update and isinstance(params, list) and params):
+        return None
+    pk = [col.key for col in sa_inspect(cls).primary_key]
+    if not all(all(k in row for k in pk) for row in params):
+        return None
+    return [format_pk([row[k] for k in pk]) for row in params]
+
+
+def _summary(ctx: _Ctx, stmt: Any, rowcount: Any, action: str) -> AuditRecord:
+    where = getattr(stmt, "whereclause", None)
+    summary = [
+        {"field": "where_sql", "new": str(where) if where is not None else None},
+        {"field": "rowcount", "new": rowcount},
+        {"field": "truncated", "new": True},
+    ]
+    return ctx.record(SUMMARY_ENTITY_ID, [*ctx.changes, *summary], action)
+
+
+def _deliver(session: Session, callback: Any, records: list[AuditRecord]) -> None:
+    if not records:
+        return
+    session.info[_ACTIVE_KEY] = True
+    try:
+        callback(session, records)
+    except Exception:
+        logger.exception("Audit sink failed for %d bulk record(s)", len(records))
+    finally:
+        session.info.pop(_ACTIVE_KEY, None)
+
+
+def record_bulk_audit(
+    session: Any,
+    entity_type: type | str,
+    action: str,
+    ids: Iterable[object] | None,
+    changes: dict[str, Any] | None = None,
+) -> None:
+    """Audit a write the listeners cannot see — a ``text("UPDATE ...")`` statement.
+
+    One record per id (``ids=None`` records one row with ``entity_id`` ``"*"``),
+    in the session's transaction: a rollback discards them with the write.
+    ``changes`` maps column name to new value. A no-op on an unaudited engine;
+    never raises because of the audit sink. Accepts an ``AsyncSession`` or its
+    sync ``Session``.
+    """
+    sync = getattr(session, "sync_session", session)
+    callback = getattr(engine_policy(sync), "audit_callback", None)
+    if callback is None:
+        return
+    name = entity_type if isinstance(entity_type, str) else entity_type.__name__
+    diff = [{"field": k, "new": _serialize(v)} for k, v in (changes or {}).items()]
+    ctx = _Ctx(name, action, diff)
+    keys = [SUMMARY_ENTITY_ID] if ids is None else [str(i) for i in ids]
+    _deliver(sync, callback, [ctx.record(k) for k in keys])

simple_module_db-0.0.38/simple_module_db/_core_joins.py

@@ -0,0 +1,239 @@
+"""Tenant / soft-delete criteria for Core joins over ``Model.__table__`` (#506).
+
+ORM joins get their criteria from ``with_loader_criteria``, which renders into
+each join's ``ON``. A Core join — ``tag.outerjoin(link, ...)`` in
+``select_from``, or ``select(...).outerjoin(link, ...)`` on a raw table — has
+no loader criteria, and a ``WHERE`` on its nullable side would turn the outer
+join into an inner one. So this module rewrites the joins themselves:
+
+* a LEFT join's nullable (right) side gets its predicates in ``ON``, which
+  filters it exactly;
+* a FULL join preserves both sides, and ``ON`` never removes a preserved row,
+  so both sides' predicates go in ``ON`` *and* each side owes
+  ``pred OR <side padded>`` (its primary key ``IS NULL``) to whatever encloses
+  the join — that drops another tenant's (or a trashed) row coming back
+  unmatched while keeping the NULL padding the join adds;
+* an INNER join's sides, and a LEFT join's preserved side, owe their
+  predicates to the enclosing join's ``ON`` — or, at the top, to ``WHERE``.
+
+The FULL-join form is exact, not merely safe: a row survives only if every
+side that is present passed its own predicates, which is what pre-filtering
+both inputs would give, without wrapping the tables in subqueries (which
+would break every column reference to them).
+
+Every plain leaf inside a join is reported back, so the caller does not also
+``WHERE``-filter it through the columns clause. ORM-annotated leaves are left
+to their loader criteria. ``core_scope`` calls this for each SELECT in a
+statement, nested ones included.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from sqlalchemy import and_, exc, or_
+from sqlalchemy.sql.selectable import Alias, FromGrouping, Join, Select, TableClause
+
+Predicates = Callable[[Any], list[Any]]
+
+
+def _base_name(from_obj: Any) -> str | None:
+    while isinstance(from_obj, Alias):  # ``table.alias().alias()`` nests
+        from_obj = from_obj.element
+    return getattr(from_obj, "name", None)
+
+
+def _is_orm(el: Any) -> bool:
+    return "parententity" in getattr(el, "_annotations", {})
+
+
+def is_plain_leaf(node: Any) -> bool:
+    """A Core table or alias of one — not an ORM-annotated occurrence."""
+    if _is_orm(node):
+        return False
+    base = node
+    while isinstance(base, Alias):
+        base = base.element
+    return isinstance(base, TableClause)
+
+
+def _padded(leaf: Any) -> Any | None:
+    """``leaf``'s row is the NULL padding of an outer join: its primary key is NULL."""
+    pk = list(leaf.primary_key)
+    return and_(*(c.is_(None) for c in pk)) if pk else None
+
+
+class _Scoper:
+    def __init__(self, predicates_for: Predicates) -> None:
+        self.predicates_for = predicates_for
+        self.covered: list[Any] = []
+
+    def scope(self, node: Any) -> tuple[Any, list[Any]]:
+        """``node`` with its joins scoped, and the predicates its rows still owe."""
+        if isinstance(node, Join):
+            return self._join(node)
+        if isinstance(node, FromGrouping):  # a join nested as another join's side
+            inner, owed = self.scope(node.element)
+            return (node if inner is node.element else FromGrouping(inner)), owed
+        if not is_plain_leaf(node):
+            return node, []
+        preds = self.predicates_for(node)
+        if preds:
+            self.covered.append(node)
+        return node, [(node, preds)] if preds else []
+
+    def _join(self, node: Join) -> tuple[Any, list[Any]]:
+        left, owed_left = self.scope(node.left)
+        right, owed_right = self.scope(node.right)
+        if not node.isouter:
+            on, owed = [], owed_left + owed_right
+        elif node.full:
+            on, owed = owed_left + owed_right, [_or_padded(o) for o in owed_left + owed_right]
+        else:
+            on, owed = owed_right, owed_left
+        if not on and left is node.left and right is node.right:
+            return node, owed
+        onclause = and_(node.onclause, *_flatten(on)) if on else node.onclause  # ty: ignore[invalid-argument-type]
+        return Join(left, right, onclause, isouter=node.isouter, full=node.full), owed
+
+
+def _or_padded(owed: tuple) -> tuple:
+    """``owed`` as ``pred OR <leaf padded>``: tagged with a third item so it is padded once."""
+    if len(owed) == 3:
+        return owed
+    leaf, preds = owed
+    padded = _padded(leaf)
+    # No primary key to tell padding apart: keep the plain predicates, which
+    # over-filter (drop the padded rows) but never leak.
+    return (leaf, preds) if padded is None else (leaf, [or_(and_(*preds), padded)], True)
+
+
+def _flatten(owed: list[tuple]) -> list[Any]:
+    return [p for _leaf, preds, *_ in owed for p in preds]
+
+
+class JoinScope:
+    """What scoping one SELECT's joins produced, for the caller to install."""
+
+    def __init__(self, from_obj: tuple, setup_joins: tuple, where: list, covered: list) -> None:
+        self.from_obj = from_obj
+        self.setup_joins = setup_joins
+        self.where = where
+        self.covered = covered
+
+
+def scope_joins(stmt: Select, predicates_for: Predicates) -> JoinScope:
+    """Scope ``stmt``'s Core joins: its ``FROM`` joins and ``.join()`` steps.
+
+    ``covered`` lists every plain leaf filtered here — in ``ON`` or through
+    ``where`` — which must not get another ``WHERE`` predicate from the
+    caller: on a nullable side it would make the outer join inner.
+    ``predicates_for`` raises under strict mode with no tenant bound, so a
+    Core join fails closed like everything else.
+
+    Once any ``.join()`` step is FULL, every ``WHERE`` predicate owed here
+    takes the padded form ``pred OR <pk> IS NULL``. That is never a leak —
+    a primary key is NULL only on a row an outer join padded, which carries
+    nothing of that table — and it is what keeps the FULL join's left side
+    from being filtered down to a RIGHT join.
+    """
+    scoper = _Scoper(predicates_for)
+    owed: list[tuple] = []
+    froms: list[Any] = []
+    for from_obj in stmt._from_obj:
+        if isinstance(from_obj, Join):
+            from_obj, more = scoper.scope(from_obj)
+            owed.extend(more)
+        froms.append(from_obj)
+    joins = [_scope_setup_join(stmt, i, scoper, owed) for i in range(len(stmt._setup_joins))]
+    if any(entry[3].get("full") for entry in stmt._setup_joins):
+        owed = [_or_padded(o) for o in owed]
+    return JoinScope(tuple(froms), tuple(joins), _flatten(owed), scoper.covered)
+
+
+def _scope_setup_join(stmt: Select, index: int, scoper: _Scoper, owed: list[tuple]) -> tuple:
+    """One ``select(...).join(target, onclause)`` step over a Core target.
+
+    The target is scoped like a ``Join``'s right side. A FULL step also
+    preserves its left side — the FROM built so far — so that side's plain
+    leaves get their (padded) predicates in this ``ON`` and owe the padded
+    form to ``WHERE``. Without an explicit ``onclause`` the one SQLAlchemy
+    infers is used; if it cannot be resolved, predicates fall back to plain
+    ``WHERE`` (over-filters, never leaks).
+    """
+    entry = stmt._setup_joins[index]
+    target, onclause, from_, flags = entry
+    full = bool(flags.get("full"))
+    outer = full or bool(flags.get("isouter"))
+    target, target_owed = scoper.scope(target)
+    resolved = None
+    if full or (outer and onclause is None and target_owed):
+        resolved = _resolved_join(stmt, index)
+    left_owed = _left_owed(resolved.left, scoper, owed) if full and resolved is not None else []
+    if not target_owed and not left_owed:
+        return (target, onclause, from_, flags)
+    if onclause is None and resolved is not None:
+        onclause = resolved.onclause
+    if not outer or onclause is None:
+        owed.extend(target_owed)
+        return (target, onclause, from_, flags)
+    on = [*target_owed, *(_or_padded(o) for o in left_owed)]
+    if full:
+        owed.extend(target_owed)
+    return (target, and_(onclause, *_flatten(on)), from_, flags)  # ty: ignore[invalid-argument-type]
+
+
+def _resolved_join(stmt: Select, index: int) -> Join | None:
+    """The ``Join`` SQLAlchemy builds for setup join ``index``: its left side and ``ON``."""
+    target = stmt._setup_joins[index][0]
+    probe = stmt._generate()
+    probe._setup_joins = stmt._setup_joins[: index + 1]
+    try:
+        froms = probe.get_final_froms()
+    except exc.SQLAlchemyError:
+        return None
+    stack = list(froms)
+    while stack:
+        node = stack.pop()
+        if isinstance(node, FromGrouping):
+            stack.append(node.element)
+        elif isinstance(node, Join):
+            if node.right is target or getattr(node.right, "element", None) is target:
+                return node
+            stack.extend((node.left, node.right))
+    return None
+
+
+def _left_owed(left: Any, scoper: _Scoper, owed: list[tuple]) -> list[tuple]:
+    """What the plain leaves preserved on a FULL step's left side owe.
+
+    A leaf already filtered in an earlier outer join's ``ON`` owes nothing;
+    one already owing ``WHERE`` predicates is reported as is; one nobody has
+    scoped yet (a columns-clause FROM) is scoped here and joins ``owed``.
+    """
+    found: list[tuple] = []
+    stack = [left]
+    while stack:
+        node = stack.pop()
+        if isinstance(node, FromGrouping):
+            stack.append(node.element)
+        elif isinstance(node, Join):
+            stack.extend((node.left, node.right))
+        elif is_plain_leaf(node):
+            mine = [o for o in owed if same_from(o[0], node)]
+            if mine:
+                found.extend(mine)
+            elif not any(same_from(node, c) for c in scoper.covered):
+                preds = scoper.predicates_for(node)
+                if preds:
+                    scoper.covered.append(node)
+                    owed.append((node, preds))
+                    found.append((node, preds))
+    return found
+
+
+def same_from(a: Any, b: Any) -> bool:
+    """One FROM occurrence: the same object, or clones of one (an alias the traversal
+    copied while a column still points at the original — SQL renders them as one)."""
+    return a is b or not a._cloned_set.isdisjoint(b._cloned_set)

simple_module_db-0.0.38/simple_module_db/_core_walk.py

@@ -0,0 +1,188 @@
+"""The cheap walk ``core_scope`` runs on every statement (#506, #559).
+
+``references_plain`` answers one question — does this statement read a
+scoped table outside the ORM's annotations? — and ORM statements usually
+answer no, so this runs on nearly every query while tenancy is on. It is a
+reachability search over the clause tree, pruned at ORM-annotated elements;
+everything here is about expanding fewer nodes, or expanding them more
+cheaply, without changing which elements are reachable (#559):
+
+* each element is expanded once, however many parents name it;
+* a bound parameter has no clause children and is not expanded;
+* a SELECT's declared children skip its empty collections, and the FROMs
+  ``froms_read`` would add are added only when its internals do not
+  already hold them (or they are ORM-annotated, which the walk prunes);
+* ``table`` is looked up without the costly ``AttributeError`` that a
+  column expression's ``__getattr__`` raises for it.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy.sql.elements import ClauseElement, ColumnClause, ColumnElement
+from sqlalchemy.sql.selectable import Alias, Join, Select, TableClause
+from sqlalchemy.sql.traversals import _get_children
+
+from simple_module_db._core_joins import _base_name, _is_orm, is_plain_leaf
+
+
+def orm_less(stmt: Any) -> bool:
+    """A SELECT naming no ORM entity in its columns, FROM list or joins.
+
+    Loader criteria have nothing to attach to there — ``exists().where(
+    Doc.x == ...)`` — so the tables its ``WHERE`` reads must be scoped like
+    Core ones. In an ORM select those tables are the entities' own.
+    """
+    targets = [entry[0] for entry in stmt._setup_joins]
+    return not any(_is_orm(el) for el in (*stmt._raw_columns, *stmt._from_obj, *targets))
+
+
+def where_froms(stmt: Any) -> list[Any]:
+    return [f for crit in stmt._where_criteria for f in crit._from_objects]
+
+
+def froms_read(stmt: Any) -> list[Any]:
+    """The FROMs a SELECT reads besides its joins, and the extra FROMs of a DML."""
+    if not isinstance(stmt, Select):
+        target = stmt.table._deannotate()
+        return [f for f in where_froms(stmt) if f is not target]
+    froms = [*stmt.columns_clause_froms, *(f for f in stmt._from_obj if not isinstance(f, Join))]
+    return [*froms, *(where_froms(stmt) if orm_less(stmt) else core_where_froms(stmt))]
+
+
+def core_where_froms(stmt: Select) -> list[Any]:
+    """The FROMs a SELECT's ``WHERE`` pulls in through plain (non-ORM) columns.
+
+    ``select(Tag.name).where(link.c.tag_id == Tag.id)`` reads ``link`` only
+    through its ``WHERE``. ``where_froms`` cannot be used for an ORM select:
+    an entity column's ``_from_objects`` is its bare table too, and an
+    ``aliased()`` entity's would gain a stray cartesian FROM. So the criteria
+    are walked down to their columns, pruning ORM-annotated elements and
+    anything that adds no FROM to this SELECT (a nested select's own
+    references are scoped where that select is visited).
+    """
+    found: list[Any] = []
+    stack: list[ClauseElement] = list(stmt._where_criteria)
+    while stack:
+        el = stack.pop()
+        if _is_orm(el) or not el._from_objects:
+            continue
+        if isinstance(el, ColumnClause):
+            found.extend(el._from_objects)
+        else:
+            stack.extend(el.get_children())
+    return found
+
+
+def references_plain(stmt: Any, names: set[str]) -> bool:
+    """Whether ``stmt`` reads a scoped table outside the ORM's annotations.
+
+    ORM-annotated elements are not descended into: their tables are the
+    loader criteria's business, and every ORM column leads to a plain table.
+    The answer depends only on *which* elements are reachable, so an element
+    met twice is expanded once. ``seen`` keeps the objects, not just their
+    ids, so a temporary child list cannot free one and recycle its id.
+    """
+    stack = [stmt]
+    seen: dict[int, Any] = {}
+    while stack:
+        el = stack.pop()
+        if id(el) in seen or _is_orm(el):
+            continue
+        seen[id(el)] = el
+        target = el if isinstance(el, (TableClause, Alias)) else _table_of(el)
+        if (
+            isinstance(target, (TableClause, Alias))
+            and is_plain_leaf(target)
+            and _base_name(target) in names
+        ):
+            return True
+        if el.__visit_name__ != "bindparam":  # a bound value: no clause children
+            stack.extend(_children(el))
+    return False
+
+
+_SELECT_OMIT = ("_correlate", "_correlate_except")
+_EMPTYABLE = (tuple, list)
+
+
+def _children(el: Any) -> list[Any]:
+    # ``Select.get_children`` adds every FROM it derives from the columns and
+    # WHERE, deannotated, so every ORM statement would look Core. Its declared
+    # internals plus the FROMs ``froms_read`` would scope are what counts —
+    # less what the internals already hold: the FROM list itself, and the
+    # columns-clause FROMs of an all-entity ORM columns clause (#559).
+    if isinstance(el, Select):
+        kids = _declared_children(el)
+        if not _orm_columns_only(el):
+            kids.extend(el.columns_clause_froms)
+        if orm_less(el):
+            kids.extend(where_froms(el))
+        return kids
+    if el.__visit_name__ in ("update", "delete"):
+        return [*el.get_children(), *froms_read(el)]
+    return list(el.get_children())
+
+
+def _declared_children(stmt: Select) -> list[Any]:
+    """``HasTraverseInternals.get_children(stmt, omit_attrs=_SELECT_OMIT)``, as a list.
+
+    The same generated dispatch, minus the call per empty collection: most
+    of a SELECT's ~30 declared attributes are ``()`` on any given statement.
+    """
+    kids: list[Any] = []
+    dispatch = _get_children.run_generated_dispatch(
+        stmt, stmt._traverse_internals, "_generated_get_children_traversal"
+    )
+    for attrname, obj, meth in dispatch:
+        if obj is None or (obj.__class__ in _EMPTYABLE and not obj) or attrname in _SELECT_OMIT:
+            continue
+        kids.extend(meth(obj))
+    return kids
+
+
+def _orm_columns_only(stmt: Select) -> bool:
+    """Every ``columns_clause_froms`` entry is ORM-annotated, so the walk prunes it.
+
+    Under the ORM compile plugin an annotated column's FROM is its entity's
+    ``__clause_element__()`` — a ``Mapper``'s or ``AliasedInsp``'s selectable,
+    annotated with ``parententity`` itself. The Core plugin would give the
+    column's own ``_from_objects`` instead, which may be a plain table.
+    """
+    return stmt._propagate_attrs.get("compile_state_plugin") == "orm" and all(
+        _is_orm(c) for c in stmt._raw_columns
+    )
+
+
+# Per class: does attribute lookup of ``table`` end in ``ColumnElement.__getattr__``?
+_COMPARATOR_LOOKUP: dict[type, bool] = {}
+
+
+def _table_of(el: Any) -> Any:
+    """``getattr(el, "table", None)``, exactly — minus the ``AttributeError`` it costs.
+
+    When no class in the MRO defines ``table``, Python tries the instance
+    ``__dict__`` and then ``__getattr__``; for a ``ColumnElement`` that is
+    ``getattr(self.comparator, "table")``, which this calls directly instead
+    of letting ``__getattr__`` format an error message to be thrown away.
+    Any other class (one that defines ``table``, has no ``__dict__`` or its
+    own ``__getattr__``) takes the plain ``getattr``.
+    """
+    cls = el.__class__
+    via_comparator = _COMPARATOR_LOOKUP.get(cls)
+    if via_comparator is None:
+        via_comparator = _COMPARATOR_LOOKUP[cls] = (
+            cls.__getattr__ is ColumnElement.__getattr__
+            if issubclass(cls, ColumnElement)
+            and cls.__dictoffset__ != 0
+            and not any("table" in vars(k) for k in cls.__mro__)
+            else False
+        )
+    if not via_comparator:
+        return getattr(el, "table", None)
+    found = el.__dict__.get("table", _MISSING)
+    return getattr(el.comparator, "table", None) if found is _MISSING else found
+
+
+_MISSING = object()