(Resolver Prototype) Added Typing and Changed getReffs to output Base…

…ReferenceSet

- Created BaseReferenceSet(list) with .citation kwarg and property
- ResolverPrototype.getReffs
  - BaseReferenceSet is a non breaking change : it's a forked class of list comprehending a citation property
  - Added `include_descendants` to address the long lasting issue #132
  - Added `additional_parameters` to address potential particularities of specific resolvers
  - Added `typing` as dependency as a result

- Changed BasePassageId to BaseReference

MyCapytain/common/reference/__init__.py

@@ -6,6 +6,6 @@
 .. moduleauthor:: Thibault Clérice <leponteineptique@gmail.com>
 
 """
-from ._base import NodeId, BaseCitationSet
+from ._base import NodeId, BaseCitationSet, BaseReference, BaseReferenceSet
 from ._capitains_cts import Citation, Reference, URN
 from ._dts_1 import DtsCitation, DtsCitationSet

MyCapytain/common/reference/_base.py

@@ -5,7 +5,7 @@
 from abc import abstractmethod
 
 
-class BasePassageId:
+class BaseReference:
     def __init__(self, start=None, end=None):
         self._start = start
         self._end = end
@@ -31,6 +31,21 @@ def end(self):
         return self._end
 
 
+class BaseReferenceSet(list):
+    @property
+    def citation(self):
+        return self._citation
+
+    def __new__(cls, *args, **kwargs):
+        obj = list.__new__(*args, **kwargs)
+        obj._citation = None
+
+        if "citation" in kwargs:
+            obj._citation = kwargs["citation"]
+
+        return obj
+
+
 class BaseCitationSet(Exportable):
     """ A citation set is a collection of citations that optionnaly can be matched using a .match() function
 

MyCapytain/common/reference/_capitains_cts.py

@@ -6,7 +6,7 @@
 from MyCapytain.common.constants import Mimetypes, get_graph, RDF_NAMESPACES, XPATH_NAMESPACES
 from MyCapytain.common.utils import make_xml_node
 
-from ._base import BaseCitation, BasePassageId
+from ._base import BaseCitation, BaseReference
 
 REFSDECL_SPLITTER = re.compile(r"/+[*()|\sa-zA-Z0-9:\[\]@=\\{$'\".\s]+")
 REFSDECL_REPLACER = re.compile(r"\$[0-9]+")
@@ -26,7 +26,7 @@ def __childOrNone__(liste):
         return None
 
 
-class Reference(BasePassageId):
+class Reference(BaseReference):
     """ A reference object giving information
 
     :param reference: CapitainsCtsPassage Reference part of a Urn

MyCapytain/resolvers/prototypes.py

@@ -7,14 +7,19 @@
 
 """
 
+from typing import Tuple, Union, Optional, Dict, Any
+from MyCapytain.resources.prototypes.metadata import Collection
+from MyCapytain.resources.prototypes.text import TextualNode
+from MyCapytain.common.reference import BaseReference, BaseReferenceSet
+
 
 class Resolver(object):
     """ Resolver provide a native python API which returns python objects.
 
     Initiation of resolvers are dependent on the implementation of the prototype
 
     """
-    def getMetadata(self, objectId=None, **filters):
+    def getMetadata(self, objectId: str=None, **filters) -> Collection:
         """ Request metadata about a text or a collection
 
         :param objectId: Object Identifier to filter on
@@ -25,7 +30,13 @@ def getMetadata(self, objectId=None, **filters):
         """
         raise NotImplementedError()
 
-    def getTextualNode(self, textId, subreference=None, prevnext=False, metadata=False):
+    def getTextualNode(
+            self,
+            textId: str,
+            subreference: Union[str, BaseReference]=None,
+            prevnext: bool=False,
+            metadata: bool=False
+    ) -> TextualNode:
         """ Retrieve a text node from the API
 
         :param textId: CtsTextMetadata Identifier
@@ -41,7 +52,7 @@ def getTextualNode(self, textId, subreference=None, prevnext=False, metadata=Fal
         """
         raise NotImplementedError()
 
-    def getSiblings(self, textId, subreference):
+    def getSiblings(self, textId: str, subreference: Union[str, BaseReference]) -> Tuple[str, str]:
         """ Retrieve the siblings of a textual node
 
         :param textId: CtsTextMetadata Identifier
@@ -53,7 +64,14 @@ def getSiblings(self, textId, subreference):
         """
         raise NotImplementedError()
 
-    def getReffs(self, textId, level=1, subreference=None):
+    def getReffs(
+            self,
+            textId: str,
+            level: int=1,
+            subreference: Union[str, BaseReference]=None,
+            include_descendants: bool=False,
+            additional_parameters: Optional[Dict[str, Any]]=None
+    ) -> BaseReferenceSet:
         """ Retrieve the siblings of a textual node
 
         :param textId: CtsTextMetadata Identifier
@@ -62,7 +80,11 @@ def getReffs(self, textId, level=1, subreference=None):
         :type level: int
         :param subreference: CapitainsCtsPassage Reference
         :type subreference: str
+        :param include_descendants:
+        :param additional_parameters:
         :return: List of references
         :rtype: [str]
+
+        ..toDo :: This starts to be a bloated function....
         """
         raise NotImplementedError()

requirements.txt

@@ -7,4 +7,5 @@ xmlunittest>=0.3.2
 rdflib-jsonld>=0.4.0
 responses>=0.8.1
 LinkHeader==0.4.3
-pyld==1.0.3
+pyld==1.0.3
+typing

setup.py

@@ -18,7 +18,8 @@
     "future>=0.16.0",
     "rdflib-jsonld>=0.4.0",
     "LinkHeader>=0.4.3",
-    "pyld>=1.0.3"
+    "pyld>=1.0.3",
+    "typing"
   ],
   tests_require=[
     "mock>=2.0.0",