Welcome to MyCapytains’s documentation!¶
Contents:
MyCapytain.common¶
The common namespace aims to regroup together common tools for different parts of the abstraction
MyCapytain.common.metadata¶
-
class
MyCapytain.common.metadata.
Metadata
(keys=None)[source]¶ Bases:
future.types.newobject.newobject
A metadatum aggregation object provided to centralize metadata
Parameters: key (List.<basestring>) – A metadata field name Variables: metadata – Dictionary of metadatum -
__getitem__
(key)[source]¶ Add a quick access system through getitem on the instance
Parameters: key (basestring, int, tuple) – Index key representing a set of metadatum
Returns: An element of children whose index is key
Raises: KeyError If key is not registered or recognized
Example: >>> a = Metadata() >>> m1 = Metadatum(name="title", [("lat", "Amores"), ("fre", "Les Amours")]) >>> m2 = Metadatum(name="author", [("lat", "Ovidius"), ("fre", "Ovide")]) >>> a[("title", "author")] = (m1, m2)
>>> a["title"] == m1 >>> a[0] == m1 >>> a[("title", "author")] == (m1, m2)
-
__setitem__
(key, value)[source]¶ Set a new metadata field
Parameters: - key (basestring, tuple) – Name of metadatum field
- value (Metadatum) – Metadum dictionary
Returns: An element of children whose index is key
Raises: TypeError if key is not basestring or tuple of basestring
Raises: ValueError if key and value are list and are not the same size
Example: >>> a = Metadata()
>>> a["title"] = Metadatum(name="title", [("lat", "Amores"), ("fre", "Les Amours")]) >>> print(a["title"]["lat"]) # Amores
>>> a[("title", "author")] = ( >>> Metadatum(name="title", [("lat", "Amores"), ("fre", "Les Amours")]), >>> Metadatum(name="author", [("lat", "Ovidius"), ("fre", "Ovide")]) >>> ) >>> print(a["title"]["lat"], a["author"]["fre"]) # Amores, Ovide
-
__iter__
()[source]¶ Iter method of Metadata
Example: >>> a = Metadata(("title", "desc", "author")) >>> for key, value in a: >>> print(key, value) # Print ("title", "<Metadatum object>") then ("desc", "<Metadatum object>")...
-
__len__
()[source]¶ Returns the number of Metadatum registered in the object
Return type: Returns: Number of metadatum objects
Example: >>> a = Metadata(("title", "description", "author")) >>> print(len(a)) # 3
-
__add__
(other)[source]¶ Merge Metadata objects together
Parameters: other (Metadata) – Metadata object to merge with the current one
Returns: The merge result of both metadata object
Return type: Example: >>> a = Metadata(name="label") >>> b = Metadata(name="title") >>> a + b == Metadata(name=["label", "title"])
-
-
class
MyCapytain.common.metadata.
Metadatum
(name, children=None)[source]¶ Bases:
future.types.newobject.newobject
Metadatum object represent a single field of metadata
Parameters: - name (basestring) – Name of the field
- children (List) – List of tuples, where first element is the key, and second the value
Example: >>> a = Metadatum(name="label", [("lat", "Amores"), ("fre", "Les Amours")]) >>> print(a["lat"]) # == "Amores"
-
__getitem__
(key)[source]¶ Add an iterable access method
Int typed key access to the n th registered key in the instance. If string based key does not exist, see for a default.
Parameters: key (basestring, tuple, int) – Key of wished value
Returns: An element of children whose index is key
Raises: KeyError if key is unknown (when using Int based key or when default is not set)
Example: >>> a = Metadatum(name="label", [("lat", "Amores"), ("fre", "Les Amours")]) >>> print(a["lat"]) # Amores >>> print(a[("lat", "fre")]) # Amores, Les Amours >>> print(a[0]) # Amores >>> print(a["dut"]) # Amores
-
__setitem__
(key, value)[source]¶ Register index key and value for the instance
Parameters: - key (basestring, list, tuple) – Index key(s) for the metadata
- value (basestring, list, tuple) – Values for the metadata
Returns: An element of children whose index is key
Raises: TypeError if key is not basestring or tuple of basestring
Raises: ValueError if key and value are list and are not the same size
Example: >>> a = Metadatum(name="label")
>>> a["eng"] = "Illiad" >>> print(a["eng"]) # Illiad
>>> a[("fre", "grc")] = ("Illiade", "Ἰλιάς") >>> print(a["fre"], a["grc"]) # Illiade, Ἰλιάς
>>> a[("ger", "dut")] = "Iliade" >>> print(a["ger"], a["dut"]) # Iliade, Iliade
-
__iter__
()[source]¶ Iter method of Metadatum
Example: >>> a = Metadata(name="label", [("lat", "Amores"), ("fre", "Les Amours")]) >>> for key, value in a: >>> print(key, value) # Print ("lat", "Amores") and then ("fre", "Les Amours")
-
setDefault
(key)[source]¶ Set a default key when a field does not exist
Parameters: key (basestring) – An existing key of the instance
Returns: Default key
Raises: ValueError If key is not registered
Example: >>> a = Metadatum(name="label", [("lat", "Amores"), ("fre", "Les Amours")]) >>> a.setDefault("fre") >>> print(a["eng"]) # == "Les Amours"
MyCapytain.common.reference¶
>>> from MyCapytain.common.reference import (URN, Reference, Citation)
-
class
MyCapytain.common.reference.
Citation
(name=None, xpath=None, scope=None, refsDecl=None, child=None)[source]¶ Bases:
future.types.newobject.newobject
A citation object gives informations about the scheme
Parameters: - name (basestring) – Name of the citation (e.g. “book”)
- xpath (basestring) – Xpath of the citation (As described by CTS norm)
- scope – Scope of the citation (As described by CTS norm)
- refsDecl (basestring) – refsDecl version
- child (Citation) – A citation
-
__iter__
()[source]¶ Iteration method
Loop over the citation childs
Example: >>> c = Citation(name="line") >>> b = Citation(name="poem", child=c) >>> a = Citation(name="book", child=b) >>> [e for e in a] == [a, b, c]
-
child
¶ Child of a citation
Type: Citation or None Example: Citation.name==poem would have a child Citation.name==line
-
fill
(passage=None, xpath=None)[source]¶ Fill the xpath with given informations
Parameters: - passage (Reference or lsit) – Passage reference
- xpath (Boolean) – If set to True, will return the replaced self.xpath value and not the whole self.refsDecl
Return type: Returns: Xpath to find the passage
-
name
¶ Type of the citation represented
Type: basestring Example: Book, Chapter, Textpart, Section, Poem...
-
refsDecl
¶ ResfDecl expression of the citation scheme
Type: basestring Example: /tei:TEI/tei:text/tei:body/tei:div//tei:l[@n=’$1’]
-
scope
¶ TextInventory scope property of a citation (ie. identifier of all element but the last of the citation)
Type: basestring Example: /tei:TEI/tei:text/tei:body/tei:div
-
xpath
¶ TextInventory xpath property of a citation (ie. identifier of the last element of the citation)
Type: basestring Example: //tei:l[@n=”?”]
-
MyCapytain.common.reference.
REF_REPLACER
(match, passage)[source]¶ Helper to replace xpath/scope/refsDecl on iteration with passage value
Parameters: - match (re.SRE_MATCH) – A RegExp match
- passage (iter) – A list with subreference informations
Return type: Returns: Replaced string
-
class
MyCapytain.common.reference.
Reference
(reference)[source]¶ Bases:
future.types.newobject.newobject
A reference object giving informations
Parameters: reference (basestring) – Passage Reference part of a Urn
Example: >>> a = Reference(reference="1.1@Achiles[1]-1.2@Zeus[1]") >>> b = Reference(reference="1.1")
-
__str__
()[source]¶ Return full reference in string format
Return type: Returns: String representation of Reference Object
Example: >>> a = Reference(reference="1.1@Achiles[1]-1.2@Zeus[1]") >>> b = Reference(reference="1.1") >>> str(a) == "1.1@Achiles[1]-1.2@Zeus[1]" >>> str(b) == "1.1"
-
__eq__
(other)[source]¶ Equality checker for Reference object
Parameters: other – An object to be checked against
Return type: boolean
Returns: Equality between other and self
Example: >>> a = Reference(reference="1.1@Achiles[1]-1.2@Zeus[1]") >>> b = Reference(reference="1.1") >>> c = Reference(reference="1.1") >>> (a == b) == False >>> (c == b) == True
-
__getitem__
(key)[source]¶ Return part of or full passage reference
- Available keys :
- 1 | start : First part of the reference
- 2 | start_list : Reference start parsed into a list
- 3 | start_sub : Subreference start parsed into a tuple
- 4 | end : Last part of the reference
- 5 | end_list : Reference start parsed into a list
- 6 | end_sub : Subreference end parsed into a tuple
- default : full string reference
Parameters: key (basestring or int) – Identifier of the part to return
Return type: basestring or List.<int> or None or Tuple.<string>
Returns: Desired part of the passage reference
Example: >>> a = Reference(reference="1.1@Achiles[1]-1.2@Zeus[1]") >>> print(a[1]) # "1.1@Achiles[1]" >>> print(a["start_list"]) # ("1", "1") >>> print(a[6]) # ("Zeus", "1") >>> print(a[7]) # "1.1@Achiles[1]-1.2@Zeus[1]"
-
parent
¶ Returns:
-
-
class
MyCapytain.common.reference.
URN
(urn)[source]¶ Bases:
future.types.newobject.newobject
A URN object giving all useful sections
Parameters: urn (basestring) – A CTS URN
Example: >>> a = URN(urn="urn:cts:latinLit:phi1294.phi002.perseus-lat2:1.1")
-
__len__
()[source]¶ Returns the len of the URN
Return type: int Returns: Length of the URN Warning
Does not take into account the passage !
Example: >>> a = URN(urn="urn:cts:latinLit:phi1294.phi002.perseus-lat2:1.1") >>> print(len(a)) #
-
__gt__
(other)[source]¶ Allows for greater comparison
Parameters: other (URN) – Comparison object Return type: boolean Returns: Indicator of bigger size Warning
Does not take into account the passage !
Example: >>> a = URN(urn="urn:cts:latinLit:phi1294.phi002.perseus-lat2:1.1") >>> b = URN(urn="urn:cts:latinLit:phi1294.phi002:1.1") >>> (a > b) == True #
-
__lt__
(other)[source]¶ Allows for lower comparison
Parameters: other (URN) – Comparison object Return type: boolean Returns: Indicator of lower size Warning
Does not take into account the passage !
Example: >>> a = URN(urn="urn:cts:latinLit:phi1294.phi002.perseus-lat2:1.1") >>> b = URN(urn="urn:cts:latinLit:phi1294.phi002:1.1") >>> (b < a) == True #
-
__eq__
(other)[source]¶ Equality checker for URN object
Parameters: other (URN) – An object to be checked against
Return type: boolean
Returns: Equality between other and self
Example: >>> a = URN(urn="urn:cts:latinLit:phi1294.phi002.perseus-lat2:1.1") >>> b = URN(urn="urn:cts:latinLit:phi1294.phi002:1.1") >>> (b == a) == False #
-
__str__
()[source]¶ Return full initial urn
Return type: Returns: String representation of URN Object
Example: >>> a = URN(urn="urn:cts:latinLit:phi1294.phi002.perseus-lat2:1.1") >>> str(a) == "urn:cts:latinLit:phi1294.phi002.perseus-lat2:1.1"
-
__getitem__
(key)[source]¶ Returns the urn (int) level or up to (str) level.
- Available keys :
- 0 : URN
- full : URN
- 1 : Namespace of the urn (cts)
- urn_namespace : URN until the Namespace of the urn
- 2 : CTS Namespace of the URN (e.g. latinLit)
- cts_namespace : URN until the CTS Namespace
- 3 : Textgroup of the URN
- textgroup : URN until the Textgroup
- 4 : Work of the URN
- work : URN until the Work
- 5 : Text of the URN
- text : URN until the Text
- 6 or passage: Passage of URN
Parameters: key (int or basestring) – Identifier of the wished resource
Return type: basestring or Reference
Returns: Part or complete URN
Warning: urn: is not counted as an element !
Example: >>> a = URN(urn="urn:cts:latinLit:phi1294.phi002.perseus-lat2:1.1") >>> a["textgroup"] == "urn:cts:latinLit:phi1294" >>> a[3] == "phi1294
-
MyCapytain.common.utils¶
-
MyCapytain.common.utils.
NS
= {u'xml': u'http://www.w3.org/XML/1998/namespace', u'tei': u'http://www.tei-c.org/ns/1.0', u'ahab': u'http://localhost.local', u'ti': u'http://chs.harvard.edu/xmlns/cts'}¶ Dictionary of namespace that can be useful
-
MyCapytain.common.utils.
normalize
(string)[source]¶ Remove double-or-more spaces in a string
Parameters: string (basestring) – A string to change Return type: Basestring Returns: Clean string
MyCapytain.resources package¶
MyCapytain.resources.texts package¶
-
class
MyCapytain.resources.texts.tei.
Citation
(name=None, xpath=None, scope=None, refsDecl=None, child=None)[source]¶ Bases:
MyCapytain.common.reference.Citation
Implementation of Citation for TEI markup
-
static
ingest
(resource, xpath='.//tei:cRefPattern')[source]¶ Ingest a resource and store data in its instance
Parameters: - resource (lxml.etree._Element) – XML node cRefPattern or list of them in ASC hierarchy order (deepest to highest, eg. lines to poem to book)
- xpath (str) – XPath to use to retrieve citation
Returns: A citation object
Return type:
-
static
-
class
MyCapytain.resources.texts.tei.
Passage
(parent=None, **kwargs)[source]¶ Bases:
MyCapytain.resources.proto.text.Passage
-
text
(exclude=None)[source]¶ Text content of the passage
Parameters: exclude (List) – Remove some nodes from text
Return type: Returns: Text of the xml node
Example: >>> P = Passage(resource='<l n="8">Ibis <note>hello<a>b</a></note> ab excusso missus in astra <hi>sago.</hi> </l>') >>> P.text == "Ibis hello b ab excusso missus in astra sago. " >>> P.text(exclude=["note"]) == "Ibis hello b ab excusso missus in astra sago. "
-
xml
¶ XML Representation of the Passage
Return type: lxml.etree._Element Returns: XML element representing the passage
-
-
class
MyCapytain.resources.texts.local.
Text
(urn=None, citation=None, resource=None)[source]¶ Bases:
MyCapytain.resources.proto.text.Text
Implementation of CTS tools for local files
Parameters: - urn (MyCapytain.common.reference.URN) – A URN identifier
- resource (lxml.etree._Element) – A resource
- citation (MyCapytain.common.reference.Citation) – Highest Citation level
Variables: resource – lxml
-
citation
¶ Get the lowest cRefPattern in the hierarchy
Return type: MyCapytain.resources.texts.tei.Citation
-
getPassage
(reference)[source]¶ Finds a passage in the current text
Parameters: reference (List, MyCapytain.common.reference.Reference) – Identifier of the subreference / passages Return type: Passage Returns: Asked passage
-
getPassagePlus
(reference)[source]¶ Finds a passage in the current text with its previous and following node
Parameters: reference (List, MyCapytain.common.reference.Reference) – Identifier of the subreference / passages Return type: text.PassagePlus Returns: Asked passage with metainformations
-
getValidReff
(level=1, reference=None)[source]¶ Retrieve valid passages directly
Parameters: - level (Int) – Depth required. If not set, should retrieve first encountered level (1 based)
- reference (Reference) – Subreference (optional)
Return type: List.basestring
Returns: List of levels
Note
GetValidReff works for now as a loop using Passage, subinstances of Text, to retrieve the valid informations. Maybe something is more powerfull ?
-
class
MyCapytain.resources.texts.api.
Text
(urn, resource, citation=None, **kwargs)[source]¶ Bases:
MyCapytain.resources.proto.text.Text
Passage representing object prototype
Parameters: - urn (MyCapytain.common.reference.URN) – A URN identifier
- resource (MyCapytain.endpoints.proto.CTS) – An API endpoint
- citation (MyCapytain.resources.texts.tei.Citation) – Citation for children level
- id (List) – Identifier of the subreference without URN informations
-
DEFAULT_LANG
= u'eng'¶
-
getLabel
()[source]¶ Retrieve metadata about the text
Return type: Metadata Returns: Dictionary with label informations
-
getPassage
(reference=None)[source]¶ Retrieve a passage and store it in the object
Parameters: reference (MyCapytain.common.reference.Reference or List of basestring) – Reference of the passage Return type: Passage Returns: Object representing the passage Raises: TypeError when reference is not a list or a Reference
-
getPassagePlus
(reference=None)[source]¶ Retrieve a passage and informations around it and store it in the object
Parameters: reference (MyCapytain.common.reference.Reference or List of basestring) – Reference of the passage Return type: Passage Returns: Object representing the passage Raises: TypeError when reference is not a list or a Reference
-
getValidReff
(level=1, reference=None)[source]¶ Given a resource, Text will compute valid reffs
Parameters: - level (Int) – Depth required. If not set, should retrieve first encountered level (1 based)
- reference (Reference) – Subreference (optional)
Return type: List.basestring
Returns: List of levels
-
reffs
¶ Get all valid reffs for every part of the Text
Return type: MyCapytain.resources.texts.tei.Citation
MyCapytain.resources.proto.inventory module¶
-
class
MyCapytain.resources.proto.inventory.
Resource
(resource=None)[source]¶ Bases:
object
Resource represents any resource from the inventory
-
class
MyCapytain.resources.proto.inventory.
Text
(resource=None, urn=None, parents=None, subtype='Edition')[source]¶ Bases:
MyCapytain.resources.proto.inventory.Resource
Represents a CTS Text
-
class
MyCapytain.resources.proto.inventory.
TextGroup
(resource=None, urn=None, parents=None)[source]¶ Bases:
MyCapytain.resources.proto.inventory.Resource
Represents a CTS Textgroup
-
class
MyCapytain.resources.proto.inventory.
TextInventory
(resource=None, id=None)[source]¶ Bases:
MyCapytain.resources.proto.inventory.Resource
Represents a CTS Inventory file
-
class
MyCapytain.resources.proto.inventory.
Work
(resource=None, urn=None, parents=None)[source]¶ Bases:
MyCapytain.resources.proto.inventory.Resource
Represents a CTS Work
-
getLang
(key=None)[source]¶ Find a translation with given language
Parameters: key (basestring) – Language to find Return type: [Text] Returns: List of availables translations
-
MyCapytain.resources.proto.text module¶
-
class
MyCapytain.resources.proto.text.
Passage
(parent=None, **kwargs)[source]¶ Bases:
MyCapytain.resources.proto.text.Resource
Passage representing object prototype
Parameters: - urn (MyCapytain.common.reference.URN) – A URN identifier
- resource (lxml.etree._Element) – A resource
- parent (MyCapytain.resources.texts.tei.Passage) – Parent of the current passage
- citation (MyCapytain.resources.texts.tei.Citation) – Citation for children level
- id (List) – Identifier of the subreference without URN informations
-
children
¶ Children of the passage
Return type: OrderedDict Returns: Dictionary of chidren, where key are subreferences
-
first
¶ First child of current Passage
Return type: None or Passage Returns: None if current Passage has no children, first child passage if available
-
last
¶ Last child of current Passage
Return type: None or Passage Returns: None if current Passage has no children, last child passage if available
-
class
MyCapytain.resources.proto.text.
PassagePlus
(passage, prev, next)¶ Bases:
tuple
-
next
¶ Alias for field number 2
-
passage
¶ Alias for field number 0
-
prev
¶ Alias for field number 1
-
-
class
MyCapytain.resources.proto.text.
Resource
(urn=None, resource=None)[source]¶ Bases:
object
Initiate a Resource object
Parameters: - urn (MyCapytain.common.reference.URN) – A URN identifier
- resource (Any) – A resource
-
urn
¶ URN Identifier of the object
Return type: MyCapytain.common.reference.URN
-
class
MyCapytain.resources.proto.text.
Text
(citation=None, metadata=None, **kwargs)[source]¶ Bases:
MyCapytain.resources.proto.text.Resource
A CTS Text
-
citation
¶ Get the lowest cRefPattern in the hierarchy
Return type: MyCapytain.common.reference.Citation
-
getLabel
()[source]¶ Retrieve metadata about the text
Return type: dict Returns: Dictionary with label informations
-
getPassage
(reference)[source]¶ Retrieve a passage and store it in the object
Parameters: reference (MyCapytain.common.reference.Reference or List of basestring) – Reference of the passage Return type: Passage Returns: Object representing the passage Raises: TypeError when reference is not a list or a Reference
-
getValidReff
(level=1, reference=None)[source]¶ Given a resource, Text will compute valid reffs
Parameters: - level (Int) – Depth required. If not set, should retrieve first encountered level (1 based)
- passage (Reference) – Subreference (optional)
Return type: List.basestring
Returns: List of levels
-
reffs
¶ Get all valid reffs for every part of the Text
Return type: MyCapytain.resources.texts.tei.Citation
-
MyCapytain.endpoints package¶
MyCapytain.endpoints.ahab module¶
-
class
MyCapytain.endpoints.ahab.
Ahab
(endpoint)[source]¶ Bases:
MyCapytain.endpoints.proto.Ahab
Basic integration of the proto.CTS abstraction
MyCapytain.endpoints.cts5 module¶
-
class
MyCapytain.endpoints.cts5.
CTS
(endpoint, inventory=None)[source]¶ Bases:
MyCapytain.endpoints.proto.CTS
Basic integration of the MyCapytain.endpoints.proto.CTS abstraction
-
call
(parameters)[source]¶ Call an endpoint given the parameters
Parameters: parameters (dict) – Dictionary of parameters Return type: text
-
getCapabilities
(inventory=None)[source]¶ Retrieve the inventory information of an API
Parameters: inventory (text) – Name of the inventory Return type: str
-
getFirstUrn
(urn, inventory=None)[source]¶ Retrieve the first passage urn of a text
Parameters: Return type:
-
getLabel
(urn, inventory=None)[source]¶ Retrieve informations about a CTS Urn
Parameters: Return type:
-
getPassage
(urn, inventory=None, context=None)[source]¶ Retrieve a passage
Parameters: - urn (text) – URN identifying the text’s passage (Minimum depth : 1)
- inventory (text) – Name of the inventory
- context (int) – Number of citation units at the same level of the citation hierarchy as the requested urn, immediately preceding and immediately following the requested urn to include in the reply
Return type:
-
getPassagePlus
(urn, inventory=None, context=None)[source]¶ Retrieve a passage and informations about it
Parameters: - urn (text) – URN identifying the text’s passage (Minimum depth : 1)
- inventory (text) – Name of the inventory
- context (int) – Number of citation units at the same level of the citation hierarchy as the requested urn, immediately preceding and immediately following the requested urn to include in the reply
Return type:
-
MyCapytain.endpoints.proto module¶
-
class
MyCapytain.endpoints.proto.
API
(endpoint)[source]¶ Bases:
object
API Prototype object
Parameters: Variables: endpoint – Url of the endpoint
-
class
MyCapytain.endpoints.proto.
Ahab
(endpoint)[source]¶ Bases:
MyCapytain.endpoints.proto.API
Abstract Capitains Ahab API See : http://capitains.github.io/pages/ahab.html
-
class
MyCapytain.endpoints.proto.
CTS
(endpoint)[source]¶ Bases:
MyCapytain.endpoints.proto.API
CTS API Endpoint Prototype
-
getCapabilities
(inventory)[source]¶ Retrieve the inventory information of an API
Parameters: inventory (text) – Name of the inventory Return type: str
-
getFirstUrn
(urn, inventory)[source]¶ Retrieve the first passage urn of a text
Parameters: Return type:
-
getPassage
(urn, inventory, context=None)[source]¶ Retrieve a passage
Parameters: - urn (text) – URN identifying the text’s passage (Minimum depth : 1)
- inventory (text) – Name of the inventory
- context (int) – Number of citation units at the same level of the citation hierarchy as the requested urn, immediately preceding and immediately following the requested urn to include in the reply
Return type:
-
getPassagePlus
(urn, inventory, context=None)[source]¶ Retrieve a passage and informations about it
Parameters: - urn (text) – URN identifying the text’s passage (Minimum depth : 1)
- inventory (text) – Name of the inventory
- context (int) – Number of citation units at the same level of the citation hierarchy as the requested urn, immediately preceding and immediately following the requested urn to include in the reply
Return type:
-