Citation refactoring

[PonteIneptique]

Currently on https://github.com/Capitains/MyCapytain/tree/dts-retriever/MyCapytain/common/reference , I have started refactoring CTS Focused object. In this context, the original objects will retain their CTS specificity.

I have not changed the basic sense of most citations, keep in mind one of the objective is to prepare the arrival of the new guidelines : https://github.com/Capitains/guidelines#texts

I would really like to gather feedback on the current BaseCitation and if you have any wishes regarding these objects.

• New Generic / Prototype CitationSetObject
  • New .match(passageId) function
• New Generic / Prototype Citation Object
  • New .children Property
  • New .depth property (Not ported to CTS Citation object yet)
  • New meaning of .__len__() magic method
• New .root and is_root properties to link back to the citation set (for match implementations)
• Guidelines / CTS Citation Object
  • Implementation of the .match(passageId) method

[balmas]

I think this makes sense. Certainly having a base citation class so that we can have citations that are not CTS specific is important.

I'm not sure I understand how the match function on a citation would be used. If you already have a citation and you pass it a passageId to match, is it a test to see if the citation matches or does it find the child of the citation that matches?

[PonteIneptique]

So, one of the thing that will be introduced is also a .root property or a CitationSet object and property that will allow .match() to really work.
For CTS it's straight forward : .match("1.2.3") will go to citation level 3, for the new guidelines (which will be regexp based), it will be a little more useful.

[PonteIneptique]

I updated the list of changes in the main commit and you can find a test of the .match() property with description in

MyCapytain/tests/common/test_reference/test_capitains_cts.py

Lines 381 to 420 in 9c666ff

	def test_ingest_and_match(self):
	""" Ensure matching and parsing XML works correctly """
	xml = xmlparser("""<TEI xmlns="http://www.tei-c.org/ns/1.0">
	<refsDecl n="CTS">
	<cRefPattern n="line"
	matchPattern="(\w+).(\w+).(\w+)"
	replacementPattern="#xpath(/tei:TEI/tei:text/tei:body/tei:div/tei:div[@n='$1']/tei:div[@n='$2']/tei:l[@n='$3'])">
	<p>This pointer pattern extracts book and poem and line</p>
	</cRefPattern>
	<cRefPattern n="poem"
	matchPattern="(\w+).(\w+)"
	replacementPattern="#xpath(/tei:TEI/tei:text/tei:body/tei:div/tei:div[@n='$1']/tei:div[@n='$2'])">
	<p>This pointer pattern extracts book and poem</p>
	</cRefPattern>
	<cRefPattern n="book"
	matchPattern="(\w+)"
	replacementPattern="#xpath(/tei:TEI/tei:text/tei:body/tei:div/tei:div[@n='$1'])">
	<p>This pointer pattern extracts book</p>
	</cRefPattern>
	</refsDecl>
	</TEI>""")
	citation = Citation.ingest(xml)
	# The citation that should be returned is the root
	self.assertEqual(citation.name, "book", "Name should have been parsed")
	self.assertEqual(citation.child.name, "poem", "Name of child should have been parsed")
	self.assertEqual(citation.child.child.name, "line", "Name of descendants should have been parsed")
	self.assertEqual(citation.is_root, True, "Root should be true on root")
	self.assertEqual(citation.match("1.2"), citation.child, "Matching should make use of root matching")
	self.assertEqual(citation.match("1.2.4"), citation.child.child, "Matching should make use of root matching")
	self.assertEqual(citation.match("1"), citation, "Matching should make use of root matching")
	self.assertEqual(citation.child.match("1.2").name, "poem", "Matching should retrieve poem at 2nd level")
	self.assertEqual(citation.child.match("1.2.4").name, "line", "Matching should retrieve line at 3rd level")
	self.assertEqual(citation.child.match("1").name, "book", "Matching retrieve book at 1st level")
	citation = citation.child
	self.assertEqual(citation.child.match("1.2").name, "poem", "Matching should retrieve poem at 2nd level")
	self.assertEqual(citation.child.match("1.2.4").name, "line", "Matching should retrieve line at 3rd level")
	self.assertEqual(citation.child.match("1").name, "book", "Matching retrieve book at 1st level")

[balmas]

ohhh. I understand now. I think maybe the name "match" is what threw me off. I was thinking of it from the regex meaning of match.

[PonteIneptique]

This will actually be the case for new citation object that will be created for the new guidelines. :)

[PonteIneptique]

Adding a list of breaking change from : debe1a1

• CitationSet.is_root -> CitationSet.is_root() # Keep in check with other practices
• BaseCitation.is_empty() now checks if the object has children
• BaseCitation.is_set() checks if objects have their properties set
• cts.Citation.isEmpty() old behaviour is now in .is_set() and has been reversed in meaning
  • Old system would check if the CTS Citation was not set, old code such as
    if citation.isEmpty() should be moved to if citation.is_set()

I am thinking to change the .depth() behaviour to __len()__ and the current __len()__ behaviour to .count() so that citation[len(citation)-1] == citation[-1] which would make sense.

[PonteIneptique]

Pining @mromanello and @jtauber as they are user of the APIs who probably make use of this.