feat explain (#241)

Author: mansueli

postgrest/base_request_builder.py

@@ -402,6 +402,25 @@ def __init__(
     ) -> None:
         BaseFilterRequestBuilder.__init__(self, session, headers, params)
 
+    def explain(
+        self: _FilterT,
+        analyze: bool = False,
+        verbose: bool = False,
+        settings: bool = False,
+        buffers: bool = False,
+        wal: bool = False,
+        format: str = "",
+    ) -> _FilterT:
+        options = [
+            key
+            for key, value in locals().items()
+            if key not in ["self", "format"] and value
+        ]
+        options_str = "|".join(options)
+        options_str = f'options="{options_str};"' if options_str else ""
+        self.headers["Accept"] = f"application/vnd.pgrst.plan+{format}; {options_str}"
+        return self
+
     def order(
         self: _FilterT,
         column: str,

tests/_async/test_request_builder.py

@@ -129,6 +129,23 @@ def test_text_search(self, request_builder: AsyncRequestBuilder):
         )
 
 
+class TestExplain:
+    def test_explain_plain(self, request_builder: AsyncRequestBuilder):
+        builder = request_builder.select("*").explain()
+        assert builder.params["select"] == "*"
+        assert "application/vnd.pgrst.plan+" in str(builder.headers.get("accept"))
+
+    def test_explain_options(self, request_builder: AsyncRequestBuilder):
+        builder = request_builder.select("*").explain(
+            format="json", analyze=True, verbose=True, buffers=True, wal=True
+        )
+        assert builder.params["select"] == "*"
+        assert "application/vnd.pgrst.plan+json" in str(builder.headers.get("accept"))
+        assert 'options="analyze|verbose|buffers|wal;' in str(
+            builder.headers.get("accept")
+        )
+
+
 @pytest.fixture
 def api_response_with_error() -> Dict[str, Any]:
     return {