[1d] Add returning() to queryset update() and delete()

[davegaeddert]

What

Adds a queryset-chain API for Postgres RETURNING on set-based writes:

# No args -> RETURNING every concrete column -> list of hydrated model instances
running = Job.query.filter(status="pending").returning().update(status="running")

# Field refs -> RETURNING those columns -> list of dicts
deleted = Event.query.filter(created_at__lt=cutoff).returning(Event.id, Event.payload).delete()

# Unchanged: int rowcount when returning() is not used
n = Job.query.filter(...).update(status="x")

returning() is a queryset clone method set before the write, so the SQL is fully known before execution.

Semantics

• No-arg returning() -> RETURNING all concrete columns -> list of model instances (converters applied). For update() these reflect post-update values; for delete(), the rows as they were.
• returning(*fields: Field[Any]) -> RETURNING those columns -> list of dicts (not partial instances), keyed by field name. Fields are passed as typed field references (Event.id, not "id"); a string argument raises TypeError pointing at the Model.field form, and a field belonging to a different model raises FieldError. Validation happens in _resolve_returning_fields() at the returning() call, not when the write runs.
• Without returning() -> update()/delete() return an int exactly as before.
• RETURNING only reports the statement's own target-table rows; cascade-deleted children never appear (documented in the delete docstring and README).
• .values() before a returning write raises TypeError rather than misbehaving silently.

Typing

returning() returns a ReturningQuerySet[T, R] flavor (a two-type-parameter subclass) whose update()/delete() are typed -> R. Two overloads pin R: no-arg -> list[T], field refs -> list[dict[str, Any]]. The plain QuerySet keeps update/delete -> int. Verified with assert_type that the four shapes resolve honestly (int / list[Model] / list[dict]).

Implementation

• RETURNING selection stored on UpdateQuery/DeleteQuery; the clause is emitted by SQLUpdateCompiler.as_sql and SQLDeleteCompiler._as_sql (reusing the insert path's returning_columns and convert_returning_rows helpers). The JOIN -> WHERE id IN (subquery) rewrite stays a single statement, so RETURNING works there too.
• No changes to insert / bulk_create / upsert / bulk_update paths.

Tests

New public tests in plain-postgres/tests/public/test_returning.py: instances reflect new values, dicts for named delete, unchanged int behavior, JSON converter application, bad-field validation (string arg, wrong-model field), returning()-before-filter(), empty result sets, and a FK-cascade case proving only target-table rows are returned.

./scripts/fix, ./scripts/test plain-postgres, full ./scripts/test, and ./scripts/type-check plain-postgres all pass.

[pullapprove5]

PASS: 1 review scope passed

	Scope	Progress
✅	all	0/0

View in PullApprove

Next steps:

• @davegaeddert: Merge or close