Cumbersome usage of terminology

Inizia tracciando i punti di ingresso di Document e Section mostrati negli esempi: repository, get_terminology_equivalent, merge e la costruzione di Section. Confronta i workflow dell’intero documento e di una Section autonoma, quindi chiarisci l’API prevista e i criteri di accettazione per rendere meno macchinoso l’uso della terminologia.

While preparing the new documentation I stumbled upon the functionality of terminology for Document and Section objects. Let me demonstrate the cumbersome aspects of the repository functionality for integrating terminologies via the following example (performed in odml v1.2):

import odml

# define the G-Node repo
repo_doc = 'http://portal.g-node.org/odml/terminologies/v1.0/terminologies.xml'

# doc1 should be the Document I would like to create by using terminologies of the G-Node repo
doc1 = odml.Document('WantedDoc', repository=repo_doc)

# doc1 is now an empty Document with the G-Node repository
print(doc1)
# output: None by WantedDoc (0 sections)>

# to actually use the terminologies provided via the repository,
# to include an Event section with the provided terminology
# I now have to generate secondary objects

# A: for example, via another Document
doc2 = doc1.get_terminology_equivalent()
# output: Document containing all Sections that are provided as terminologies via the G-Node repo
# <Doc None by None (54 sections)>
# (note that this will currently give a lot of warnings, 
#  since the terminologies are not yet updated to the recent changes of odML)
doc1.append(odml.Section('MyEvent1', type='whatever'))
doc1.sections['MyEvent1'].merge(doc2.sections['Event'])

# B: via creating and appending a Section which has a type equivalent terminology in the G-Node repo
doc1.append(odml.Section('MyEvent2', type='event'))
ev_sec_a = doc1.sections['MyEvent2'].get_terminology_equivalent()
# output: first Section (with children) occurring in the term. of the G-Node repo with Section type 'event'
# <Section Event[event] (0)>
doc1.sections['MyEvent2'].merge(ev_sec_a)

# NOTE: 
# that for A the Section type is irrelevant, because the user actively selects a Section 
# from the complete terminology tree of the given repo
# for B, the terminology of the wanted Section is AUTOMATICALLY extracted from the repo
# by matching the Section types

# B also works for a standalone Section, but defining a Section specific repo is only indirectly possible:
repo_sec = 'http://portal.g-node.org/odml/terminologies/v1.0/event/event.xml'
# my_ev_sec = odml.Section('MyEvent3', type='event', repository=repo_sec) 
# -> will give a TypeError: __init__() got an unexpected keyword argument 'repository'
# but the following is possible:
my_ev_sec = odml.Section('MyEvent3', type='event')
my_ev_sec.repository = repo_sec
# and then follow B to use the repository functionality 
ev_sec_b = my_ev_sec.get_terminology_equivalent()
doc1.append(ev_sec_b.clone())
# will append a clone of the Section with the extracted terminology <Section Event[event] (0)> to doc1