UDDF

The kenozooid.uddf module provides support for parsing, searching and manipulation of data stored in UDDF files.

The functions implemented in this module can be divided into the following categories

• XML nodes functions

• generic XML data searching and manipulation functions

• functions for searching and manipulation of diving specific data

Searching functions use XPath expressions (queries) to find data. Each tag name in an query should be prefixed with ‘uddf:’ string to indicate UDDF namespace, i.e. ‘uddf:diver’, ‘uddf:waypoint’ - appropriate namespace mapping for this prefix is defined for each XPath call.

The result of parsing or search of data is usually iterator of XML nodes or data records (named tuples in Python terms).

Module lxml is used for XML parsing and querying with XPath. Full capabilities of underlying libxml2 library is used by design. The ElementTree XML data model is used for XML nodes.

XML Nodes Parsing, Searching and Manipulation

kenozooid.uddf.XPath(*args, **kwargs)

XPath query constructor for UDDF data.

Use uddf prefix to create a query, i.e.:

XPath('uddf:informationbeforedive/uddf:datetime/text()')

kenozooid.uddf.find(f, query, **params)

Find XML nodes in UDDF file using XPath query.

UDDF file can be a file name, file object, URL and basically everything what is supported by lxml library.

File to parse can be a file name ending with ‘.bz2’. It is treated as file compressed with bzip2.

Parameters

f

UDDF file to parse.

query

XPath expression or XPath object.

params

XPath query parameters.

See also

XPath(), parse()

kenozooid.uddf.parse(f, ver_check=True)

Parse XML file and return document object.

File to parse can be anything supported by lxml library.

If file to parse is file name and ends with ‘.bz2’, then it is treated as file compressed with bzip2.

Parameters

f

File to parse.

ver_check

Check version of UDDF file.

kenozooid.uddf.xp(node, query)

Find items with XPath query.

The query is performed using UDDF namespace.

Iterator of items (strings, nodes) found by query is returned.

Parameters

node

Document node or query starting node.

query

XPath query.

See also

lxml.etree.Element.xpath

kenozooid.uddf.xp_first(node, query)

Get first element found with XPath query.

The query is performed using UDDF namespace.

First element is returned or None if it is not found.

Parameters

node

Document node or query starting node.

query

XPath query.

See also

lxml.etree.Element.xpath

kenozooid.uddf.xp_last(node, query)

Get last element found with XPath query.

The query is performed using UDDF namespace.

Last element is returned or None if it is not found.

Parameters

node

Document node or query starting node.

query

XPath query.

See also

lxml.etree.Element.xpath

kenozooid.uddf.create_node(path, parent=None, append=True)

TODO: get rid of parent, does not make sense

Create a hierarchy of nodes using XML nodes path specification.

Path is a string of node names separated by slash character, i.e. a/b/c creates:

<a><b><c/></b><a>

If parent node is specified and some part of node hierarchy already exists then only non-existant nodes are created, i.e. if parent is ‘x’ node in

<x><y/></x>

then path ‘x/z’ modifies XML document as follows

<x><y/><z/></x>

Parameters

path

Hierarchy of nodes.

parent

Optional parent node.

kenozooid.uddf.set_data(node, queries, formatters=None, **data)

Set data of nodes or attributes using XPath queries relative to specified XML node.

The data values are converted to string with formatters functions.

Parameters

node

XML node.

queries

Path-like expressions of XML structure to be created.

formatters

Data formatters.

data

Data values to be set within XML document.

kenozooid.uddf.save(doc, fout, validate=True)

Save UDDF XML data into a file.

If output file is file name ending with ‘.bz2’, then it is compressed with bzip2.

The UDDF XML data can be ElementTree XML object or iterable of strings.

If output file exists then backup file with .bak extension is created.

Parameters

doc

UDDF XML data.

fout

Output file.

validate

Validate UDDF file after saving if True.

class kenozooid.uddf.NodeCopier(doc)

UDDF dcument node copier.

See NodeCopier.copy() for details.

Attributes

doc

The target document.

doc_ids

The cache of target document ids.

copy(node, target)

Copy node from UDDF document to target node in destination UDDF document. Target node becomes parent of node to be copied.

The copying works under following assumptions

• whole node is being copied including its descendants

• node is not copied if it has id and id already exists in the target

• if copied nodes reference non-descendant nodes and they do _not_ exist in destination document, then referencing nodes are _removed_

• if, due to node removal, its parent node becomes empty, then parent is removed, too

Copy of the node is returned.

Parameters

node

Node to copy.

target

The future parent of the copied node.

Generic Data Access and Manipulation

• find_data

Dive Data Specific Functions

• reorder

• dive

• buddy

• dive sites

• dc