fix: validation issues with examples

I want to add examples for securing RDFLib network access using
`sys.addaudithook` and `urllib.request.install_opener`, but I want to
also validate the examples in our CI pipeline, so we can demonstrate
they work to our users.

This change adds validation for all examples, and the addition of the
security examples in a seperate PR will then also get validated.

examples/berkeleydb_example.py

@@ -16,10 +16,12 @@
 * does not delete the DB at the end so you can see it on disk
 """
 import os
-from rdflib import ConjunctiveGraph, Namespace, Literal
-from rdflib.store import NO_STORE, VALID_STORE
 import tempfile
 
+from rdflib import ConjunctiveGraph, Literal, Namespace
+from rdflib.plugins.stores.berkeleydb import has_bsddb
+from rdflib.store import NO_STORE, VALID_STORE
+
 
 def example_1():
     """Creates a ConjunctiveGraph and performs some BerkeleyDB tasks with it"""
@@ -98,10 +100,10 @@ def example_2():
         9719
         ...
     """
-    from urllib.request import urlopen, Request
-    from urllib.error import HTTPError
-    import json
     import base64
+    import json
+    from urllib.error import HTTPError
+    from urllib.request import Request, urlopen
 
     g = ConjunctiveGraph("BerkeleyDB")
     g.open("gsg_vocabs", create=True)
@@ -129,5 +131,7 @@ def example_2():
 
 
 if __name__ == "__main__":
-    example_1()
-    example_2()
+    if has_bsddb:
+        # Only run the examples if BerkeleyDB is available
+        example_1()
+        example_2()

examples/conjunctive_graphs.py

@@ -8,12 +8,11 @@
 conjunction (union) of all the graphs.
 """
 
-from rdflib import Namespace, Literal, URIRef
-from rdflib.graph import Graph, ConjunctiveGraph
+from rdflib import Literal, Namespace, URIRef
+from rdflib.graph import ConjunctiveGraph, Graph
 from rdflib.plugins.stores.memory import Memory
 
 if __name__ == "__main__":
-
     LOVE = Namespace("http://love.com#")
     LOVERS = Namespace("http://love.com/lovers/")
 
@@ -59,7 +58,7 @@
 
     print("Query the conjunction of all graphs:")
     xx = None
-    for x in g[mary : LOVE.loves / LOVE.hasCuteName]:
+    for x in g[mary : LOVE.loves / LOVE.hasCuteName]:  # type: ignore[misc]
         xx = x
     print("Q: Who does Mary love?")
     print("A: Mary loves {}".format(xx))

examples/custom_datatype.py

@@ -9,11 +9,9 @@
 """
 
 
-from rdflib import Graph, Literal, Namespace, XSD
-from rdflib import term
+from rdflib import XSD, Graph, Literal, Namespace, term
 
 if __name__ == "__main__":
-
     # Complex numbers are not registered by default
     # No custom constructor/serializer needed since
     # complex('(2+3j)') works fine
@@ -46,4 +44,5 @@
 
     # Compare with the original python complex object (should be True)
     # l2[2] is the object of the triple
+    assert isinstance(l2[2], Literal)
     print(l2[2].value == c)

examples/custom_eval.py

@@ -16,12 +16,19 @@
     }
 """
 
-import rdflib
 
-from rdflib.plugins.sparql.evaluate import evalBGP
+from pathlib import Path
+
+import rdflib
 from rdflib.namespace import FOAF, RDF, RDFS
+from rdflib.plugins.sparql.evaluate import evalBGP
 
-inferredSubClass = RDFS.subClassOf * "*"  # any number of rdfs.subClassOf
+EXAMPLES_DIR = Path(__file__).parent
+
+
+inferred_sub_class = (
+    RDFS.subClassOf * "*"  # type: ignore[operator]
+)  # any number of rdfs.subClassOf
 
 
 def customEval(ctx, part):
@@ -36,7 +43,7 @@ def customEval(ctx, part):
             if t[1] == RDF.type:
                 bnode = rdflib.BNode()
                 triples.append((t[0], t[1], bnode))
-                triples.append((bnode, inferredSubClass, t[2]))
+                triples.append((bnode, inferred_sub_class, t[2]))
             else:
                 triples.append(t)
 
@@ -47,24 +54,23 @@ def customEval(ctx, part):
 
 
 if __name__ == "__main__":
-
     # add function directly, normally we would use setuptools and entry_points
     rdflib.plugins.sparql.CUSTOM_EVALS["exampleEval"] = customEval
 
     g = rdflib.Graph()
-    g.parse("foaf.n3")
+    g.parse(f"{EXAMPLES_DIR / 'foaf.n3'}")
 
     # Add the subClassStmt so that we can query for it!
     g.add((FOAF.Person, RDFS.subClassOf, FOAF.Agent))
 
     # Find all FOAF Agents
     for x in g.query(
         f"""
-        PREFIX foaf: <{FOAF}> 
-        
-        SELECT * 
+        PREFIX foaf: <{FOAF}>
+
+        SELECT *
         WHERE {{
-            ?s a foaf:Agent . 
+            ?s a foaf:Agent .
         }}
         """
     ):

examples/datasets.py

@@ -7,7 +7,7 @@
 and remove things from it.
 """
 
-from rdflib import Dataset, URIRef, Literal, Namespace
+from rdflib import Dataset, Literal, Namespace, URIRef
 
 #
 #   Create & Add
@@ -26,15 +26,15 @@
 
 # Add two quads to Graph graph_1 in the Dataset
 d.add(
-    (
+    (  # type: ignore[arg-type]
         URIRef("http://example.com/subject-x"),
         URIRef("http://example.com/predicate-x"),
         Literal("Triple X"),
         graph_1,
     )
 )
 d.add(
-    (
+    (  # type: ignore[arg-type]
         URIRef("http://example.com/subject-z"),
         URIRef("http://example.com/predicate-z"),
         Literal("Triple Z"),
@@ -45,7 +45,7 @@
 # Add another quad to the Dataset to a non-existent Graph:
 # the Graph is created automatically
 d.add(
-    (
+    (  # type: ignore[arg-type]
         URIRef("http://example.com/subject-y"),
         URIRef("http://example.com/predicate-y"),
         Literal("Triple Y"),
@@ -99,7 +99,7 @@
 """
 print("Printing all triple from one Graph in the Dataset:")
 print("---")
-for triple in d.triples((None, None, None, graph_1)):
+for triple in d.triples((None, None, None, graph_1)):  # type: ignore[arg-type]
     print(triple)
 print("---")
 print()

examples/foafpaths.py

@@ -26,13 +26,16 @@
 This example shows how to get the name of friends (i.e values two steps away x knows y, y name z) with a single query.
 """
 
-from rdflib import URIRef, Graph
+from pathlib import Path
+
+from rdflib import Graph, URIRef
 from rdflib.namespace import FOAF
 
-if __name__ == "__main__":
+EXAMPLES_DIR = Path(__file__).parent
 
+if __name__ == "__main__":
     g = Graph()
-    g.parse("foaf.n3")
+    g.parse(f"{EXAMPLES_DIR / 'foaf.n3'}")
 
     tim = URIRef("http://www.w3.org/People/Berners-Lee/card#i")
 

examples/prepared_query.py

@@ -8,22 +8,27 @@
 ``initBindings`` keyword parameter.
 """
 
+from pathlib import Path
+
 import rdflib
-from rdflib.plugins.sparql import prepareQuery
 from rdflib.namespace import FOAF
+from rdflib.plugins.sparql import prepareQuery
 
+EXAMPLES_DIR = Path(__file__).parent
 
 if __name__ == "__main__":
-
     q = prepareQuery(
         "SELECT ?name WHERE { ?person foaf:knows/foaf:name ?name . }",
         initNs={"foaf": FOAF},
     )
 
     g = rdflib.Graph()
-    g.parse("foaf.n3")
+    g.parse(f"{EXAMPLES_DIR / 'foaf.n3'}")
 
     tim = rdflib.URIRef("http://www.w3.org/People/Berners-Lee/card#i")
 
     for row in g.query(q, initBindings={"person": tim}):
+        # For select queries, the Result object is an iterable of ResultRow
+        # objects.
+        assert isinstance(row, rdflib.query.ResultRow)
         print(row.name)

examples/resource_example.py

@@ -7,7 +7,7 @@
 This example shows g.resource() in action.
 """
 
-from rdflib import Graph, RDF, RDFS, Literal
+from rdflib import RDF, RDFS, Graph, Literal
 from rdflib.namespace import FOAF
 
 if __name__ == "__main__":

examples/simple_example.py

@@ -1,8 +1,10 @@
-from rdflib import Graph, Literal, BNode, RDF
-from rdflib.namespace import FOAF, DC
+import os.path
+from tempfile import TemporaryDirectory
 
-if __name__ == "__main__":
+from rdflib import RDF, BNode, Graph, Literal
+from rdflib.namespace import DC, FOAF
 
+if __name__ == "__main__":
     store = Graph()
 
     # Bind a few prefix, namespace pairs for pretty output
@@ -29,9 +31,11 @@
         for mbox in store.objects(person, FOAF["mbox"]):
             print(mbox)
 
-    print("--- saving RDF to a file (donna_foaf.rdf) ---")
+    tmp_dir = TemporaryDirectory()
+    output_file = os.path.join(tmp_dir.name, "donna_foaf.rdf")
+    print(f"--- saving RDF to a file ({output_file}) ---")
     # Serialize the store as RDF/XML to the file donna_foaf.rdf.
-    store.serialize("donna_foaf.rdf", format="pretty-xml", max_depth=3)
+    store.serialize(f"{output_file}", format="pretty-xml", max_depth=3)
 
     # Let's show off the serializers
     print()

examples/slice.py

@@ -9,16 +9,20 @@
 See :meth:`rdflib.graph.Graph.__getitem__` for details
 """
 
-from rdflib import Graph, RDF
+from pathlib import Path
+
+from rdflib import RDF, Graph
 from rdflib.namespace import FOAF
 
-if __name__ == "__main__":
+EXAMPLES_DIR = Path(__file__).parent
 
+
+if __name__ == "__main__":
     graph = Graph()
-    graph.parse("foaf.n3", format="n3")
+    graph.parse(f"{EXAMPLES_DIR / 'foaf.n3'}", format="n3")
 
-    for person in graph[: RDF.type : FOAF.Person]:
-        friends = list(graph[person : FOAF.knows * "+" / FOAF.name])
+    for person in graph[: RDF.type : FOAF.Person]:  # type: ignore[misc]
+        friends = list(graph[person : FOAF.knows * "+" / FOAF.name])  # type: ignore[operator]
         if friends:
             print(f"{graph.value(person, FOAF.name)}'s circle of friends:")
             for name in friends:

examples/smushing.py

@@ -21,17 +21,25 @@
 with my existing data.
 """
 
+from pathlib import Path
+
 from rdflib import Graph, Namespace
 from rdflib.namespace import FOAF
 
 STABLE = Namespace("http://example.com/person/mbox_sha1sum/")
 
+EXAMPLES_DIR = Path(__file__).parent
+
 if __name__ == "__main__":
     g = Graph()
-    g.parse("smushingdemo.n3", format="n3")
+    g.parse(f"{EXAMPLES_DIR / 'smushingdemo.n3'}", format="n3")
 
     newURI = {}  # old subject : stable uri
     for s, p, o in g.triples((None, FOAF["mbox_sha1sum"], None)):
+        # For this graph, all objects are Identifiers, which is a subclass of
+        # string. `n3` does allow for objects which are not Identifiers, like
+        # subgraphs.
+        assert isinstance(o, str)
         newURI[s] = STABLE[o]
 
     out = Graph()

examples/sparql_query_example.py

@@ -11,16 +11,26 @@
 :attr:`~rdflib.query.Result.vars` contains the variables
 """
 
+import logging
+import sys
+from pathlib import Path
+
 import rdflib
 
+EXAMPLES_DIR = Path(__file__).parent
+
 if __name__ == "__main__":
+    logging.basicConfig(level=logging.DEBUG, stream=sys.stderr)
 
     g = rdflib.Graph()
-    g.parse("foaf.n3", format="n3")
+    g.parse(f"{EXAMPLES_DIR / 'foaf.n3'}", format="n3")
 
     # The QueryProcessor knows the FOAF prefix from the graph
     # which in turn knows it from reading the N3 RDF file
     for row in g.query("SELECT ?s WHERE { [] foaf:knows ?s .}"):
+        # For select queries, the Result object is an iterable of ResultRow
+        # objects.
+        assert isinstance(row, rdflib.query.ResultRow)
         print(row.s)
         # or row["s"]
         # or row[rdflib.Variable("s")]

examples/sparql_update_example.py

@@ -2,21 +2,25 @@
 SPARQL Update statements can be applied with :meth:`rdflib.graph.Graph.update`
 """
 
+from pathlib import Path
+
 import rdflib
 
-if __name__ == "__main__":
+EXAMPLES_DIR = Path(__file__).parent
 
+
+if __name__ == "__main__":
     g = rdflib.Graph()
-    g.parse("foaf.n3", format="n3")
+    g.parse(f"{EXAMPLES_DIR / 'foaf.n3'}", format="n3")
 
     print(f"Initially there are {len(g)} triples in the graph")
 
     g.update(
         """
         PREFIX foaf: <http://xmlns.com/foaf/0.1/>
         PREFIX dbpedia: <http://dbpedia.org/resource/>
-        INSERT { 
-            ?s a dbpedia:Human . 
+        INSERT {
+            ?s a dbpedia:Human .
         }
         WHERE {
             ?s a foaf:Person .