Merge pull request #1347 from RDFLib/BerkeleyDB

Replace Sleepycat with BerkeleyDB

CHANGELOG.md

@@ -978,7 +978,7 @@ Fixed a range of minor issues:
 
 * http://code.google.com/p/rdflib/issues/detail?id=149
 
-  Sleepycat Store broken with create=False
+  BerkeleyDB Store broken with create=False
 
 * http://code.google.com/p/rdflib/issues/detail?id=134
 
@@ -1228,7 +1228,7 @@ Fixed conversion of (exiplicit) MySQL ports to integers.
 Fixed MySQL store so it properly calculates ```__len__``` of
 individual Graphs
 
-Aligned with how Sleepycat is generating events (remove events
+Aligned with how BerkeleyDB is generating events (remove events
 are expressed in terms of interned strings)
 
 Added code to catch unpickling related exceptions
@@ -1248,7 +1248,7 @@ TripleRemoved.
 
 Added Journal Reader and Writer.
 
-Removed Sleepycat level journaling.
+Removed BerkeleyDB level journaling.
 
 Added support for triple quoted Literal's.
 
@@ -1329,7 +1329,7 @@ argument to util's date_time method.
 Fixed a relativize bug in the rdf/xml serializer.
 
 Fixed NameError: global name 'URIRef' is not defined error in
-Sleepycat.py by adding missing import.
+BerkeleyDB.py by adding missing import.
 
 Applied patch for Seq to sort list by integer, added by Drew
 Hess.
@@ -1360,7 +1360,7 @@ Added N3 support to Graph and Store.
 
 Added Sean's n3p parser, and ntriples parser.
 
-Sleepycat implementation has been revamped in the process of
+BerkeleyDB implementation has been revamped in the process of
 expanding it to support the new requirements n3
 requirements. It also now persists a journal -- more to come.
 
@@ -1390,7 +1390,7 @@ it provides Atomicity in the best case scenario.
 2005/10/10 RELEASE 2.2.3
 ========================
 
-Fixed Sleepycat backend to commit after an add and
+Fixed BerkeleyDB backend to commit after an add and
 remove. This should help just a bit with those unclean
 shutdowns ;)
 

docs/apidocs/examples.rst

@@ -32,8 +32,7 @@ These examples all live in ``./examples`` in the source-distribution of RDFLib.
 
 .. automodule:: examples.film
     :members:
-    :undoc-members:
-    :show-inheritance:
+
 
 :mod:`foafpaths` Module
 -----------------------
@@ -51,34 +50,18 @@ These examples all live in ``./examples`` in the source-distribution of RDFLib.
     :undoc-members:
     :show-inheritance:
 
-:mod:`resource` Module
-----------------------
-
-.. automodule:: examples.resource
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-:mod:`rdfa_example` Module
---------------------------
-
-.. automodule:: examples.rdfa_example
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-:mod:`simple_example` Module
-----------------------------
+:mod:`resource_example` Module
+------------------------------
 
-.. automodule:: examples.simple_example
+.. automodule:: examples.resource_example
     :members:
     :undoc-members:
     :show-inheritance:
 
-:mod:`sleepycat_example` Module
+:mod:`berkeleydb_example` Module
 --------------------------------
 
-.. automodule:: examples.sleepycat_example
+.. automodule:: examples.berkeleydb_example
     :members:
     :undoc-members:
     :show-inheritance:

docs/docs.rst

@@ -5,31 +5,33 @@ Writing RDFLib Documentation
 ================================
 
 
-The docs are generated with Sphinx.
+These docs are generated with Sphinx.
 
 Sphinx makes it very easy to pull in doc-strings from modules,
 classes, methods, etc.  When writing doc-strings, special reST fields
-can be used to annotate parameters, return-types, etc. This make for
+can be used to annotate parameters, return-types, etc. This makes for
 pretty API docs:
 
 http://sphinx-doc.org/domains.html?highlight=param#info-field-lists
 
 Building
 --------
 
-To build you must have the `sphinx` package installed:
+To build you must have the ``sphinx`` package installed:
 
 .. code-block:: bash
 
   pip install sphinx
 
-Then you can do:
+See the documentation's full set of requirements in the ``sphinx-require,ens.txt`` file within the :file:`docs/` directory.
+
+ Once you have all the requirements installed you can run this command in the rdflib root directory:
 
 .. code-block:: bash
 
   python setup.py build_sphinx
 
-The docs will be generated in :file:`build/sphinx/html/`
+Docs will be generated in :file:`build/sphinx/html/` and API documentation, generated from doc-strings, will be placed in :file:`docs/apidocs/`.
 
 API Docs
 --------
@@ -40,8 +42,8 @@ API Docs are automatically generated with ``sphinx-apidoc``:
 
    sphinx-apidoc -f -d 10 -o docs/apidocs/ rdflib examples
 
-(then ``rdflib.rst`` was tweaked manually to not include all
-convenience imports that are directly in the ``rdflib/__init__.py``)
+Note that ``rdflib.rst`` was manually tweaked so as to not include all
+ imports in ``rdflib/__init__.py``.
 
 Tables
 ------

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,52 +63,54 @@ 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
     donna = URIRef("http://example.org/donna")
 
     # 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