Final Example + Fixed doc

MyCapytain/resources/texts/api/cts.py

@@ -394,9 +394,13 @@ def __init__(self, urn, resource, *args, **kwargs):
 
         self.__parse__()
 
+    @property
+    def id(self):
+        return str(self.urn.reference)
+
     @property
     def prevId(self):
-        """ Previous passage
+        """ Previous passage Identifier
 
         :rtype: Passage
         :returns: Previous passage at same level
@@ -406,9 +410,18 @@ def prevId(self):
             self.__prev__, self.__nextId__ = self.getPrevNextUrn(reference=self.urn.reference)
         return self.__prev__
 
+    @property
+    def parentId(self):
+        """ Shortcut for getting the parent passage identifier
+
+        :rtype: Reference
+        :returns: Following passage reference
+        """
+        return str(self.urn.reference.parent)
+
     @property
     def nextId(self):
-        """ Shortcut for getting the following passage
+        """ Shortcut for getting the following passage identifier
 
         :rtype: Reference
         :returns: Following passage reference

doc/DistantText.py

@@ -0,0 +1,82 @@
+from MyCapytain.retrievers.cts5 import CTS
+from MyCapytain.resources.texts.api.cts import Text
+
+# We set up a retriever which communicates with an API available in Leipzig
+retriever = CTS("http://cts.dh.uni-leipzig.de/api/cts/")
+
+# Given that we have other examples that shows how to work with text,
+# we will focus here on playing with the graph functionality of texts implementations.
+# We are gonna retrieve a text passage and the retrieve all its siblings in different fashion#
+# The main point is to find all children of the same parent.
+# The use case could be the following : some one want to retrieve the full text around a citation
+# To enhance the display a little.
+
+# We will work with the line 7 of poem 39 of book 4 of Martial's Epigrammata
+# The text is urn:cts:latinLit:phi1294.phi002.perseus-lat2
+text = Text(retriever=retriever, urn="urn:cts:latinLit:phi1294.phi002.perseus-lat2")
+
+# We retrieve up the passage
+target = text.getTextualNode(subreference="4.39.7")
+print(target.text)
+"""
+Nec quae Callaico linuntur auro,
+"""
+
+# The parent way :
+# - get to the parent,
+# - retrieve each node,
+# - print only the one which are not target
+
+parent = target.parent
+for node in parent.children:
+    if node.id != target.id:
+        print("{}\t{}".format(node.id, node.text))
+    else:
+        print("------Original Node-----------")
+
+"""
+4.39.1	Argenti genus omne comparasti,
+4.39.2	Et solus veteres Myronos artes,
+4.39.3	Solus Praxitelus manum Scopaeque,
+4.39.4	Solus Phidiaci toreuma caeli,
+4.39.5	Solus Mentoreos habes labores.
+4.39.6	Nec desunt tibi vera Gratiana,
+------Original Node-----------
+4.39.8	Nec mensis anaglypta de paternis.
+4.39.9	Argentum tamen inter omne miror
+4.39.10	Quare non habeas, Charine, purum.
+"""
+
+print("\n\nSecond Method\n\n")
+
+# We are gonna do another way this time :
+# - get the previous until we change parent
+# - get the next until we change parent
+
+parentId = node.parentId
+# Deal with the previous ones
+current = target.prev
+while current.parentId == parentId:
+    print("{}\t{}".format(current.id, current.text))
+    current = current.prev
+
+print("------Original Node-----------")
+
+# Deal with the next ones
+current = target.next
+while current.parentId == parentId:
+    print("{}\t{}".format(current.id, current.text))
+    current = current.next
+"""
+4.39.6	Nec desunt tibi vera Gratiana,
+4.39.5	Solus Mentoreos habes labores.
+4.39.4	Solus Phidiaci toreuma caeli,
+4.39.3	Solus Praxitelus manum Scopaeque,
+4.39.2	Et solus veteres Myronos artes,
+4.39.1	Argenti genus omne comparasti,
+------Original Node-----------
+4.39.8	Nec mensis anaglypta de paternis.
+4.39.9	Argentum tamen inter omne miror
+4.39.10	Quare non habeas, Charine, purum.
+
+"""

doc/MyCapytain.classes.rst

@@ -97,9 +97,7 @@ being able to interact with citable, in-graph texts that are retrieve through we
 implementation should make sure that the whole set of navigation tool are covered. Those are :
 
 +---------------------------------------------+----------------------------------------------------------------------+-----------------------------------+-------------------------------------------------------------+
-| Tree Identifiers
-(Returns str Identifiers)  | Tree Navigations
-(Returns InteractiveTextualNode or children class)  | Retrieval Methods                 | Other                                                       |
+| Tree Identifiers(Returns str Identifiers)   | Tree Navigations (Returns InteractiveTextualNode or children class)  | Retrieval Methods                 | Other                                                       |
 +=============================================+======================================================================+===================================+=============================================================+
 | prevId                                      | prev                                                                 | .getTextualNode(subreference)     | id : TextualNode Identifier [str]                           |
 +---------------------------------------------+----------------------------------------------------------------------+-----------------------------------+-------------------------------------------------------------+
@@ -115,8 +113,6 @@ implementation should make sure that the whole set of navigation tool are covere
 +---------------------------------------------+----------------------------------------------------------------------+-----------------------------------+-------------------------------------------------------------+
 | lastId                                      | last                                                                 |                                   |                                                             |
 +---------------------------------------------+----------------------------------------------------------------------+-----------------------------------+-------------------------------------------------------------+
-|                                             |                                                                      |                                   |                                                             |
-+---------------------------------------------+----------------------------------------------------------------------+-----------------------------------+-------------------------------------------------------------+
 
 
 The encodings module
@@ -133,7 +129,9 @@ lxml etree interface.
 Implementation example : HTTP API Passage work
 **********************************************
 
-
+.. literalinclude:: DistantText.py
+   :language: python
+   :linenos:
 
 Other Example
 *************

tests/resources/texts/api/test_cts.py

@@ -662,6 +662,27 @@ def test_get_last_id(self):
             "FirstId should resolve"
         )
 
+    def test_parentId(self):
+        """ Test next property, given that next information already exists or not)
+        """
+
+        passage = Passage(
+            urn="urn:cts:latinLit:phi1294.phi002.perseus-lat2:1.1",
+            resource=GET_PASSAGE,
+            retriever=self.endpoint
+        )
+
+        self.assertEqual(
+            passage.parentId, "1",
+            "ParentId should resolve"
+        )
+        self.assertIsInstance(
+            passage.parent, Passage,
+            "Parent Passage should be a passage"
+        )
+        self.endpoint.getPassage.assert_called_with(urn="urn:cts:latinLit:phi1294.phi002.perseus-lat2:1")
+
+
     def test_prev_id(self):
         """ Test next property, given that next information already exists or not)
         """