update to 6.0.0; add SPARQL e.g.

1 files changed, 62 insertions, 23 deletions

diff --git a/docs/gettingstarted.rst b/docs/gettingstarted.rst
index a3637210..48e13d0f 100644
--- a/docs/gettingstarted.rst
+++ b/docs/gettingstarted.rst
@@ -8,7 +8,7 @@ Installation
 ============
 
 RDFLib is open source and is maintained in a
-`GitHub <http://github.com/RDFLib/rdflib/>`_ repository. RDFLib releases, current and previous
+`GitHub <http://github.com/RDFLib/rdflib/>`_ repository. RDFLib releases, current and previous,
 are listed on `PyPi <http://pypi.python.org/pypi/rdflib/>`_
 
 The best way to install RDFLib is to use ``pip`` (sudo as required):
@@ -17,7 +17,13 @@ The best way to install RDFLib is to use ``pip`` (sudo as required):
 
     $ pip install rdflib
 
-If you want the latest code to run, clone the master branch of the GitHub repo and use that.
+If you want the latest code to run, clone the master branch of the GitHub repo and use that or you can  ``pip install``
+directly from GitHub:
+
+.. code-block :: bash
+
+    $ pip install git+https://github.com/RDFLib/rdflib.git@master#egg=rdflib
+
 
 Support
 =======
@@ -39,12 +45,12 @@ who hasn't worked with RDF before.*
 The primary interface that RDFLib exposes for working with RDF is a
 :class:`~rdflib.graph.Graph`.
 
-RDFLib graphs are not sorted containers; they have ordinary ``set``
+RDFLib graphs are un-sorted containers; they have ordinary ``set``
 operations (e.g. :meth:`~rdflib.Graph.add` to add a triple) plus
 methods that search triples and return them in arbitrary order.
 
 RDFLib graphs also redefine certain built-in Python methods in order
-to behave in a predictable way; they `emulate container types
+to behave in a predictable way: they `emulate container types
 <http://docs.python.org/release/2.5.2/ref/sequence-types.html>`_ and
 are best thought of as a set of 3-item tuples ("triples", in RDF-speak):
 
@@ -57,44 +63,46 @@ are best thought of as a set of 3-item tuples ("triples", in RDF-speak):
         (subjectN, predicateN, objectN)
      ]
 
-A tiny usage example:
+A tiny example
+==============
 
 .. code-block:: python
 
-    import rdflib
+    from rdflib import Graph
 
-    # create a Graph
-    g = rdflib.Graph()
+    # Create a Graph
+    g = Graph()
 
-    # parse in an RDF file hosted on the Internet
-    result = g.parse("http://www.w3.org/People/Berners-Lee/card")
+    # Parse in an RDF file hosted on the Internet
+    g.parse("http://www.w3.org/People/Berners-Lee/card")
 
-    # loop through each triple in the graph (subj, pred, obj)
+    # Loop through each triple in the graph (subj, pred, obj)
     for subj, pred, obj in g:
-        # check if there is at least one triple in the Graph
+        # Check if there is at least one triple in the Graph
         if (subj, pred, obj) not in g:
            raise Exception("It better be!")
 
-    # print the number of "triples" in the Graph
-    print("graph has {} statements.".format(len(g)))
-    # prints graph has 86 statements.
+    # Print the number of "triples" in the Graph
+    print(f"Graph g has {len(g)} statements.")
+    # Prints: Graph g has 86 statements.
 
-    # print out the entire Graph in the RDF Turtle format
-    print(g.serialize(format="turtle").decode("utf-8"))
+    # Print out the entire Graph in the RDF Turtle format
+    print(g.serialize(format="turtle"))
 
 Here a :class:`~rdflib.graph.Graph` is created and then an RDF file online, Tim Berners-Lee's social network details, is
 parsed into that graph. The ``print()`` statement uses the ``len()`` function to count the number of triples in the
 graph.
 
-A more extensive example:
+A more extensive example
+========================
 
 .. code-block:: python
 
     from rdflib import Graph, Literal, RDF, URIRef
-    # rdflib knows about some namespaces, like FOAF
+    # rdflib knows about quite a few popular namespaces, like W3C ontologies, schema.org etc.
     from rdflib.namespace import FOAF , XSD
 
-    # create a Graph
+    # Create a Graph
     g = Graph()
 
     # Create an RDF URI node to use as the subject for multiple triples
@@ -102,7 +110,7 @@ A more extensive example:
 
     # Add triples using store's add() method.
     g.add((donna, RDF.type, FOAF.Person))
-    g.add((donna, FOAF.nick, Literal("donna", lang="ed")))
+    g.add((donna, FOAF.nick, Literal("donna", lang="en")))
     g.add((donna, FOAF.name, Literal("Donna Fales")))
     g.add((donna, FOAF.mbox, URIRef("mailto:donna@example.org")))
 
@@ -113,7 +121,7 @@ A more extensive example:
     g.add((ed, RDF.type, FOAF.Person))
     g.add((ed, FOAF.nick, Literal("ed", datatype=XSD.string)))
     g.add((ed, FOAF.name, Literal("Edward Scissorhands")))
-    g.add((ed, FOAF.mbox, URIRef("mailto:e.scissorhands@example.org")))
+    g.add((ed, FOAF.mbox, Literal("e.scissorhands@example.org", datatype=XSD.anyURI)))
 
     # Iterate over triples in store and print them out.
     print("--- printing raw triples ---")
@@ -131,7 +139,38 @@ A more extensive example:
 
     # print all the data in the Notation3 format
     print("--- printing mboxes ---")
-    print(g.serialize(format='n3').decode("utf-8"))
+    print(g.serialize(format='n3'))
+
+
+A SPARQL query example
+======================
+
+.. code-block:: python
+
+    from rdflib import Graph
+
+    # Create a Graph, pare in Internet data
+    g = Graph().parse("http://www.w3.org/People/Berners-Lee/card")
+
+    # Query the data in g using SPARQL
+    # This query returns the 'name' of all ``foaf:Person`` instances
+    q = """
+        PREFIX foaf: <http://xmlns.com/foaf/0.1/>
+
+        SELECT ?name
+        WHERE {
+            ?p rdf:type foaf:Person .
+
+            ?p foaf:name ?name .
+        }
+    """
+
+    # Apply the query to the graph and iterate through results
+    for r in g.query(q):
+        print(r["name"])
+
+    # prints: Timothy Berners-Lee
+
 
 
 More examples