encore-dev 2.0.0a16__tar.gz → 2.0.0a17__tar.gz

{encore_dev-2.0.0a16 → encore_dev-2.0.0a17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: encore-dev
-Version: 2.0.0a16
+Version: 2.0.0a17
 Summary: Encore SDK for Python — infrastructure resources
 Author: Encore
 License: MPL-2.0
@@ -78,7 +78,8 @@ Declare `postgres.Database("orders", migrations="./migrations")` at module scope
 reference a database declared elsewhere.
 
 `query(sql, *params)` returns a `Cursor`. Use `async for` to stream rows,
-`await query.one()` to fetch one row or `None` (rejecting multiple rows), or
+`await query.one()` to fetch exactly one row (raising `EncoreError` on no rows or
+more than one), `await query.first()` to fetch the first row or `None`, or
 `await query.all()` to collect all rows in a list. Each query can be consumed
 once. Reusing it or mixing helpers with iteration raises `EncoreError`, including
 after partial iteration or an error. Helpers close their cursors automatically.
@@ -90,7 +91,7 @@ dictionaries keyed by column name. Values are bound with `$1`, `$2`, etc.
 
 ```python
 async def find_order(database: postgres.Queryable, order_id: int):
-    return await database.query("SELECT * FROM orders WHERE id = $1", order_id).one()
+    return await database.query("SELECT * FROM orders WHERE id = $1", order_id).first()
 
 
 async def handle_order(order_id: int):

{encore_dev-2.0.0a16 → encore_dev-2.0.0a17}/README.md

@@ -65,7 +65,8 @@ Declare `postgres.Database("orders", migrations="./migrations")` at module scope
 reference a database declared elsewhere.
 
 `query(sql, *params)` returns a `Cursor`. Use `async for` to stream rows,
-`await query.one()` to fetch one row or `None` (rejecting multiple rows), or
+`await query.one()` to fetch exactly one row (raising `EncoreError` on no rows or
+more than one), `await query.first()` to fetch the first row or `None`, or
 `await query.all()` to collect all rows in a list. Each query can be consumed
 once. Reusing it or mixing helpers with iteration raises `EncoreError`, including
 after partial iteration or an error. Helpers close their cursors automatically.
@@ -77,7 +78,7 @@ dictionaries keyed by column name. Values are bound with `$1`, `$2`, etc.
 
 ```python
 async def find_order(database: postgres.Queryable, order_id: int):
-    return await database.query("SELECT * FROM orders WHERE id = $1", order_id).one()
+    return await database.query("SELECT * FROM orders WHERE id = $1", order_id).first()
 
 
 async def handle_order(order_id: int):

{encore_dev-2.0.0a16 → encore_dev-2.0.0a17}/encore/storage/postgres/__init__.py

@@ -53,7 +53,7 @@ class ExecResult:
 
 
 class Cursor:
-    """A SQL cursor consumed once by iteration, one(), or all().
+    """A SQL cursor consumed once by iteration, one(), first(), or all().
 
     Execution starts when iteration advances or a helper is awaited. Starting
     one consumption mode prevents any other consumption of this query, including
@@ -62,8 +62,8 @@ class Cursor:
 
     Exhaust a stream or call aclose() to release its connection. For early exits,
     use the query as an async context manager. Entering the context does not
-    execute or consume the query. Leaving it closes the stream. The one() and
-    all() helpers close their cursors automatically.
+    execute or consume the query. Leaving it closes the stream. The one(),
+    first(), and all() helpers close their cursors automatically.
     """
 
     def __init__(self, rows: AsyncGenerator[Row, None]) -> None:
@@ -89,23 +89,47 @@ class Cursor:
         """
         return self._consume()
 
-    async def one(self) -> Row | None:
-        """Return zero or one row and close the cursor.
+    async def one(self) -> Row:
+        """Return the query's only row and close the cursor.
+
+        Use first() when the query may match no rows.
 
         Returns:
-            A dictionary of column names to values, or None if no rows match.
+            A dictionary of column names to values.
 
         Raises:
-            EncoreError: The query fails or returns more than one row.
+            EncoreError: The query fails, returns no rows, or returns more than
+                one row.
         """
         rows = self._consume()
         try:
-            first = None
+            found = None
             async for row in rows:
-                if first is not None:
+                if found is not None:
                     raise EncoreError("query returned more than one row")
-                first = row
-            return first
+                found = row
+            if found is None:
+                raise EncoreError("query returned no rows")
+            return found
+        finally:
+            await rows.aclose()
+
+    async def first(self) -> Row | None:
+        """Return the query's first row, if any, and close the cursor.
+
+        Rows after the first are not read.
+
+        Returns:
+            A dictionary of column names to values, or None if no rows match.
+
+        Raises:
+            EncoreError: The query fails.
+        """
+        rows = self._consume()
+        try:
+            async for row in rows:
+                return row
+            return None
         finally:
             await rows.aclose()
 
@@ -231,9 +255,9 @@ class Queryable:
     def query(self, sql: str, *params: Any) -> Cursor:
         """Create a query for streaming or fetching rows.
 
-        Consume the query once with async iteration, one(), or all(). No SQL runs
-        until iteration advances or a helper is awaited. Exhaust the stream or
-        close it before reusing its connection or transaction. Use
+        Consume the query once with async iteration, one(), first(), or all().
+        No SQL runs until iteration advances or a helper is awaited. Exhaust the
+        stream or close it before reusing its connection or transaction. Use
         the query as an async context manager when leaving iteration early.
 
         Args:
@@ -445,9 +469,9 @@ class Database:
     def query(self, sql: str, *params: Any) -> Cursor:
         """Create a query for streaming or fetching rows.
 
-        Consume the query once with async iteration, one(), or all(). No SQL runs
-        until iteration advances or a helper is awaited. See Queryable.query
-        for stream cleanup requirements.
+        Consume the query once with async iteration, one(), first(), or all().
+        No SQL runs until iteration advances or a helper is awaited. See
+        Queryable.query for stream cleanup requirements.
 
         Args:
             sql: A SQL statement with positional placeholders such as $1 and $2.

{encore_dev-2.0.0a16 → encore_dev-2.0.0a17}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "encore-dev"
-version = "2.0.0a16"
+version = "2.0.0a17"
 description = "Encore SDK for Python — infrastructure resources"
 readme = "README.md"
 requires-python = ">=3.9"

{encore_dev-2.0.0a16 → encore_dev-2.0.0a17}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "encore-dev"
-version = "2.0.0a16"
+version = "2.0.0a17"
 description = "Encore SDK for Python — infrastructure resources"
 readme = "README.md"
 requires-python = ">=3.9"