feat: add HTTP method selection with GET default for read queries [release]

Author: arcangelo7

.coverage

@@ -43,6 +43,7 @@ export default defineConfig({
 				{
 					label: 'Configuration',
 					items: [
+						{ label: 'HTTP methods', slug: 'configuration/http-methods' },
 						{ label: 'Connection pooling', slug: 'configuration/connection-pooling' },
 						{ label: 'Retry settings', slug: 'configuration/retry-settings' },
 					],

docs/astro.config.mjs

@@ -0,0 +1,64 @@
+---
+title: HTTP methods
+description: Configure GET and POST for SPARQL requests
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+sparqlite supports both GET and POST HTTP methods for SPARQL requests, following the SPARQL 1.1 Protocol specification.
+
+## Default methods
+
+Each query type uses a default HTTP method:
+
+| Query type | Default method | Reason |
+|------------|---------------|--------|
+| SELECT | GET | Read operation, cacheable |
+| ASK | GET | Read operation, cacheable |
+| CONSTRUCT | GET | Read operation, cacheable |
+| DESCRIBE | GET | Read operation, cacheable |
+| UPDATE | POST | Write operation (required by spec) |
+
+GET requests pass the query as a URL parameter (`?query=...`). POST requests pass the query in the request body as form-encoded data.
+
+## Overriding the default method
+
+All read query methods accept a `method` keyword argument:
+
+```python
+from sparqlite import SPARQLClient
+
+with SPARQLClient("https://opencitations.net/meta/sparql") as client:
+    # Use POST for a long SELECT query that may exceed URL length limits
+    result = client.query(long_query, method="POST")
+
+    # Use POST for ASK
+    exists = client.ask(query, method="POST")
+
+    # Use POST for CONSTRUCT
+    triples = client.construct(query, method="POST")
+
+    # Use POST for DESCRIBE
+    data = client.describe(query, method="POST")
+```
+
+<Aside type="note">
+  The `update()` method always uses POST. The SPARQL 1.1 Protocol specification requires POST for update operations.
+</Aside>
+
+## When to use POST for read queries
+
+Use `method="POST"` when:
+
+- The query string is very long and may exceed URL length limits (typically 2000-8000 characters depending on the server)
+- You want to avoid caching of results
+
+```python
+with SPARQLClient("https://opencitations.net/meta/sparql") as client:
+    long_query = "SELECT * WHERE { " + " UNION ".join(
+        f"{{ ?s <http://example.org/p{i}> ?o }}" for i in range(100)
+    ) + " }"
+
+    # POST avoids URL length issues
+    result = client.query(long_query, method="POST")
+```

docs/src/content/docs/configuration/http-methods.mdx

@@ -123,5 +123,6 @@ with SPARQLClient("https://opencitations.net/meta/sparql") as client:
 ## Next steps
 
 - Learn about [SELECT queries](/sparqlite/guides/select-queries/) in detail
+- Configure [HTTP methods](/sparqlite/configuration/http-methods/) (GET vs POST)
 - Understand [connection pooling](/sparqlite/configuration/connection-pooling/) for performance
 - Configure [retry settings](/sparqlite/configuration/retry-settings/) for reliability

docs/src/content/docs/getting-started/quick-start.mdx

@@ -16,6 +16,7 @@ dependencies = [
 dev = [
     "coverage>=7.10.7",
     "isort>=6.1.0",
+    "pyright>=1.1.408",
     "pytest>=8.4.2",
     "pytest-cov>=7.0.0",
     "virtuoso-utilities>=1.6.1",

pyproject.toml

@@ -1,11 +1,12 @@
 """sparqlite - a modern, lightweight SPARQL 1.1 client for Python."""
 
-from sparqlite.client import SPARQLClient
+from sparqlite.client import HTTPMethod, SPARQLClient
 from sparqlite.exceptions import EndpointError, QueryError, SPARQLError
 
 __version__ = "0.1.0"
 
 __all__ = [
+    "HTTPMethod",
     "SPARQLClient",
     "SPARQLError",
     "QueryError",

src/sparqlite/__init__.py

@@ -4,15 +4,17 @@
 import time
 import warnings
 from io import BytesIO
+from typing import Literal
 from urllib.parse import urlencode
 
 import pycurl
 
 from sparqlite.exceptions import EndpointError, QueryError
 
+HTTPMethod = Literal["GET", "POST"]
+
 
 class SPARQLClient:
-    """Synchronous SPARQL 1.1 client with connection pooling and automatic retry."""
 
     def __init__(
         self,
@@ -22,24 +24,16 @@ def __init__(
         backoff_factor: float = 0.5,
         timeout: float | None = None,
     ):
-        """Initialize the SPARQL client.
-
-        Args:
-            endpoint: The SPARQL endpoint URL.
-            max_retries: Maximum number of retry attempts for transient errors.
-            backoff_factor: Factor for exponential backoff (wait = factor * 2^retry).
-            timeout: Request timeout in seconds. None means no timeout.
-        """
         self.endpoint = endpoint
         self.max_retries = max_retries
         self.backoff_factor = backoff_factor
         self.timeout = timeout
-        self._curl = pycurl.Curl()
+        self._curl: pycurl.Curl | None = pycurl.Curl()
 
     def __enter__(self) -> "SPARQLClient":
         return self
 
-    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+    def __exit__(self, exc_type: object, exc_val: object, exc_tb: object) -> None:
         self.close()
 
     def __del__(self) -> None:
@@ -53,10 +47,6 @@ def __del__(self) -> None:
         self.close()
 
     def close(self) -> None:
-        """Close the client and release resources.
-
-        This method is idempotent - calling it multiple times is safe.
-        """
         if self._curl is not None:
             self._curl.close()
             self._curl = None
@@ -66,42 +56,49 @@ def _request(
         query: str,
         accept: str,
         *,
+        method: HTTPMethod = "GET",
         is_update: bool = False,
     ) -> bytes:
-        """Execute an HTTP request with retry logic."""
-        last_error = None
+        if self._curl is None:
+            raise EndpointError("Client is closed")
+
+        curl = self._curl
+        last_error: EndpointError | None = None
 
         for attempt in range(self.max_retries + 1):
             if attempt > 0:
                 wait_time = self.backoff_factor * (2**attempt)
                 time.sleep(wait_time)
 
             buffer = BytesIO()
-            self._curl.reset()
+            curl.reset()
 
             if self.timeout is not None:
-                self._curl.setopt(pycurl.TIMEOUT_MS, int(self.timeout * 1000))
+                curl.setopt(pycurl.TIMEOUT_MS, int(self.timeout * 1000))
 
             try:
-                self._curl.setopt(pycurl.URL, self.endpoint)
-                self._curl.setopt(pycurl.WRITEDATA, buffer)
-                self._curl.setopt(
+                param_key = "update" if is_update else "query"
+
+                if method == "GET":
+                    url = f"{self.endpoint}?{urlencode({param_key: query})}"
+                    curl.setopt(pycurl.URL, url)
+                    curl.setopt(pycurl.HTTPGET, 1)
+                else:
+                    curl.setopt(pycurl.URL, self.endpoint)
+                    curl.setopt(pycurl.POSTFIELDS, urlencode({param_key: query}))
+
+                curl.setopt(pycurl.WRITEDATA, buffer)
+                curl.setopt(
                     pycurl.HTTPHEADER,
                     [
                         f"Accept: {accept}",
                         "User-Agent: sparqlite/0.1.0",
                     ],
                 )
 
-                if is_update:
-                    post_data = urlencode({"update": query})
-                else:
-                    post_data = urlencode({"query": query})
-
-                self._curl.setopt(pycurl.POSTFIELDS, post_data)
-                self._curl.perform()
+                curl.perform()
 
-                status_code = self._curl.getinfo(pycurl.RESPONSE_CODE)
+                status_code = curl.getinfo(pycurl.RESPONSE_CODE)
 
                 if status_code == 400:
                     raise QueryError(f"Query syntax error: {buffer.getvalue().decode()}")
@@ -131,62 +128,30 @@ def _request(
                     last_error = EndpointError(f"Request error: {error_msg}")
                 continue
 
-        raise last_error
-
-    def query(self, query: str) -> dict:
-        """Execute a SELECT query.
+        raise last_error  # type: ignore[misc]
 
-        Args:
-            query: The SPARQL SELECT query string.
-
-        Returns:
-            Dictionary with SPARQL JSON results format.
-        """
-        content = self._request(query, "application/sparql-results+json")
+    def query(self, query: str, *, method: HTTPMethod = "GET") -> dict:
+        content = self._request(
+            query, "application/sparql-results+json", method=method
+        )
         return json.loads(content)
 
-    def select(self, query: str) -> dict:
-        """Execute a SELECT query. Alias for query()."""
-        return self.query(query)
-
-    def ask(self, query: str) -> bool:
-        """Execute an ASK query.
+    def select(self, query: str, *, method: HTTPMethod = "GET") -> dict:
+        return self.query(query, method=method)
 
-        Args:
-            query: The SPARQL ASK query string.
-
-        Returns:
-            Boolean result of the ASK query.
-        """
-        content = self._request(query, "application/sparql-results+json")
+    def ask(self, query: str, *, method: HTTPMethod = "GET") -> bool:
+        content = self._request(
+            query, "application/sparql-results+json", method=method
+        )
         return json.loads(content)["boolean"]
 
-    def construct(self, query: str) -> bytes:
-        """Execute a CONSTRUCT query.
-
-        Args:
-            query: The SPARQL CONSTRUCT query string.
+    def construct(self, query: str, *, method: HTTPMethod = "GET") -> bytes:
+        return self._request(query, "application/n-triples", method=method)
 
-        Returns:
-            Raw N-Triples bytes.
-        """
-        return self._request(query, "application/n-triples")
-
-    def describe(self, query: str) -> bytes:
-        """Execute a DESCRIBE query.
-
-        Args:
-            query: The SPARQL DESCRIBE query string.
-
-        Returns:
-            Raw N-Triples bytes.
-        """
-        return self._request(query, "application/n-triples")
+    def describe(self, query: str, *, method: HTTPMethod = "GET") -> bytes:
+        return self._request(query, "application/n-triples", method=method)
 
     def update(self, query: str) -> None:
-        """Execute a SPARQL UPDATE query (INSERT, DELETE, etc.).
-
-        Args:
-            query: The SPARQL UPDATE query string.
-        """
-        self._request(query, "application/sparql-results+json", is_update=True)
+        self._request(
+            query, "application/sparql-results+json", method="POST", is_update=True
+        )

src/sparqlite/client.py

@@ -185,3 +185,34 @@ def track_setopt(opt, val):
 
         timeout_calls = [opt for opt, val in setopt_calls if opt == pycurl.TIMEOUT_MS]
         assert timeout_calls == []
+
+
+class TestHTTPMethod:
+
+    def test_post_method_uses_postfields(self):
+        mock_curl = MagicMock()
+        mock_curl.getinfo.return_value = 200
+        setopt_calls: list[tuple[int, object]] = []
+
+        def track_setopt(opt: int, val: object) -> None:
+            setopt_calls.append((opt, val))
+
+        mock_curl.setopt = track_setopt
+
+        with patch("pycurl.Curl", return_value=mock_curl):
+            client = SPARQLClient("http://example.org/sparql")
+            client._curl = mock_curl
+            client._request("SELECT ?s WHERE { ?s ?p ?o }", "application/json", method="POST")
+            client.close()
+
+        assert any(opt == pycurl.POSTFIELDS for opt, _ in setopt_calls)
+        assert not any(opt == pycurl.HTTPGET for opt, _ in setopt_calls)
+
+    def test_request_on_closed_client_raises(self):
+        with patch("pycurl.Curl") as mock_curl_class:
+            mock_curl_class.return_value = MagicMock()
+            client = SPARQLClient("http://example.org/sparql")
+            client.close()
+
+            with pytest.raises(EndpointError):
+                client._request("SELECT ?s WHERE { ?s ?p ?o }", "application/json")