pgdevkit 0.14.0__py3-none-any.whl → 0.14.2__py3-none-any.whl

pgdevkit/fastapi/json_response.py

@@ -6,9 +6,10 @@ Requires the ``fastapi`` extra: ``pip install pgdevkit[fastapi]``.
 import asyncio
 import json
 import logging
-from collections.abc import AsyncIterator, Mapping
+from contextlib import aclosing
+from collections.abc import AsyncGenerator, Mapping
 from string.templatelib import Template
-from typing import Any
+from typing import Any, cast
 
 import anyio
 from fastapi.responses import StreamingResponse
@@ -24,7 +25,7 @@ from starlette.types import Message, Receive, Scope, Send
 from ..db.fetch import (
     ConnectionSource,
     QueryParams,
-    SqlQueryNoTemplate,
+    SqlQuery,
     _acquire,
     _check_statement_timeout,
     _render,
@@ -45,7 +46,8 @@ class PostgresJsonResponse(StreamingResponse):
     response has been sent, e.g. a ``Depends`` with ``yield``), or ``pool`` (anything with ``.connection()``), or
     register the app's pool once with ``set_default_pool()``. A pooled connection is acquired when streaming starts
     and released when it ends. ``query`` and ``params`` are those of ``fetch_all`` too (a literal string, a
-    ``psycopg.sql`` composable or a sqlglot expression; never a t-string) with values bound via ``params``.
+    ``psycopg.sql`` composable, a sqlglot expression or a t-string) with values bound via ``params``; a t-string carries
+    its own values and takes no ``params``.
 
     The query is wrapped as a subquery, so it cannot be a data-modifying CTE; for that (or for custom JSON) pass
     ``query_produces_json=True`` and make it return one *text* column holding the JSON of each row.
@@ -71,7 +73,7 @@ class PostgresJsonResponse(StreamingResponse):
 
     def __init__(
         self,
-        query: SqlQueryNoTemplate,
+        query: SqlQuery,
         params: QueryParams = None,
         *,
         con: AsyncConnection | None = None,
@@ -87,8 +89,8 @@ class PostgresJsonResponse(StreamingResponse):
         if batch_size < 1:
             raise ValueError(f"batch_size must be >= 1, got {batch_size}")
         _check_statement_timeout(statement_timeout)
-        if isinstance(query, Template):
-            raise TypeError("t-strings can't be wrapped in a subquery: use a literal string or psycopg.sql with params")
+        if isinstance(query, Template) and params is not None:
+            raise TypeError("A t-string query carries its own values; don't pass `params` with it.")
         rendered = _render(query)
         self.query = rendered if query_produces_json else _as_json_rows(rendered)
         self.params = params
@@ -128,11 +130,14 @@ class PostgresJsonResponse(StreamingResponse):
         try:
             async with _acquire(self.con, self.pool) as conn:
                 try:
-                    async for chunk in self._chunks(conn):
-                        if not started:
-                            await _send(send, self._start_message(self.status_code, self.raw_headers))
-                            started = True
-                        await _send(send, {"type": "http.response.body", "body": chunk, "more_body": True})
+                    # aclosing: an `async for` leaves its generator suspended when the body fails (e.g. send()
+                    # raising); the event loop would finalize it later, after the connection is closed.
+                    async with aclosing(self._chunks(conn)) as chunks:
+                        async for chunk in chunks:
+                            if not started:
+                                await _send(send, self._start_message(self.status_code, self.raw_headers))
+                                started = True
+                            await _send(send, {"type": "http.response.body", "body": chunk, "more_body": True})
                 finally:
                     # Runs for completion too, but only acts if the query is still in flight.
                     await _cancel_if_running(conn)
@@ -171,7 +176,7 @@ class PostgresJsonResponse(StreamingResponse):
         await _send(send, self._start_message(status, headers))
         await _send(send, {"type": "http.response.body", "body": body, "more_body": False})
 
-    async def _chunks(self, conn: AsyncConnection) -> AsyncIterator[bytes]:
+    async def _chunks(self, conn: AsyncConnection) -> AsyncGenerator[bytes]:
         """Yield the JSON array in pieces of ``batch_size`` rows. Nothing is yielded before the first batch is
         complete, so a failing query surfaces before any byte (and the status line) is sent."""
         if self.statement_timeout is not None and conn.autocommit:
@@ -183,19 +188,25 @@ class PostgresJsonResponse(StreamingResponse):
             _statement_timeout(conn, self.statement_timeout),
             conn.cursor(row_factory=tuple_row) as cur,  # whatever the connection was configured with
         ):
-            rows = cur.stream(self.query, self.params, size=self.batch_size if _CHUNKED_ROWS else 1)
-            async for (row_json,) in rows:
-                batch.append(row_json)
-                if len(batch) >= self.batch_size:
-                    yield (prefix + ",\n".join(batch)).encode()
-                    batch, prefix = [], ","
+            # (typed as an iterator, but it is an async generator, which is what aclosing() needs)
+            size = self.batch_size if _CHUNKED_ROWS else 1
+            rows = cast("AsyncGenerator[tuple[Any, ...]]", cur.stream(self.query, self.params, size=size))
+            async with aclosing(rows):  # same reason as in stream_response(): finish psycopg's cleanup in order
+                async for (row_json,) in rows:
+                    batch.append(row_json)
+                    if len(batch) >= self.batch_size:
+                        yield (prefix + ",\n".join(batch)).encode()
+                        batch, prefix = [], ","
         if batch or prefix == "[":  # remaining rows, or an empty result
             yield (prefix + ",\n".join(batch) + "]").encode()
         else:  # the last batch was full and has been sent already
             yield b"]"
 
 
-def _as_json_rows(query: Any) -> Composed:
+def _as_json_rows(query: Any) -> Composed | Template:
+    if isinstance(query, Template):
+        # psycopg expands a Template nested with `:q` in place, its own values staying bound parameters
+        return t"select row_to_json(s)::text from (\n{query:q}\n) s"
     if isinstance(query, Composable):
         inner = query
     else:

pgdevkit/skills/pgdevkit/SKILL.md

@@ -272,7 +272,7 @@ async def articles(lng: str) -> PostgresJsonResponse:
     return PostgresJsonResponse(sql.load_sql("articles", "list_articles"), {"lng": lng})
 ```
 
-- Query: from a `.sql` file via `SqlLoader` like any non-trivial query (or `psycopg.sql`/sqlglot), values via `params` (`%(name)s`); a literal string is enforced by the type checker only, never build it from user input. Data-modifying CTE or custom JSON: `query_produces_json=True` (one text column per row).
+- Query: from a `.sql` file via `SqlLoader` like any non-trivial query (or `psycopg.sql`, sqlglot or a t-string for dynamic SQL), values via `params` (`%(name)s`; none with a t-string, it carries its own). That it is a literal is enforced by the type checker only: never build it from user input. Data-modifying CTE or custom JSON: `query_produces_json=True` (one text column per row).
 - `responses={200: {"model": ...}}` keeps the OpenAPI schema typed for the generated frontend client; `response_model` is ignored and rows are **not validated**.
 - Connections as in `fetch_all`: default pool, `pool=`, or `con=`. Prefer the pool: a `con` you opened must outlive the response (`Depends` with `yield`, never `async with ... as conn: return PostgresJsonResponse(q, con=conn)`), and a disconnect aborts its transaction.
 - Errors show as `{"error": "Internal Server Error"}` (500); `expose_errors = IS_DEV` in a subclass shows the text (leaks SQL/values: never in prod). An error after the first byte leaves the array unterminated, so clients fail to parse it.

{pgdevkit-0.14.0.dist-info → pgdevkit-0.14.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pgdevkit
-Version: 0.14.0
+Version: 0.14.2
 Summary: A helper for developing with Postgres
 Requires-Python: >=3.14
 Requires-Dist: docker>=7.1.0
@@ -521,11 +521,12 @@ for a `Response`, and the rows are *not* validated against the model.
   starts and released when it ends. A `con` must stay open until the response has been sent, i.e. come from a `Depends`
   with `yield` (FastAPI >= 0.118); `async with pool.connection() as conn: return PostgresJsonResponse(q, con=conn)`
   closes it too early. Prefer the pool.
-- **Query** — a literal string, a `psycopg.sql` composable or a sqlglot expression, with values bound through `params`
-  (`%(name)s`). Passing only literals is enforced by the type checker, **not at runtime**: the query is wrapped
-  as a subquery, never parsed, so never build it from user input. For a data-modifying CTE, or custom JSON, pass
-  `query_produces_json=True` and return one *text* column per row (a `json` column or NULL fails). A trailing `;`
-  is fine, a `;` followed by a comment is not. t-strings aren't supported (they can't be wrapped).
+- **Query** — a literal string, a `psycopg.sql` composable, a sqlglot expression or a t-string, with values bound
+  through `params` (`%(name)s`; a t-string carries its own values and takes no `params`). Passing only literals
+  is enforced by the type checker, **not at runtime**: the query is wrapped as a subquery, never parsed, so never
+  build it from user input. For a data-modifying CTE, or custom JSON, pass `query_produces_json=True` and return one
+  *text* column per row (a `json` column or NULL fails). A trailing `;` is fine in a string, a `;` followed by a
+  comment is not.
 - **Options** — `batch_size` (rows per chunk, >= 1, default 1000; don't take it from user input),
   `statement_timeout` (seconds, see below), `status_code`, `headers` (e.g. `{"Cache-Control": "max-age=3600"}`).
 

{pgdevkit-0.14.0.dist-info → pgdevkit-0.14.2.dist-info}/RECORD

@@ -30,7 +30,7 @@ pgdevkit/db/model.py,sha256=ntuXonq-SCGkbNw-lvdMS5VuzLjxYRT8O6xaVqiw56I,980
 pgdevkit/db/mssql_crud.py,sha256=yN4izZ0fsFwAs14008JECHH4dqjNbdHUHGEG8kidyNs,11374
 pgdevkit/db/mssql_sql.py,sha256=DO3UMsTFN9pg0tNdaPGb0wf6lWlHGcqwqzkrGVhJF2g,2292
 pgdevkit/fastapi/__init__.py,sha256=Oku0U7wNblWJj_wbyiw_ik299vAsdl1fX6FCth0KliI,84
-pgdevkit/fastapi/json_response.py,sha256=WtQfcYYts4MT0ag5u42nAIdexTJelVsi8umH5dF0Egs,12167
+pgdevkit/fastapi/json_response.py,sha256=9NbsHeGARrhKoORIFEJtMivprXyHe_QvGgu6CEK0DKk,13058
 pgdevkit/testdb/__init__.py,sha256=tphuORo4t0QHQp_gFi6ZHXXgd32w6qUoKlaQCab6izA,366
 pgdevkit/testdb/_docker.py,sha256=-W59YBbcSIl9H_YmySRtVbOV4ImZPHOq9hxmlO-p56s,2807
 pgdevkit/testdb/api.py,sha256=13YgTz6hPcYWfsUlQJhJ7k20-W_4hzepedVaT8gWhxI,9709
@@ -45,10 +45,10 @@ pgdevkit/testdb/mssql/api.py,sha256=Ah95QTsOLvtubyHxRWDywjX9NCvTVgurmANLP5RY2Ck,
 pgdevkit/testdb/mssql/constants.py,sha256=qyA1FCv-2LAQ_C8OydePEXhyG_ZBPPB7vg1686xVpVU,3453
 pgdevkit/testdb/mssql/container.py,sha256=sqJPAuhN1by3kZZ96gLet4pRt3uJmUMO6Kkmvjydg1w,3791
 pgdevkit/docs/database-layout.md,sha256=j9N8GuT63D2oVf9rIOEv8GTWs4yTtjZTGH-zM5Wrg5o,8163
-pgdevkit/skills/pgdevkit/SKILL.md,sha256=vN9TlRYCmidx4shFY0S0XPiVmK6q5Rr714uGhFDCcsE,19181
+pgdevkit/skills/pgdevkit/SKILL.md,sha256=pAJF-Xd6wLeiGJ2VPyOfVaSIw1yWUNczjA-x4HICz_A,19258
 pgdevkit/skills/pgdevkit/references/dynamic-sql.md,sha256=jA-sO8Z10CaFFjYhGHlzZFrvNeXxj1QiAxoCn8RPPVc,2974
 pgdevkit/skills/pgdevkit/references/temporal-tables.md,sha256=LwZnItvQWI7bB0oRHxIfUc0ynnq7N0V5Mnv-QHvFN3Q,1364
-pgdevkit-0.14.0.dist-info/METADATA,sha256=lOm-KoqZLippFCZBum1dEE_-eDsnjtQdzljgkv-VOLQ,31252
-pgdevkit-0.14.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-pgdevkit-0.14.0.dist-info/entry_points.txt,sha256=FK2P55lf0WaGlOZJIINOGgCt8WB7ep0OnPsgnrp80bg,42
-pgdevkit-0.14.0.dist-info/RECORD,,
+pgdevkit-0.14.2.dist-info/METADATA,sha256=QD23CSUwKMdpV_AesUYjoM15XeHW1ftPNHt_WbL5YcU,31283
+pgdevkit-0.14.2.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+pgdevkit-0.14.2.dist-info/entry_points.txt,sha256=FK2P55lf0WaGlOZJIINOGgCt8WB7ep0OnPsgnrp80bg,42
+pgdevkit-0.14.2.dist-info/RECORD,,