fix(postgrest): align rpc maybe_single with select (#1555)

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: joaompneves

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

@@ -197,6 +197,10 @@ def __init__(self, request: ReqConfig) -> None:
         BaseFilterRequestBuilder.__init__(self, request)
         AsyncSingleRequestBuilder.__init__(self, request)
 
+    def maybe_single(self) -> AsyncMaybeSingleRequestBuilder:
+        """Retrieves at most one row from the result. Result must be at most one row (e.g. using `eq` on a UNIQUE column), otherwise this will result in an error."""
+        return AsyncMaybeSingleRequestBuilder(self.request)
+
 
 class AsyncSelectRequestBuilder(
     AsyncQueryRequestBuilder, BaseSelectRequestBuilder[AsyncClient]

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

@@ -197,6 +197,10 @@ def __init__(self, request: ReqConfig) -> None:
         BaseFilterRequestBuilder.__init__(self, request)
         SyncSingleRequestBuilder.__init__(self, request)
 
+    def maybe_single(self) -> SyncMaybeSingleRequestBuilder:
+        """Retrieves at most one row from the result. Result must be at most one row (e.g. using `eq` on a UNIQUE column), otherwise this will result in an error."""
+        return SyncMaybeSingleRequestBuilder(self.request)
+
 
 class SyncSelectRequestBuilder(
     SyncQueryRequestBuilder, BaseSelectRequestBuilder[Client]

src/postgrest/src/postgrest/base_request_builder.py

@@ -668,11 +668,6 @@ def single(self) -> Self:
         self.request.headers["Accept"] = "application/vnd.pgrst.object+json"
         return self
 
-    def maybe_single(self) -> Self:
-        """Retrieves at most one row from the result. Result must be at most one row (e.g. using `eq` on a UNIQUE column), otherwise this will result in an error."""
-        self.request.headers["Accept"] = "application/vnd.pgrst.object+json"
-        return self
-
     def csv(self) -> Self:
         """Specify that the query must retrieve data as a single CSV string."""
         self.request.headers["Accept"] = "text/csv"

src/postgrest/tests/_async/test_filter_request_builder_integration.py

@@ -1,4 +1,7 @@
+import pytest
+
 from postgrest import CountMethod
+from postgrest.exceptions import APIError
 
 from .client import rest_client, rest_client_httpx
 
@@ -76,6 +79,23 @@ async def test_no_match_maybe_single():
     assert res is None
 
 
+async def test_maybe_single_multiple_rows():
+    with pytest.raises(APIError) as exc_info:
+        await (
+            rest_client()
+            .from_("countries")
+            .select("country_name, iso")
+            .lte("numcode", 8)
+            .gte("numcode", 4)
+            .maybe_single()
+            .execute()
+        )
+
+    assert exc_info.value.code == "406"
+    assert exc_info.value.message == "Cannot coerce the result to a single JSON object"
+    assert exc_info.value.details == "The result contains more than one row."
+
+
 async def test_equals():
     res = (
         await rest_client()
@@ -500,6 +520,47 @@ async def test_rpc_with_single():
     assert res.data == {"nicename": "Albania", "country_name": "ALBANIA", "iso": "AL"}
 
 
+async def test_rpc_with_maybe_single():
+    res = (
+        await rest_client()
+        .rpc("list_stored_countries", {})
+        .select("nicename, country_name, iso")
+        .eq("nicename", "Albania")
+        .maybe_single()
+        .execute()
+    )
+
+    assert res.data == {"nicename": "Albania", "country_name": "ALBANIA", "iso": "AL"}
+
+
+async def test_rpc_with_maybe_single_no_match():
+    res = (
+        await rest_client()
+        .rpc("list_stored_countries", {})
+        .select("nicename, country_name, iso")
+        .eq("nicename", "Wonderland")
+        .maybe_single()
+        .execute()
+    )
+
+    assert res is None
+
+
+async def test_rpc_with_maybe_single_multiple_rows():
+    with pytest.raises(APIError) as exc_info:
+        await (
+            rest_client()
+            .rpc("list_stored_countries", {})
+            .select("nicename, country_name, iso")
+            .maybe_single()
+            .execute()
+        )
+
+    assert exc_info.value.code == "406"
+    assert exc_info.value.message == "Cannot coerce the result to a single JSON object"
+    assert exc_info.value.details == "The result contains more than one row."
+
+
 async def test_rpc_with_limit():
     res = (
         await rest_client()

src/postgrest/tests/_sync/test_filter_request_builder_integration.py

@@ -1,4 +1,7 @@
+import pytest
+
 from postgrest import CountMethod
+from postgrest.exceptions import APIError
 
 from .client import rest_client, rest_client_httpx
 
@@ -76,6 +79,23 @@ def test_no_match_maybe_single():
     assert res is None
 
 
+def test_maybe_single_multiple_rows():
+    with pytest.raises(APIError) as exc_info:
+        (
+            rest_client()
+            .from_("countries")
+            .select("country_name, iso")
+            .lte("numcode", 8)
+            .gte("numcode", 4)
+            .maybe_single()
+            .execute()
+        )
+
+    assert exc_info.value.code == "406"
+    assert exc_info.value.message == "Cannot coerce the result to a single JSON object"
+    assert exc_info.value.details == "The result contains more than one row."
+
+
 def test_equals():
     res = (
         rest_client()
@@ -493,6 +513,47 @@ def test_rpc_with_single():
     assert res.data == {"nicename": "Albania", "country_name": "ALBANIA", "iso": "AL"}
 
 
+def test_rpc_with_maybe_single():
+    res = (
+        rest_client()
+        .rpc("list_stored_countries", {})
+        .select("nicename, country_name, iso")
+        .eq("nicename", "Albania")
+        .maybe_single()
+        .execute()
+    )
+
+    assert res.data == {"nicename": "Albania", "country_name": "ALBANIA", "iso": "AL"}
+
+
+def test_rpc_with_maybe_single_no_match():
+    res = (
+        rest_client()
+        .rpc("list_stored_countries", {})
+        .select("nicename, country_name, iso")
+        .eq("nicename", "Wonderland")
+        .maybe_single()
+        .execute()
+    )
+
+    assert res is None
+
+
+def test_rpc_with_maybe_single_multiple_rows():
+    with pytest.raises(APIError) as exc_info:
+        (
+            rest_client()
+            .rpc("list_stored_countries", {})
+            .select("nicename, country_name, iso")
+            .maybe_single()
+            .execute()
+        )
+
+    assert exc_info.value.code == "406"
+    assert exc_info.value.message == "Cannot coerce the result to a single JSON object"
+    assert exc_info.value.details == "The result contains more than one row."
+
+
 def test_rpc_with_limit():
     res = (
         rest_client()