Merge pull request #997 from kushagr08/master

Fix #280: Added container.py for adding container class and seq, alt and bag as it's subclasses

Author: Nicholas Car

docs/conf.py

@@ -154,7 +154,7 @@ def find_version(filename):
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
-html_favicon = "_static/logo-rdflib.ico"
+html_favicon = "_static/RDFlib.ico"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

docs/intro_to_creating_rdf.rst

@@ -128,24 +128,46 @@ When removing, it is possible to leave parts of the triple unspecified (i.e. pas
 
 .. code-block:: python
 
-    g.remove((bob, None, None)) # remove all triples about bob
+    g.remove((bob, None, None))  # remove all triples about bob
 
 
 An example
 ----------
 
 LiveJournal produces FOAF data for their users, but they seem to use
-``foaf:member_name`` for a person's full name. To align with data from
-other sources, it would be nice to have ``foaf:name`` act as a synonym
-for ``foaf:member_name`` (a poor man's one-way
-``owl:equivalentProperty``):
+``foaf:member_name`` for a person's full name but ``foaf:member_name``
+isn't in FOAF's namespace and perhaps they should have used ``foaf:name``
+
+To retrieve some LiveJournal data, add a ``foaf:name`` for every
+``foaf:member_name`` and then remove the ``foaf:member_name`` values to
+ensure the data actually aligns with other FOAF data, we could do this:
 
 .. code-block:: python
 
+    from rdflib import Graph
     from rdflib.namespace import FOAF
-    g.parse("http://danbri.livejournal.com/data/foaf") 
+
+    g = Graph()
+    # get the data
+    g.parse("http://danbri.livejournal.com/data/foaf")
+
+    # for every foaf:member_name, add foaf:name and remove foaf:member_name
     for s, p, o in g.triples((None, FOAF['member_name'], None)):
         g.add((s, FOAF['name'], o))
+        g.remove((s, FOAF['member_name'], o))
+
+.. note:: Since rdflib 5.0.0, using ``foaf:member_name`` is somewhat prevented in RDFlib since FOAF is declared
+    as a :meth:`~rdflib.namespace.ClosedNamespace` class instance that has a closed set of members and
+    ``foaf:member_name`` isn't one of them! If LiveJournal used RDFlib 5.0.0, an error would have been raised for
+    ``foaf:member_name`` when the triple was created.
+
+
+Creating Containers & Collections
+---------------------------------
+There are two convenience classes for RDF Containers & Collections which you can use instead of declaring each
+triple of a Containers or a Collections individually:
+
+    * :meth:`~rdflib.container.Container` (also ``Bag``, ``Seq`` & ``Alt``) and
+    * :meth:`~rdflib.collection.Collection`
 
-Note that since rdflib 5.0.0, using ``foaf:member_name`` is somewhat prevented in rdflib since FOAF is declared as a :meth:`~rdflib.namespace.ClosedNamespace`
-class instance that has a closed set of members and ``foaf:member_name`` isnt one of them!
+See their documentation for how.

docs/rdf_terms.rst

@@ -20,7 +20,7 @@ matching nodes by term-patterns probably will only be terms and not nodes.
 BNodes
 ======
 
-    In RDF, a blank node (also called BNode) is a node in an RDF graph representing a resource for which a URI or literal is not given. The resource represented by a blank node is also called an anonymous resource. By RDF standard a blank node can only be used as subject or object in an RDF triple, although in some syntaxes like Notation 3 [1] it is acceptable to use a blank node as a predicate. If a blank node has a node ID (not all blank nodes are labelled in all RDF serializations), it is limited in scope to a serialization of a particular RDF graph, i.e. the node p1 in the subsequent example does not represent the same node as a node named p1 in any other graph  --`wikipedia`__
+In RDF, a blank node (also called BNode) is a node in an RDF graph representing a resource for which a URI or literal is not given. The resource represented by a blank node is also called an anonymous resource. By RDF standard a blank node can only be used as subject or object in an RDF triple, although in some syntaxes like Notation 3 [1] it is acceptable to use a blank node as a predicate. If a blank node has a node ID (not all blank nodes are labelled in all RDF serializations), it is limited in scope to a serialization of a particular RDF graph, i.e. the node p1 in the subsequent example does not represent the same node as a node named p1 in any other graph  --`wikipedia`__
 
 
 .. __: http://en.wikipedia.org/wiki/Blank_node
@@ -40,7 +40,7 @@ BNodes
 URIRefs
 =======
 
-    A URI reference within an RDF graph is a Unicode string that does not contain any control characters ( #x00 - #x1F, #x7F-#x9F) and would produce a valid URI character sequence representing an absolute URI with optional fragment identifier -- `W3 RDF Concepts`__
+A URI reference within an RDF graph is a Unicode string that does not contain any control characters ( #x00 - #x1F, #x7F-#x9F) and would produce a valid URI character sequence representing an absolute URI with optional fragment identifier -- `W3 RDF Concepts`__
 
 .. __: http://www.w3.org/TR/rdf-concepts/#section-Graph-URIref
 
@@ -159,4 +159,3 @@ All this happens automatically when creating ``Literal`` objects by passing Pyth
 
 You can add custom data-types with :func:`rdflib.term.bind`, see also :mod:`examples.custom_datatype`
 
-

rdflib/__init__.py

@@ -196,3 +196,5 @@
 assert query
 
 from rdflib import util
+
+from .container import *

rdflib/container.py

@@ -0,0 +1,265 @@
+from rdflib.namespace import RDF
+from rdflib.term import BNode
+from rdflib import URIRef
+from random import randint
+
+__all__ = ["Container", "Bag", "Seq", "Alt", "NoElementException"]
+
+
+class Container(object):
+    """A class for constructing RDF containers, as per https://www.w3.org/TR/rdf11-mt/#rdf-containers
+
+    Basic usage, creating a ``Bag`` and adding to it::
+
+        >>> from rdflib import Graph, BNode, Literal, Bag
+        >>> g = Graph()
+        >>> b = Bag(g, BNode(), [Literal("One"), Literal("Two"), Literal("Three")])
+        >>> print(g.serialize(format="turtle").decode())
+        @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+        <BLANKLINE>
+        [] a rdf:Bag ;
+            rdf:_1 "One" ;
+            rdf:_2 "Two" ;
+            rdf:_3 "Three" .
+        <BLANKLINE>
+        <BLANKLINE>
+
+        >>> # print out an item using an index reference
+        >>> print(b[2])
+        Two
+
+        >>> # add a new item
+        >>> b.append(Literal("Hello"))
+        >>> print(g.serialize(format="turtle").decode())
+        @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+        <BLANKLINE>
+        [] a rdf:Bag ;
+            rdf:_1 "One" ;
+            rdf:_2 "Two" ;
+            rdf:_3 "Three" ;
+            rdf:_4 "Hello" .
+        <BLANKLINE>
+        <BLANKLINE>
+
+    """
+
+    def __init__(self, graph, uri, seq=[], rtype="Bag"):
+        """Creates a Container
+
+        :param graph: a Graph instance
+        :param uri: URI or Blank Node of the Container
+        :param seq: the elements of the Container
+        :param rtype: the type of Container, one of "Bag", "Seq" or "Alt"
+        """
+
+        self.graph = graph
+        self.uri = uri or BNode()
+        self._len = 0
+        self._rtype = rtype  # rdf:Bag or rdf:Seq or rdf:Alt
+
+        self.append_multiple(seq)
+
+        # adding triple corresponding to container type
+        self.graph.add((self.uri, RDF.type, RDF[self._rtype]))
+
+    def n3(self):
+
+        items = []
+        for i in range(len(self)):
+
+            v = self[i + 1]
+            items.append(v)
+
+        return "( %s )" % " ".join([a.n3() for a in items])
+
+    def _get_container(self):
+        """Returns the URI of the container"""
+
+        return self.uri
+
+    def __len__(self):
+        """Number of items in container"""
+
+        return self._len
+
+    def type_of_conatiner(self):
+        return self._rtype
+
+    def index(self, item):
+        """Returns the 1-based numerical index of the item in the container"""
+
+        pred = self.graph.predicates(self.uri, item)
+        if not pred:
+            raise ValueError("%s is not in %s" % (item, "container"))
+        LI_INDEX = URIRef(str(RDF) + "_")
+
+        i = None
+        for p in pred:
+            i = int(p.replace(LI_INDEX, ""))
+        return i
+
+    def __getitem__(self, key):
+        """Returns item of the container at index key"""
+
+        c = self._get_container()
+
+        assert isinstance(key, int)
+        elem_uri = str(RDF) + "_" + str(key)
+        if key <= 0 or key > len(self):
+            raise KeyError(key)
+        v = self.graph.value(c, URIRef(elem_uri))
+        if v:
+            return v
+        else:
+            raise KeyError(key)
+
+    def __setitem__(self, key, value):
+        """Sets the item at index key or predicate rdf:_key of the container to value"""
+
+        assert isinstance(key, int)
+
+        c = self._get_container()
+        elem_uri = str(RDF) + "_" + str(key)
+        if key <= 0 or key > len(self):
+            raise KeyError(key)
+
+        self.graph.set((c, URIRef(elem_uri), value))
+
+    def __delitem__(self, key):
+        """Removing the item with index key or predicate rdf:_key"""
+
+        assert isinstance(key, int)
+        if key <= 0 or key > len(self):
+            raise KeyError(key)
+
+        graph = self.graph
+        container = self.uri
+        elem_uri = str(RDF) + "_" + str(key)
+        graph.remove((container, URIRef(elem_uri), None))
+        for j in range(key + 1, len(self) + 1):
+            elem_uri = str(RDF) + "_" + str(j)
+            v = graph.value(container, URIRef(elem_uri))
+            graph.remove((container, URIRef(elem_uri), v))
+            elem_uri = str(RDF) + "_" + str(j - 1)
+            graph.add((container, URIRef(elem_uri), v))
+
+        self._len -= 1
+
+    def items(self):
+        """Returns a list of all items in the container"""
+
+        l_ = []
+        container = self.uri
+        i = 1
+        while True:
+            elem_uri = str(RDF) + "_" + str(i)
+
+            if (container, URIRef(elem_uri), None) in self.graph:
+                i += 1
+                l_.append(self.graph.value(container, URIRef(elem_uri)))
+            else:
+                break
+        return l_
+
+    def end(self):  #
+
+        # find end index (1-based) of container
+
+        container = self.uri
+        i = 1
+        while True:
+            elem_uri = str(RDF) + "_" + str(i)
+
+            if (container, URIRef(elem_uri), None) in self.graph:
+                i += 1
+            else:
+                return i - 1
+
+    def append(self, item):
+        """Adding item to the end of the container"""
+
+        end = self.end()
+        elem_uri = str(RDF) + "_" + str(end + 1)
+        container = self.uri
+        self.graph.add((container, URIRef(elem_uri), item))
+        self._len += 1
+
+    def append_multiple(self, other):
+        """Adding multiple elements to the container to the end which are in python list other"""
+
+        end = self.end()  # it should return the last index
+
+        container = self.uri
+        for item in other:
+
+            end += 1
+            self._len += 1
+            elem_uri = str(RDF) + "_" + str(end)
+            self.graph.add((container, URIRef(elem_uri), item))
+
+    def clear(self):
+        """Removing all elements from the container"""
+
+        container = self.uri
+        graph = self.graph
+        i = 1
+        while True:
+            elem_uri = str(RDF) + "_" + str(i)
+            if (container, URIRef(elem_uri), None) in self.graph:
+                graph.remove((container, URIRef(elem_uri), None))
+                i += 1
+            else:
+                break
+        self._len = 0
+
+
+class Bag(Container):
+    """Unordered container (no preference order of elements)"""
+
+    def __init__(self, graph, uri, seq=[]):
+        Container.__init__(self, graph, uri, seq, "Bag")
+
+
+class Alt(Container):
+    def __init__(self, graph, uri, seq=[]):
+        Container.__init__(self, graph, uri, seq, "Alt")
+
+    def anyone(self):
+        if len(self) == 0:
+            raise NoElementException()
+        else:
+            p = randint(1, len(self))
+            item = self.__getitem__(p)
+            return item
+
+
+class Seq(Container):
+    def __init__(self, graph, uri, seq=[]):
+        Container.__init__(self, graph, uri, seq, "Seq")
+
+    def add_at_position(self, pos, item):
+        assert isinstance(pos, int)
+        if pos <= 0 or pos > len(self) + 1:
+            raise ValueError("Invalid Position for inserting element in rdf:Seq")
+
+        if pos == len(self) + 1:
+            self.append(item)
+        else:
+            for j in range(len(self), pos - 1, -1):
+                container = self._get_container()
+                elem_uri = str(RDF) + "_" + str(j)
+                v = self.graph.value(container, URIRef(elem_uri))
+                self.graph.remove((container, URIRef(elem_uri), v))
+                elem_uri = str(RDF) + "_" + str(j + 1)
+                self.graph.add((container, URIRef(elem_uri), v))
+            elem_uri_pos = str(RDF) + "_" + str(pos)
+            self.graph.add((container, URIRef(elem_uri_pos), item))
+            self._len += 1
+
+
+class NoElementException(Exception):
+    def __init__(self, message="rdf:Alt Container is empty"):
+        self.message = message
+
+    def __str__(self):
+        return self.message

requirements.dev.txt

@@ -0,0 +1,3 @@
+sphinx
+sphinxcontrib-apidoc
+black