You can extract u-forms from a hierarchical index using the code in MAYA/utils/indexing/hier_index.py
To start with, create a hierarchical index reader object as follows:
my_idx = hier_index.HIndexReader(<REPOSITORY>, <ROOT_UUID>)
Child nodes of a hierarchical index node are given by the attribute idx. These are retrieved by the API call <READER>.getChildren(). An optional argument is the path through the index, which is a list of strings. To get the u-form for the childe node, the API extends the parent UUID with the child's identifier using the function _extenduuid. This enables the index reader to find child nodes given the parent node and the contents of the idx attribute.
Some factors that may lead to confusion include:
-
The actual root of the index is given by the root UUID concatenated with 00 (i.e., chr(0). This is because the intention of the original design was that the official root UUID be used to keep metadata about the index using the [roles] system. Forcing someone to create new roles every time they create a new data structure is nowadays regarded as a bad idea. We're learning.
-
The right extension procedure is not entirely transparent: it involves encoding the path as a UTF8 expression and infixing some length information, to make sure you can't accidentally create the same UUID in different ways. Again, this process is now deprecated, 'manufactured' UUIDs of this nature are generally a bad idea.
Once you've navigated the tree down to its leaf nodes, the actual data items in the hierarchical index are usually given by the members attribute of a standard Collection u-form. For example, using the root of the main index of world pupolated places ~fd000efddada14, and the path ['us', 'pa', 'allegheny county', 'pi'], you can construct an index node by creating the index pop_places_idx = hier_index.HIndexReader(<REPOSITORY>, uuid._('~fd000efddada14') and issuing the the API call pop_places_index.getNode(['us', 'pa', 'allegheny county', 'pi']). This returns the (somewhat lengthy) UUID ~fd000efddada140002757302706110616c6c656768656e7920636f756e7479027069, andf if you construct this in a uform browser, you'll see that it does contain populated places in Allegheny County beginning with the letters 'pi'.
