Enhancing Collection Documentation

Capitains · Dec 21, 2016 · a28fbac · a28fbac
1 parent a6345a9
commit a28fbac
Show file tree

Hide file tree

Showing 10 changed files with 139 additions and 19 deletions.
diff --git a/MyCapytain/common/metadata.py b/MyCapytain/common/metadata.py
@@ -104,15 +104,15 @@ def __getitem__(self, key):
         if isinstance(key, int):
             items = list(self.children.keys())
             if key + 1 > len(items):
-                raise KeyError()
+                raise KeyError("Unknown key %s" % key)
             else:
                 key = items[key]
         elif isinstance(key, tuple):
             return tuple([self[k] for k in key])
 
         if key not in self.children:
             if self.default is None:
-                raise KeyError()
+                raise KeyError("Unknown key %s" % key)
             else:
                 return self.children[self.default]
         else:
@@ -186,10 +186,8 @@ def __iter__(self):
             >>> for key, value in a:
             >>>     print(key, value) # Print ("lat", "Amores") and then ("fre", "Les Amours")
         """
-        i = 0
         for key in self.children:
             yield (key, self.children[key])
-            i += 1
 
     def __len__(self):
         """ Get the length of the current Metadatum object

diff --git a/MyCapytain/resources/prototypes/cts/inventory.py b/MyCapytain/resources/prototypes/cts/inventory.py
@@ -156,7 +156,7 @@ class Text(CTSCollection):
     :type subtype: str
     """
 
-    DC_TITLE = "label"
+    DC_TITLE_KEY = "label"
 
     @property
     def TEXT_URI(self):

diff --git a/MyCapytain/resources/prototypes/metadata.py b/MyCapytain/resources/prototypes/metadata.py
@@ -8,7 +8,7 @@
 """
 from copy import deepcopy
 
-from MyCapytain.common.metadata import Metadata
+from MyCapytain.common.metadata import Metadatum, Metadata
 from MyCapytain.common.constants import NAMESPACES, RDF_PREFIX, Mimetypes, Exportable
 
 
@@ -32,21 +32,17 @@ class Collection(Exportable):
     def title(self):
         """ Title of the collection Item
 
-        :rtype: Metadata
+        :rtype: Metadatum
         """
-        if self.__title__ is not None:
-            return self.__title__
         if hasattr(type(self), "DC_TITLE_KEY") and self.DC_TITLE_KEY:
-            self.__title__ = Metadata(keys=["dc:title"])
-            self.__title__["dc:title"] = deepcopy(self.metadata[type(self).DC_TITLE_KEY])
-            self.__title__["dc:title"].namespace = NAMESPACES.DC
-            self.__title__["dc:title"].name = "title"
-            return self.__title__
+            return Metadatum(
+                "title", namespace=NAMESPACES.DC,
+                children=[(lang, value) for lang, value in self.metadata[type(self).DC_TITLE_KEY]]
+            )
 
     def __init__(self):
         self.metadata = Metadata()
         self.__id__ = None
-        self.__title__ = None
         self.properties = {
             RDF_PREFIX["dts"]+"model": "http://w3id.org/dts-ontology/collection",
             RDF_PREFIX["rdf"]+"type": self.TYPE_URI
@@ -112,7 +108,9 @@ def __export__(self, output=None, domain=""):
             if self.id is None:
                 identifier = ""
             if self.title:
-                m = self.metadata + self.title
+                m = Metadata(keys="dc:title")
+                m["dc:title"] = self.title
+                m += self.metadata
             else:
                 m = self.metadata
             o = {

diff --git a/doc/Collections.py b/doc/Collections.py
@@ -0,0 +1,57 @@
+from MyCapytain.retrievers.cts5 import CTS
+from MyCapytain.resources.collections.cts import TextInventory
+from MyCapytain.common.constants import Mimetypes
+from pprint import pprint
+
+"""
+In order to have a real life example,
+we are gonna query for data in the Leipzig CTS API
+We are gonna query for metadata about Seneca who
+is represented by urn:cts:latinLit:stoa0255
+
+To retrieve data, we are gonna make a GetMetadata query
+to the CTS Retriever.
+"""
+retriever = CTS("http://cts.dh.uni-leipzig.de/api/cts/")
+# We store the response (Pure XML String)
+response = retriever.getMetadata(objectId="urn:cts:latinLit:stoa0255")
+
+"""
+From here, we actually have the necessary data, we can now
+play with collections. TextInventory is the main collection type that is needed to
+parse the whole response.
+"""
+inventory = TextInventory(resource=response)
+# What we are gonna do is print the title of each descendant :
+for descendant in inventory.descendants:
+    print(descendant.title["default"])
+
+"""
+You should see in there things such as
+-   "Seneca, Lucius Annaeus" (The TextGroup or main object)
+-   "de Ira" (The Work object)
+-   "de Ira, Moral essays Vol 2" (The Edition specific Title)
+
+We can now see other functions, such as the export to JSON DTS.
+CTS Collection have a uniquely feature built in : they allow for
+accessing an item using its key as if it were a dictionary :
+The identifier of a De Ira is urn:cts:latinLit:stoa0255.stoa0110
+"""
+deIra = inventory["urn:cts:latinLit:stoa0255.stoa010"]
+pprint(deIra.export(output=Mimetypes.JSON.DTS.Std))
+# you should see a DTS representation of the work
+
+"""
+What we might want to do is to browse metadata about seneca's De Ira
+Remember that CTSCollections have a parents attribute !
+"""
+for descAsc in deIra.descendants + [deIra] + deIra.parents:
+    # We filter out Textgroup which has an empty Metadata value
+    if not isinstance(descAsc, TextInventory):
+        print(
+            descAsc.metadata.export(output=Mimetypes.JSON.Std)
+        )
+"""
+And of course, we can simply export deIra to CTS XML format
+"""
+print(deIra.export(Mimetypes.XML.CTS))
diff --git a/doc/MyCapytain.classes.rst b/doc/MyCapytain.classes.rst
@@ -106,14 +106,30 @@ Main Properties
 Implementation : CTS Collections
 ********************************
 
+.. note:: For a recap on what Textgroup means or any CTS jargon, go to http://capitains.github.io/pages/vocabulary
+
 CTS Collections are divided in 4 kinds : TextInventory, TextGroup, Work, Text. Their specificity is that the hierarchy\
-of these objects are predefined and always follow the same order.
+of these objects are predefined and always follow the same order. They implement a special export (\
+:code:`MyCapytain.common.constants.Mimetypes.XML.CTS`) which basically exports to the XML Text Inventory Format\
+that one would find making a GetCapabilities request.
+
+CapiTainS CTS Collections implement a parents property which represent a list of parents where .parents' order is equal\
+to :code:`Text.parents = [Work(), TextGroup(), TextInventory()]`).
+
+Their finale implementation accepts to parse resources through the :code:`resource=` named argument.
 
 
 .. image:: _static/images/Collections.svg
     :target: _static/images/Collections.dia
     :alt: Diagram of collections prototypes
 
+Example
+*******
+
+.. literalinclude:: Collections.py
+   :language: python
+   :linenos:
+
 Resolvers
 #########
 

diff --git a/doc/_static/images/Collections.dia b/doc/_static/images/Collections.dia
diff --git a/doc/_static/images/Collections.png b/doc/_static/images/Collections.png
diff --git a/doc/_static/images/Collections.svg b/doc/_static/images/Collections.svg
diff --git a/tests/resources/collections/test_cts_collection_inheritance.py b/tests/resources/collections/test_cts_collection_inheritance.py
@@ -0,0 +1,42 @@
+from unittest import TestCase
+from MyCapytain.resources.collections.cts import TextInventory, TextGroup, Work, Text
+from MyCapytain.common.metadata import Metadatum
+
+with open("tests/testing_data/examples/getcapabilities.seneca.xml") as f:
+    SENECA = f.read()
+
+
+class TestCollectionCTSInheritance(TestCase):
+    def test_types(self):
+        TI = TextInventory(resource=SENECA)
+        self.assertCountEqual(
+            [type(descendant) for descendant in TI.descendants],
+            [TextGroup] + [Work]*10 + [Text]*10,
+            "Descendant should be correctly parsed into correct types"
+        )
+        self.assertCountEqual(
+            [type(descendant) for descendant in TI.readableDescendants],
+            [Work]*10 + [Text]*10,
+            "Descendant should be correctly parsed into correct types and filtered when readable"
+        )
+
+    def test_title(self):
+        TI = TextInventory(resource=SENECA)
+        self.assertCountEqual(
+            [descendant.title["default"] for descendant in TI.descendants],
+            ["Seneca, Lucius Annaeus", "de Ira", "de Vita Beata", "de consolatione ad Helviam", "de Constantia",
+             "de Tranquilitate Animi", "de Brevitate Vitae", "de consolatione ad Polybium",
+             "de consolatione ad Marciam", "de Providentia", "de Otio Sapientis", "de Ira, Moral essays Vol 2",
+             "de Vita Beata, Moral essays Vol 2", "de consolatione ad Helviam, Moral essays Vol 2",
+             "de Constantia, Moral essays Vol 2", "de Tranquilitate Animi, Moral essays Vol 2",
+             "de Brevitate Vitae, Moral essays Vol 2", "de consolatione ad Polybium, Moral essays Vol 2",
+             "de consolatione ad Marciam, Moral essays Vol 2", "de Providentia, Moral essays Vol 2",
+             "de Otio Sapientis, Moral essays Vol 2"],
+            "Title should be computed correctly : default should be set"
+        )
+        self.assertEqual(
+            [isinstance(descendant.title, Metadatum) for descendant in TI.descendants],
+            [True, True, True, True, True, True, True, True, True, True, True, True, True, True, True, True, True, True,
+             True, True, True],
+            "Title should be Metadatum objects"
+        )
diff --git a/tests/testing_data/examples/getcapabilities.seneca.xml b/tests/testing_data/examples/getcapabilities.seneca.xml
@@ -0,0 +1,9 @@
+<GetCapabilities xmlns="http://chs.harvard.edu/xmlns/cts">
+            <request>
+                <requestName>GetInventory</requestName>
+                <requestFilters>urn=urn:cts:latinLit:stoa0255</requestFilters>
+            </request>
+            <reply>
+                <ti:TextInventory xmlns:ti='http://chs.harvard.edu/xmlns/cts'><ti:textgroup urn='urn:cts:latinLit:stoa0255' xmlns:ti='http://chs.harvard.edu/xmlns/cts'><ti:groupname xml:lang='eng'>Seneca, Lucius Annaeus</ti:groupname><ti:work xml:lang="lat" urn='urn:cts:latinLit:stoa0255.stoa010' groupUrn='urn:cts:latinLit:stoa0255' xmlns:ti='http://chs.harvard.edu/xmlns/cts'><ti:title xml:lang='lat'>de Ira</ti:title><ti:edition urn='urn:cts:latinLit:stoa0255.stoa010.perseus-lat2' workUrn='urn:cts:latinLit:stoa0255.stoa010' xmlns:ti='http://chs.harvard.edu/xmlns/cts'><ti:label xml:lang='eng'>de Ira, Moral essays Vol 2</ti:label><ti:description xml:lang='eng'>Seneca, Lucius Annaeus, ca. 4 B.C.-65 A.D, creator; Basore, John W. (John William), b. 1870, editor; Basore, John W. (John William), b. 1870, editor, translator</ti:description><ti:online><ti:citationMapping><ti:citation label="book" xpath="/tei:div[@n='?']" scope="/tei:TEI/tei:text/tei:body/tei:div"><ti:citation label="chapter" xpath="/tei:div[@n='?']" scope="/tei:TEI/tei:text/tei:body/tei:div/tei:div[@n='?']"><ti:citation label="section" xpath="/tei:div[@n='?']" scope="/tei:TEI/tei:text/tei:body/tei:div/tei:div[@n='?']/tei:div[@n='?']"></ti:citation></ti:citation></ti:citation></ti:citationMapping></ti:online></ti:edition></ti:work><ti:work xml:lang="lat" urn='urn:cts:latinLit:stoa0255.stoa006' groupUrn='urn:cts:latinLit:stoa0255' xmlns:ti='http://chs.harvard.edu/xmlns/cts'><ti:title xml:lang='lat'>de consolatione ad Helviam</ti:title><ti:edition urn='urn:cts:latinLit:stoa0255.stoa006.perseus-lat2' workUrn='urn:cts:latinLit:stoa0255.stoa006' xmlns:ti='http://chs.harvard.edu/xmlns/cts'><ti:label xml:lang='eng'>de consolatione ad Helviam, Moral essays Vol 2</ti:label><ti:description xml:lang='eng'>Seneca, Lucius Annaeus, ca. 4 B.C.-65 A.D, creator; Basore, John W. (John William), b. 1870, editor; Basore, John W. (John William), b. 1870, editor, translator</ti:description><ti:online><ti:citationMapping><ti:citation label="chapter" xpath="/tei:div[@n='?']" scope="/tei:TEI/tei:text/tei:body/tei:div/tei:div"><ti:citation label="section" xpath="/tei:div[@n='?']" scope="/tei:TEI/tei:text/tei:body/tei:div/tei:div/tei:div[@n='?']"></ti:citation></ti:citation></ti:citationMapping></ti:online></ti:edition></ti:work><ti:work xml:lang="lat" urn='urn:cts:latinLit:stoa0255.stoa013' groupUrn='urn:cts:latinLit:stoa0255' xmlns:ti='http://chs.harvard.edu/xmlns/cts'><ti:title xml:lang='lat'>de Tranquilitate Animi</ti:title><ti:edition urn='urn:cts:latinLit:stoa0255.stoa013.perseus-lat2' workUrn='urn:cts:latinLit:stoa0255.stoa013' xmlns:ti='http://chs.harvard.edu/xmlns/cts'><ti:label xml:lang='eng'>de Tranquilitate Animi, Moral essays Vol 2</ti:label><ti:description xml:lang='eng'>Seneca, Lucius Annaeus, ca. 4 B.C.-65 A.D, creator; Basore, John W. (John William), b. 1870, editor; Basore, John W. (John William), b. 1870, editor, translator</ti:description><ti:online><ti:citationMapping><ti:citation label="chapter" xpath="/tei:div[@n='?']" scope="/tei:TEI/tei:text/tei:body/tei:div/tei:div"><ti:citation label="section" xpath="/tei:div[@n='?']" scope="/tei:TEI/tei:text/tei:body/tei:div/tei:div/tei:div[@n='?']"></ti:citation></ti:citation></ti:citationMapping></ti:online></ti:edition></ti:work><ti:work xml:lang="lat" urn='urn:cts:latinLit:stoa0255.stoa008' groupUrn='urn:cts:latinLit:stoa0255' xmlns:ti='http://chs.harvard.edu/xmlns/cts'><ti:title xml:lang='lat'>de consolatione ad Polybium</ti:title><ti:edition urn='urn:cts:latinLit:stoa0255.stoa008.perseus-lat2' workUrn='urn:cts:latinLit:stoa0255.stoa008' xmlns:ti='http://chs.harvard.edu/xmlns/cts'><ti:label xml:lang='eng'>de consolatione ad Polybium, Moral essays Vol 2</ti:label><ti:description xml:lang='eng'>Seneca, Lucius Annaeus, ca. 4 B.C.-65 A.D, creator; Basore, John W. (John William), b. 1870, editor; Basore, John W. (John William), b. 1870, editor, translator</ti:description><ti:online><ti:citationMapping><ti:citation label="chapter" xpath="/tei:div[@n='?']" scope="/tei:TEI/tei:text/tei:body/tei:div/tei:div"><ti:citation label="section" xpath="/tei:div[@n='?']" scope="/tei:TEI/tei:text/tei:body/tei:div/tei:div/tei:div[@n='?']"></ti:citation></ti:citation></ti:citationMapping></ti:online></ti:edition></ti:work><ti:work xml:lang="lat" urn='urn:cts:latinLit:stoa0255.stoa004' groupUrn='urn:cts:latinLit:stoa0255' xmlns:ti='http://chs.harvard.edu/xmlns/cts'><ti:title xml:lang='lat'>de Brevitate Vitae</ti:title><ti:edition urn='urn:cts:latinLit:stoa0255.stoa004.perseus-lat2' workUrn='urn:cts:latinLit:stoa0255.stoa004' xmlns:ti='http://chs.harvard.edu/xmlns/cts'><ti:label xml:lang='eng'>de Brevitate Vitae, Moral essays Vol 2</ti:label><ti:description xml:lang='eng'>Seneca, Lucius Annaeus, ca. 4 B.C.-65 A.D, creator; Basore, John W. (John William), b. 1870, editor; Basore, John W. (John William), b. 1870, editor, translator</ti:description><ti:online><ti:citationMapping><ti:citation label="chapter" xpath="/tei:div[@n='?']" scope="/tei:TEI/tei:text/tei:body/tei:div/tei:div"><ti:citation label="section" xpath="/tei:div[@n='?']" scope="/tei:TEI/tei:text/tei:body/tei:div/tei:div/tei:div[@n='?']"></ti:citation></ti:citation></ti:citationMapping></ti:online></ti:edition></ti:work><ti:work xml:lang="lat" urn='urn:cts:latinLit:stoa0255.stoa011' groupUrn='urn:cts:latinLit:stoa0255' xmlns:ti='http://chs.harvard.edu/xmlns/cts'><ti:title xml:lang='lat'>de Otio Sapientis</ti:title><ti:edition urn='urn:cts:latinLit:stoa0255.stoa011.perseus-lat2' workUrn='urn:cts:latinLit:stoa0255.stoa011' xmlns:ti='http://chs.harvard.edu/xmlns/cts'><ti:label xml:lang='eng'>de Otio Sapientis, Moral essays Vol 2</ti:label><ti:description xml:lang='eng'>Seneca, Lucius Annaeus, ca. 4 B.C.-65 A.D, creator; Basore, John W. (John William), b. 1870, editor; Basore, John W. (John William), b. 1870, editor, translator</ti:description><ti:online><ti:citationMapping><ti:citation label="chapter" xpath="/tei:div[@n='?']" scope="/tei:TEI/tei:text/tei:body/tei:div/tei:div"><ti:citation label="section" xpath="/tei:div[@n='?']" scope="/tei:TEI/tei:text/tei:body/tei:div/tei:div/tei:div[@n='?']"></ti:citation></ti:citation></ti:citationMapping></ti:online></ti:edition></ti:work><ti:work xml:lang="lat" urn='urn:cts:latinLit:stoa0255.stoa014' groupUrn='urn:cts:latinLit:stoa0255' xmlns:ti='http://chs.harvard.edu/xmlns/cts'><ti:title xml:lang='lat'>de Vita Beata</ti:title><ti:edition urn='urn:cts:latinLit:stoa0255.stoa014.perseus-lat2' workUrn='urn:cts:latinLit:stoa0255.stoa014' xmlns:ti='http://chs.harvard.edu/xmlns/cts'><ti:label xml:lang='eng'>de Vita Beata, Moral essays Vol 2</ti:label><ti:description xml:lang='eng'>Seneca, Lucius Annaeus, ca. 4 B.C.-65 A.D, creator; Basore, John W. (John William), b. 1870, editor; Basore, John W. (John William), b. 1870, editor, translator</ti:description><ti:online><ti:citationMapping><ti:citation label="chapter" xpath="/tei:div[@n='?']" scope="/tei:TEI/tei:text/tei:body/tei:div/tei:div"><ti:citation label="section" xpath="/tei:div[@n='?']" scope="/tei:TEI/tei:text/tei:body/tei:div/tei:div/tei:div[@n='?']"></ti:citation></ti:citation></ti:citationMapping></ti:online></ti:edition></ti:work><ti:work xml:lang="lat" urn='urn:cts:latinLit:stoa0255.stoa012' groupUrn='urn:cts:latinLit:stoa0255' xmlns:ti='http://chs.harvard.edu/xmlns/cts'><ti:title xml:lang='lat'>de Providentia</ti:title><ti:edition urn='urn:cts:latinLit:stoa0255.stoa012.perseus-lat2' workUrn='urn:cts:latinLit:stoa0255.stoa012' xmlns:ti='http://chs.harvard.edu/xmlns/cts'><ti:label xml:lang='eng'>de Providentia, Moral essays Vol 2</ti:label><ti:description xml:lang='eng'>Seneca, Lucius Annaeus, ca. 4 B.C.-65 A.D, creator; Basore, John W. (John William), b. 1870, editor; Basore, John W. (John William), b. 1870, editor, translator</ti:description><ti:online><ti:citationMapping><ti:citation label="chapter" xpath="/tei:div[@n='?']" scope="/tei:TEI/tei:text/tei:body/tei:div/tei:div"><ti:citation label="section" xpath="/tei:div[@n='?']" scope="/tei:TEI/tei:text/tei:body/tei:div/tei:div/tei:div[@n='?']"></ti:citation></ti:citation></ti:citationMapping></ti:online></ti:edition></ti:work><ti:work xml:lang="lat" urn='urn:cts:latinLit:stoa0255.stoa009' groupUrn='urn:cts:latinLit:stoa0255' xmlns:ti='http://chs.harvard.edu/xmlns/cts'><ti:title xml:lang='lat'>de Constantia</ti:title><ti:edition urn='urn:cts:latinLit:stoa0255.stoa009.perseus-lat2' workUrn='urn:cts:latinLit:stoa0255.stoa009' xmlns:ti='http://chs.harvard.edu/xmlns/cts'><ti:label xml:lang='eng'>de Constantia, Moral essays Vol 2</ti:label><ti:description xml:lang='eng'>Seneca, Lucius Annaeus, ca. 4 B.C.-65 A.D, creator; Basore, John W. (John William), b. 1870, editor; Basore, John W. (John William), b. 1870, editor, translator</ti:description><ti:online><ti:citationMapping><ti:citation label="chapter" xpath="/tei:div[@n='?']" scope="/tei:TEI/tei:text/tei:body/tei:div/tei:div"><ti:citation label="section" xpath="/tei:div[@n='?']" scope="/tei:TEI/tei:text/tei:body/tei:div/tei:div/tei:div[@n='?']"></ti:citation></ti:citation></ti:citationMapping></ti:online></ti:edition></ti:work><ti:work xml:lang="lat" urn='urn:cts:latinLit:stoa0255.stoa007' groupUrn='urn:cts:latinLit:stoa0255' xmlns:ti='http://chs.harvard.edu/xmlns/cts'><ti:title xml:lang='lat'>de consolatione ad Marciam</ti:title><ti:edition urn='urn:cts:latinLit:stoa0255.stoa007.perseus-lat2' workUrn='urn:cts:latinLit:stoa0255.stoa007' xmlns:ti='http://chs.harvard.edu/xmlns/cts'><ti:label xml:lang='eng'>de consolatione ad Marciam, Moral essays Vol 2</ti:label><ti:description xml:lang='eng'>Seneca, Lucius Annaeus, ca. 4 B.C.-65 A.D, creator; Basore, John W. (John William), b. 1870, editor; Basore, John W. (John William), b. 1870, editor, translator</ti:description><ti:online><ti:citationMapping><ti:citation label="chapter" xpath="/tei:div[@n='?']" scope="/tei:TEI/tei:text/tei:body/tei:div/tei:div"><ti:citation label="section" xpath="/tei:div[@n='?']" scope="/tei:TEI/tei:text/tei:body/tei:div/tei:div/tei:div[@n='?']"></ti:citation></ti:citation></ti:citationMapping></ti:online></ti:edition></ti:work></ti:textgroup></ti:TextInventory>
+            </reply>
+            </GetCapabilities>