Added Documentation

Clean up the benchmark scripts
Added a test and a fix for CTS API Passage regarding siblingsId ( #94 )

.travis.yml

@@ -1,9 +1,8 @@
 language: python
 python:
+  - python: "2.7"
   - "3.4.5"
   - "3.5"
-  - "pypy"
-  - "pypy3"
 
 install:
     - pip install -r requirements.txt

MyCapytain/resources/prototypes/cts/inventory.py

@@ -12,7 +12,7 @@
 from MyCapytain.resources.prototypes.metadata import Collection
 from MyCapytain.common.reference import URN
 from MyCapytain.common.metadata import Metadata, Metadatum
-from MyCapytain.common.constants import NAMESPACES, RDF_PREFIX, Mimetypes
+from MyCapytain.common.constants import NAMESPACES, RDF_PREFIX
 from MyCapytain.errors import InvalidURN
 from collections import defaultdict
 from copy import copy, deepcopy

MyCapytain/resources/texts/api/cts.py

@@ -387,7 +387,7 @@ def __init__(self, urn, resource, *args, **kwargs):
         self.urn = urn
 
         # Could be set during parsing
-        self.__next__ = False
+        self.__nextId__ = False
         self.__prev__ = False
         self.__first__ = False
         self.__last__ = False
@@ -403,7 +403,7 @@ def prevId(self):
         """
         if self.__prev__ is False:
             # Request the next urn
-            self.__prev__, self.__next__ = self.getPrevNextUrn(reference=self.urn.reference)
+            self.__prev__, self.__nextId__ = self.getPrevNextUrn(reference=self.urn.reference)
         return self.__prev__
 
     @property
@@ -413,20 +413,31 @@ def nextId(self):
         :rtype: Reference
         :returns: Following passage reference
         """
-        if self.__next__ is False:
+        if self.__nextId__ is False:
             # Request the next urn
-            self.__prev__, self.__next__ = self.getPrevNextUrn(reference=self.urn.reference)
-        return self.__next__
+            self.__prev__, self.__nextId__ = self.getPrevNextUrn(reference=self.urn.reference)
+        return self.__nextId__
+
+    @property
+    def siblingsId(self):
+        """ Shortcut for getting the previous and next passage identifier
+
+        :rtype: Reference
+        :returns: Following passage reference
+        """
+        if self.__nextId__ is False or self.__prev__ is False:
+            self.__prev__, self.__nextId__ = self.getPrevNextUrn(reference=self.urn.reference)
+        return self.__prev__, self.__nextId__
 
     def __parse__(self):
-        """ Given self.resource, split informations from the CTS API
+        """ Given self.resource, split information from the CTS API
 
         :return: None
         """
         self.response = self.resource
         self.resource = self.resource.xpath("//ti:passage/tei:TEI", namespaces=NS)[0]
 
-        self.__prev__, self.__next__ = __SharedMethod__.prevnext(self.response)
+        self.__prev__, self.__nextId__ = __SharedMethod__.prevnext(self.response)
 
         if self.citation.isEmpty() and len(self.resource.xpath("//ti:citation", namespaces=NS)):
             self.citation = CTSCollection.Citation.ingest(

README.rst

@@ -15,7 +15,71 @@
 .. image:: https://api.codacy.com/project/badge/grade/8e63e69a94274422865e4f275dbf08ea
    :target: https://www.codacy.com/app/leponteineptique/MyCapytain
 
-MyCapytain is a python package which provides a large set of tools to deal with CTS and Capitains Guidelines in Python.
+MyCapytain is a python library which provides a large set of methods to interact with Text Services API  such as the \
+Canonical Text Services, the Distributed Text Services. It also provides a programming interface to exploit local \
+textual resources developed according to the Capitains Guidelines.
+
+Simple Example of what it does
+##############################
+
+On Leipzig DH Chair's Canonical Text Services API, we can find the Epigrammata of Martial. This texts are identified \
+by the identifier "urn:cts:latinLit:phi1294.phi002.perseus-lat2". We want to have some information about this text \
+so we are gonna ask the API to give its metadata to us :
+
+.. code-block:: python
+   :linenos:
+   :caption: example.py from the Github Repository
+
+    from MyCapytain.resolvers.cts.api import HttpCTSResolver
+    from MyCapytain.retrievers.cts5 import CTS
+    from MyCapytain.common.constants import Mimetypes
+
+    # We set up a resolver which communicates with an API available in Leipzig
+    resolver = HttpCTSResolver(CTS("http://cts.dh.uni-leipzig.de/api/cts/"))
+    # We require some metadata information
+    textMetadata = resolver.getMetadata("urn:cts:latinLit:phi1294.phi002.perseus-lat2")
+    # Texts in CTS Metadata have one interesting property : its citation scheme.
+    # Citation are embedded objects that carries information about how a text can be quoted, what depth it has
+    print(type(textMetadata), [citation.name for citation in textMetadata.citation])
+
+This query will return the following information :
+
+.. code-block:: none
+
+   <class 'MyCapytain.resources.collections.cts.Text'> ['book', 'poem', 'line']
+
+.. code-block:: python
+   :linenos:
+   :lineno-start: 12
+
+   # Now, we want to retrieve the first line of poem seventy two of the second book
+   passage = resolver.getTextualNode("urn:cts:latinLit:phi1294.phi002.perseus-lat2", subreference="2.72.1")
+   # And we want to have its content exported to plain text and have the siblings of this passage (previous and next line)
+   print(passage.export(Mimetypes.PLAINTEXT), passage.siblingsId)
+
+And we will get
+
+.. code-block:: none
+
+   Hesterna factum narratur, Postume, cena
+
+If you want to play more with this, like having a list of what can be found in book three, you could go and do
+
+.. code-block:: python
+   :linenos:
+   :lineno-start: 16
+
+   poemsInBook3 = resolver.getReffs("urn:cts:latinLit:phi1294.phi002.perseus-lat2", subreference="3")
+   print(poemsInBook3)
+
+Which would be equal to :
+
+.. code-block:: none
+
+   ['3.1', '3.2', '3.3', '3.4', '3.5', '3.6', '3.7', '3.8', '3.9', '3.10', '3.11', '3.12', '3.13', ...]
+
+Now, it's your time to work with the resource ! See the CapiTainS Classes page on ReadTheDocs to have a general \
+introduction to MyCapytain objects !
 
 Installation and Requirements
 #############################
@@ -35,5 +99,4 @@ If you prefer to use setup.py, you should clone and use the following
 
    git clone https://github.com/Capitains/MyCapytain.git
    cd MyCapytain
-   python setup.py install
-
+   python setup.py install

example.py

@@ -0,0 +1,17 @@
+from MyCapytain.resolvers.cts.api import HttpCTSResolver
+from MyCapytain.retrievers.cts5 import CTS
+from MyCapytain.common.constants import Mimetypes
+
+# We set up a resolver which communicates with an API available in Leipzig
+resolver = HttpCTSResolver(CTS("http://cts.dh.uni-leipzig.de/api/cts/"))
+# We require some metadata information
+textMetadata = resolver.getMetadata("urn:cts:latinLit:phi1294.phi002.perseus-lat2")
+# Texts in CTS Metadata have one interesting property : its citation scheme.
+# Citation are embedded objects that carries information about how a text can be quoted, what depth it has
+print(type(textMetadata), [citation.name for citation in textMetadata.citation])
+# Now, we want to retrieve the first line of poem seventy two of the second book
+passage = resolver.getTextualNode("urn:cts:latinLit:phi1294.phi002.perseus-lat2", subreference="2.72.1")
+# And we want to have its content exported to plain text and have the siblings of this passage (previous and next line)
+print(passage.export(Mimetypes.PLAINTEXT), passage.siblingsId)
+poemsInBook3 = resolver.getReffs("urn:cts:latinLit:phi1294.phi002.perseus-lat2", subreference="3")
+print(poemsInBook3)

tests/resources/texts/api/test_cts.py

@@ -391,6 +391,26 @@ def test_get_first_id(self):
             "FirstId should resolve"
         )
 
+    def test_get_siblings(self):
+        self.endpoint.getPassage = mock.MagicMock(return_value=GET_PASSAGE)
+        self.endpoint.getPrevNextUrn = mock.MagicMock(return_value=NEXT_PREV)
+        self.endpoint.getFirstUrn = mock.MagicMock(return_value=Get_FIRST)
+        self.endpoint.getValidReff = mock.MagicMock(return_value=GET_VALID_REFF_1_1)
+        text = Text(
+            urn="urn:cts:latinLit:phi1294.phi002.perseus-lat2",
+            retriever=self.endpoint
+        )
+        passage = text.getTextualNode("1.1")
+
+        # When next does not exist from the original resource
+        self.endpoint.getPrevNextUrn.assert_called_with(
+            urn="urn:cts:latinLit:phi1294.phi002.perseus-lat2:1.1"
+        )
+        self.assertEqual(
+            passage.siblingsId, ("1.pr", "1.2"),
+            "SiblingsId should resolve"
+        )
+
     def test_get_last_id(self):
         self.endpoint.getPassage = mock.MagicMock(return_value=GET_PASSAGE)
         self.endpoint.getPrevNextUrn = mock.MagicMock(return_value=NEXT_PREV)
@@ -553,6 +573,7 @@ def test_prev_prev_next_property(self):
         # When next does not exist from the original resource
         self.assertEqual(passage.prevId, "1.pr")
         self.assertEqual(passage.nextId, "1.2")
+        self.assertEqual(passage.siblingsId, ("1.pr", "1.2"))
         self.endpoint.getPrevNextUrn.assert_called_with(urn="urn:cts:latinLit:phi1294.phi002.perseus-lat2:1.1")
 
     def test_prev_resource(self):