MyCapytain API Documentation

Utilities, metadata and references

Module common contains tools such as a namespace dictionary as well as cross-implementation objects, like URN, Citations...

Constants

class MyCapytain.common.constants.Exportable[source]

Objects that supports Export

Variables:EXPORT_TO – List of Mimetypes the resource can export to
export(output=None, **kwargs)[source]

Export the collection item in the Mimetype required.

Parameters:output (str) – Mimetype to export to (Uses MyCapytain.common.utils.Mimetypes)
Returns:Object using a different representation
export_capacities

List Mimetypes that current object can export to

class MyCapytain.common.constants.Mimetypes[source]

Mimetypes constants that are used to provide export functionality to base MyCapytain object.

Variables:
  • JSON – JSON Resource mimetype
  • XML – XML Resource mimetype
  • PYTHON – Python Native Object
  • PLAINTEXT – Plain string format
class JSON[source]

Json Mimetype

Variables:
  • Std – Standard JSON Export
  • CTS – CTS Json Export
class DTS[source]

JSON DTS Expression

Variables:
  • Std – Standard DTS Json-LD Expression
  • NoParents – DTS Json-LD Expression without parents expression
class Mimetypes.PYTHON[source]

Python Native Objects

Variables:
  • NestedDict – Nested Dictionary Object
  • ETREE – Python LXML Etree Object
class MyCapytain[source]

MyCapytain Objects

Variables:ReadableText – MyCapytain.resources.prototypes.text.CitableText
class Mimetypes.XML[source]

XML Mimetype

Variables:
  • Std – Standard XML Export
  • RDF – RDF XML Expression Export
  • CTS – CTS API XML Expression Export
class MyCapytain.common.constants.NAMESPACES[source]

Namespaces Constants used to provide Namespace capacities across the library

Variables:
  • CTS – CTS Namespace
  • TEI – TEI Namespace
  • DC – DC Elements
MyCapytain.common.constants.NS = {'ahab': 'http://localhost.local', 'tei': 'http://www.tei-c.org/ns/1.0', 'xml': 'http://www.w3.org/XML/1998/namespace', 'ti': 'http://chs.harvard.edu/xmlns/cts'}

List of XPath Namespaces used in guidelines

class MyCapytain.common.constants.Namespace(uri, prefix)

Namespace tuple that can be used to express namespace information

prefix

Alias for field number 1

uri

Alias for field number 0

MyCapytain.common.constants.RDF_MAPPING = {'http://www.w3.org/2003/01/geo/wgs84_pos#': 'geo', 'http://www.w3.org/2001/XMLSchema#': 'xsd', 'http://xmlns.com/wot/0.1/': 'wot', 'http://rdfs.org/sioc/ns#': 'sioc', 'http://purl.org/rss/1.0/modules/content/': 'content', 'http://dbpedia.org/resource/': 'dbpedia', 'http://www.w3.org/2000/01/rdf-schema#': 'rdfs', 'http://www.w3.org/2002/07/owl#': 'owl', 'http://www.w3.org/2004/02/skos/core#': 'skos', 'http://www.geonames.org/ontology#': 'geonames', 'http://dbpedia.org/property/': 'dbp', 'http://usefulinc.com/ns/doap#': 'doap', 'http://swrc.ontoware.org/ontology#': 'swrc', 'http://purl.org/gen/0.1#': 'gen', 'http://xmlns.com/foaf/0.1/': 'foaf', 'http://chs.harvard.edu/xmlns/cts/': 'ti', 'http://purl.org/rss/1.0/': 'rss', 'http://purl.org/dc/elements/1.1/': 'dc11', 'http://dbpedia.org/ontology/': 'dbo', 'http://www.tei-c.org/ns/1.0/': 'tei', 'http://www.w3.org/1999/02/22-rdf-syntax-ns#': 'rdf'}

List of RDF URI with their equivalent Prefix

MyCapytain.common.constants.RDF_PREFIX = {'rss': 'http://purl.org/rss/1.0/', 'ti': 'http://chs.harvard.edu/xmlns/cts/', 'dbp': 'http://dbpedia.org/property/', 'sioc': 'http://rdfs.org/sioc/ns#', 'swrc': 'http://swrc.ontoware.org/ontology#', 'tei': 'http://www.tei-c.org/ns/1.0/', 'xsd': 'http://www.w3.org/2001/XMLSchema#', 'wot': 'http://xmlns.com/wot/0.1/', 'gen': 'http://purl.org/gen/0.1#', 'foaf': 'http://xmlns.com/foaf/0.1/', 'geonames': 'http://www.geonames.org/ontology#', 'dbpedia': 'http://dbpedia.org/resource/', 'dbpprop': 'http://dbpedia.org/property/', 'dts': 'http://w3id.org/dts-ontology/', 'geo': 'http://www.w3.org/2003/01/geo/wgs84_pos#', 'rdfs': 'http://www.w3.org/2000/01/rdf-schema#', 'dc': 'http://purl.org/dc/elements/1.1/', 'dbo': 'http://dbpedia.org/ontology/', 'content': 'http://purl.org/rss/1.0/modules/content/', 'dc11': 'http://purl.org/dc/elements/1.1/', 'rdf': 'http://www.w3.org/1999/02/22-rdf-syntax-ns#', 'owl': 'http://www.w3.org/2002/07/owl#', 'skos': 'http://www.w3.org/2004/02/skos/core#', 'doap': 'http://usefulinc.com/ns/doap#'}

List of RDF Prefixes with their equivalents

URN, References and Citations

class MyCapytain.common.reference.NodeId(identifier=None, children=None, parent=None, siblings=(None, None), depth=None)[source]

Collection of directional references for a Tree

Parameters:
  • identifier (str) – Current object identifier
  • children ([str]) – Current node Children’s Identifier
  • parent (str) – Parent of the current node
  • siblings (str) – Previous and next node of the current node
  • depth (int) – Depth of the node in the global hierarchy of the text tree
childIds

Children Node

Return type:[str]
depth

Depth of the node in the global hierarchy of the text tree

Return type:int
firstId

First child Node

Return type:str
id

Current object identifier

Return type:str
lastId

Last child Node

Return type:str
nextId

Next Node (Sibling)

Return type:str
parentId

Parent Node

Return type:str
prevId

Previous Node (Sibling)

Return type:str
siblingsId

Siblings Node

Return type:(str, str)
class MyCapytain.common.reference.URN(urn)[source]

A URN object giving all useful sections

Parameters:

urn (str) – A CTS URN

Variables:
  • NAMESPACE – Constant representing the URN until its namespace
  • TEXTGROUP – Constant representing the URN until its textgroup
  • WORK – Constant representing the URN until its work
  • VERSION – Constant representing the URN until its version
  • PASSAGE – Constant representing the URN until its full passage
  • PASSAGE_START – Constant representing the URN until its passage (end excluded)
  • PASSAGE_END – Constant representing the URN until its passage (start excluded)
  • NO_PASSAGE – Constant representing the URN until its passage excluding its passage
  • COMPLETE – Constant representing the complete URN
Example:
>>>    a = URN(urn="urn:cts:latinLit:phi1294.phi002.perseus-lat2:1.1")

URN object supports the following magic methods : len(), str() and eq(), gt() and lt().

Example:
>>>     b = URN("urn:cts:latinLit:phi1294.phi002")
>>>     a != b
>>>     a > b # It has more member. Only member count is compared
>>>     b < a
>>>     len(a) == 5 # Reference is not counted to not induce count equivalencies with the optional version
>>>     len(b) == 4
static model()[source]

Generate a standard dictionary model for URN inside function

Returns:Dictionary of CTS elements
namespace

CTS Namespace element of the URN

Return type:str
Returns:Namespace part of the URN
reference

Reference element of the URN

Return type:Reference
Returns:Reference part of the URN
textgroup

Textgroup element of the URN

Return type:str
Returns:Textgroup part of the URN
upTo(key)[source]

Returns the urn up to given level using URN Constants

Parameters:

key (int) – Identifier of the wished resource using URN constants

Returns:

String representation of the partial URN requested

Return type:

str

Example:
>>>    a = URN(urn="urn:cts:latinLit:phi1294.phi002.perseus-lat2:1.1") 
>>>    a.upTo(URN.TEXTGROUP) == "urn:cts:latinLit:phi1294"
urn_namespace

General Namespace element of the URN

Return type:str
Returns:Namespace part of the URN
version

Version element of the URN

Return type:str
Returns:Version part of the URN
work

Work element of the URN

Return type:str
Returns:Work part of the URN
class MyCapytain.common.reference.Reference(reference='')[source]

A reference object giving information

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")
>>>    Reference("1.1-2.2.2").highest == ["1", "1"]

Reference object supports the following magic methods : len(), str() and eq().

Example:
>>>    len(a) == 2 && len(b) == 1
>>>    str(a) == "1.1@Achiles[1]-1.2@Zeus[1]"
>>>    b == Reference("1.1") && b != a

Note

While Reference(...).subreference and .list are not available for range, Reference(..).start.subreference and Reference(..).end.subreference as well as .list are available

static convert_subreference(word, counter)[source]

Convert a word and a counter into a standard tuple representation

Parameters:
  • word – Word Element of the subreference
  • counter – Index of the Word
Returns:

Tuple representing the element

Return type:

(str, int)

end

Quick access property for reference end list

Return type:Reference
highest

Return highest reference level

For references such as 1.1-1.2.8, with different level, it can be useful to access to the highest node in the hierarchy. In this case, the highest level would be 1.1. The function would return [“1”, “1”]

Note

By default, this property returns the start level

Return type:Reference
list

Return a list version of the object if it is a single passage

Note

Access to start list and end list should be done through obj.start.list and obj.end.list

Return type:[str]
parent

Parent of the actual URN, for example, 1.1 for 1.1.1

Return type:Reference
start

Quick access property for start list

Return type:Reference
subreference

Return the subreference of a single node reference

Note

Access to start and end subreference should be done through obj.start.subreference and obj.end.subreference

Return type:(str, int)
class MyCapytain.common.reference.Citation(name=None, xpath=None, scope=None, refsDecl=None, child=None)[source]

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
Variables:
  • name – Name of the citation (e.g. “book”)
  • xpath – Xpath of the citation (As described by CTS norm)
  • scope – Scope of the citation (As described by CTS norm)
  • refsDecl – refsDecl version
  • child – 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]
__len__()[source]

Length method

Return type:int
Returns:Number of nested citations
fill(passage=None, xpath=None)[source]

Fill the xpath with given informations

Parameters:
  • passage (Reference or list or None. Can be list of None and not None) – Passage reference
  • xpath (Boolean) – If set to True, will return the replaced self.xpath value and not the whole self.refsDecl
Return type:

basestring

Returns:

Xpath to find the passage

citation = Citation(name="line", scope="/TEI/text/body/div/div[@n="?"]",xpath="//l[@n="?"]")
print(citation.fill(["1", None]))
# /TEI/text/body/div/div[@n='1']//l[@n]
print(citation.fill(None))
# /TEI/text/body/div/div[@n]//l[@n]
print(citation.fill(Reference("1.1"))
# /TEI/text/body/div/div[@n='1']//l[@n='1']
print(citation.fill("1", xpath=True)
# //l[@n='1']

Metadata containers

class MyCapytain.common.metadata.Metadata(keys=None)[source]

A metadatum aggregation object provided to centralize metadata

param keys:A metadata field names list
type keys:[text_type]
ivar metadata:Dictionary of metadatum
__getitem__(key)[source]

Add a quick access system through getitem on the instance

Parameters:

key (text_type, 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("title", [("lat", "Amores"), ("fre", "Les Amours")])
>>>    m2 = Metadatum("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 (text_type, tuple) – Name of metadatum field
  • value (Metadatum) – Metadum dictionary
Returns:

An element of children whose index is key

Raises:

TypeError if key is not text_type or tuple of text_type

Raises:

ValueError if key and value are list and are not the same size

Example:
>>>    a = Metadata()
>>>    a["title"] = Metadatum("title", [("lat", "Amores"), ("fre", "Les Amours")])
>>>    print(a["title"]["lat"]) # Amores
>>>    a[("title", "author")] = (
>>>         Metadatum("title", [("lat", "Amores"), ("fre", "Les Amours")]),
>>>         Metadatum("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:

int

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:

Metadata

Example:
>>> a = Metadata(name="label")
>>> b = Metadata(name="title")
>>> a + b == Metadata(name=["label", "title"])
Variables:
export(output=None, **kwargs)

Export the collection item in the Mimetype required.

Parameters:output (str) – Mimetype to export to (Uses MyCapytain.common.utils.Mimetypes)
Returns:Object using a different representation
export_capacities

List Mimetypes that current object can export to

keys()[source]

List of keys available

Returns:List of metadatum keys
class MyCapytain.common.metadata.Metadatum(name, children=None, namespace=None)[source]

Metadatum object represent a single field of metadata

Parameters:
  • name (text_type) – Name of the field
  • children (List) – List of tuples, where first element is the key, and second the value
  • namespace (Namespace) – Object representing a namespace
Example:
>>>    a = Metadatum("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 (text_type, 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("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 (text_type, list, tuple) – Index key(s) for the metadata
  • value (text_type, list, tuple) – Values for the metadata
Returns:

An element of children whose index is key

Raises:

TypeError if key is not text_type or tuple of text_type

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("label", [("lat", "Amores"), ("fre", "Les Amours")])
>>> for key, value in a:
>>>     print(key, value) # Print ("lat", "Amores") and then ("fre", "Les Amours")
namespace

Namespace of the metadata entry

setDefault(key)[source]

Set a default key when a field does not exist

Parameters:

key (text_type) – An existing key of the instance

Returns:

Default key

Raises:

ValueError If key is not registered

Example:
>>>    a = Metadatum("label", [("lat", "Amores"), ("fre", "Les Amours")])
>>>    a.setDefault("fre")
>>>    print(a["eng"]) # == "Les Amours"

Utilities

class MyCapytain.common.utils.OrderedDefaultDict(default_factory=None, *args, **kwargs)[source]

Extension of Default Dict that makes an OrderedDefaultDict

Parameters:default_factory – Default class to initiate
MyCapytain.common.utils.copyNode(node, children=False, parent=False)[source]

Copy an XML Node

Parameters:
  • node – Etree Node
  • children – Copy children nodes is set to True
  • parent – Append copied node to parent if given
Returns:

New Element

MyCapytain.common.utils.nested_get(dictionary, keys)[source]

Get value in dictionary for dictionary[keys[0]][keys[1]][keys[..n]]

Parameters:
  • dictionary – An input dictionary
  • keys – Keys where to store data
Returns:

MyCapytain.common.utils.nested_ordered_dictionary()[source]

Helper to create a nested ordered default dictionary

Rtype OrderedDefaultDict:
 
Returns:Nested Ordered Default Dictionary instance
MyCapytain.common.utils.nested_set(dictionary, keys, value)[source]

Set value in dictionary for dictionary[keys[0]][keys[1]][keys[..n]]

Parameters:
  • dictionary – An input dictionary
  • keys – Keys where to store data
  • value – Value to set at keys** target
Returns:

None

MyCapytain.common.utils.normalize(string)[source]

Remove double-or-more spaces in a string

Parameters:string (text_type) – A string to change
Return type:text_type
Returns:Clean string
MyCapytain.common.utils.normalizeXpath(xpath)[source]

Normalize XPATH split around slashes

Parameters:xpath ([str]) – List of xpath elements
Returns:List of refined xpath
Return type:[str]
MyCapytain.common.utils.passageLoop(parent, new_tree, xpath1, xpath2=None, preceding_siblings=False, following_siblings=False)[source]

Loop over passages to construct and increment new tree given a parent and XPaths

Parameters:
  • parent – Parent on which to perform xpath
  • new_tree – Parent on which to add nodes
  • xpath1 ([str]) – List of xpath elements
  • xpath2 ([str]) – List of xpath elements
  • preceding_siblings – Append preceding siblings of XPath 1/2 match to the tree
  • following_siblings – Append following siblings of XPath 1/2 match to the tree
Returns:

Newly incremented tree

MyCapytain.common.utils.performXpath(parent, xpath)[source]

Perform an XPath on an element and indicate if we need to loop over it to find something

Parameters:
  • parent – XML Node on which to perform XPath
  • xpath – XPath to run
Returns:

(Result, Need to loop Indicator)

MyCapytain.common.utils.xmliter(node)[source]

Provides a simple XML Iter method which complies with either _Element or _ObjectifiedElement

Parameters:node – XML Node
Returns:Iterator for iterating over children of said node.
MyCapytain.common.utils.xmlparser(xml, objectify=True)[source]

Parse xml

Parameters:xml (Union[text_type, lxml.etree._Element]) – XML element
Return type:lxml.etree._Element
Returns:An element object
Raises:TypeError if element is not in accepted type

API Retrievers

Module endpoints contains prototypes and implementation of retrievers in MyCapytain

CTS 5 API

class MyCapytain.retrievers.cts5.CTS(endpoint, inventory=None)[source]

Bases: MyCapytain.retrievers.prototypes.CTS

Basic integration of the MyCapytain.retrievers.proto.CTS abstraction

call(parameters)[source]

Call an endpoint given the parameters

Parameters:parameters (dict) – Dictionary of parameters
Return type:text
getCapabilities(inventory=None, urn=None)[source]

Retrieve the inventory information of an API

Parameters:
  • inventory (text) – Name of the inventory
  • urn (str) – URN to filter with
Return type:

str

getFirstUrn(urn, inventory=None)[source]

Retrieve the first passage urn of a text

Parameters:
  • urn (text) – URN identifying the text
  • inventory (text) – Name of the inventory
Return type:

str

getLabel(urn, inventory=None)[source]

Retrieve informations about a CTS Urn

Parameters:
  • urn (text) – URN identifying the text’s passage (Minimum depth : 1)
  • inventory (text) – Name of the inventory
Return type:

str

getMetadata(objectId=None, **filters)[source]

Request metadata about a text or a collection

Parameters:
  • objectId – Filter for some object identifier
  • filters – Kwargs parameters. URN and Inv are available
Returns:

GetCapabilities CTS API request response

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:

str

getPassagePlus(urn, inventory=None, context=None)[source]

Retrieve a passage and information 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:

str

getPrevNextUrn(urn, inventory=None)[source]

Retrieve the previous and next passage urn of one passage

Parameters:
  • urn (text) – URN identifying the text’s passage (Minimum depth : 1)
  • inventory (text) – Name of the inventory
Return type:

str

getReffs(textId, level=1, subreference=None)[source]

Retrieve the siblings of a textual node

Parameters:
  • textId (str) – Text Identifier
  • level (int) – Depth for retrieval
  • subreference (str) – Passage Reference
Returns:

List of references

Return type:

[str]

getSiblings(textId, subreference)[source]

Retrieve the siblings of a textual node

Parameters:
  • textId – Text Identifier
  • reference – Passage Reference
Returns:

GetPrevNextUrn request response from the endpoint

getTextualNode(textId, subreference=None, prevnext=False, metadata=False)[source]

Retrieve a text node from the API

Parameters:
  • textId – Text Identifier
  • subreference – Passage Reference
  • prevnext – Retrieve graph representing previous and next passage
  • metadata – Retrieve metadata about the passage and the text
Returns:

GetPassage or GetPassagePlus CTS API request response

getValidReff(urn, inventory=None, level=None)[source]

Retrieve valid urn-references for a text

Parameters:
  • urn (text) – URN identifying the text
  • inventory (text) – Name of the inventory
  • level (int) – Depth of references expected
Returns:

XML Response from the API as string

Return type:

str

Prototypes

class MyCapytain.retrievers.prototypes.API(endpoint)[source]

Bases: object

API Prototype object

Parameters:
  • self (API) – Object
  • endpoint (text) – URL of the API
Variables:

endpoint – Url of the endpoint

class MyCapytain.retrievers.prototypes.CTS(endpoint)[source]

Bases: MyCapytain.retrievers.prototypes.CitableTextServiceRetriever

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:
  • urn (text) – URN identifying the text
  • inventory (text) – Name of the inventory
Return type:

str

getLabel(urn, inventory)[source]

Retrieve informations about a CTS Urn

Parameters:
  • urn (text) – URN identifying the text’s passage (Minimum depth : 1)
  • inventory (text) – Name of the inventory
Return type:

str

getMetadata(objectId=None, **filters)

Request metadata about a text or a collection

Parameters:
  • objectId – Text Identifier
  • filters – Kwargs parameters. URN and Inv are available
Returns:

Metadata of text from an API or the likes as bytes

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:

str

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:

str

getPrevNextUrn(urn, inventory)[source]

Retrieve the previous and next passage urn of one passage

Parameters:
  • urn (text) – URN identifying the text’s passage (Minimum depth : 1)
  • inventory (text) – Name of the inventory
Return type:

str

getReffs(textId, level=1, subreference=None)

Retrieve the siblings of a textual node

Parameters:
  • textId (str) – Text Identifier
  • level (int) – Depth for retrieval
  • subreference (str) – Passage Reference
Returns:

List of references

Return type:

[str]

getSiblings(textId, subreference)

Retrieve the siblings of a textual node

Parameters:
  • textId – Text Identifier
  • subreference – Passage Reference
Returns:

Siblings references from an API or the likes as bytes

getTextualNode(textId, subreference=None, prevnext=False, metadata=False)

Retrieve a text node from the API

Parameters:
  • textId – Text Identifier
  • subreference – Passage Reference
  • prevnext – Retrieve graph representing previous and next passage
  • metadata – Retrieve metadata about the passage and the text
Returns:

Text of a Passage from an API or the likes as bytes

getValidReff(urn, inventory, level=1)[source]

Retrieve valid urn-references for a text

Parameters:
  • urn (text) – URN identifying the text
  • inventory (text) – Name of the inventory
  • level (int) – Depth of references expected
Return type:

str

class MyCapytain.retrievers.prototypes.CitableTextServiceRetriever(endpoint)[source]

Bases: MyCapytain.retrievers.prototypes.API

Citable Text Service retrievers should have at least have some of the following properties

getMetadata(objectId=None, **filters)[source]

Request metadata about a text or a collection

Parameters:
  • objectId – Text Identifier
  • filters – Kwargs parameters. URN and Inv are available
Returns:

Metadata of text from an API or the likes as bytes

getReffs(textId, level=1, subreference=None)[source]

Retrieve the siblings of a textual node

Parameters:
  • textId (str) – Text Identifier
  • level (int) – Depth for retrieval
  • subreference (str) – Passage Reference
Returns:

List of references

Return type:

[str]

getSiblings(textId, subreference)[source]

Retrieve the siblings of a textual node

Parameters:
  • textId – Text Identifier
  • subreference – Passage Reference
Returns:

Siblings references from an API or the likes as bytes

getTextualNode(textId, subreference=None, prevnext=False, metadata=False)[source]

Retrieve a text node from the API

Parameters:
  • textId – Text Identifier
  • subreference – Passage Reference
  • prevnext – Retrieve graph representing previous and next passage
  • metadata – Retrieve metadata about the passage and the text
Returns:

Text of a Passage from an API or the likes as bytes

Resolvers

Remote CTS API

class MyCapytain.resolvers.cts.api.HttpCTSResolver(endpoint)[source]

HttpCTSResolver provide a resolver for CTS API http endpoint.

Parameters:endpoint (CTS) – CTS API Retriever
Variables:endpoint – CTS API Retriever
endpoint

CTS Endpoint of the resolver

Returns:CTS Endpoint
Return type:CTS
getMetadata(objectId=None, **filters)[source]

Request metadata about a text or a collection

Parameters:
  • objectId (str) – Object Identifier to filter on
  • filters (dict) – Kwargs parameters.
Returns:

Collection

getReffs(textId, level=1, subreference=None)[source]

Retrieve the siblings of a textual node

Parameters:
  • textId (str) – Text Identifier
  • level (int) – Depth for retrieval
  • subreference (str) – Passage Reference
Returns:

List of references

Return type:

[str]

getSiblings(textId, subreference)[source]

Retrieve the siblings of a textual node

Parameters:
  • textId (str) – Text Identifier
  • subreference (str) – Passage Reference
Returns:

Tuple of references

Return type:

(str, str)

getTextualNode(textId, subreference=None, prevnext=False, metadata=False)[source]

Retrieve a text node from the API

Parameters:
  • textId (str) – Text Identifier
  • subreference (str) – Passage Reference
  • prevnext (boolean) – Retrieve graph representing previous and next passage
  • metadata (boolean) – Retrieve metadata about the passage and the text
Returns:

Passage

Return type:

Passage

Local CapiTainS Guidelines CTS Resolver

class MyCapytain.resolvers.cts.local.CTSCapitainsLocalResolver(resource, name=None, logger=None)[source]

XML Folder Based resolver. Text and metadata resolver based on local directories

Parameters:
  • resource ([str]) – Resource should be a list of folders retaining data as Capitains Guidelines Repositories
  • name (str) – Key used to differentiate Repository and thus enabling different repo to be used
  • logger (logging) – Logging object
Variables:
  • TEXT_CLASS – Text Class [not instantiated] to be used to parse Texts. Can be changed to support Cache for example
  • DEFAULT_PAGE – Default Page to show
  • PER_PAGE – Tuple representing the minimal number of texts returned, the default number and the maximum number of texts returned
TEXT_CLASS

alias of Text

getMetadata(objectId=None, **filters)[source]

Request metadata about a text or a collection

Parameters:
  • objectId (str) – Object Identifier to filter on
  • filters (dict) – Kwargs parameters.
Returns:

Collection

getReffs(textId, level=1, subreference=None)[source]

Retrieve the siblings of a textual node

Parameters:
  • textId (str) – Text Identifier
  • level (int) – Depth for retrieval
  • subreference (str) – Passage Reference
Returns:

List of references

Return type:

[str]

getSiblings(textId, subreference)[source]

Retrieve the siblings of a textual node

Parameters:
  • textId (str) – Text Identifier
  • subreference (str) – Passage Reference
Returns:

Tuple of references

Return type:

(str, str)

getTextualNode(textId, subreference=None, prevnext=False, metadata=False)[source]

Retrieve a text node from the API

Parameters:
  • textId (str) – Text Identifier
  • subreference (str) – Passage Reference
  • prevnext (boolean) – Retrieve graph representing previous and next passage
  • metadata (boolean) – Retrieve metadata about the passage and the text
Returns:

Passage

Return type:

Passage

static pagination(page, limit, length)[source]

Help for pagination :param page: Provided Page :param limit: Number of item to show :param length: Length of the list to paginate :return: (Start Index, End Index, Page Number, Item Count)

parse(resource)[source]

Parse a list of directories ans :param resource: List of folders :param cache: Auto cache the results :return: An inventory resource and a list of Text metadata-objects

xmlparse(file)[source]

Parse a XML file :param file: Opened File :return: Tree

Prototypes

class MyCapytain.resolvers.prototypes.Resolver[source]

Resolver provide a native python API which returns python objects.

Initiation of resolvers are dependent on the implementation of the prototype

getMetadata(objectId=None, **filters)[source]

Request metadata about a text or a collection

Parameters:
  • objectId (str) – Object Identifier to filter on
  • filters (dict) – Kwargs parameters.
Returns:

Collection

getReffs(textId, level=1, subreference=None)[source]

Retrieve the siblings of a textual node

Parameters:
  • textId (str) – Text Identifier
  • level (int) – Depth for retrieval
  • subreference (str) – Passage Reference
Returns:

List of references

Return type:

[str]

getSiblings(textId, subreference)[source]

Retrieve the siblings of a textual node

Parameters:
  • textId (str) – Text Identifier
  • subreference (str) – Passage Reference
Returns:

Tuple of references

Return type:

(str, str)

getTextualNode(textId, subreference=None, prevnext=False, metadata=False)[source]

Retrieve a text node from the API

Parameters:
  • textId (str) – Text Identifier
  • subreference (str) – Passage Reference
  • prevnext (boolean) – Retrieve graph representing previous and next passage
  • metadata (boolean) – Retrieve metadata about the passage and the text
Returns:

Passage

Return type:

Passage

Texts and inventories

Text

TEI based texts

class MyCapytain.resources.texts.encodings.TEIResource(resource, **kwargs)[source]

Bases: MyCapytain.resources.prototypes.text.InteractiveTextualNode

TEI Encoded Resource

Parameters:

resource (Union[str,_Element]) – XML Resource that needs to be parsed into a Passage/Text

Variables:
DEFAULT_EXPORT = 'text/plain'
EXPORT_TO = ['python/lxml', 'text/xml', 'python/NestedDict', 'text/plain']
about

Metadata information about the text

Returns:Collection object with metadata about the text
Rtype Collection:
 
childIds

Identifiers of children

Returns:Identifiers of children
Return type:[str]
children

Children Passages

Return type:iterator(Passage)
citation

Citation Object of the Text

Returns:Citation Object of the Text
Return type:Citation
default_exclude = []
depth

Depth of the node in the global hierarchy of the text tree

Return type:int
export(output=None, exclude=None, **kwargs)

Export the collection item in the Mimetype required.

..note:: If current implementation does not have special mimetypes, reuses default_export method

Parameters:
  • output (str) – Mimetype to export to (Uses MyCapytain.common.constants.Mimetypes)
  • exclude ([str]) – Information to exclude. Specific to implementations
Returns:

Object using a different representation

export_capacities

List Mimetypes that current object can export to

first

First Passage

Return type:Passage
firstId

First child of current Passage

Return type:str
Returns:First passage node Information
getReffs(level=1, subreference=None)

Reference available at a given level

Parameters:
  • level (Int) – Depth required. If not set, should retrieve first encountered level (1 based)
  • passage (Reference) – Subreference (optional)
Return type:

[text_type]

Returns:

List of levels

getTextualNode(subreference)

Retrieve a passage and store it in the object

Parameters:subreference (str or Node or Reference) – Reference of the passage to retrieve
Return type:TextualNode
Returns:Object representing the passage
Raises:TypeError when reference is not a list or a Reference
id

Identifier of the text

Returns:Identifier of the text
Return type:text_type
last

Last Passage

Return type:Passage
lastId

Last child of current Passage

Return type:str
Returns:Last passage Node representation
metadata

Metadata information about the text

Returns:Collection object with metadata about the text
Return type:Metadata
next

Get Next Passage

Return type:Passage
nextId

Next Node (Sibling)

Return type:str
parent

Parent Passage

Return type:Passage
parentId

Parent Node

Return type:str
prev

Get Previous Passage

Return type:Passage
prevId

Previous Node (Sibling)

Return type:str
siblingsId

Siblings Node

Return type:(str, str)
text

String representation of the text

Returns:String representation of the text
Return type:text_type
xml

XML Representation of the Passage

Return type:lxml.etree._Element
Returns:XML element representing the passage

Locally read text

class MyCapytain.resources.texts.locals.tei.Text(urn=None, citation=None, resource=None)[source]

Bases: MyCapytain.resources.texts.locals.tei.__SharedMethods__, MyCapytain.resources.texts.encodings.TEIResource, MyCapytain.resources.prototypes.text.CitableText

Implementation of CTS tools for local files

Parameters:
  • urn (MyCapytain.common.reference.URN) – A URN identifier
  • resource (lxml.etree._Element) – A resource
  • citation (Citation) – Highest Citation level
  • autoreffs (bool) – Parse references on load (default : True)
Variables:

resource – lxml

DEFAULT_EXPORT = 'text/plain'
EXPORT_TO = ['python/lxml', 'text/xml', 'python/NestedDict', 'text/plain']
about

Metadata information about the text

Returns:Collection object with metadata about the text
Rtype Collection:
 
childIds

Identifiers of children

Returns:Identifiers of children
Return type:[str]
children

Children Passages

Return type:iterator(Passage)
citation

Citation Object of the Text

Returns:Citation Object of the Text
Return type:Citation
default_exclude = []
depth

Depth of the node in the global hierarchy of the text tree

Return type:int
export(output=None, exclude=None, **kwargs)

Export the collection item in the Mimetype required.

..note:: If current implementation does not have special mimetypes, reuses default_export method

Parameters:
  • output (str) – Mimetype to export to (Uses MyCapytain.common.constants.Mimetypes)
  • exclude ([str]) – Information to exclude. Specific to implementations
Returns:

Object using a different representation

export_capacities

List Mimetypes that current object can export to

first

First Passage

Return type:Passage
firstId

First child of current Passage

Return type:str
Returns:First passage node Information
getLabel()

Retrieve metadata about the text

Return type:Collection
Returns:Retrieve Label informations in a Collection format
getReffs(level=1, subreference=None)

Reference available at a given level

Parameters:
  • level (Int) – Depth required. If not set, should retrieve first encountered level (1 based)
  • subreference (str) – Subreference (optional)
Return type:

List.basestring

Returns:

List of levels

getTextualNode(subreference=None, simple=False)

Finds a passage in the current text

Parameters:
  • subreference (Union[list, Reference]) – Identifier of the subreference / passages
  • simple (boolean) – If set to true, retrieves nodes up to the given one, cleaning non required siblings.
Return type:

Passage, ContextPassage

Returns:

Asked passage

getValidReff(level=None, reference=None, _debug=False)

Retrieve valid passages directly

Parameters:
  • level (int) – Depth required. If not set, should retrieve first encountered level (1 based)
  • reference (Reference) – Passage Reference
  • _debug (bool) – Check on passages duplicates
Returns:

List of levels

Return type:

list(basestring, str)

Note

GetValidReff works for now as a loop using Passage, subinstances of Text, to retrieve the valid informations. Maybe something is more powerfull ?

id

Identifier of the text

Returns:Identifier of the text
Return type:text_type
last

Last Passage

Return type:Passage
lastId

Last child of current Passage

Return type:str
Returns:Last passage Node representation
metadata

Metadata information about the text

Returns:Collection object with metadata about the text
Return type:Metadata
next

Get Next Passage

Return type:Passage
nextId

Next Node (Sibling)

Return type:str
parent

Parent Passage

Return type:Passage
parentId

Parent Node

Return type:str
prev

Get Previous Passage

Return type:Passage
prevId

Previous Node (Sibling)

Return type:str
reffs

Get all valid reffs for every part of the CitableText

Return type:[str]
siblingsId

Siblings Node

Return type:(str, str)
test()[source]

Parse the object and generate the children

text

String representation of the text

Returns:String representation of the text
Return type:text_type
textObject

Textual Object with full capacities (Unlike Simple Passage)

Return type:Text, Passage
Returns:Textual Object with full capacities (Unlike Simple Passage)
tostring(*args, **kwargs)

Transform the Passage in XML string

Parameters:
  • args – Ordered arguments for etree.tostring() (except the first one)
  • kwargs – Named arguments
Returns:

urn

URN Identifier of the object

Return type:URN
xml

XML Representation of the Passage

Return type:lxml.etree._Element
Returns:XML element representing the passage
xpath(*args, **kwargs)

Perform XPath on the passage XML

Parameters:
  • args – Ordered arguments for etree._Element().xpath()
  • kwargs – Named arguments
Returns:

Result list

Return type:

list(etree._Element)

class MyCapytain.resources.texts.locals.tei.Passage(reference, urn=None, citation=None, resource=None, text=None)[source]

Bases: MyCapytain.resources.texts.locals.tei.__SharedMethods__, MyCapytain.resources.texts.encodings.TEIResource, MyCapytain.resources.prototypes.text.Passage

Passage class for local texts which rebuilds the tree up to the passage.

For design purposes, some people would prefer the output of GetPassage to be consistent. ContextPassage rebuilds the tree of the text up to the passage, keeping attributes of original nodes

Example : for a text with a citation scheme with following refsDecl : /TEI/text/body/div[@type=’edition’]/div[@n=’$1’]/div[@n=’$2’]/l[@n=’$3’] and a passage 1.1.1-1.2.3, this class will build an XML tree looking like the following

<TEI ...>
    <text ...>
        <body ...>
            <div type='edition' ...>
                <div n='1' ...>

                    <div n='1' ...>
                        <l n='1'>...</l>
                        ...
                    </div>
                    <div n='2' ...>
                        <l n='3'>...</l>
                    </div>
                </div>
            </div>
        </body>
    </text>
</TEI>
Parameters:
  • reference (Reference) – Passage reference
  • urn (URN) – URN of the source text or of the passage
  • citation (Citation) – Citation scheme of the text
  • resource (etree._Element) – Element representing the passage
  • text (Text) – Text containing the passage

Note

.prev, .next, .first and .last won’t run on passage with a range made of two different level, such as 1.1-1.2.3 or 1-a.b. Those will raise InvalidSiblingRequest

DEFAULT_EXPORT = 'text/plain'
EXPORT_TO = ['python/lxml', 'text/xml', 'python/NestedDict', 'text/plain']
about

Metadata information about the text

Returns:Collection object with metadata about the text
Rtype Collection:
 
childIds

Children of the passage

Return type:None, Reference
Returns:Dictionary of chidren, where key are subreferences
children

Children Passages

Return type:iterator(Passage)
citation

Citation Object of the Text

Returns:Citation Object of the Text
Return type:Citation
default_exclude = []
depth

Depth of the node in the global hierarchy of the text tree

Return type:int
export(output=None, exclude=None, **kwargs)

Export the collection item in the Mimetype required.

..note:: If current implementation does not have special mimetypes, reuses default_export method

Parameters:
  • output (str) – Mimetype to export to (Uses MyCapytain.common.constants.Mimetypes)
  • exclude ([str]) – Information to exclude. Specific to implementations
Returns:

Object using a different representation

export_capacities

List Mimetypes that current object can export to

first

First Passage

Return type:Passage
firstId

First child of current Passage

Return type:str
Returns:First passage node Information
getLabel()

Retrieve metadata about the text

Return type:Collection
Returns:Retrieve Label informations in a Collection format
getReffs(level=1, subreference=None)

Reference available at a given level

Parameters:
  • level (Int) – Depth required. If not set, should retrieve first encountered level (1 based)
  • subreference (str) – Subreference (optional)
Return type:

List.basestring

Returns:

List of levels

getTextualNode(subreference=None, *args, **kwargs)[source]
getValidReff(level=None, reference=None, _debug=False)

Retrieve valid passages directly

Parameters:
  • level (int) – Depth required. If not set, should retrieve first encountered level (1 based)
  • reference (Reference) – Passage Reference
  • _debug (bool) – Check on passages duplicates
Returns:

List of levels

Return type:

list(basestring, str)

Note

GetValidReff works for now as a loop using Passage, subinstances of Text, to retrieve the valid informations. Maybe something is more powerfull ?

id

Identifier of the text

Returns:Identifier of the text
Return type:text_type
last

Last Passage

Return type:Passage
lastId

Last child of current Passage

Return type:str
Returns:Last passage Node representation
metadata

Metadata information about the text

Returns:Collection object with metadata about the text
Return type:Metadata
next

Next Passage (Interactive Passage)

nextId

Next passage

Returns:Next passage at same level
Return type:None, Reference
parent

Parent Passage

Return type:Passage
parentId

Parent Node

Return type:str
prev

Previous Passage (Interactive Passage)

prevId

Get the Previous passage reference

Returns:Previous passage reference at the same level
Return type:None, Reference
reference

Reference of the object

siblingsId

Siblings Identifiers of the passage

Return type:(str, str)
text

String representation of the text

Returns:String representation of the text
Return type:text_type
textObject

Text Object. Required for NextPrev

Return type:Text
tostring(*args, **kwargs)

Transform the Passage in XML string

Parameters:
  • args – Ordered arguments for etree.tostring() (except the first one)
  • kwargs – Named arguments
Returns:

urn

URN Identifier of the object

Return type:URN
xml

XML Representation of the Passage

Return type:lxml.etree._Element
Returns:XML element representing the passage
xpath(*args, **kwargs)

Perform XPath on the passage XML

Parameters:
  • args – Ordered arguments for etree._Element().xpath()
  • kwargs – Named arguments
Returns:

Result list

Return type:

list(etree._Element)

class MyCapytain.resources.texts.locals.tei.__SimplePassage__(resource, reference, citation, text, urn=None)[source]

Bases: MyCapytain.resources.texts.locals.tei.__SharedMethods__, MyCapytain.resources.texts.encodings.TEIResource, MyCapytain.resources.prototypes.text.Passage

Passage for simple and quick parsing of texts

Parameters:
  • resource (etree._Element) – Element representing the passage
  • reference (Reference) – Passage reference
  • urn (URN) – URN of the source text or of the passage
  • citation (Citation) – Citation scheme of the text
  • text (Text) – Text containing the passage
about

Metadata information about the text

Returns:Collection object with metadata about the text
Rtype Collection:
 
childIds

Children of the passage

Return type:None, Reference
Returns:Dictionary of chidren, where key are subreferences
children

Children Passages

Return type:iterator(Passage)
citation

Citation Object of the Text

Returns:Citation Object of the Text
Return type:Citation
depth

Depth of the node in the global hierarchy of the text tree

Return type:int
export(output=None, exclude=None, **kwargs)

Export the collection item in the Mimetype required.

..note:: If current implementation does not have special mimetypes, reuses default_export method

Parameters:
  • output (str) – Mimetype to export to (Uses MyCapytain.common.constants.Mimetypes)
  • exclude ([str]) – Information to exclude. Specific to implementations
Returns:

Object using a different representation

export_capacities

List Mimetypes that current object can export to

first

First Passage

Return type:Passage
firstId

First child of current Passage

Return type:str
Returns:First passage node Information
getLabel()

Retrieve metadata about the text

Return type:Collection
Returns:Retrieve Label informations in a Collection format
getReffs(level=1, subreference=None)[source]

Reference available at a given level

Parameters:
  • level (Int) – Depth required. If not set, should retrieve first encountered level (1 based)
  • subreference (Reference) – Subreference (optional)
Return type:

List.basestring

Returns:

List of levels

getTextualNode(subreference=None)[source]

Special GetPassage implementation for SimplePassage (Simple is True by default)

Parameters:subreference
Returns:
getValidReff(level=None, reference=None, _debug=False)

Retrieve valid passages directly

Parameters:
  • level (int) – Depth required. If not set, should retrieve first encountered level (1 based)
  • reference (Reference) – Passage Reference
  • _debug (bool) – Check on passages duplicates
Returns:

List of levels

Return type:

list(basestring, str)

Note

GetValidReff works for now as a loop using Passage, subinstances of Text, to retrieve the valid informations. Maybe something is more powerfull ?

id

Identifier of the text

Returns:Identifier of the text
Return type:text_type
last

Last Passage

Return type:Passage
lastId

Last child of current Passage

Return type:str
Returns:Last passage Node representation
metadata

Metadata information about the text

Returns:Collection object with metadata about the text
Return type:Metadata
next

Get Next Passage

Return type:Passage
nextId

Next passage

Returns:Next passage at same level
Return type:None, Reference
parent

Parent Passage

Return type:Passage
parentId

Parent Node

Return type:str
prev

Get Previous Passage

Return type:Passage
prevId

Get the Previous passage reference

Returns:Previous passage reference at the same level
Return type:None, Reference
reference

URN Passage Reference

Returns:Reference
Return type:Reference
siblingsId

Siblings Identifiers of the passage

Return type:(str, str)
text

String representation of the text

Returns:String representation of the text
Return type:text_type
textObject

Text Object. Required for NextPrev

Return type:Text
tostring(*args, **kwargs)

Transform the Passage in XML string

Parameters:
  • args – Ordered arguments for etree.tostring() (except the first one)
  • kwargs – Named arguments
Returns:

urn

URN Identifier of the object

Return type:URN
xml

XML Representation of the Passage

Return type:lxml.etree._Element
Returns:XML element representing the passage
xpath(*args, **kwargs)

Perform XPath on the passage XML

Parameters:
  • args – Ordered arguments for etree._Element().xpath()
  • kwargs – Named arguments
Returns:

Result list

Return type:

list(etree._Element)

CTS API Texts

Formerly MyCapytain.resources.texts.api (< 2.0.0)

class MyCapytain.resources.texts.api.cts.Text(urn, retriever, citation=None, **kwargs)[source]

Bases: MyCapytain.resources.texts.api.cts.__SharedMethod__, MyCapytain.resources.prototypes.text.CitableText

API Text object

Parameters:
  • urn (Union[URN, str, unicode]) – A URN identifier
  • resource (CitableTextServiceRetriever) – An API endpoint
  • citation (Citation) – Citation for children level
  • id (List) – Identifier of the subreference without URN informations
DEFAULT_EXPORT = None
DEFAULT_LANG = 'eng'
EXPORT_TO = []
about

Metadata information about the text

Returns:Collection object with metadata about the text
Rtype Collection:
 
childIds

Identifiers of children

Returns:Identifiers of children
Return type:[str]
children

Children Passages

Return type:iterator(Passage)
citation

Citation Object of the Text

Returns:Citation Object of the Text
Return type:Citation
default_exclude = []
depth

Depth of the current opbject

Returns:Int representation of the depth based on URN information
Return type:int
export(output='text/plain', exclude=None, **kwargs)[source]

Export the collection item in the Mimetype required.

..note:: If current implementation does not have special mimetypes, reuses default_export method

Parameters:
  • output (str) – Mimetype to export to (Uses Mimetypes)
  • exclude ([str]) – Informations to exclude. Specific to implementations
Returns:

Object using a different representation

export_capacities

List Mimetypes that current object can export to

first

First Passage

Return type:Passage
firstId

Children passage

Return type:str
Returns:First children of the graph. Shortcut to self.graph.children[0]
firstUrn(resource)

Parse a resource to get the first URN

Parameters:resource (etree._Element) – XML Resource
Returns:Tuple representing previous and next urn
Return type:str
getFirstUrn(reference=None)

Get the first children URN for a given resource

Parameters:reference (Reference, str) – Reference from which to find child (If None, find first reference)
Returns:Children URN
Return type:URN
getLabel()

Retrieve metadata about the text

Return type:Metadata
Returns:Dictionary with label informations
getPassagePlus(reference=None)

Retrieve a passage and informations around it and store it in the object

Parameters:reference (Reference or List of text_type) – Reference of the passage
Return type:Passage
Returns:Object representing the passage
Raises:TypeError when reference is not a list or a Reference
getPrevNextUrn(reference)

Get the previous URN of a reference of the text

Parameters:reference (Union[Reference, str]) – Reference from which to find siblings
Returns:(Previous Passage Reference,Next Passage Reference)
getReffs(level=1, subreference=None)

Reference available at a given level

Parameters:
  • level (Int) – Depth required. If not set, should retrieve first encountered level (1 based)
  • subreference (Reference) – Subreference (optional)
Return type:

[text_type]

Returns:

List of levels

getTextualNode(subreference=None)

Retrieve a passage and store it in the object

Parameters:subreference (Union[Reference, URN, str, list]) – Reference of the passage (Note : if given a list, this should be a list of string that compose the reference)
Return type:Passage
Returns:Object representing the passage
Raises:TypeError when reference is not a list or a Reference
getValidReff(level=1, reference=None)

Given a resource, CitableText will compute valid reffs

Parameters:
  • level (Int) – Depth required. If not set, should retrieve first encountered level (1 based)
  • reference (Reference) – Passage reference
Return type:

list(str)

Returns:

List of levels

id

Identifier of the text

Returns:Identifier of the text
Return type:text_type
last

Last Passage

Return type:Passage
lastId

Children passage

Return type:str
Returns:First children of the graph. Shortcut to self.graph.children[0]
metadata

Metadata information about the text

Returns:Collection object with metadata about the text
Return type:Metadata
next
nextId
parent

Parent Passage

Return type:Passage
parentId

Parent Node

Return type:str
prev
prevId
prevnext(resource)

Parse a resource to get the prev and next urn

Parameters:resource (etree._Element) – XML Resource
Returns:Tuple representing previous and next urn
Return type:(str, str)
reffs

Get all valid reffs for every part of the CitableText

Return type:MyCapytain.resources.texts.tei.Citation
retriever

Retriever object used to query for more data

Return type:CitableTextServiceRetriever
siblingsId
text

String representation of the text

Returns:String representation of the text
Return type:text_type
urn

URN Identifier of the object

Return type:URN
class MyCapytain.resources.texts.api.cts.Passage(urn, resource, *args, **kwargs)[source]

Bases: MyCapytain.resources.texts.api.cts.__SharedMethod__, MyCapytain.resources.prototypes.text.Passage, MyCapytain.resources.texts.encodings.TEIResource

Passage representing

Parameters:
  • urn
  • resource
  • retriever
  • args
  • kwargs
DEFAULT_EXPORT = 'text/plain'
EXPORT_TO = ['python/lxml', 'text/xml', 'python/NestedDict', 'text/plain']
about

Metadata information about the text

Returns:Collection object with metadata about the text
Rtype Collection:
 
childIds

Identifiers of children

Returns:Identifiers of children
Return type:[str]
children

Children Passages

Return type:iterator(Passage)
citation

Citation Object of the Text

Returns:Citation Object of the Text
Return type:Citation
default_exclude = []
depth

Depth of the current opbject

Returns:Int representation of the depth based on URN information
Return type:int
export(output=None, exclude=None, **kwargs)

Export the collection item in the Mimetype required.

..note:: If current implementation does not have special mimetypes, reuses default_export method

Parameters:
  • output (str) – Mimetype to export to (Uses MyCapytain.common.constants.Mimetypes)
  • exclude ([str]) – Information to exclude. Specific to implementations
Returns:

Object using a different representation

export_capacities

List Mimetypes that current object can export to

first

First Passage

Return type:Passage
firstId

Children passage

Return type:str
Returns:First children of the graph. Shortcut to self.graph.children[0]
firstUrn(resource)

Parse a resource to get the first URN

Parameters:resource (etree._Element) – XML Resource
Returns:Tuple representing previous and next urn
Return type:str
getFirstUrn(reference=None)

Get the first children URN for a given resource

Parameters:reference (Reference, str) – Reference from which to find child (If None, find first reference)
Returns:Children URN
Return type:URN
getLabel()

Retrieve metadata about the text

Return type:Metadata
Returns:Dictionary with label informations
getPassagePlus(reference=None)

Retrieve a passage and informations around it and store it in the object

Parameters:reference (Reference or List of text_type) – Reference of the passage
Return type:Passage
Returns:Object representing the passage
Raises:TypeError when reference is not a list or a Reference
getPrevNextUrn(reference)

Get the previous URN of a reference of the text

Parameters:reference (Union[Reference, str]) – Reference from which to find siblings
Returns:(Previous Passage Reference,Next Passage Reference)
getReffs(level=1, subreference=None)

Reference available at a given level

Parameters:
  • level (Int) – Depth required. If not set, should retrieve first encountered level (1 based)
  • subreference (Reference) – Subreference (optional)
Return type:

[text_type]

Returns:

List of levels

getTextualNode(subreference=None)

Retrieve a passage and store it in the object

Parameters:subreference (Union[Reference, URN, str, list]) – Reference of the passage (Note : if given a list, this should be a list of string that compose the reference)
Return type:Passage
Returns:Object representing the passage
Raises:TypeError when reference is not a list or a Reference
getValidReff(level=1, reference=None)

Given a resource, CitableText will compute valid reffs

Parameters:
  • level (Int) – Depth required. If not set, should retrieve first encountered level (1 based)
  • reference (Reference) – Passage reference
Return type:

list(str)

Returns:

List of levels

id
last

Last Passage

Return type:Passage
lastId

Children passage

Return type:str
Returns:First children of the graph. Shortcut to self.graph.children[0]
metadata

Metadata information about the text

Returns:Collection object with metadata about the text
Return type:Metadata
next

Get Next Passage

Return type:Passage
nextId

Shortcut for getting the following passage identifier

Return type:Reference
Returns:Following passage reference
parent

Parent Passage

Return type:Passage
parentId

Shortcut for getting the parent passage identifier

Return type:Reference
Returns:Following passage reference
prev

Get Previous Passage

Return type:Passage
prevId

Previous passage Identifier

Return type:Passage
Returns:Previous passage at same level
prevnext(resource)

Parse a resource to get the prev and next urn

Parameters:resource (etree._Element) – XML Resource
Returns:Tuple representing previous and next urn
Return type:(str, str)
reference
retriever

Retriever object used to query for more data

Return type:CitableTextServiceRetriever
siblingsId

Shortcut for getting the previous and next passage identifier

Return type:Reference
Returns:Following passage reference
text

String representation of the text

Returns:String representation of the text
Return type:text_type
urn

URN Identifier of the object

Return type:URN
xml

XML Representation of the Passage

Return type:lxml.etree._Element
Returns:XML element representing the passage

Collections

Metadata

class MyCapytain.resources.prototypes.metadata.Collection[source]

Bases: MyCapytain.common.constants.Exportable

Collection represents any resource’s metadata. It has members and parents

Variables:
  • properties – Properties of the collection
  • parents – Parent of the node from the direct parent to the highest ascendant
  • metadata – Metadata
  • DC_TITLE_KEY – Key representing the object title in the Metadata property
DC_TITLE_KEY = None
DEFAULT_EXPORT = None
EXPORT_TO = ['application/ld+json:DTS/NoParents', 'application/ld+json:DTS']
TYPE_URI = 'http://w3id.org/dts-ontology/collection'
descendants

Any descendant (no max level) of the collection’s item

Return type:[Collection]
export(output=None, **kwargs)

Export the collection item in the Mimetype required.

Parameters:output (str) – Mimetype to export to (Uses MyCapytain.common.utils.Mimetypes)
Returns:Object using a different representation
export_capacities

List Mimetypes that current object can export to

id

Identifier of the collection item

Return type:str
members

Children of the collection’s item

Return type:[Collection]
readable

Readable property should return elements where the element can be queried for getPassage / getReffs

readableDescendants

List of element available which are readable

Return type:[Collection]
title

Title of the collection Item

Return type:Metadatum

CTS inventory

class MyCapytain.resources.collections.cts.Citation(name=None, xpath=None, scope=None, refsDecl=None, child=None)[source]

Bases: MyCapytain.common.reference.Citation

Citation XML implementation for TextInventory

child

Child of a citation

Type:Citation or None
Example:Citation.name==poem would have a child Citation.name==line
escape = re.compile('(")')
fill(passage=None, xpath=None)[source]

Fill the xpath with given informations

Parameters:
  • passage (Reference or list or None. Can be list of None and not None) – Passage reference
  • xpath (Boolean) – If set to True, will return the replaced self.xpath value and not the whole self.refsDecl
Return type:

basestring

Returns:

Xpath to find the passage

citation = Citation(name="line", scope="/TEI/text/body/div/div[@n="?"]",xpath="//l[@n="?"]")
print(citation.fill(["1", None]))
# /TEI/text/body/div/div[@n='1']//l[@n]
print(citation.fill(None))
# /TEI/text/body/div/div[@n]//l[@n]
print(citation.fill(Reference("1.1"))
# /TEI/text/body/div/div[@n='1']//l[@n='1']
print(citation.fill("1", xpath=True)
# //l[@n='1']
static ingest(resource, element=None, xpath='ti:citation')[source]

Ingest xml to create a citation

Parameters:
  • resource – XML on which to do xpath
  • element – Element where the citation should be stored
  • xpath – XPath to use to retrieve citation
Returns:

Citation

isEmpty()[source]

Check if the citation has not been set

Returns:True if nothing was setup
Return type:bool
name

Type of the citation represented

Type:text_type
Example:Book, Chapter, Textpart, Section, Poem...
refsDecl

ResfDecl expression of the citation scheme

Return type:str
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.resources.collections.cts.Edition(resource=None, urn=None, parents=None)[source]

Create an edition subtyped Text object

class MyCapytain.resources.collections.cts.Text(**kwargs)[source]

Bases: MyCapytain.resources.prototypes.cts.inventory.Text

Represents a CTS Text

CTSMODEL = 'CTSCollection'
DC_TITLE_KEY = 'label'
DEFAULT_EXPORT = 'python/lxml'
EXPORT_TO = ['Capitains/ReadableText', 'python/lxml', 'text/xml:CTS']
TEXT_URI

Ontology URI of the text

Returns:CTS Ontology Edition or Translation object
Return type:str
TYPE_URI = 'http://w3id.org/dts-ontology/collection'
descendants

List of descendants

Return type:list
editions()[source]

Get all editions of the texts

Returns:List of editions
Return type:[Text]
export(output=None, **kwargs)

Export the collection item in the Mimetype required.

Parameters:output (str) – Mimetype to export to (Uses MyCapytain.common.utils.Mimetypes)
Returns:Object using a different representation
export_capacities

List Mimetypes that current object can export to

id
members
parse(resource)[source]

Parse a resource to feed the object

Parameters:resource (basestring or lxml.etree._Element) – An xml representation object
Returns:None
readable

Readable property should return elements where the element can be queried for getPassage / getReffs

Return type:bool
readableDescendants

List of element available which are readable

Return type:[Collection]
setResource(resource)

Set the object property resource

Parameters:resource (Any) – Resource representing the TextInventory
Return type:Any
Returns:Input resource
title

Title of the collection Item

Return type:Metadatum
translations(key=None)[source]

Get translations in given language

Parameters:key – Language ISO Code to filter on
Returns:
class MyCapytain.resources.collections.cts.TextGroup(**kwargs)[source]

Bases: MyCapytain.resources.prototypes.cts.inventory.TextGroup

Represents a CTS Textgroup in XML

Variables:
CTSMODEL = 'CTSCollection'
DC_TITLE_KEY = 'groupname'
DEFAULT_EXPORT = 'python/lxml'
EXPORT_TO = ['python/lxml', 'text/xml:CTS']
TYPE_URI = 'http://chs.harvard.edu/xmlns/cts/TextGroup'
descendants

Any descendant (no max level) of the collection’s item

Return type:[Collection]
export(output=None, **kwargs)

Export the collection item in the Mimetype required.

Parameters:output (str) – Mimetype to export to (Uses MyCapytain.common.utils.Mimetypes)
Returns:Object using a different representation
export_capacities

List Mimetypes that current object can export to

id
members
parse(resource)[source]

Parse a resource

Parameters:
  • resource – Element representing the textgroup
  • type – basestring or etree._Element
readable

Readable property should return elements where the element can be queried for getPassage / getReffs

readableDescendants

List of element available which are readable

Return type:[Collection]
setResource(resource)

Set the object property resource

Parameters:resource (Any) – Resource representing the TextInventory
Return type:Any
Returns:Input resource
title

Title of the collection Item

Return type:Metadatum
update(other)[source]

Merge two Textgroup Objects.

  • Original (left Object) keeps his parent.
  • Added document merges with work if it already exists
Parameters:other (TextGroup) – Textgroup object
Returns:Textgroup Object
Return type:TextGroup
class MyCapytain.resources.collections.cts.TextInventory(**kwargs)[source]

Bases: MyCapytain.resources.prototypes.cts.inventory.TextInventory

Represents a CTS Inventory file

Variables:
CTSMODEL = 'CTSCollection'
DC_TITLE_KEY = None
DEFAULT_EXPORT = 'python/lxml'
EXPORT_TO = ['python/lxml', 'text/xml:CTS']
TYPE_URI = 'http://chs.harvard.edu/xmlns/cts/TextInventory'
descendants

Any descendant (no max level) of the collection’s item

Return type:[Collection]
export(output=None, **kwargs)

Export the collection item in the Mimetype required.

Parameters:output (str) – Mimetype to export to (Uses MyCapytain.common.utils.Mimetypes)
Returns:Object using a different representation
export_capacities

List Mimetypes that current object can export to

id
members
parse(resource)[source]

Parse a resource

Parameters:
  • resource – Element representing the text inventory
  • type – basestring, etree._Element
readable

Readable property should return elements where the element can be queried for getPassage / getReffs

readableDescendants

List of element available which are readable

Return type:[Collection]
setResource(resource)

Set the object property resource

Parameters:resource (Any) – Resource representing the TextInventory
Return type:Any
Returns:Input resource
title

Title of the collection Item

Return type:Metadatum
MyCapytain.resources.collections.cts.Translation(resource=None, urn=None, parents=None)[source]

Create a translation subtyped Text object

class MyCapytain.resources.collections.cts.Work(**kwargs)[source]

Bases: MyCapytain.resources.prototypes.cts.inventory.Work

Represents a CTS Textgroup in XML

Variables:
CTSMODEL = 'CTSCollection'
DC_TITLE_KEY = 'title'
DEFAULT_EXPORT = 'python/lxml'
EXPORT_TO = ['python/lxml', 'text/xml:CTS']
TYPE_URI = 'http://chs.harvard.edu/xmlns/cts/Work'
descendants

Any descendant (no max level) of the collection’s item

Return type:[Collection]
export(output=None, **kwargs)

Export the collection item in the Mimetype required.

Parameters:output (str) – Mimetype to export to (Uses MyCapytain.common.utils.Mimetypes)
Returns:Object using a different representation
export_capacities

List Mimetypes that current object can export to

getLang(key=None)[source]

Find a translation with given language

Parameters:key (text_type) – Language to find
Return type:[Text]
Returns:List of availables translations
id
members
parse(resource)[source]

Parse a resource

Parameters:
  • resource – Element rerpresenting a work
  • type – basestring, etree._Element
readable
readableDescendants

List of element available which are readable

Return type:[Collection]
setResource(resource)

Set the object property resource

Parameters:resource (Any) – Resource representing the TextInventory
Return type:Any
Returns:Input resource
title

Title of the collection Item

Return type:Metadatum
update(other)[source]

Merge two Work Objects.

  • Original (left Object) keeps his parent.
  • Added document overwrite text if it already exists
Parameters:other (Work) – Work object
Returns:Work Object
Rtype Work:
MyCapytain.resources.collections.cts.xpathDict(xml, xpath, children, parents, **kwargs)[source]

Returns a default Dict given certain information

Parameters:
  • xml (etree) – An xml tree
  • xpath – XPath to find children
  • children (inventory.Resource) – Object identifying children
  • parents (tuple.<inventory.Resource>) – Tuple of parents
Return type:

collections.defaultdict.<basestring, inventory.Resource>

Returns:

Dictionary of children

CTS Inventory Prototypes

class MyCapytain.resources.prototypes.cts.inventory.CTSCollection(resource=None)[source]

Bases: MyCapytain.resources.prototypes.metadata.Collection

Resource represents any resource from the inventory

Parameters:resource (Any) – Resource representing the TextInventory
Variables:CTSMODEL – String Representation of the type of collection
CTSMODEL = 'CTSCollection'
DC_TITLE_KEY = None
DEFAULT_EXPORT = None
EXPORT_TO = ['application/ld+json:DTS/NoParents', 'application/ld+json:DTS']
TYPE_URI = 'http://w3id.org/dts-ontology/collection'
descendants

Any descendant (no max level) of the collection’s item

Return type:[Collection]
export(output=None, **kwargs)

Export the collection item in the Mimetype required.

Parameters:output (str) – Mimetype to export to (Uses MyCapytain.common.utils.Mimetypes)
Returns:Object using a different representation
export_capacities

List Mimetypes that current object can export to

id

Identifier of the collection item

Return type:str
members

Children of the collection’s item

Return type:[Collection]
parse(resource)[source]

Parse the object resource

Parameters:resource (Any) – Resource representing the TextInventory
Return type:List
readable

Readable property should return elements where the element can be queried for getPassage / getReffs

readableDescendants

List of element available which are readable

Return type:[Collection]
setResource(resource)[source]

Set the object property resource

Parameters:resource (Any) – Resource representing the TextInventory
Return type:Any
Returns:Input resource
title

Title of the collection Item

Return type:Metadatum
MyCapytain.resources.prototypes.cts.inventory.Edition(resource=None, urn=None, parents=None)[source]

Represents a CTS Edition

Parameters:
  • resource (Any) – Resource representing the TextInventory
  • urn (str) – Identifier of the Text
  • parents ([CTSCollection]) – Item parents of the current collection
class MyCapytain.resources.prototypes.cts.inventory.Text(resource=None, urn=None, parents=None, subtype='Edition')[source]

Bases: MyCapytain.resources.prototypes.cts.inventory.CTSCollection

Represents a CTS Text

Parameters:
  • resource (Any) – Resource representing the TextInventory
  • urn (URN) – Identifier of the Text
  • parents ([CTSCollection]) – Item parents of the current collection
  • subtype (str) – Subtype of the object (Edition, Translation)
Variables:
  • urn – URN Identifier
  • parents – List of ancestors, from parent to furthest
CTSMODEL = 'CTSCollection'
DC_TITLE_KEY = 'label'
DEFAULT_EXPORT = None
EXPORT_TO = ['application/ld+json:DTS/NoParents', 'application/ld+json:DTS']
TEXT_URI

Ontology URI of the text

Returns:CTS Ontology Edition or Translation object
Return type:str
TYPE_URI = 'http://w3id.org/dts-ontology/collection'
descendants
editions()[source]

Get all editions of the texts

Returns:List of editions
Return type:[Text]
export(output=None, **kwargs)

Export the collection item in the Mimetype required.

Parameters:output (str) – Mimetype to export to (Uses MyCapytain.common.utils.Mimetypes)
Returns:Object using a different representation
export_capacities

List Mimetypes that current object can export to

id
members
parse(resource)

Parse the object resource

Parameters:resource (Any) – Resource representing the TextInventory
Return type:List
readable
readableDescendants

List of element available which are readable

Return type:[Collection]
setResource(resource)

Set the object property resource

Parameters:resource (Any) – Resource representing the TextInventory
Return type:Any
Returns:Input resource
title

Title of the collection Item

Return type:Metadatum
translations(key=None)[source]

Get translations in given language

Parameters:key – Language ISO Code to filter on
Returns:
class MyCapytain.resources.prototypes.cts.inventory.TextGroup(resource=None, urn=None, parents=None)[source]

Bases: MyCapytain.resources.prototypes.cts.inventory.CTSCollection

Represents a CTS Textgroup

CTS TextGroup can be added to each other which would most likely happen if you take your data from multiple API or Textual repository. This works close to dictionary update in Python. See update

Parameters:
  • resource (Any) – Resource representing the TextInventory
  • urn (URN) – Identifier of the TextGroup
  • parents (Tuple.<TextInventory>) – List of parents for current object
Variables:
  • urn – URN Identifier
  • parents – List of ancestors, from parent to furthest
CTSMODEL = 'CTSCollection'
DC_TITLE_KEY = 'groupname'
DEFAULT_EXPORT = None
EXPORT_TO = ['application/ld+json:DTS/NoParents', 'application/ld+json:DTS']
TYPE_URI = 'http://chs.harvard.edu/xmlns/cts/TextGroup'
descendants

Any descendant (no max level) of the collection’s item

Return type:[Collection]
export(output=None, **kwargs)

Export the collection item in the Mimetype required.

Parameters:output (str) – Mimetype to export to (Uses MyCapytain.common.utils.Mimetypes)
Returns:Object using a different representation
export_capacities

List Mimetypes that current object can export to

id
members
parse(resource)

Parse the object resource

Parameters:resource (Any) – Resource representing the TextInventory
Return type:List
readable

Readable property should return elements where the element can be queried for getPassage / getReffs

readableDescendants

List of element available which are readable

Return type:[Collection]
setResource(resource)

Set the object property resource

Parameters:resource (Any) – Resource representing the TextInventory
Return type:Any
Returns:Input resource
title

Title of the collection Item

Return type:Metadatum
update(other)[source]

Merge two Textgroup Objects.

  • Original (left Object) keeps his parent.
  • Added document merges with work if it already exists
Parameters:other (TextGroup) – Textgroup object
Returns:Textgroup Object
Return type:TextGroup
class MyCapytain.resources.prototypes.cts.inventory.TextInventory(resource=None, name=None)[source]

Bases: MyCapytain.resources.prototypes.cts.inventory.CTSCollection

Initiate a TextInventory resource

Parameters:
  • resource (Any) – Resource representing the TextInventory
  • id (str) – Identifier of the TextInventory
CTSMODEL = 'CTSCollection'
DC_TITLE_KEY = None
DEFAULT_EXPORT = None
EXPORT_TO = ['application/ld+json:DTS/NoParents', 'application/ld+json:DTS']
TYPE_URI = 'http://chs.harvard.edu/xmlns/cts/TextInventory'
descendants

Any descendant (no max level) of the collection’s item

Return type:[Collection]
export(output=None, **kwargs)

Export the collection item in the Mimetype required.

Parameters:output (str) – Mimetype to export to (Uses MyCapytain.common.utils.Mimetypes)
Returns:Object using a different representation
export_capacities

List Mimetypes that current object can export to

id
members
parse(resource)

Parse the object resource

Parameters:resource (Any) – Resource representing the TextInventory
Return type:List
readable

Readable property should return elements where the element can be queried for getPassage / getReffs

readableDescendants

List of element available which are readable

Return type:[Collection]
setResource(resource)

Set the object property resource

Parameters:resource (Any) – Resource representing the TextInventory
Return type:Any
Returns:Input resource
title

Title of the collection Item

Return type:Metadatum
MyCapytain.resources.prototypes.cts.inventory.Translation(resource=None, urn=None, parents=None)[source]

Represents a CTS Translation

Parameters:
  • resource (Any) – Resource representing the TextInventory
  • urn (str) – Identifier of the Text
  • parents ([CTSCollection]) – Item parents of the current collection
class MyCapytain.resources.prototypes.cts.inventory.Work(resource=None, urn=None, parents=None)[source]

Bases: MyCapytain.resources.prototypes.cts.inventory.CTSCollection

Represents a CTS Work

CTS Work can be added to each other which would most likely happen if you take your data from multiple API or Textual repository. This works close to dictionary update in Python. See update

Parameters:
  • resource (Any) – Resource representing the TextInventory
  • urn (URN) – Identifier of the Work
  • parents (Tuple.<TextInventory>) – List of parents for current object
Variables:
  • urn – URN Identifier
  • parents – List of ancestors, from parent to furthest
CTSMODEL = 'CTSCollection'
DC_TITLE_KEY = 'title'
DEFAULT_EXPORT = None
EXPORT_TO = ['application/ld+json:DTS/NoParents', 'application/ld+json:DTS']
TYPE_URI = 'http://chs.harvard.edu/xmlns/cts/Work'
descendants

Any descendant (no max level) of the collection’s item

Return type:[Collection]
export(output=None, **kwargs)

Export the collection item in the Mimetype required.

Parameters:output (str) – Mimetype to export to (Uses MyCapytain.common.utils.Mimetypes)
Returns:Object using a different representation
export_capacities

List Mimetypes that current object can export to

getLang(key=None)[source]

Find a translation with given language

Parameters:key (text_type) – Language to find
Return type:[Text]
Returns:List of availables translations
id
members
parse(resource)

Parse the object resource

Parameters:resource (Any) – Resource representing the TextInventory
Return type:List
readable
readableDescendants

List of element available which are readable

Return type:[Collection]
setResource(resource)

Set the object property resource

Parameters:resource (Any) – Resource representing the TextInventory
Return type:Any
Returns:Input resource
title

Title of the collection Item

Return type:Metadatum
update(other)[source]

Merge two Work Objects.

  • Original (left Object) keeps his parent.
  • Added document overwrite text if it already exists
Parameters:other (Work) – Work object
Returns:Work Object
Rtype Work:

Text Prototypes

class MyCapytain.resources.prototypes.text.CTSNode(urn=None, **kwargs)[source]

Bases: MyCapytain.resources.prototypes.text.InteractiveTextualNode

Initiate a Resource object

Parameters:
  • urn (URN) – A URN identifier
  • metadata (Collection) – Collection Information about the Item
  • citation (Citation) – Citation system of the text
  • children ([str]) – Current node Children’s Identifier
  • parent (str) – Parent of the current node
  • siblings (str) – Previous and next node of the current node
  • depth (int) – Depth of the node in the global hierarchy of the text tree
  • resource – Resource used to navigate through the textual graph
Variables:

default_exclude – Default exclude for exports

DEFAULT_EXPORT = None
EXPORT_TO = []
about

Metadata information about the text

Returns:Collection object with metadata about the text
Rtype Collection:
 
childIds

Identifiers of children

Returns:Identifiers of children
Return type:[str]
children

Children Passages

Return type:iterator(Passage)
citation

Citation Object of the Text

Returns:Citation Object of the Text
Return type:Citation
default_exclude = []
depth

Depth of the node in the global hierarchy of the text tree

Return type:int
export(output=None, exclude=None, **kwargs)

Export the collection item in the Mimetype required.

..note:: If current implementation does not have special mimetypes, reuses default_export method

Parameters:
  • output (str) – Mimetype to export to (Uses MyCapytain.common.constants.Mimetypes)
  • exclude ([str]) – Information to exclude. Specific to implementations
Returns:

Object using a different representation

export_capacities

List Mimetypes that current object can export to

first

First Passage

Return type:Passage
firstId

First child of current Passage

Return type:str
Returns:First passage node Information
getLabel()[source]

Retrieve metadata about the text

Return type:Collection
Returns:Retrieve Label informations in a Collection format
getReffs(level=1, subreference=None)

Reference available at a given level

Parameters:
  • level (Int) – Depth required. If not set, should retrieve first encountered level (1 based)
  • passage (Reference) – Subreference (optional)
Return type:

[text_type]

Returns:

List of levels

getTextualNode(subreference)

Retrieve a passage and store it in the object

Parameters:subreference (str or Node or Reference) – Reference of the passage to retrieve
Return type:TextualNode
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, CitableText 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.text_type

Returns:

List of levels

id

Identifier of the text

Returns:Identifier of the text
Return type:text_type
last

Last Passage

Return type:Passage
lastId

Last child of current Passage

Return type:str
Returns:Last passage Node representation
metadata

Metadata information about the text

Returns:Collection object with metadata about the text
Return type:Metadata
next

Get Next Passage

Return type:Passage
nextId

Next Node (Sibling)

Return type:str
parent

Parent Passage

Return type:Passage
parentId

Parent Node

Return type:str
prev

Get Previous Passage

Return type:Passage
prevId

Previous Node (Sibling)

Return type:str
siblingsId

Siblings Node

Return type:(str, str)
text

String representation of the text

Returns:String representation of the text
Return type:text_type
urn

URN Identifier of the object

Return type:URN
class MyCapytain.resources.prototypes.text.CitableText(citation=None, metadata=None, **kwargs)[source]

Bases: MyCapytain.resources.prototypes.text.CTSNode

A CTS CitableText

DEFAULT_EXPORT = None
EXPORT_TO = []
about

Metadata information about the text

Returns:Collection object with metadata about the text
Rtype Collection:
 
childIds

Identifiers of children

Returns:Identifiers of children
Return type:[str]
children

Children Passages

Return type:iterator(Passage)
citation

Citation Object of the Text

Returns:Citation Object of the Text
Return type:Citation
default_exclude = []
depth

Depth of the node in the global hierarchy of the text tree

Return type:int
export(output=None, exclude=None, **kwargs)

Export the collection item in the Mimetype required.

..note:: If current implementation does not have special mimetypes, reuses default_export method

Parameters:
  • output (str) – Mimetype to export to (Uses MyCapytain.common.constants.Mimetypes)
  • exclude ([str]) – Information to exclude. Specific to implementations
Returns:

Object using a different representation

export_capacities

List Mimetypes that current object can export to

first

First Passage

Return type:Passage
firstId

First child of current Passage

Return type:str
Returns:First passage node Information
getLabel()

Retrieve metadata about the text

Return type:Collection
Returns:Retrieve Label informations in a Collection format
getReffs(level=1, subreference=None)

Reference available at a given level

Parameters:
  • level (Int) – Depth required. If not set, should retrieve first encountered level (1 based)
  • passage (Reference) – Subreference (optional)
Return type:

[text_type]

Returns:

List of levels

getTextualNode(subreference)

Retrieve a passage and store it in the object

Parameters:subreference (str or Node or Reference) – Reference of the passage to retrieve
Return type:TextualNode
Returns:Object representing the passage
Raises:TypeError when reference is not a list or a Reference
getValidReff(level=1, reference=None)

Given a resource, CitableText 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.text_type

Returns:

List of levels

id

Identifier of the text

Returns:Identifier of the text
Return type:text_type
last

Last Passage

Return type:Passage
lastId

Last child of current Passage

Return type:str
Returns:Last passage Node representation
metadata

Metadata information about the text

Returns:Collection object with metadata about the text
Return type:Metadata
next

Get Next Passage

Return type:Passage
nextId

Next Node (Sibling)

Return type:str
parent

Parent Passage

Return type:Passage
parentId

Parent Node

Return type:str
prev

Get Previous Passage

Return type:Passage
prevId

Previous Node (Sibling)

Return type:str
reffs

Get all valid reffs for every part of the CitableText

Return type:[str]
siblingsId

Siblings Node

Return type:(str, str)
text

String representation of the text

Returns:String representation of the text
Return type:text_type
urn

URN Identifier of the object

Return type:URN
class MyCapytain.resources.prototypes.text.InteractiveTextualNode(identifier=None, **kwargs)[source]

Bases: MyCapytain.resources.prototypes.text.TextualGraph

Node representing a text passage.

Parameters:
  • identifier (str) – Identifier of the text
  • metadata (Collection) – Collection Information about the Item
  • citation (Citation) – Citation system of the text
  • children ([str]) – Current node Children’s Identifier
  • parent (str) – Parent of the current node
  • siblings (str) – Previous and next node of the current node
  • depth (int) – Depth of the node in the global hierarchy of the text tree
  • resource – Resource used to navigate through the textual graph
Variables:

default_exclude – Default exclude for exports

DEFAULT_EXPORT = None
EXPORT_TO = []
about

Metadata information about the text

Returns:Collection object with metadata about the text
Rtype Collection:
 
childIds

Identifiers of children

Returns:Identifiers of children
Return type:[str]
children

Children Passages

Return type:iterator(Passage)
citation

Citation Object of the Text

Returns:Citation Object of the Text
Return type:Citation
default_exclude = []
depth

Depth of the node in the global hierarchy of the text tree

Return type:int
export(output=None, exclude=None, **kwargs)

Export the collection item in the Mimetype required.

..note:: If current implementation does not have special mimetypes, reuses default_export method

Parameters:
  • output (str) – Mimetype to export to (Uses MyCapytain.common.constants.Mimetypes)
  • exclude ([str]) – Information to exclude. Specific to implementations
Returns:

Object using a different representation

export_capacities

List Mimetypes that current object can export to

first

First Passage

Return type:Passage
firstId

First child of current Passage

Return type:str
Returns:First passage node Information
getReffs(level=1, subreference=None)

Reference available at a given level

Parameters:
  • level (Int) – Depth required. If not set, should retrieve first encountered level (1 based)
  • passage (Reference) – Subreference (optional)
Return type:

[text_type]

Returns:

List of levels

getTextualNode(subreference)

Retrieve a passage and store it in the object

Parameters:subreference (str or Node or Reference) – Reference of the passage to retrieve
Return type:TextualNode
Returns:Object representing the passage
Raises:TypeError when reference is not a list or a Reference
id

Identifier of the text

Returns:Identifier of the text
Return type:text_type
last

Last Passage

Return type:Passage
lastId

Last child of current Passage

Return type:str
Returns:Last passage Node representation
metadata

Metadata information about the text

Returns:Collection object with metadata about the text
Return type:Metadata
next

Get Next Passage

Return type:Passage
nextId

Next Node (Sibling)

Return type:str
parent

Parent Passage

Return type:Passage
parentId

Parent Node

Return type:str
prev

Get Previous Passage

Return type:Passage
prevId

Previous Node (Sibling)

Return type:str
siblingsId

Siblings Node

Return type:(str, str)
text

String representation of the text

Returns:String representation of the text
Return type:text_type
class MyCapytain.resources.prototypes.text.Passage(**kwargs)[source]

Bases: MyCapytain.resources.prototypes.text.CTSNode

Passage objects possess metadata informations

Parameters:
  • urn (URN) – A URN identifier
  • metadata (Collection) – Collection Information about the Item
  • citation (Citation) – Citation system of the text
  • children ([str]) – Current node Children’s Identifier
  • parent (str) – Parent of the current node
  • siblings (str) – Previous and next node of the current node
  • depth (int) – Depth of the node in the global hierarchy of the text tree
  • resource – Resource used to navigate through the textual graph
Variables:

default_exclude – Default exclude for exports

DEFAULT_EXPORT = None
EXPORT_TO = []
about

Metadata information about the text

Returns:Collection object with metadata about the text
Rtype Collection:
 
childIds

Identifiers of children

Returns:Identifiers of children
Return type:[str]
children

Children Passages

Return type:iterator(Passage)
citation

Citation Object of the Text

Returns:Citation Object of the Text
Return type:Citation
default_exclude = []
depth

Depth of the node in the global hierarchy of the text tree

Return type:int
export(output=None, exclude=None, **kwargs)

Export the collection item in the Mimetype required.

..note:: If current implementation does not have special mimetypes, reuses default_export method

Parameters:
  • output (str) – Mimetype to export to (Uses MyCapytain.common.constants.Mimetypes)
  • exclude ([str]) – Information to exclude. Specific to implementations
Returns:

Object using a different representation

export_capacities

List Mimetypes that current object can export to

first

First Passage

Return type:Passage
firstId

First child of current Passage

Return type:str
Returns:First passage node Information
getLabel()

Retrieve metadata about the text

Return type:Collection
Returns:Retrieve Label informations in a Collection format
getReffs(level=1, subreference=None)

Reference available at a given level

Parameters:
  • level (Int) – Depth required. If not set, should retrieve first encountered level (1 based)
  • passage (Reference) – Subreference (optional)
Return type:

[text_type]

Returns:

List of levels

getTextualNode(subreference)

Retrieve a passage and store it in the object

Parameters:subreference (str or Node or Reference) – Reference of the passage to retrieve
Return type:TextualNode
Returns:Object representing the passage
Raises:TypeError when reference is not a list or a Reference
getValidReff(level=1, reference=None)

Given a resource, CitableText 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.text_type

Returns:

List of levels

id

Identifier of the text

Returns:Identifier of the text
Return type:text_type
last

Last Passage

Return type:Passage
lastId

Last child of current Passage

Return type:str
Returns:Last passage Node representation
metadata

Metadata information about the text

Returns:Collection object with metadata about the text
Return type:Metadata
next

Get Next Passage

Return type:Passage
nextId

Next Node (Sibling)

Return type:str
parent

Parent Passage

Return type:Passage
parentId

Parent Node

Return type:str
prev

Get Previous Passage

Return type:Passage
prevId

Previous Node (Sibling)

Return type:str
reference
siblingsId

Siblings Node

Return type:(str, str)
text

String representation of the text

Returns:String representation of the text
Return type:text_type
urn

URN Identifier of the object

Return type:URN
class MyCapytain.resources.prototypes.text.TextualElement(identifier=None, metadata=None)[source]

Bases: MyCapytain.common.constants.Exportable

Node representing a text passage.

Parameters:
  • identifier (str) – Identifier of the text
  • metadata (Collection) – Collection Information about the Item
Variables:

default_exclude – Default exclude for exports

DEFAULT_EXPORT = None
EXPORT_TO = []
about

Metadata information about the text

Returns:Collection object with metadata about the text
Rtype Collection:
 
default_exclude = []
export(output=None, exclude=None, **kwargs)[source]

Export the collection item in the Mimetype required.

..note:: If current implementation does not have special mimetypes, reuses default_export method

Parameters:
  • output (str) – Mimetype to export to (Uses MyCapytain.common.constants.Mimetypes)
  • exclude ([str]) – Information to exclude. Specific to implementations
Returns:

Object using a different representation

export_capacities

List Mimetypes that current object can export to

id

Identifier of the text

Returns:Identifier of the text
Return type:text_type
metadata

Metadata information about the text

Returns:Collection object with metadata about the text
Return type:Metadata
text

String representation of the text

Returns:String representation of the text
Return type:text_type
class MyCapytain.resources.prototypes.text.TextualGraph(identifier=None, **kwargs)[source]

Bases: MyCapytain.resources.prototypes.text.TextualNode

Node representing a text passage.

Parameters:
  • identifier (str) – Identifier of the text
  • metadata (Collection) – Collection Information about the Item
  • citation (Citation) – Citation system of the text
  • children ([str]) – Current node Children’s Identifier
  • parent (str) – Parent of the current node
  • siblings (str) – Previous and next node of the current node
  • depth (int) – Depth of the node in the global hierarchy of the text tree
  • resource – Resource used to navigate through the textual graph
Variables:

default_exclude – Default exclude for exports

DEFAULT_EXPORT = None
EXPORT_TO = []
about

Metadata information about the text

Returns:Collection object with metadata about the text
Rtype Collection:
 
childIds

Children Node

Return type:[str]
citation

Citation Object of the Text

Returns:Citation Object of the Text
Return type:Citation
default_exclude = []
depth

Depth of the node in the global hierarchy of the text tree

Return type:int
export(output=None, exclude=None, **kwargs)

Export the collection item in the Mimetype required.

..note:: If current implementation does not have special mimetypes, reuses default_export method

Parameters:
  • output (str) – Mimetype to export to (Uses MyCapytain.common.constants.Mimetypes)
  • exclude ([str]) – Information to exclude. Specific to implementations
Returns:

Object using a different representation

export_capacities

List Mimetypes that current object can export to

firstId

First child Node

Return type:str
getReffs(level=1, subreference=None)[source]

Reference available at a given level

Parameters:
  • level (Int) – Depth required. If not set, should retrieve first encountered level (1 based)
  • passage (Reference) – Subreference (optional)
Return type:

[text_type]

Returns:

List of levels

getTextualNode(subreference)[source]

Retrieve a passage and store it in the object

Parameters:subreference (str or Node or Reference) – Reference of the passage to retrieve
Return type:TextualNode
Returns:Object representing the passage
Raises:TypeError when reference is not a list or a Reference
id

Identifier of the text

Returns:Identifier of the text
Return type:text_type
lastId

Last child Node

Return type:str
metadata

Metadata information about the text

Returns:Collection object with metadata about the text
Return type:Metadata
nextId

Next Node (Sibling)

Return type:str
parentId

Parent Node

Return type:str
prevId

Previous Node (Sibling)

Return type:str
siblingsId

Siblings Node

Return type:(str, str)
text

String representation of the text

Returns:String representation of the text
Return type:text_type
class MyCapytain.resources.prototypes.text.TextualNode(identifier=None, citation=None, **kwargs)[source]

Bases: MyCapytain.resources.prototypes.text.TextualElement, MyCapytain.common.reference.NodeId

Node representing a text passage.

Parameters:
  • identifier (str) – Identifier of the text
  • metadata (Collection) – Collection Information about the Item
  • citation (Citation) – Citation system of the text
  • children ([str]) – Current node Children’s Identifier
  • parent (str) – Parent of the current node
  • siblings (str) – Previous and next node of the current node
  • depth (int) – Depth of the node in the global hierarchy of the text tree
Variables:

default_exclude – Default exclude for exports

DEFAULT_EXPORT = None
EXPORT_TO = []
about

Metadata information about the text

Returns:Collection object with metadata about the text
Rtype Collection:
 
childIds

Children Node

Return type:[str]
citation

Citation Object of the Text

Returns:Citation Object of the Text
Return type:Citation
default_exclude = []
depth

Depth of the node in the global hierarchy of the text tree

Return type:int
export(output=None, exclude=None, **kwargs)

Export the collection item in the Mimetype required.

..note:: If current implementation does not have special mimetypes, reuses default_export method

Parameters:
  • output (str) – Mimetype to export to (Uses MyCapytain.common.constants.Mimetypes)
  • exclude ([str]) – Information to exclude. Specific to implementations
Returns:

Object using a different representation

export_capacities

List Mimetypes that current object can export to

firstId

First child Node

Return type:str
id

Identifier of the text

Returns:Identifier of the text
Return type:text_type
lastId

Last child Node

Return type:str
metadata

Metadata information about the text

Returns:Collection object with metadata about the text
Return type:Metadata
nextId

Next Node (Sibling)

Return type:str
parentId

Parent Node

Return type:str
prevId

Previous Node (Sibling)

Return type:str
siblingsId

Siblings Node

Return type:(str, str)
text

String representation of the text

Returns:String representation of the text
Return type:text_type