Documentation Improvement (#102)

- Mostly Example Writing
- Collections now behaves like CTS Collections : ablity to acces children by `obj.__getitem__(id)` method [ Enhanced collections by implementing identifier browsing ]
- Fixed few discrepancies
- Fixed some tests issues
- Added coverage
- Clean up the benchmark scripts
- Added a test and a fix for CTS API Passage regarding siblingsId ( #94 )
- Release 2.0.0b2

.travis.yml

@@ -1,9 +1,8 @@
 language: python
 python:
+  - "2.7"
   - "3.4.5"
   - "3.5"
-  - "pypy"
-  - "pypy3"
 
 install:
     - pip install -r requirements.txt
@@ -16,8 +15,6 @@ script:
 matrix:
   allow_failures:
     - python: "2.7"
-    - python: pypy
-    - python: pypy3
 
 after_success:
     - if [[ $TRAVIS_PYTHON_VERSION == 3* ]]; then coveralls; fi

Makefile

@@ -3,4 +3,19 @@ svg:
 		source ./env/bin/activate; \
 		pyreverse -o png -p MyCapytain MyCapytain; \
 		pyreverse -o svg -p MyCapytain MyCapytain; \
-	)
+	)
+
+classes:
+	( \
+		source ./env/bin/activate; \
+		pyreverse -A -k -o svg -p MyCapytain_texts MyCapytain.resources.prototypes.text; \
+		pyreverse -A -k -o png -p MyCapytain_texts MyCapytain.resources.prototypes.text;
+	)
+
+move:
+	( \
+		mv classes_* doc/_static/pyreverse/;\
+		mv packages_* doc/_static/pyreverse/;\
+	)
+
+all:svg classes move

MyCapytain/__init__.py

@@ -9,4 +9,4 @@
 
 """
 
-__version__ = "2.0.0b1"
+__version__ = "2.0.0b2"

MyCapytain/common/constants.py

@@ -157,8 +157,6 @@ def export_capacities(self):
     def __export__(self, output=None, **kwargs):
         """ Export the collection item in the Mimetype required.
 
-        ..note:: If current implementation does not have special mimetypes, reuses default_export method
-
         :param output: Mimetype to export to (Uses MyCapytain.common.utils.Mimetypes)
         :type output: str
         :return: Object using a different representation

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

MyCapytain/resources/collections/cts.py

@@ -228,7 +228,7 @@ def __export__(self, output=Mimetypes.PYTHON.ETREE, domain="", **kwargs):
             return str(self)
 
     def __findCitations(self, xml, xpath="ti:citation"):
-        """ Find citation in current xml. Used as a loop for self.xmlparser()
+        """ Find citation in current xml. Used as a loop for xmlparser()
         
         :param xml: Xml resource to be parsed
         :param xpath: Xpath to use to retrieve the xml node
@@ -242,31 +242,31 @@ def parse(self, resource):
         :type resource: basestring or lxml.etree._Element
         :returns: None
         """
-        self.xml = xmlparser(resource)
-        self.urn = URN(self.xml.get("urn"))
+        xml = xmlparser(resource)
+        self.urn = URN(xml.get("urn"))
         self.id = str(self.urn)
 
         if self.subtype == "Translation":
-            lang = self.xml.get("{http://www.w3.org/XML/1998/namespace}lang")
+            lang = xml.get("{http://www.w3.org/XML/1998/namespace}lang")
             if lang is not None:
                 self.lang = lang
 
-        for child in self.xml.xpath("ti:description", namespaces=NS):
+        for child in xml.xpath("ti:description", namespaces=NS):
             lg = child.get("{http://www.w3.org/XML/1998/namespace}lang")
             if lg is not None:
                 self.metadata["description"][lg] = child.text
 
-        for child in self.xml.xpath("ti:label", namespaces=NS):
+        for child in xml.xpath("ti:label", namespaces=NS):
             lg = child.get("{http://www.w3.org/XML/1998/namespace}lang")
             if lg is not None:
                 self.metadata["label"][lg] = child.text
 
         self.__findCitations(
-            xml=self.xml,
+            xml=xml,
             xpath="ti:online/ti:citationMapping/ti:citation"
         )
 
-        online = self.xml.xpath("ti:online", namespaces=NS)
+        online = xml.xpath("ti:online", namespaces=NS)
         if len(online) > 0:
             online = online[0]
             self.docname = online.get("docname")
@@ -376,27 +376,27 @@ def parse(self, resource):
         :param resource: Element rerpresenting a work
         :param type: basestring, etree._Element
         """
-        self.xml = xmlparser(resource)
-        self.urn = URN(self.xml.get("urn"))
+        xml = xmlparser(resource)
+        self.urn = URN(xml.get("urn"))
         self.id = str(self.urn)
 
-        lang = self.xml.get("{http://www.w3.org/XML/1998/namespace}lang")
+        lang = xml.get("{http://www.w3.org/XML/1998/namespace}lang")
         if lang is not None:
             self.lang = lang
 
-        for child in self.xml.xpath("ti:title", namespaces=NS):
+        for child in xml.xpath("ti:title", namespaces=NS):
             lg = child.get("{http://www.w3.org/XML/1998/namespace}lang")
             if lg is not None:
                 self.metadata["title"][lg] = child.text
 
         self.__editions = xpathDict(
-            xml=self.xml,
+            xml=xml,
             xpath='ti:edition',
             children=Edition,
             parents=[self] + self.parents
         )
         self.__translations = xpathDict(
-            xml=self.xml,
+            xml=xml,
             xpath='ti:translation',
             children=Translation,
             parents=[self] + self.parents
@@ -467,18 +467,18 @@ def parse(self, resource):
         :param resource: Element representing the textgroup
         :param type: basestring or etree._Element
         """
-        self.xml = xmlparser(resource)
+        xml = xmlparser(resource)
 
-        self.urn = URN(self.xml.get("urn"))
+        self.urn = URN(xml.get("urn"))
         self.id = str(self.urn)
 
-        for child in self.xml.xpath("ti:groupname", namespaces=NS):
+        for child in xml.xpath("ti:groupname", namespaces=NS):
             lg = child.get("{http://www.w3.org/XML/1998/namespace}lang")
             if lg is not None:
                 self.metadata["groupname"][lg] = child.text
 
         self.works = xpathDict(
-            xml=self.xml,
+            xml=xml,
             xpath='ti:work',
             children=Work,
             parents=[self] + self.parents
@@ -537,10 +537,10 @@ def parse(self, resource):
         :param resource: Element representing the text inventory
         :param type: basestring, etree._Element
         """
-        self.xml = xmlparser(resource)
+        xml = xmlparser(resource)
 
         self.textgroups = xpathDict(
-            xml=self.xml,
+            xml=xml,
             xpath='//ti:textgroup',
             children=TextGroup,
             parents=[self]

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
@@ -38,21 +38,6 @@ def __init__(self, resource=None):
         if resource is not None:
             self.setResource(resource)
 
-    def __getitem__(self, key):
-        """ Direct key access function for Text objects """
-        if key == 0:
-            return self
-        elif isinstance(key, int) and 1 <= key <= len(self.parents):
-            r = self.parents[key - 1]
-            if isinstance(r, (list, tuple)):
-                return r[0]
-            else:
-                return r
-        elif isinstance(key, text_type):
-            return self.__urnitem__(key)
-        else:
-            return None
-
     def __eq__(self, other):
         if self is other:
             return True
@@ -66,37 +51,6 @@ def __eq__(self, other):
     def __str__(self):
         raise NotImplementedError()
 
-    def __urnitem__(self, key):
-        urn = URN(key)
-
-        if len(urn) <= 2:
-            raise ValueError("Not valid urn")
-        elif hasattr(self, "urn") and self.urn == urn:
-            return self
-        else:
-            if hasattr(self, "urn"):
-                i = len(self.urn)
-            else:
-                i = 2
-
-            if isinstance(self, TextInventory):
-                children = self.textgroups
-            elif isinstance(self, TextGroup):
-                children = self.works
-            elif isinstance(self, Work):
-                children = self.texts
-
-            order = ["", "", URN.TEXTGROUP, URN.WORK, URN.VERSION]
-            while i <= len(urn) - 1:
-                children = children[urn.upTo(order[i])]
-                if not hasattr(children, "urn") or str(children.urn) != urn.upTo(order[i]):
-                    error = "Unrecognized urn at " + [
-                        "URN namespace", "CTS Namespace", "URN Textgroup", "URN Work", "URN Version"
-                    ][i]
-                    raise ValueError(error)
-                i += 1
-            return children
-
     def setResource(self, resource):
         """ Set the object property resource
 
@@ -154,9 +108,13 @@ class Text(CTSCollection):
     :type parents: [CTSCollection]
     :param subtype: Subtype of the object (Edition, Translation)
     :type subtype: str
+
+    :ivar urn: URN Identifier
+    :type urn: URN
+    :ivar parents: List of ancestors, from parent to furthest
     """
 
-    DC_TITLE = "label"
+    DC_TITLE_KEY = "label"
 
     @property
     def TEXT_URI(self):
@@ -184,7 +142,6 @@ def __init__(self, resource=None, urn=None, parents=None, subtype="Edition"):
 
         if urn is not None:
             self.urn = URN(urn)
-            self.id = str(self.urn)
 
         if parents is not None:
             self.parents = parents
@@ -225,6 +182,14 @@ def editions(self):
                 if self.parents[0].texts[urn].subtype == "Edition"
             ]
 
+    @property
+    def id(self):
+        return str(self.urn)
+
+    @id.setter
+    def id(self, value):
+        self.urn = URN(value)
+
 
 def Edition(resource=None, urn=None, parents=None):
     """ Represents a CTS Edition
@@ -264,6 +229,10 @@ class Work(CTSCollection):
     :type urn: str
     :param parents: List of parents for current object
     :type parents: Tuple.<TextInventory>
+
+    :ivar urn: URN Identifier
+    :type urn: URN
+    :ivar parents: List of ancestors, from parent to furthest
     """
 
     DC_TITLE_KEY = "title"
@@ -345,6 +314,14 @@ def __len__(self):
     def members(self):
         return list(self.texts.values())
 
+    @property
+    def id(self):
+        return str(self.urn)
+
+    @id.setter
+    def id(self, value):
+        self.urn = URN(value)
+
 
 class TextGroup(CTSCollection):
     """ Represents a CTS Textgroup
@@ -358,6 +335,10 @@ class TextGroup(CTSCollection):
     :type urn: str
     :param parents: List of parents for current object
     :type parents: Tuple.<TextInventory>
+
+    :ivar urn: URN Identifier
+    :type urn: URN
+    :ivar parents: List of ancestors, from parent to furthest
     """
     DC_TITLE_KEY = "groupname"
     TYPE_URI = RDF_PREFIX["ti"] + "TextGroup"
@@ -377,7 +358,6 @@ def __init__(self, resource=None, urn=None, parents=None):
 
         if urn is not None:
             self.urn = URN(urn)
-            self.id = str(self.urn)
 
         if parents:
             self.parents = parents
@@ -424,6 +404,14 @@ def __len__(self):
             for text in work.texts.values()
         ])
 
+    @property
+    def id(self):
+        return str(self.urn)
+
+    @id.setter
+    def id(self, value):
+        self.urn = URN(value)
+
 
 class TextInventory(CTSCollection):
     """ Initiate a TextInventory resource
@@ -448,6 +436,14 @@ def __init__(self, resource=None, name=None):
         if resource is not None:
             self.setResource(resource)
 
+    @property
+    def id(self):
+        return self.__id__
+
+    @id.setter
+    def id(self, value):
+        self.__id__ = value
+
     def __len__(self):
         """ Get the number of text in the Inventory