feat: suppress open client warnings in SPARQLWrapper.queries

The `SPARQLWrapper.queries` method is a sync wrapper around async code
and intended to be a convenience method for users wishing to execute
multiple operations concurrently but do not want to write async code themselves.

`SPARQLWrapper.queries` internally creates a `SPARQLWrapper` instance
with a shared `httpx.AsyncClient` that is then used in an async
context manger for calls to `SPARQLWrapper.aquery`.

> `SPARQLWrapper.queries` ergo is a managed application of
`SPARQLWrapper.aquery` that uses the context manager API of
`SPARQLWrapper` internally.

This application causes the sparqlx `ClientManager` to emit a warning
about an open client though. While this is technically correct and
intended behavior, it is superfluos and potentially misleading for
`SPARQLWrapper.queries` which actually manages the client through the
context manager.

It is therefore preferable to suppress client warnings for
`SPARQLWrapper.queries`.

The change uses a PEP-806-inspired async wrapper around the sync
`warnings.catch_warnings` context manager to suppress `Userwarnings`
coming from `sparqlx.utils.client_manager` within
`SPARQLWrapper.queries`.

Note: `warnings.catch_warnings` is not concurrency-safe, see
[Concurrent safety of Context
Managers](https://docs.python.org/3/library/warnings.html#concurrent-safety-of-context-managers)
in the `warnings` docs. Although the implemented change uses a
`contextlib.contextmanager` which closures context state and can ergo mitigate concurrency-safety
problems, `warnings` filters are global and would actually need
explicit locking or protection from a `ContextVar`. In the case at hand,
this is of no concern however, since `SPARQLWrapper.queries` controls
its own encapsulated event loop.

Closes #124.

Author: lu-pl

src/sparqlx/sparqlwrapper.py

@@ -5,6 +5,7 @@
 from contextlib import AbstractAsyncContextManager, AbstractContextManager
 import functools
 from typing import Literal as TLiteral, Self, overload
+import warnings
 
 import httpx
 from rdflib import Dataset, Graph
@@ -32,7 +33,12 @@
     RDFLibQueryTransport,
     RDFLibUpdateTransport,
 )
-from sparqlx.utils.utils import Endpoint, _get_query_type, _get_response_converter
+from sparqlx.utils.utils import (
+    Endpoint,
+    _get_query_type,
+    _get_response_converter,
+    as_async_context,
+)
 
 
 class SPARQLWrapper(AbstractContextManager, AbstractAsyncContextManager):
@@ -486,7 +492,21 @@ def queries(
         )
 
         async def _runner() -> Iterator[httpx.Response]:
-            async with query_component, asyncio.TaskGroup() as tg:
+            acatch_warnings: AbstractAsyncContextManager[None] = as_async_context(
+                warnings.catch_warnings()
+            )
+
+            async with (
+                acatch_warnings,
+                query_component,
+                asyncio.TaskGroup() as tg,
+            ):
+                warnings.filterwarnings(
+                    action="ignore",
+                    category=UserWarning,
+                    module="sparqlx.utils.client_manager",
+                )
+
                 tasks = [
                     tg.create_task(
                         query_component.aquery(

src/sparqlx/utils/utils.py

@@ -1,9 +1,11 @@
+import asyncio
+from collections.abc import AsyncIterator
+from contextlib import AbstractContextManager, asynccontextmanager
 from typing import cast
 
 from rdflib import BNode, Graph
 from rdflib.plugins.sparql import prepareQuery
 from rdflib.plugins.sparql.sparql import Query
-
 from sparqlx.types import SPARQLQuery, SPARQLQueryTypeLiteral, SPARQLResponseFormat
 from sparqlx.utils.converters import _convert_ask, _convert_bindings, _convert_graph
 
@@ -71,3 +73,16 @@ def url(self) -> str:
     @property
     def graph(self) -> Graph | None:
         return self._endpoint if isinstance(self._endpoint, Graph) else None
+
+
+@asynccontextmanager
+async def as_async_context[T](sync_cm: AbstractContextManager[T]) -> AsyncIterator[T]:
+    """Async context wrapper around a sync context manager.
+
+    The async context manager allows to call a sync context manager
+    from an async context statement. This workaround is mentioned in PEP 806,
+    see https://peps.python.org/pep-0806/#workaround-an-as-acm-wrapper.
+    """
+    with sync_cm as result:
+        await asyncio.sleep(0)
+        yield result