Bring docs up to 3.2.0rc, refresh and recover inappropriately discarded explanatory doc

4 files changed, 127 insertions, 31 deletions

diff --git a/docs/conf.py b/docs/conf.py
index 46af9d40..9f297928 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -47,16 +47,16 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'rdflib'
-copyright = u'2009, Daniel Krech'
+copyright = u'2009 - 2012, Daniel Krech'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '3.1.0'
+version = '3.2.0rc'
 # The full version, including alpha/beta/rc tags.
-release = '3.1.0'
+release = '3.2.0rc'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/docs/graph_utilities.rst b/docs/graph_utilities.rst
index d0be7d90..3a08cea8 100644
--- a/docs/graph_utilities.rst
+++ b/docs/graph_utilities.rst
@@ -79,37 +79,39 @@ RDFLib Literals essentially behave like unicode characters with an XML Schema da
         datetime   : (lambda i:i.isoformat(),XSD_NS+u'dateTime'),
     }
 
-Maps Python instances to WXS datatyped Literals
+Maps Python instances to WXS datatyped Literals (the parse_time, _date and _datetime
+functions are imports from the `isodate <http://pypi.python.org/pypi/isodate/>`_ 
+package).
 
 .. code-block:: python
 
-    XSDToPython = {  
-        XSD_NS+u'time'               : (None,_strToTime),
-        XSD_NS+u'date'               : (None,_strToDate),
-        XSD_NS+u'dateTime'           : (None,_strToDateTime),    
-        XSD_NS+u'string'             : (None,None),
-        XSD_NS+u'normalizedString'   : (None,None),
-        XSD_NS+u'token'              : (None,None),
-        XSD_NS+u'language'           : (None,None),
-        XSD_NS+u'boolean'            : (None, lambda i:i.lower() in ['1','true']),
-        XSD_NS+u'decimal'            : (float,None), 
-        XSD_NS+u'integer'            : (long ,None),
-        XSD_NS+u'nonPositiveInteger' : (int,None),
-        XSD_NS+u'long'               : (long,None),
-        XSD_NS+u'nonNegativeInteger' : (int, None),
-        XSD_NS+u'negativeInteger'    : (int, None),
-        XSD_NS+u'int'                : (int, None),
-        XSD_NS+u'unsignedLong'       : (long, None),
-        XSD_NS+u'positiveInteger'    : (int, None),
-        XSD_NS+u'short'              : (int, None),
-        XSD_NS+u'unsignedInt'        : (long, None),
-        XSD_NS+u'byte'               : (int, None),
-        XSD_NS+u'unsignedShort'      : (int, None),
-        XSD_NS+u'unsignedByte'       : (int, None),
-        XSD_NS+u'float'              : (float, None),
-        XSD_NS+u'double'             : (float, None),
-        XSD_NS+u'base64Binary'       : (base64.decodestring, None),
-        XSD_NS+u'anyURI'             : (None,None),
+     XSDToPython = {
+        URIRef(_XSD_PFX+'time')               : parse_time,
+        URIRef(_XSD_PFX+'date')               : parse_date,
+        URIRef(_XSD_PFX+'dateTime')           : parse_datetime,
+        URIRef(_XSD_PFX+'string')             : None,
+        URIRef(_XSD_PFX+'normalizedString')   : None,
+        URIRef(_XSD_PFX+'token')              : None,
+        URIRef(_XSD_PFX+'language')           : None,
+        URIRef(_XSD_PFX+'boolean')            : lambda i:i.lower() in ['1','true'],
+        URIRef(_XSD_PFX+'decimal')            : float,
+        URIRef(_XSD_PFX+'integer')            : long,
+        URIRef(_XSD_PFX+'nonPositiveInteger') : int,
+        URIRef(_XSD_PFX+'long')               : long,
+        URIRef(_XSD_PFX+'nonNegativeInteger') : int,
+        URIRef(_XSD_PFX+'negativeInteger')    : int,
+        URIRef(_XSD_PFX+'int')                : long,
+        URIRef(_XSD_PFX+'unsignedLong')       : long,
+        URIRef(_XSD_PFX+'positiveInteger')    : int,
+        URIRef(_XSD_PFX+'short')              : int,
+        URIRef(_XSD_PFX+'unsignedInt')        : long,
+        URIRef(_XSD_PFX+'byte')               : int,
+        URIRef(_XSD_PFX+'unsignedShort')      : int,
+        URIRef(_XSD_PFX+'unsignedByte')       : int,
+        URIRef(_XSD_PFX+'float')              : float,
+        URIRef(_XSD_PFX+'double')             : float,
+        URIRef(_XSD_PFX+'base64Binary')       : lambda s: base64.b64decode(py3compat.b(s)),
+        URIRef(_XSD_PFX+'anyURI')             : None,
     }
 
 Maps WXS datatyped Literals to Python.  This mapping is used by the :meth:`toPython` method defined on all Literal instances.
diff --git a/docs/index.rst b/docs/index.rst
index 7da60f7c..4a24fa87 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -39,6 +39,7 @@ Additional discussions / notes
 
    univrdfstore
    graphs_bnodes
+   persisting_n3_terms
    Documentation notes <apidocs>
 
 
diff --git a/docs/persisting_n3_terms.rst b/docs/persisting_n3_terms.rst
new file mode 100644
index 00000000..820f307f
--- /dev/null
+++ b/docs/persisting_n3_terms.rst
@@ -0,0 +1,93 @@
+.. _persisting_n3_terms:
+
+===========================
+Persisting Notation 3 Terms
+===========================
+
+Using N3 Syntax for Persistence
+-------------------------------
+Blank Nodes, Literals, URI References, and Variables can be distinguished in persistence by relying on Notation 3 syntax convention. 
+
+All URI References can be expanded and persisted as:
+
+.. code-block:: text
+
+    <..URI..>
+
+All Literals can be expanded and persisted as:
+
+.. code-block:: text
+
+    "..value.."@lang or "..value.."^^dtype_uri
+
+.. note:: ``@lang`` is a language tag and ``^^dtype_uri`` is the URI of a data type associated with the Literal
+
+Blank Nodes can be expanded and persisted as:
+
+.. code-block:: text
+
+    _:Id 
+
+.. note:: where Id is an identifier as determined by skolemization. Skolemization is a syntactic transformation routinely used in automatic inference systems in which existential variables are replaced by 'new' functions - function names not used elsewhere - applied to any enclosing universal variables. In RDF, Skolemization amounts to replacing every blank node in a graph by a 'new' name, i.e. a URI reference which is guaranteed to not occur anywhere else. In effect, it gives 'arbitrary' names to the anonymous entities whose existence was asserted by the use of blank nodes: the arbitrariness of the names ensures that nothing can be inferred that would not follow from the bare assertion of existence represented by the blank node. (Using a literal would not do. Literals are never 'new' in the required sense.)
+
+Variables can be persisted as they appear in their serialization ``(?varName)`` - since they only need be unique within their scope (the context of their associated statements)
+
+These syntactic conventions can facilitate term round-tripping.
+
+Variables by Scope
+------------------
+Would an interface be needed in order to facilitate a quick way to aggregate all the variables in a scope (given by a formula identifier)? An interface such as:
+
+.. code-block:: python
+
+    def variables(formula_identifier)
+
+The Need to Skolemize Formula Identifiers
+-----------------------------------------
+It would seem reasonable to assume that a formula-aware store would assign Blank Node identifiers as names of formulae that appear in a N3 serialization. So for instance, the following bit of N3:
+
+.. code-block:: text
+
+    {?x a :N3Programmer} => {?x :has :Migrane}
+
+Could be interpreted as the assertion of the following statement:
+
+.. code-block:: text
+
+    _:a log:implies _:b
+
+However, how are ``_:a`` and ``_:b`` distinguished from other Blank Nodes? A formula-aware store would be expected to persist the first set of statements as quoted statements in a formula named ``_:a`` and the second set as quoted statements in a formula named ``_:b``, but it would not be cost-effective for a serializer to have to query the store for all statements in a context named ``_:a`` in order to determine if ``_:a`` was associated with a formula (so that it could be serialized properly).
+
+Relying on ``log:Formula`` Membership
+-------------------------------------
+
+The store could rely on explicit ``log:Formula`` membership (via ``rdf:type`` statements) to model the distinction of Blank Nodes associated with formulae. However, would these statements be expected from an N3 parser or known implicitly by the store? i.e., would all such Blank Nodes match the following pattern:
+
+.. code-block:: text
+
+    ?formula rdf:type log:Formula
+
+Relying on an Explicit Interface
+--------------------------------
+A formula-aware store could also support the persistence of this distinction by implementing a method that returns an iterator over all the formulae in the store:
+
+.. code-block:: python
+
+    def formulae(triple=None)
+
+This function would return all the Blank Node identifiers assigned to formulae or just those that contain statements matching the given triple pattern and would be the way a serializer determines if a term refers to a formula (in order to properly serializer it).
+
+How much would such an interface reduce the need to model formulae terms as first class objects (perhaps to be returned by the :meth:`~rdflib.Graph.triple` function)? Would it be more useful for the :class:`~rdflib.Graph` (or the store itself) to return a Context object in place of a formula term (using the formulae interface to make this determination)?
+
+Conversely, would these interfaces (variables and formulae) be considered optimizations only since you have the distinction by the kinds of terms triples returns (which would be expanded to include variables and formulae)?
+
+Persisting Formula Identifiers
+------------------------------
+This is the most straight forward way to maintain this distinction - without relying on extra interfaces. Formula identifiers could be persisted distinctly from other terms by using the following notation:
+
+.. code-block:: text
+
+    {_:bnode} or {<.. URI ..>}
+
+This would facilitate their persistence round-trip - same as the other terms that rely on N3 syntax to distinguish between each other.
+