ecoxipy.pyxom.indexing - Indexing PyXOM Structures

This package is a foundation for indexing ecoxipy.pyxom structures. The abstract base class Indexer establishes an interface for indexing PyXOM structures.

Two mapping implementations are provided to serve as indexes:

• UniqueValueIndex allows only one value per key.
• MultiValueIndex holds a set of values per key.

For easier implementation of indexers there are some abstract base classes:

• Indexer.new_index() and Indexer.register() are implemented by UniqueValueIndexer and MultiValueIndexer, which use UniqueValueIndex or MultiValueIndex respectively.
• AttributeValueIndexer in contrast implements Indexer.node_predicate() and Indexer.extract_items() to index attributes by their value.

Two ready-to-use indexer implementations are provided:

• ElementByUniqueAttributeValueIndexer indexes ecoxipy.pyxom.Element instances under the value of a specific attribute they have, e.g. xml:id or id.
• To index ecoxipy.pyxom.Element instances by their name use ElementsByNameIndexer.

The IndexDescriptor makes index access and deletion more convenient.

Examples

First we create a test document:

>>> from ecoxipy import MarkupBuilder
>>> b = MarkupBuilder()
>>> test = b.test(
...     b.foo(id='b'),
...     b.foo('Foo Bar', no_id='d'),
...     b.bar(id='c'),
...     id='a'
... )

Here is an example how to use ElementByUniqueAttributeValueIndexer:

>>> indexer = ElementByUniqueAttributeValueIndexer()
>>> index = indexer(test)
>>> len(index) == 3
True
>>> u'a' in index and index[u'a'] is test
True
>>> index[u'b'] is test[0] and index[u'c'] is test[-1]
True
>>> u'd' in index
False
>>> index = indexer(b[:](b.test0(id='test'), b.test1(id='test')))
Traceback (most recent call last):
ValueError: A value for key "test" is already registered

And this is how ElementsByNameIndexer works:

>>> indexer = ElementsByNameIndexer()
>>> index = indexer(test)
>>> len(index) == 3
True
>>> u'test' in index
True
>>> list(index[u'test'])[0] is test
True
>>> u'bar' in index
True
>>> list(index[u'bar'])[0] is test[-1]
True
>>> foo_elements = set(index[u'foo'])
>>> len(foo_elements) == 2
True
>>> foo_elements == {test[0], test[1]}
True
>>> u'unknown' in index
False

Abstract Base Classes

class ecoxipy.pyxom.indexing.Indexer

Abstract base class for ecoxipy.pyxom stucture indexers.

__call__(root_node)

Indexes a ecoxipy.pyxom.XMLNode tree.

Parameters:root_node (ecoxipy.pyxom.ContainerNode) – the node to start indexing on Returns:an index data structure

The following is done for indexing:

1. new_index() is called to create the index data structure.
2. For root_node and its descendants on which node_predicate() returns True:
   1. A single item or an iterator of items is obtained by calling extract_items().
   2. The single item or each item of the iterator is registered on the index by calling register().
3. The index data structure ist returned.

new_index()

Creates and returns an index data structure.

node_predicate(node)

Determines if node should be used to extract index items from.

Parameters:node (ecoxipy.pyxom.XMLNode) – the node to test Returns:True if node should be used to extract index items, False otherwise.

extract_items(node)

Extracts index items from node. An index item is a 2-tuple() with the key as first item and value as second item.

Parameters:node (ecoxipy.pyxom.XMLNode) – the node to extract index items from Returns:A single index item or an iterator of index items.

register(index, key, value)

Registers value under key on index.

Parameters:

• index – the index data structure
• key – the identifier for value
• value – the value registered under key

class ecoxipy.pyxom.indexing.UniqueValueIndexer

An abstract Indexer base class which uses UniqueValueIndex as the index.

new_index()

Creates and returns an UniqueValueIndex instance.

register(index, key, node)

Registers value under key by calling register(key, value) on index.

class ecoxipy.pyxom.indexing.MultiValueIndexer

An abstract Indexer base class which uses MultiValueIndex as the index.

new_index()

Creates and returns a MultiValueIndex instance.

class ecoxipy.pyxom.indexing.AttributeValueIndexer(attribute_name)

An abstract Indexer base class which selects ecoxipy.pyxom.Element nodes that contain an ecoxipy.pyxom.Attribute having a name equal to attribute_name. The index items are those attributes, identified by their value.

Parameters:attribute_name – defines attribute_name

attribute_name

The name of the attributes whose values define the indexing keys.

node_predicate(node)

Returns True if node is an ecoxipy.pyxom.Element instance and has an attribute with name attribute_name, False otherwise.

extract_items(node)

Returns a 2-tuple() with the value of the attribute with name attribute_name on node as first item and the attribute itself as second item.

Indexing-related Classes

class ecoxipy.pyxom.indexing.ElementByUniqueAttributeValueIndexer(attribute_name=u'id')

An Indexer implementation creating an UniqueValueIndex of elements having an attribute with the name equal to attribute_name identified by the value of that attribute.

Parameters:attribute_name – defines AttributeValueIndexer.attribute_name

extract_items(node)

Returns a 2-tuple() with the value of the attribute with name AttributeValueIndexer.attribute_name on node as first item and node as second item.

class ecoxipy.pyxom.indexing.ElementsByNameIndexer

An Indexer implementation creating an MultiValueIndex of elements identified by their name.

node_predicate(node)

Returns True if node is an ecoxipy.pyxom.Element instance, False otherwise.

extract_items(node)

Returns a 2-tuple() with the name of node as first item and node as second item.

class ecoxipy.pyxom.indexing.UniqueValueIndex

A read-only-semantics mapping enforcing only one value is registered under a specific key. Entries can be set using register(). Value access and containment tests convert the key to a Unicode string first.

register(key, value)

Set the entry for key to value.

Parameters:

• key (Unicode string) – the identifier
• value – the entry’s value

Raises ValueError:  

if a value for key is already registered.

class ecoxipy.pyxom.indexing.MultiValueIndex

A read-only-semantics mapping holding a set of values under a specific key. Values can be added to an key’s set using register(). Value access and containment tests convert the key to a Unicode string first.

register(key, value)

Add value to the set identified by key.

Parameters:

• key (Unicode string) – the identifier
• value – the entry’s value

class ecoxipy.pyxom.indexing.NamespaceIndex

An index holding XML namespace information.

Nodes are retrieved by calling an instance.

register(namespace_uri, local_name, node)

Registers the node with the namespace information.

Parameters:

• namespace_uri – The namespace URI of the node.
• local_name – The local name of the node.
• node – The node to register.

class ecoxipy.pyxom.indexing.NamespaceIndexer

new_index()

node_predicate(node)

extract_items(node)

register(index, key, value)

class ecoxipy.pyxom.indexing.IndexDescriptor(indexer)

A descriptor handling index creation using a given Indexer.

Parameters:indexer (Indexer.) – The indexer to use for indexing, this becomes indexer.

On value retrieval this descriptor returns itself on classes, on instances it returns an index created by the indexer. If such does not yet exist, first a new one is created.

Attribute setting is not allowed by the descriptor. Deletion deletes the index for the instance.

Important: This class does not hold track of changes in the indexed structures for performance reasons. It is the responsibility of using code to ensure the index is deleted after an instance is modified.

This descriptor does not modify the indexed instance, instead it holds a weakref.WeakValueDictionary, mapping instance IDs (as generated by id()) to the generated index for the instance.

indexer

The Indexer instance used for index creation.