feat(postgrest): return a select builder from insert, upsert, update and delete

`insert()` and `upsert()` returned a query builder and `update()` and `delete()`
returned a filter builder. Neither exposes `single()`, `maybe_single()`, `csv()`,
`explain()`, `order()`, `limit()` or `range()`, so a chain that reads naturally
in the JS client has no equivalent in Python:

    client.from_("users").insert({...}).select().single().execute()

`select()` on those builders returns `self`, so the chain stops at a builder that
never had `single()` to begin with. In supabase-js all four of these methods
return a `PostgrestFilterBuilder`, which carries the transform methods.

Return `SelectRequestBuilder` from all four instead. It already derives from the
query builder and from the filter builder, so this only widens the surface: every
method that worked before still works, on the same object, with the same request
state. Filters after `update()` and `delete()` are unaffected.

The sync package is edited by hand rather than through `make build-sync`. The
generated output currently differs from the committed `_sync` in ways unrelated
to this change (`asyncio.sleep` in place of `time.sleep` in `send_with_retry`,
among others), so regenerating would have pulled unrelated breakage into this PR.

Closes #1553

Author: karpovantonme

src/postgrest/src/postgrest/_async/request_builder.py

@@ -332,7 +332,7 @@ def insert(
         returning: ReturnMethod = ReturnMethod.representation,
         upsert: bool = False,
         default_to_null: bool = True,
-    ) -> AsyncQueryRequestBuilder:
+    ) -> AsyncSelectRequestBuilder:
         """Run an INSERT query.
 
         Args:
@@ -344,7 +344,7 @@ def insert(
                 Otherwise, use the default value for the column.
                 Only applies for bulk inserts.
         Returns:
-            :class:`AsyncQueryRequestBuilder`
+            :class:`AsyncSelectRequestBuilder`
         """
         method, params, headers, json = pre_insert(
             json,
@@ -363,7 +363,7 @@ def insert(
             headers=headers,
             json=json,
         )
-        return AsyncQueryRequestBuilder(request)
+        return AsyncSelectRequestBuilder(request)
 
     def upsert(
         self,
@@ -374,7 +374,7 @@ def upsert(
         ignore_duplicates: bool = False,
         on_conflict: str = "",
         default_to_null: bool = True,
-    ) -> AsyncQueryRequestBuilder:
+    ) -> AsyncSelectRequestBuilder:
         """Run an upsert (INSERT ... ON CONFLICT DO UPDATE) query.
 
         Args:
@@ -388,7 +388,7 @@ def upsert(
                 not when merging with existing rows under `ignoreDuplicates: false`.
                 This also only applies when doing bulk upserts.
         Returns:
-            :class:`AsyncQueryRequestBuilder`
+            :class:`AsyncSelectRequestBuilder`
         """
         method, params, headers, json = pre_upsert(
             json,
@@ -408,23 +408,23 @@ def upsert(
             headers=headers,
             json=json,
         )
-        return AsyncQueryRequestBuilder(request)
+        return AsyncSelectRequestBuilder(request)
 
     def update(
         self,
         json: JSON,
         *,
         count: Optional[CountMethod] = None,
         returning: ReturnMethod = ReturnMethod.representation,
-    ) -> AsyncFilterRequestBuilder:
+    ) -> AsyncSelectRequestBuilder:
         """Run an UPDATE query.
 
         Args:
             json: The updated fields.
             count: The method to use to get the count of rows returned.
             returning: Either 'minimal' or 'representation'
         Returns:
-            :class:`AsyncFilterRequestBuilder`
+            :class:`AsyncSelectRequestBuilder`
         """
         method, params, headers, json = pre_update(
             json,
@@ -441,21 +441,21 @@ def update(
             headers=headers,
             json=json,
         )
-        return AsyncFilterRequestBuilder(request)
+        return AsyncSelectRequestBuilder(request)
 
     def delete(
         self,
         *,
         count: Optional[CountMethod] = None,
         returning: ReturnMethod = ReturnMethod.representation,
-    ) -> AsyncFilterRequestBuilder:
+    ) -> AsyncSelectRequestBuilder:
         """Run a DELETE query.
 
         Args:
             count: The method to use to get the count of rows returned.
             returning: Either 'minimal' or 'representation'
         Returns:
-            :class:`AsyncFilterRequestBuilder`
+            :class:`AsyncSelectRequestBuilder`
         """
         method, params, headers, json = pre_delete(
             count=count,
@@ -471,4 +471,4 @@ def delete(
             headers=headers,
             json=json,
         )
-        return AsyncFilterRequestBuilder(request)
+        return AsyncSelectRequestBuilder(request)

src/postgrest/src/postgrest/_sync/request_builder.py

@@ -332,7 +332,7 @@ def insert(
         returning: ReturnMethod = ReturnMethod.representation,
         upsert: bool = False,
         default_to_null: bool = True,
-    ) -> SyncQueryRequestBuilder:
+    ) -> SyncSelectRequestBuilder:
         """Run an INSERT query.
 
         Args:
@@ -344,7 +344,7 @@ def insert(
                 Otherwise, use the default value for the column.
                 Only applies for bulk inserts.
         Returns:
-            :class:`SyncQueryRequestBuilder`
+            :class:`SyncSelectRequestBuilder`
         """
         method, params, headers, json = pre_insert(
             json,
@@ -363,7 +363,7 @@ def insert(
             headers=headers,
             json=json,
         )
-        return SyncQueryRequestBuilder(request)
+        return SyncSelectRequestBuilder(request)
 
     def upsert(
         self,
@@ -374,7 +374,7 @@ def upsert(
         ignore_duplicates: bool = False,
         on_conflict: str = "",
         default_to_null: bool = True,
-    ) -> SyncQueryRequestBuilder:
+    ) -> SyncSelectRequestBuilder:
         """Run an upsert (INSERT ... ON CONFLICT DO UPDATE) query.
 
         Args:
@@ -388,7 +388,7 @@ def upsert(
                 not when merging with existing rows under `ignoreDuplicates: false`.
                 This also only applies when doing bulk upserts.
         Returns:
-            :class:`SyncQueryRequestBuilder`
+            :class:`SyncSelectRequestBuilder`
         """
         method, params, headers, json = pre_upsert(
             json,
@@ -408,23 +408,23 @@ def upsert(
             headers=headers,
             json=json,
         )
-        return SyncQueryRequestBuilder(request)
+        return SyncSelectRequestBuilder(request)
 
     def update(
         self,
         json: JSON,
         *,
         count: Optional[CountMethod] = None,
         returning: ReturnMethod = ReturnMethod.representation,
-    ) -> SyncFilterRequestBuilder:
+    ) -> SyncSelectRequestBuilder:
         """Run an UPDATE query.
 
         Args:
             json: The updated fields.
             count: The method to use to get the count of rows returned.
             returning: Either 'minimal' or 'representation'
         Returns:
-            :class:`SyncFilterRequestBuilder`
+            :class:`SyncSelectRequestBuilder`
         """
         method, params, headers, json = pre_update(
             json,
@@ -441,21 +441,21 @@ def update(
             headers=headers,
             json=json,
         )
-        return SyncFilterRequestBuilder(request)
+        return SyncSelectRequestBuilder(request)
 
     def delete(
         self,
         *,
         count: Optional[CountMethod] = None,
         returning: ReturnMethod = ReturnMethod.representation,
-    ) -> SyncFilterRequestBuilder:
+    ) -> SyncSelectRequestBuilder:
         """Run a DELETE query.
 
         Args:
             count: The method to use to get the count of rows returned.
             returning: Either 'minimal' or 'representation'
         Returns:
-            :class:`SyncFilterRequestBuilder`
+            :class:`SyncSelectRequestBuilder`
         """
         method, params, headers, json = pre_delete(
             count=count,
@@ -471,4 +471,4 @@ def delete(
             headers=headers,
             json=json,
         )
-        return SyncFilterRequestBuilder(request)
+        return SyncSelectRequestBuilder(request)

src/postgrest/tests/_async/test_request_builder.py

@@ -4,7 +4,11 @@
 from httpx import AsyncClient, Headers, QueryParams, Request, Response
 from yarl import URL
 
-from postgrest import AsyncRequestBuilder, AsyncSingleRequestBuilder
+from postgrest import (
+    AsyncMaybeSingleRequestBuilder,
+    AsyncRequestBuilder,
+    AsyncSingleRequestBuilder,
+)
 from postgrest._async.request_builder import RequestConfig
 from postgrest.base_request_builder import APIResponse, SingleAPIResponse
 from postgrest.types import JSON, CountMethod, ReturnMethod
@@ -140,6 +144,34 @@ def test_insert_with_select_forces_representation(
             "return=representation",
         ]
 
+    def test_insert_with_select_single(self, request_builder: AsyncRequestBuilder):
+        builder = request_builder.insert({"key1": "val1"}).select("id").single()
+
+        assert isinstance(builder, AsyncSingleRequestBuilder)
+        assert builder.request.params["select"] == "id"
+        assert builder.request.headers["accept"] == "application/vnd.pgrst.object+json"
+        assert builder.request.headers.get_list("prefer", True) == [
+            "return=representation"
+        ]
+        assert builder.request.http_method == "POST"
+
+    def test_insert_with_select_maybe_single(
+        self, request_builder: AsyncRequestBuilder
+    ):
+        builder = request_builder.insert({"key1": "val1"}).select("id").maybe_single()
+
+        assert isinstance(builder, AsyncMaybeSingleRequestBuilder)
+        assert builder.request.params["select"] == "id"
+        assert builder.request.http_method == "POST"
+
+    def test_upsert_with_select_single(self, request_builder: AsyncRequestBuilder):
+        builder = request_builder.upsert({"key1": "val1"}).select("id").single()
+
+        assert isinstance(builder, AsyncSingleRequestBuilder)
+        assert builder.request.params["select"] == "id"
+        assert builder.request.headers["accept"] == "application/vnd.pgrst.object+json"
+        assert builder.request.http_method == "POST"
+
     def test_bulk_upsert_with_default(self, request_builder: AsyncRequestBuilder):
         builder = request_builder.upsert(
             [{"key1": "val1", "key2": "val2"}, {"key3": "val3"}], default_to_null=False
@@ -194,6 +226,21 @@ def test_update_with_select(self, request_builder: AsyncRequestBuilder):
         assert builder.request.params["id"] == "eq.1"
         assert builder.request.params["select"] == "id"
 
+    def test_update_with_select_single(self, request_builder: AsyncRequestBuilder):
+        builder = request_builder.update({"key1": "val1"}).eq("id", 1).select().single()
+
+        assert isinstance(builder, AsyncSingleRequestBuilder)
+        assert builder.request.params["id"] == "eq.1"
+        assert builder.request.headers["accept"] == "application/vnd.pgrst.object+json"
+        assert builder.request.http_method == "PATCH"
+
+    def test_update_with_order_and_limit(self, request_builder: AsyncRequestBuilder):
+        builder = request_builder.update({"key1": "val1"}).order("id").limit(1)
+
+        assert builder.request.params["order"] == "id.asc"
+        assert builder.request.params["limit"] == "1"
+        assert builder.request.http_method == "PATCH"
+
 
 class TestDelete:
     def test_delete(self, request_builder: AsyncRequestBuilder):
@@ -230,6 +277,14 @@ def test_delete_with_select(self, request_builder: AsyncRequestBuilder):
         assert builder.request.params["id"] == "eq.1"
         assert builder.request.params["select"] == "id"
 
+    def test_delete_with_select_single(self, request_builder: AsyncRequestBuilder):
+        builder = request_builder.delete().eq("id", 1).select("id").single()
+
+        assert isinstance(builder, AsyncSingleRequestBuilder)
+        assert builder.request.params["id"] == "eq.1"
+        assert builder.request.headers["accept"] == "application/vnd.pgrst.object+json"
+        assert builder.request.http_method == "DELETE"
+
 
 class TestTextSearch:
     def test_text_search(self, request_builder: AsyncRequestBuilder):

src/postgrest/tests/_sync/test_request_builder.py

@@ -4,7 +4,11 @@
 from httpx import Client, Headers, QueryParams, Request, Response
 from yarl import URL
 
-from postgrest import SyncRequestBuilder, SyncSingleRequestBuilder
+from postgrest import (
+    SyncMaybeSingleRequestBuilder,
+    SyncRequestBuilder,
+    SyncSingleRequestBuilder,
+)
 from postgrest._async.request_builder import RequestConfig
 from postgrest.base_request_builder import APIResponse, SingleAPIResponse
 from postgrest.types import JSON, CountMethod, ReturnMethod
@@ -140,6 +144,32 @@ def test_insert_with_select_forces_representation(
             "return=representation",
         ]
 
+    def test_insert_with_select_single(self, request_builder: SyncRequestBuilder):
+        builder = request_builder.insert({"key1": "val1"}).select("id").single()
+
+        assert isinstance(builder, SyncSingleRequestBuilder)
+        assert builder.request.params["select"] == "id"
+        assert builder.request.headers["accept"] == "application/vnd.pgrst.object+json"
+        assert builder.request.headers.get_list("prefer", True) == [
+            "return=representation"
+        ]
+        assert builder.request.http_method == "POST"
+
+    def test_insert_with_select_maybe_single(self, request_builder: SyncRequestBuilder):
+        builder = request_builder.insert({"key1": "val1"}).select("id").maybe_single()
+
+        assert isinstance(builder, SyncMaybeSingleRequestBuilder)
+        assert builder.request.params["select"] == "id"
+        assert builder.request.http_method == "POST"
+
+    def test_upsert_with_select_single(self, request_builder: SyncRequestBuilder):
+        builder = request_builder.upsert({"key1": "val1"}).select("id").single()
+
+        assert isinstance(builder, SyncSingleRequestBuilder)
+        assert builder.request.params["select"] == "id"
+        assert builder.request.headers["accept"] == "application/vnd.pgrst.object+json"
+        assert builder.request.http_method == "POST"
+
     def test_bulk_upsert_with_default(self, request_builder: SyncRequestBuilder):
         builder = request_builder.upsert(
             [{"key1": "val1", "key2": "val2"}, {"key3": "val3"}], default_to_null=False
@@ -194,6 +224,21 @@ def test_update_with_select(self, request_builder: SyncRequestBuilder):
         assert builder.request.params["id"] == "eq.1"
         assert builder.request.params["select"] == "id"
 
+    def test_update_with_select_single(self, request_builder: SyncRequestBuilder):
+        builder = request_builder.update({"key1": "val1"}).eq("id", 1).select().single()
+
+        assert isinstance(builder, SyncSingleRequestBuilder)
+        assert builder.request.params["id"] == "eq.1"
+        assert builder.request.headers["accept"] == "application/vnd.pgrst.object+json"
+        assert builder.request.http_method == "PATCH"
+
+    def test_update_with_order_and_limit(self, request_builder: SyncRequestBuilder):
+        builder = request_builder.update({"key1": "val1"}).order("id").limit(1)
+
+        assert builder.request.params["order"] == "id.asc"
+        assert builder.request.params["limit"] == "1"
+        assert builder.request.http_method == "PATCH"
+
 
 class TestDelete:
     def test_delete(self, request_builder: SyncRequestBuilder):
@@ -230,6 +275,14 @@ def test_delete_with_select(self, request_builder: SyncRequestBuilder):
         assert builder.request.params["id"] == "eq.1"
         assert builder.request.params["select"] == "id"
 
+    def test_delete_with_select_single(self, request_builder: SyncRequestBuilder):
+        builder = request_builder.delete().eq("id", 1).select("id").single()
+
+        assert isinstance(builder, SyncSingleRequestBuilder)
+        assert builder.request.params["id"] == "eq.1"
+        assert builder.request.headers["accept"] == "application/vnd.pgrst.object+json"
+        assert builder.request.http_method == "DELETE"
+
 
 class TestTextSearch:
     def test_text_search(self, request_builder: SyncRequestBuilder):