Python Integration

The PyXML2XML tool can be used to pre-process more expressive PyXML files (.pyxml), which contain both Python and XML constructs, into flat XML files. Among other things the PyXML2XML tool can be used to eliminate repeating element definitions in XML files such as the Parameter objects in repetitionxml. All regular XML and Python syntax are available in PyXML files without any additional restrictions on their use.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
<Configuration UserVersion="1">
    <EtherCatObjects>
        <EtherCatObject Name="Kp" Index="0x2412" DataType="Float32" Value="1.0"/>

        <EtherCatObject Name="Generic filter" Index="0x2418">
            <EtherCatObject Name="B0" SubIndex="1" DataType="Float32" Value="1.0"/>
            <EtherCatObject Name="B1" SubIndex="2" DataType="Float32" Value="6.0"/>
            <EtherCatObject Name="B2" SubIndex="3" DataType="Float32" Value="7.3"/>
            <EtherCatObject Name="A1" SubIndex="4" DataType="Float32" Value="0.0"/>
            <EtherCatObject Name="A2" SubIndex="5" DataType="Float32" Value="0.5"/>
        </EtherCatObject>

        <EtherCatObject Name="Parameter1" Index="0x2422" DataType="Float32" Value="0.0"/>
        <EtherCatObject Name="Parameter2" Index="0x2423" DataType="Float32" Value="0.0"/>
        <EtherCatObject Name="Parameter3" Index="0x2424" DataType="Float32" Value="0.0"/>
    </EtherCatObjects>
</Configuration>

To use the PyXML2XML tool, it is required to have at least Python version 3.7 installed on your system. To use the tool, several steps need to be followed which are detailed in the following sections:

  • Defining PyXML Files

  • Preprocessing PyXML into XML Files

Defining PyXML Files

A PyXML file (.pyxml) is a file where each line is characterized by one of three types:

  • Regular Python lines: Lines contain only regular Python code. These lines can be used to define variables, iterate over structures or do anything else possible with regular Python. Python lines themselves are never visible in the flat XML file resulting from the preprocessing steps described in Preprocessing PyXML into XML Files, but rather can be used to influence the addition of other lines to the generated flat XML file. For instance, if XML lines are wrapped inside Python iteration or decision control statements, they will be added to the flat XML file according to the Python control statement’s behavior. This holds true for both regular XML lines, as well as XML lines with shorthand Python print statements (see below).

  • Regular XML lines: Regular XML lines that do not contain any Python statements at all. XML style comments that do not contain Python statements are included in this category too. During the preprocessing steps described in Preprocessing PyXML into XML Files, these lines are added to the flat XML file as-is.

  • XML lines with shorthand Python print statements: Regular XML lines that contain shorthand Python print statements of the form [[$x$]], where $x$ is a Python statement yielding a result when evaluated. During the pre-processing described in Preprocessing PyXML into XML Files these lines are added to the flat XML file with the shorthand print expressions [[$x$]] substituted by the result of evaluating expression $x$. Note that XML-style comments can also contain shorthand print statements to add parameterized comments to the generated XML file.

An example PyXML file is shown in repetitionpyxml.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
<Configuration UserVersion="1">
  <EtherCatObjects>
    <EtherCatObject Name="Kp" Index="0x2412" DataType="Float32" Value="1.0"/>

    <EtherCatObject Name="Generic filter" Index="0x2418">
        filter_param_dict = [("B0", 1.0), ("B1", 6.0), ("B2", 7.3), ("A1", 0.0), ("A2", 0.5)]
        for index, (name, value) in enumerate(filter_param_dict):
      <EtherCatObject Name="[[name]]" SubIndex="[[index + 1]]" DataType="Float32" Value="[[value]]"/>
        #end
    </EtherCatObject>

      for i in range(3):
    <EtherCatObject Name="Parameter[[i+1]]" Index="[[0x2422 + i]]" DataType="Float32" Value="0.0"/>
      #end
  </EtherCatObjects>
</Configuration>

Notes on Indentation

There are two important notes on the use of indentation in the PyXML2XML tool. Firstly, the indentation of a line in the generated flat XML file is equal to the indentation of the corresponding line in the input PyXML file. This means one can achieve the desired indentation of the generated XML file by defining that indentation in the input PyXML file. Secondly, in contrast to regular Python scripts, the indentation of lines in a PyXML file does not determine the scope of decision or iteration control statement. Instead, when using decision or iteration control statements such as if:, else:, while: or any statement ending in a colon, the statement shall end when a line contains only \#end or \# end.

Note

This also holds true when defining a function.

Preprocessing PyXML into XML Files

Because PyXML files are not supported by other tools, PyXML files need to be preprocessed into flat XML files before they can be used. To this end, a preprocessing tool has been included in the Installation installer. The steps to use the tool under Linux or Windows differ slightly, so please refer to the relevant section below.

Tool Usage on Linux

To pre-process the PyXML file into a flat XML file, follow these steps:

  • Open a new instance of your system’s shell (e.g. GNU Bash).

  • In the shell, navigate to the installation path of the preprocessing tool, which is the usr/bin/ folder of the installation.

  • Then, depending on which Python versions are installed on your system, run either the command in pythonpreprocesscommandlinux or python3preprocesscommandlinux. In these commands, replace

    • NAME_OF_INPUT_FILE with the name of your input .pyxml file.

    • PATH_TO_OUTPUT_XML_FILE with the location where the generated .xml file should be stored. This path should include the name and extension of the output file.

    Note

    --output-file argument is an optional argument. When left out, the output file path will default to the input file path with the .pyxml extension replaced by .xml.

Preprocessing a pyxml file into a flat .xml file on Linux
1
python pyxml2xml.py --input-file NAME_OF_INPUT_PYXML_FILE --output-file PATH_TO_OUTPUT_XML_FILE
Preprocessing a pyxml file into a flat xml file on Linux
1
python3 pyxml2xml.py --input-file NAME_OF_INPUT_PYXML_FILE --output-file PATH_TO_OUTPUT_XML_FILE

Tool Usage on Windows

To pre-process the PyXML file into a flat XML file, follow these steps:

  • Open a new instance of your system’s shell (e.g. cmd.exe).

  • In the shell, navigate to the installation path of the preprocessing tool, which is the miscellaneous\pyxml2xml folder of the installation.

  • Then, depending on which Python versions are installed on your system, run either the command in pythonpreprocesscommandwindows or python3preprocesscommandwindows. In these commands, replace

    • NAME_OF_INPUT_PYXML_FILE with the full or relative path to your input .pyxml file.

    • PATH_TO_OUTPUT_XML_FILE with the location where the generated .xml file should be stored.

      This path should include the name and extension of the output file.

    Note

    --output-file argument is an optional argument. When left out, the output file path will default to the input file path with the .pyxml extension replaced by .xml.

Preprocessing a pyxml file into a flat .xml file on Windows
1
python -m pyxml2xml --input-file NAME_OF_INPUT_FILE --output-file PATH_TO_OUTPUT_XML_FILE
Preprocessing a pyxml file into a flat xml file on Windows
1
python3 -m pyxml2xml --input-file NAME_OF_INPUT_FILE --output-file PATH_TO_OUTPUT_XML_FILE

General Notes on Tool Usage

This section contains some remarks that can ease the usage of the PyXML2XML preprocessing tool.

First of all, in case one wants to retrieve an exhaustive list of arguments for the PyXML2XML tool, substitute the --input-file and --output-file arguments in the above commands by the --help argument. The PyXML2XML preprocessor will output a list of all supported arguments, along with their descriptions.

Secondly, during the preprocessing of a PyXML file into a flat XML file, the PyXML2XML tool will execute a Python script that is based on the input PyXML file to create the flat XML file. In case an error occurs during this execution, the PyXML2XML tool will stop the preprocessing and report the error that occurred. It will also attempt to report the line of the input PyXML file, which contains a mistake that resulted in the error that occurred during the preprocessing.

In case the information that is reported by the PyXML2XML tool is insufficient to diagnose the cause of the error, it can be useful to inspect the intermediate Python file that is executed during preprocessing. This file can be retained by additionally supplying the --retain-python argument to the tool.

Finally, because the PyXML2XML tool is unaware of the XML schema that is used for the input and output files, the tool does not automatically validate the output file for validity. This means that the validity of the output file needs to be verified separately using standard XML tooling.