docs: move Recipes and Graph target docs to docs folder

Author: lu-pl

README.md

@@ -24,14 +24,14 @@ Python library for [httpx](https://www.python-httpx.org/)-based SPARQL Query and
 ## Installation
 `sparqlx` is a [PEP 621](https://peps.python.org/pep-0621/)-compliant package and available on PyPI.
 
-```shell
-pip install sparqlx
-```
 
+## Docs
 
-## Usage
+- [RDFLib Integration](docs/rdflib_integration.md)
+- [Recipes](docs/recipes.md)
+- [SPARQL 1.2 Protocol Client Implementation](docs/sparql_protocol_implementation.md)
 
-> Also see the [Recipes](#Recipes) section below.
+## Usage
 
 ### SPARQLWrapper.query
 
@@ -316,147 +316,3 @@ This will run the specified update operations asynchronously with an internally
 	},
 ]
 ```
-
-
-### `rdflib.Graph` Targets
-
-Apart from targeting remote SPARQL query and update endpoints, `SPARQLWrapper` also supports running SPARQL operations against `rdflib.Graph` objects.
-
-```python
-import httpx
-from rdflib import Graph
-from sparqlx import SPARQLWrapper
-
-query = "select ?x ?y where {values (?x ?y) {(1 2) (3 4)}}"
-sparql_wrapper = SPARQLWrapper(sparql_endpoint=Graph())
-
-result: httpx.Response = sparql_wrapper.query(query)
-```
-
-The feature essentially treats `rdflib.Graph` as a SPARQL endpoint i.e. SPARQL operations are delegated to an in-memory graph object using a custom transport that builds and returns an `httpx.Response`.
-
-> Note that response streaming is currently not supported for `rdflib.Graph` targets.
-
-#### RDF Source Constructor
-
-The `SPARQLWrapper` class features an alternative constructor, `sparqlx.SPARQLWrapper.from_rdf_source`, that, given a `sparqlx.types.RDFParseSource`, parses the RDF source into an `rdflib.Graph` and returns a `SPARQLWrapper` instance targeting that graph object.
-kwargs are forwarded to the rdflib.Graph.parse methods.
-
-```python
-from sparqlx import SPARQLWrapper
-
-query = """
-select distinct ?s
-where {
-	?s ?p ?o .
-	filter (contains(str(?s), 'Spacetime'))
-}
-"""
-
-wrapper = SPARQLWrapper.from_rdf_source(
-	rdf_source="https://cidoc-crm.org/rdfs/7.1.3/CIDOC_CRM_v7.1.3.rdf"
-)
-
-result = wrapper.query(
-	query=query,
-	convert=True,
-)
-
-print(result)  # [{'s': URIRef('http://www.cidoc-crm.org/cidoc-crm/E92_Spacetime_Volume')}]
-```
-
-The `sparqlx.types.RDFParseSource` is the exact type expected by the `source` parameter of `rdflib.Graph.parse`.
-
-> `sparqlx.SPARQLWrapper.from_rdf_source` creates an `rdflib.Dataset` internally in order to support RDF Quad sources.
-
-
-## Recipes
-
-The following is a loose collection of `sparqlx` recipes.
-
-Some of those recipes might become `sparqlx` features in the future.
-
-
-### JSON Response Streaming
-
-The example below uses [ijson](https://github.com/ICRAR/ijson) to process a `sparqlx.SPARQLWrapper.query_stream` byte stream.
-
-Note that `ijson` currently requires an adapter for Iterator input, see issue [#58](https://github.com/ICRAR/ijson/issues/58#issuecomment-917655522).
-
-```python
-from collections.abc import Iterator
-
-import ijson
-from sparqlx import SPARQLWrapper
-
-
-qlever_wikidata_endpoint = "https://qlever.cs.uni-freiburg.de/api//wikidata"
-sparql_wrapper = SPARQLWrapper(sparql_endpoint=qlever_wikidata_endpoint)
-
-json_result_stream: Iterator[bytes] = sparql_wrapper.query_stream(
-	query="select ?s ?p ?o where {?s ?p ?o} limit 100000"
-)
-
-class IJSONIteratorAdapter:
-	def __init__(self, byte_stream: Iterator[bytes]):
-		self.byte_stream = byte_stream
-
-	def read(self, n):
-		if n == 0:
-			return b""
-		return next(self.byte_stream, b"")
-
-adapter = IJSONIteratorAdapter(byte_stream=json_result_stream)
-json_result_iterator: Iterator[dict] = ijson.items(adapter, "results.bindings.item")
-
-print(next(json_result_iterator))
-```
-
-The `json_result_iterator` generator yields Python dictionaries holding SPARQL JSON response bindings coming from a byte stream. Buffering and incremental parsing is done by `ijson`.
-
-### Graph Response Streaming
-
-The following example processes a stream of RDF graph data coming from a SPARQL CONSTRUCT response.
-
-It uses an Iterator chunking facility `ichunk` to implement a generator that yields sized sub-graphs from a streamed graph response.
-To avoid incremental RDF parsing and possibly skolemization, `ntriples` are requested with line-based streaming.
-
-
-```python
-from collections.abc import Iterator
-from itertools import chain, islice
-from typing import cast
-
-import httpx
-from rdflib import Graph
-from sparqlx import SPARQLWrapper
-
-
-def ichunk[T](iterator: Iterator[T], size: int) -> Iterator[Iterator[T]]:
-	_missing = object()
-	chunk = islice(iterator, size)
-
-	if (first := next(chunk, _missing)) is _missing:
-		return
-
-	yield chain[T]([cast(T, first)], chunk)
-	yield from ichunk(iterator, size=size)
-
-
-releven_sparql_endpoint = "https://graphdb.r11.eu/repositories/RELEVEN"
-sparql_wrapper = SPARQLWrapper(sparql_endpoint=releven_sparql_endpoint)
-
-graph_result_stream: Iterator[bytes] = sparql_wrapper.query_stream(
-	query="construct {?s ?p ?o} where {?s ?p ?o} limit 100000",
-	response_format="ntriples",
-	streaming_method=httpx.Response.iter_lines,
-)
-
-def graph_result_iterator(size: int = 1000) -> Iterator[Graph]:
-	for chunk in ichunk(graph_result_stream, size=size):
-		graph = Graph()
-		for ntriple in chunk:
-			graph.parse(data=ntriple, format="ntriples")
-
-		yield graph
-```

docs/rdflib_integration.md

@@ -0,0 +1,55 @@
+# RDFLib Integration
+
+## SPARQL Result Conversion
+[todo]
+
+## `rdflib.Graph` Targets
+
+Apart from targeting remote SPARQL query and update endpoints, `SPARQLWrapper` also supports running SPARQL operations against `rdflib.Graph` objects.
+
+```python
+import httpx
+from rdflib import Graph
+from sparqlx import SPARQLWrapper
+
+query = "select ?x ?y where {values (?x ?y) {(1 2) (3 4)}}"
+sparql_wrapper = SPARQLWrapper(sparql_endpoint=Graph())
+
+result: httpx.Response = sparql_wrapper.query(query)
+```
+
+The feature essentially treats `rdflib.Graph` as a SPARQL endpoint i.e. SPARQL operations are delegated to an in-memory graph object using a custom transport that builds and returns an `httpx.Response`.
+
+> Note that response streaming is currently not supported for `rdflib.Graph` targets.
+
+### RDF Source Constructor
+
+The `SPARQLWrapper` class features an alternative constructor, `sparqlx.SPARQLWrapper.from_rdf_source`, that, given a `sparqlx.types.RDFParseSource`, parses the RDF source into an `rdflib.Graph` and returns a `SPARQLWrapper` instance targeting that graph object.
+kwargs are forwarded to the rdflib.Graph.parse methods.
+
+```python
+from sparqlx import SPARQLWrapper
+
+query = """
+select distinct ?s
+where {
+	?s ?p ?o .
+	filter (contains(str(?s), 'Spacetime'))
+}
+"""
+
+wrapper = SPARQLWrapper.from_rdf_source(
+	rdf_source="https://cidoc-crm.org/rdfs/7.1.3/CIDOC_CRM_v7.1.3.rdf"
+)
+
+result = wrapper.query(
+	query=query,
+	convert=True,
+)
+
+print(result)  # [{'s': URIRef('http://www.cidoc-crm.org/cidoc-crm/E92_Spacetime_Volume')}]
+```
+
+The `sparqlx.types.RDFParseSource` is the exact type expected by the `source` parameter of `rdflib.Graph.parse`.
+
+> `sparqlx.SPARQLWrapper.from_rdf_source` creates an `rdflib.Dataset` internally in order to support RDF Quad sources.

docs/recipes.md

@@ -0,0 +1,90 @@
+# Recipes
+
+The following is a loose collection of `sparqlx` recipes.
+
+Some of those recipes might become `sparqlx` features in the future.
+
+
+## JSON Response Streaming
+
+The example below uses [ijson](https://github.com/ICRAR/ijson) to process a `sparqlx.SPARQLWrapper.query_stream` byte stream.
+
+Note that `ijson` currently requires an adapter for Iterator input, see issue [#58](https://github.com/ICRAR/ijson/issues/58#issuecomment-917655522).
+
+```python
+from collections.abc import Iterator
+
+import ijson
+from sparqlx import SPARQLWrapper
+
+
+qlever_wikidata_endpoint = "https://qlever.cs.uni-freiburg.de/api//wikidata"
+sparql_wrapper = SPARQLWrapper(sparql_endpoint=qlever_wikidata_endpoint)
+
+json_result_stream: Iterator[bytes] = sparql_wrapper.query_stream(
+	query="select ?s ?p ?o where {?s ?p ?o} limit 100000"
+)
+
+class IJSONIteratorAdapter:
+	def __init__(self, byte_stream: Iterator[bytes]):
+		self.byte_stream = byte_stream
+
+	def read(self, n):
+		if n == 0:
+			return b""
+		return next(self.byte_stream, b"")
+
+adapter = IJSONIteratorAdapter(byte_stream=json_result_stream)
+json_result_iterator: Iterator[dict] = ijson.items(adapter, "results.bindings.item")
+
+print(next(json_result_iterator))
+```
+
+The `json_result_iterator` generator yields Python dictionaries holding SPARQL JSON response bindings coming from a byte stream. Buffering and incremental parsing is done by `ijson`.
+
+## Graph Response Streaming
+
+The following example processes a stream of RDF graph data coming from a SPARQL CONSTRUCT response.
+
+It uses an Iterator chunking facility `ichunk` to implement a generator that yields sized sub-graphs from a streamed graph response.
+To avoid incremental RDF parsing and possibly skolemization, `ntriples` are requested with line-based streaming.
+
+
+```python
+from collections.abc import Iterator
+from itertools import chain, islice
+from typing import cast
+
+import httpx
+from rdflib import Graph
+from sparqlx import SPARQLWrapper
+
+
+def ichunk[T](iterator: Iterator[T], size: int) -> Iterator[Iterator[T]]:
+	_missing = object()
+	chunk = islice(iterator, size)
+
+	if (first := next(chunk, _missing)) is _missing:
+		return
+
+	yield chain[T]([cast(T, first)], chunk)
+	yield from ichunk(iterator, size=size)
+
+
+releven_sparql_endpoint = "https://graphdb.r11.eu/repositories/RELEVEN"
+sparql_wrapper = SPARQLWrapper(sparql_endpoint=releven_sparql_endpoint)
+
+graph_result_stream: Iterator[bytes] = sparql_wrapper.query_stream(
+	query="construct {?s ?p ?o} where {?s ?p ?o} limit 100000",
+	response_format="ntriples",
+	streaming_method=httpx.Response.iter_lines,
+)
+
+def graph_result_iterator(size: int = 1000) -> Iterator[Graph]:
+	for chunk in ichunk(graph_result_stream, size=size):
+		graph = Graph()
+		for ntriple in chunk:
+			graph.parse(data=ntriple, format="ntriples")
+
+		yield graph
+```