xmlfesatools

Python library with tools for analysis of FESA XML files

Usage: from pylib.fesa import xmlfesatools

The library contains functions and classes to navigate in FESA XML files, mainly instance files but also design files. In addition, it contains tools to fetch files from the FESA web-server.

== PAGE UNDER DEVELOPMENT ==

Class XmlFile : Abstraction of FESA XML-Structures

The class XmlFile represents FESA XML-files. It provides methods to navigate in the XML-tree and a method to write the XML-tree back to disk. Specifics of FESA instance files and FESA design files are handled in subclasses xmlfesatools.XmlInstFile (see here) and xmlfesatools.XmlDesignFile (see here).

The fesatools.XmlFile internally uses the Python lxml.etree toolset. The fesatools.XmlFile class holds the XML content as a lxml.etree._ElementTree element tree, which is available by the method get_inst_tree() . The method get_root_element() returns the root element of this tree.

Navigating in XmlFile Objects

Representation of Hierarchy by Path-Strings

The xmlfesatools.XmlFile class provides methods to navigate in the element tree. These methods operate with path-variables (strings). They represent the XML hierarchy, separating the elements by dots. The string

means, starting with the root element, the child element with name child1 and its child element with the name child2. The root element of this relative path is given by the !baseElement parameter, which is the lxml.etree.Element root of the relative XML tree. The default value for !baseElement is the root element of the XML file.

For access to nodes in the XML-tree, three methods are provided:

Path elements may be nested to any level. Given

<root-element>
    <parent>
        <child>
            <grandchild>
            </grandchild>
        </child>
    </parent>
</root-element>

The sub node (<grandchild>) is accessed by the location string "parent.child.grandchild", which is relative to the root-element (unless otherwise given):

grandchild_node = get_element("parent.child.grandchild")

Identification of Elements with Attributes

Often an XML element has child nodes with identical tag names, which are identified by different attribute values, like

<root-element>
    <parent>
        <child name="AAA">
        </child>
        <child name="BBB">
            <grandchild name="XXX"/>
            <grandchild name="YYY"/>
        </child>
        <child name="CCC">
        </child>
    </parent>
</root-element>

Such child nodes can be accessed by given the attribute name and value in paranthesis, like

child_node1 = get_element("parent.child[name=AAA]")

grandchild_node = get_element("parent.child[name=BBB].grandchild[name=XXX]")

Attribute names "name" can be omitted- The following two commands are equivalent to the upper ones:

child_node1 = get_element("parent.child[AAA]")

grandchild_node = get_element("parent.child[BBB].grandchild[XXX]")

Abbreviation of Path-Strings

Names in the path string can be abbreviated. Only the leading part of the tag's name has to be specified. Given only 'info' will find a tag like <information> . If a name matches, it is prefered. Given 'accelerator' will find <accelerator> if both tags <accelerator> and <acceleratorZone> exist, while only 'accelerato' will result in a multiple elements found error.

As an example, given a xmlfesatools.XmlInstFile inst, containing a node information as

a call of get_element('information.fesa') will return the lxml.etree.Element for this node which results in

Giving only the heading of a name is sufficient in most cases when a naming has to be given to locate or access data in the XML files.

To exclude name extension, most methods provide an optional parameter exact_match. If set to True, the path elements must exactly match the names in the XML structure.

Obtaining Path-Strings

The class XmlFile provides two methods to get path-strings:

resolves all abbreviations in the path strin, returns a path string with completed names

returns the path string of a lxml.etree.Element in the XML tree.

As an example, presently for the instance file on scuxl0250 (presently supplying PowerSupllyHebt _DU device GTS7KS1) would provide

first accessing an lxml.etree.Element and then printing it's path would provide

Fild Child Nodes

The xmlfesatools module provides two methods to find child nodes in the XML tree.

will return all child elements of the XML node which is addressed by path, als a list of xml.etree.Element.

will return the paths addressing all child elements of the XML node which is addressed by path, als a list of strings.

Reading and Writing XML-FIles

Provided with the filename as a parameter, XML files are read from disk during instantiation of the XmlFile objects:

In addition to reading files from disk, FESA XML files can be fetched from a central storage, see section web server.

To write the XML contents back to disk, the method write_file is provided:

write_file(self, file_name=None, backup= True)

The name of the file can be specified by parameter file_name . If no new name is given, the name is used from which the XML-data are read.

If the file already exists, up to three backups are created by adding ~, ~~ and ~~~ to the filename. Creation of backups can be suppressed by the optional parameter backup.

Structure-like Classes

Associated information should be combined in one place. For this purpose several classes are defined which provide the descriptive information by getter methods.

Class ConfigValue

The class ConfigValue holds the data of an instance file configuration parameter for a device, e.g. <configuration><acceleratorZone> .

Class DeviceNode

The class DeviceNode holds information for a device (a nomenclature) which is listed in the XML instance file. The information can be accessed by the methods:

Class EventConfiguration

The class combines data for event-configuration elements from the <events-mapping> event-mapping name.

The content can be accessed by the methods:

The return data of the get_data() method is a list of tuples (type, parameter) where type is a string and parameter a dictionary of name / value pairs, as described below.

Class LogicalEvent

The class holds, for a logical event, the event configurations (the mappings), e.g. the mapping to a timing hardware-event or to a timer. The information can be access by the methods:

Class Property

The XmlInstFile Class

The XmlInstFile class provides information of FESA instance files and methods to access characteristic parts of the files. A subset of the implemented methods is listed below. For full information use the Python help command.

The XmlInstFile is a subclass of the XmlFile class (see here).

Provide General Information

Access Device Nodes (lxml.etree.Element) and Device Parameters

A ConfigValue object represents a device's configuration parameter. It provides the value as a string and, if existing, the dimension(s). The output of the get_device_value method is demonstated with the parameters <configuration><acqValue> and <setting><dcMode> :

Access Events-Mapping Entries

The XmlDesignFile Class

The !XmlDesignClass provides some information from FESA design files. This is presently limited to information on RT-actions and on properties.

The XmlDesignFile is a subclass of the XmlFile class (see here).

Get General Information

Get Information on RT-Actions and Associated Events

Get Property Information

Web-Server Files

For each FESA deploy unit which is installed in the facility, a copy of the XML instance file as well as the XML design file used to generate the FESA class is hold on a web server. These files are stored in a zip-file container.

The naming of the container is according to <deploy-unit name>_<front-end name>.zip , e.g. PowerSupplyCry_DU_scuxl0142.zip . The zip-file container contains a directory with two files, the instance file and the design file. In the given example for scuxl0142 these are

• PowerSupply.1.26.0.design
• scuxl0142.instance

The Python class xmlfesatools.FesaWebServer represents the connection to the FESA web server.

Connection to the Web Server

For access to the web server, a class is provide which represents a connection to the web server:

Looking for Container Files

After a connection to the web server has been established, the names of the existing zip-files may be obtained.

Given parts of the names of container files, lists of matching names can be obtained.

Fetching FESA XML-Files

A web server zip container file may be obtained from the web server by

The web server zip-file contains two FESA XML-files, the design file and the instance file. The xmlfesatools library provides tools to extract the XML files from the container. Extraction from the container will provide xmlfesatools.XmlInstFile and xmlfesatools.XmlDesignFile objects, which both inherit from xmlfesatools.XmlFile class.

The XML files can be extracted from the container by the extract_web_file method, which will return a list containing xmlfesatools.FesaWebFile structures:

The contianed FESA XML-files may be obtained directly by the methods get_xml_file, and especially get_xml_instance and get_xml_design methods:

In some cases, the zip-file contains data for several FESA classes. In such cases, the desired FESA class can be selected by providing the optional parameter fesa_class:

will return the file for CaenHvSYx527 and not for the also contained CaenHvSYx527Channel . The name of the FESA class can be abbreviated. In case several names match, as in the example, an exact match is preferred.