removed non-resolving links, added new multi-graph e.g., fixed e.g. file docco error, fixed parse() for Dataset/ConGr

3 files changed, 105 insertions, 45 deletions

diff --git a/docs/intro_to_parsing.rst b/docs/intro_to_parsing.rst
index 5b50e5ba..4460d30e 100644
--- a/docs/intro_to_parsing.rst
+++ b/docs/intro_to_parsing.rst
@@ -4,25 +4,26 @@
 Loading and saving RDF
 ======================
 
-Reading an n-triples file
---------------------------
+Reading RDF files
+-----------------
 
-RDF data has various syntaxes (``xml``, ``n3``, ``ntriples``,
-``trix``, ``JSON-LD``, etc) that you might want to read. The simplest format is
-``ntriples``, a line-based format. Create the file :file:`demo.nt` in
-the current directory with these two lines:
+RDF data can be represented using various syntaxes (``turtle``, ``rdf/xml``, ``n3``, ``n-triples``,
+``trix``, ``JSON-LD``, etc.). The simplest format is
+``ntriples``, which is a triple-per-line format.
+
+Create the file :file:`demo.nt` in the current directory with these two lines in it:
 
 .. code-block:: Turtle
 
-    <http://bigasterisk.com/foaf.rdf#drewp> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://xmlns.com/foaf/0.1/Person> .
-    <http://bigasterisk.com/foaf.rdf#drewp> <http://example.com/says> "Hello world" .
+    <http://example.com/drewp> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://xmlns.com/foaf/0.1/Person> .
+    <http://example.com/drewp> <http://example.com/says> "Hello World" .
+
+On line 1 this file says "drewp is a FOAF Person:. On line 2 it says "drep says "Hello World"".
 
-You need to tell RDFLib what format to parse, use the ``format``
-keyword-parameter to :meth:`~rdflib.graph.Graph.parse`, you can pass
-either a mime-type or the name (a :doc:`list of available parsers
-<plugin_parsers>` is available).  If you are not sure what format your
-file will be, you can use :func:`rdflib.util.guess_format` which will
-guess based on the file extension.
+RDFLib can guess what format the file is by the file ending (".nt" is commonly used for n-triples) so you can just use
+:meth:`~rdflib.graph.Graph.parse` to read in the file. If the file had a non-standard RDF file ending, you could set the
+keyword-parameter ``format`` to specify either an Internet Media Type or the format name (a :doc:`list of available
+parsers <plugin_parsers>` is available).
 
 In an interactive python interpreter, try this:
 
@@ -31,51 +32,112 @@ In an interactive python interpreter, try this:
     from rdflib import Graph
 
     g = Graph()
-    g.parse("demo.nt", format="nt")
+    g.parse("demo.nt")
 
-    print(len(g)) # prints 2
+    print(len(g))
+    # prints: 2
 
     import pprint
     for stmt in g:
         pprint.pprint(stmt)
-
-    # prints :
-    (rdflib.term.URIRef('http://bigasterisk.com/foaf.rdf#drewp'),
-     rdflib.term.URIRef('http://example.com/says'),
-     rdflib.term.Literal('Hello world'))
-    (rdflib.term.URIRef('http://bigasterisk.com/foaf.rdf#drewp'),
-     rdflib.term.URIRef('http://www.w3.org/1999/02/22-rdf-syntax-ns#type'),
-     rdflib.term.URIRef('http://xmlns.com/foaf/0.1/Person'))
+    # prints:
+    # (rdflib.term.URIRef('http://example.com/drewp'),
+    #  rdflib.term.URIRef('http://example.com/says'),
+    #  rdflib.term.Literal('Hello World'))
+    # (rdflib.term.URIRef('http://example.com/drewp'),
+    #  rdflib.term.URIRef('http://www.w3.org/1999/02/22-rdf-syntax-ns#type'),
+    #  rdflib.term.URIRef('http://xmlns.com/foaf/0.1/Person'))
 
 The final lines show how RDFLib represents the two statements in the
-file. The statements themselves are just length-3 tuples; and the
-subjects, predicates, and objects are all rdflib types.
+file: the statements themselves are just length-3 tuples ("triples") and the
+subjects, predicates, and objects of the triples are all rdflib types.
 
-Reading remote graphs
----------------------
+Reading remote RDF
+------------------
 
-Reading graphs from the net is just as easy:
+Reading graphs from the Internet is easy:
 
 .. code-block:: python
 
-    g.parse("http://bigasterisk.com/foaf.rdf")
-    print(len(g))
-    # prints 42
+    from rdflib import Graph
 
-The format defaults to ``xml``, which is the common format for .rdf
-files you'll find on the net.
+    g = Graph()
+    g.parse("http://www.w3.org/People/Berners-Lee/card")
+    print(len(g))
+    # prints: 86
 
-RDFLib will also happily read RDF from any file-like object,
-i.e. anything with a ``.read()`` method.
+:func:`rdflib.Graph.parse` can process local files, remote data via a URL, as in this example, or RDF data in a string
+(using the ``data`` parameter).
 
 
 Saving RDF
 ----------
 
-To store a graph in a file use the :func:`rdflib.Graph.serialize` function:
+To store a graph in a file, use the :func:`rdflib.Graph.serialize` function:
 
 .. code-block:: python
 
-    g.parse("http://bigasterisk.com/foaf.rdf")
-    with open("foaf.n3", "wb") as f:
-        g.serialize(f, format="n3")
\ No newline at end of file
+    from rdflib import Graph
+
+    g = Graph()
+    g.parse("http://www.w3.org/People/Berners-Lee/card")
+    g.serialize(destination="tbl.ttl")
+
+This parses data from http://www.w3.org/People/Berners-Lee/card and stores it in a file ``tbl.ttl`` in this directory
+using the turtle format as a default.
+
+To read the same data and to save it in a varable ``v`` a string in the RDF/XML format, do this:
+
+.. code-block:: python
+
+    from rdflib import Graph
+
+    g = Graph()
+    g.parse("http://www.w3.org/People/Berners-Lee/card")
+    v = g.serialize(format="xml")
+
+
+Working with multi-graphs
+-------------------------
+
+To read and query multi-graphs, that is RDF data that is context-aware, you need to use rdflib's
+:class:`rdflib.ConjunctiveGraph` or :class:`rdflib.Dataset` class. These are extensions to :class:`rdflib.Graph` that
+know all about quads (triples + graph IDs).
+
+If you had this multi-graph data file (in the ``trig`` format, using new-style ``PREFIX`` statement (not the older
+``@prefix``):
+
+.. code-block:: Turtle
+
+    PREFIX eg: <http://example.com/person/>
+    PREFIX foaf: <http://xmlns.com/foaf/0.1/>
+
+    eg:graph-1 {
+        eg:drewp a foaf:Person .
+        eg:drewp eg:says "Hello World" .
+    }
+
+    eg:graph-2 {
+        eg:nick a foaf:Person .
+        eg:nick eg:says "Hi World" .
+    }
+
+You could parse the file and query it like this:
+
+.. code-block:: python
+
+    from rdflib import Dataset
+    from rdflib.namespace import RDF
+
+    g = Dataset()
+    g.parse("demo.trig")
+
+    for s, p, o, g in g.quads((None, RDF.type, None, None)):
+        print(s, g)
+
+This will print out:
+
+.. code-block::
+
+    http://example.com/person/drewp http://example.com/person/graph-1
+    http://example.com/person/nick http://example.com/person/graph-2
diff --git a/examples/film.py b/examples/film.py
index bf2d5e0b..781bb63a 100644
--- a/examples/film.py
+++ b/examples/film.py
@@ -1,6 +1,5 @@
 #!/usr/bin/env python
 """
-
 film.py: a simple tool to manage your movies review
 Simon Rozet, http://atonie.org/
 
@@ -13,7 +12,6 @@ Requires download and import of Python imdb library from
 https://imdbpy.github.io/ - (warning: installation
 will trigger automatic installation of several other packages)
 
---
 Usage:
     film.py whoami "John Doe <john@doe.org>"
         Initialize the store and set your name and email.
diff --git a/rdflib/graph.py b/rdflib/graph.py
index cbaf8f2d..817a9dc3 100644
--- a/rdflib/graph.py
+++ b/rdflib/graph.py
@@ -1574,7 +1574,7 @@ class ConjunctiveGraph(Graph):
         self,
         source=None,
         publicID=None,
-        format="xml",
+        format=None,
         location=None,
         file=None,
         data=None,
@@ -1758,7 +1758,7 @@ class Dataset(ConjunctiveGraph):
         self,
         source=None,
         publicID=None,
-        format="xml",
+        format=None,
         location=None,
         file=None,
         data=None,
@@ -2060,7 +2060,7 @@ class ReadOnlyGraphAggregate(ConjunctiveGraph):
     def absolutize(self, uri, defrag=1):
         raise UnSupportedAggregateOperation()
 
-    def parse(self, source, publicID=None, format="xml", **args):
+    def parse(self, source, publicID=None, format=None, **args):
         raise ModificationException()
 
     def n3(self):