Rewrite XSY module again.

This commit is contained in:
Silcantar
2026-09-21 16:16:50 -05:00
parent 9c45a5ed23
commit 4a9cd7d9f6
2 changed files with 226 additions and 126 deletions

View File

@@ -10,149 +10,205 @@ desc: AuDaGe module for handling Schneider Electric ControlExpert XSY files.
import os
from collections.abc import Iterable
from math import ceil, floor
from dataclasses import dataclass
from importlib import resources
import pandas as pd
from pandas import DataFrame
from AuDaGe.audage_frame import AuDaGeFrame
from AuDaGe.format import Format
from AuDaGe.iec import WORD_LENGTH, DataTypes, iec_definitions
from AuDaGe.iec import *
MAX_ITERATIONS = 5
MAX_RECURSION = 5
ASSETS_PATH = "AuDaGe.formats.controlexpert.assets"
class XSY_Block(AuDaGeFrame):
"""Base class for DataBlock and Definitions that handles shared attributes."""
class XSYBlock(AuDaGeFrame):
"""Base class for DataBlock and Definitions that handles shared attributes.
May be instantiated directly from a dataframe or from an XSY file using the
from_file class method.
"""
_stylesheet_path = None
_xsy_path = None
def __init__(self, xsy_path: os.path, stylesheet_path: os.path):
@classmethod
def from_file(
cls,
xsy_path: os.PathLike,
stylesheet_path: os.PathLike,
) -> XSYBlock:
"""Load an XSY file into a dataframe using the specified stylesheet."""
self.stylesheet_path = stylesheet_path
cls.stylesheet_path = stylesheet_path
cls.xsy_path = xsy_path
with (
open(xsy_path) as xsy_file,
open(self.stylesheet_path) as stylesheet_file,
resources.as_file(cls.xsy_path) as xsy_file,
resources.as_file(cls.stylesheet_path) as stylesheet_file,
):
self.dataframe = pd.read_xml(xsy_file, stylesheet=stylesheet_file)
@property
def stylesheet_path(self) -> os.path:
return self._stylesheet_path
@stylesheet_path.setter
def stylesheet_path(self, path: os.path):
if os.path.isabs(path):
self._stylesheet_path = path
else:
self._stylesheet_path = os.path.join(
os.path.dirname(os.path.abspath(__file__)), path
)
return cls(pd.read_xml(xsy_file, stylesheet=stylesheet_file))
class Definitions(XSY_Block):
"""Read and parse the DDTSource nodes of an XSY file."""
DEFAULT_SS_PATH = "assets/flatten_ddtsource.xslt"
DEFAULT_BUILTINS_PATH = "assets/builtins.xsy"
_builtins_path = None
def __init__(
self,
xsy_path: os.path,
stylesheet_path: os.path = DEFAULT_SS_PATH,
builtins_path: os.path = DEFAULT_BUILTINS_PATH,
):
"""Read the DDTSource nodes of an XSY file into a DataFrame."""
self.builtins_path = builtins_path
super().__init__(xsy_path, stylesheet_path)
@property
def builtins_path(self) -> os.path:
return self._builtins_path
@builtins_path.setter
def builtins_path(self, path: os.path):
if os.path.isabs(path):
self._builtins_path = path
else:
self._builtins_path = os.path.join(
os.path.dirname(os.path.abspath(__file__)), path
)
def calculate_offsets(self):
"""Calculate the memory offset of each UDT member from the root address
of the UDT.
"""
# Find all UDT names in the parent column of the definitions.
unique_parents = self.dataframe.parent.unique()
definitions_list: list[dict] = []
for parent in unique_parents:
# Get all the members of the current UDT.
children = self.dataframe[self.dataframe.parent == parent]
definitions_list.extend(self._calculate_offsets(children))
class DataBlock(XSY_Block):
class DataBlock(XSYBlock):
"""Read and parse the dataBlock node of an XSY file."""
DEFAULT_SS_PATH = "assets/flatten_datablock.xslt"
DEFAULT_SS_PATH = resources.files(ASSETS_PATH).joinpath("flatten_datablock.xslt")
def __init__(
self, xsy_path: os.path, stylesheet_path: os.path = DEFAULT_SS_PATH
):
udt_lengths: dict[str, int]
@classmethod
def from_file(
cls, xsy_path: os.PathLike, stylesheet_path: os.PathLike | None = None
) -> DataBlock:
"""Read the dataBlock of an XSY file into a DataFrame."""
super().__init__(xsy_path, stylesheet_path)
if stylesheet_path is None:
stylesheet_path = cls.DEFAULT_SS_PATH
return cls(XSYBlock.from_file(xsy_path, stylesheet_path))
def expand(self, definitions: Definitions):
"""Expand the UDTs in the dataBlock using the specified Definitions."""
def calculate_all_offsets(self, mwvoea: bool = True) -> DataFrame:
"""Calculate the memory offset for all UDT members in the datablock."""
class XSY(Format):
"""Schneider Electric EcoStruxure Control Expert variable exchange file
(XSY).
class Definitions(XSYBlock):
"""Read and parse the DDTSource nodes of an XSY file."""
Includes methods for reading and (to do) ~~writing~~ said files.
DEFAULT_SS_PATH = resources.files(ASSETS_PATH).joinpath("flatten_ddtsource.xslt")
DEFAULT_BUILTINS_PATH = resources.files(ASSETS_PATH).joinpath("builtins.xsy")
Parameters
----------
xsy_path : pathlike
Path (relative or absolute) to the main XSY file to be read.
dir_path : pathlike (optional)
Absolute path to the directory containing the XSY file if it is not in
the active directory.
def_paths : list of pathlike (optional)
List of additional XSY files to read UDT (DDT) definitions from.
db_ss_path: pathlike (optional)
Path to XSLT stylesheet to flatten the XSY file and extract the
dataBlock node before importing into pandas.
ddt_ss_path: pathlike (optional)
Path to XSLT stylesheet to flatten the XSY file and extract the
DDTSource nodes before importing into pandas.
@classmethod
def from_file(
cls,
xsy_path: os.path,
stylesheet_path: os.path | None = None,
definition_paths: Iterable[os.path] | None = None,
include_builtins: bool = True,
):
"""Read the DDTSource nodes of an XSY file into a DataFrame."""
cls.stylesheet_path = (
cls.DEFAULT_SS_PATH if stylesheet_path is None else stylesheet_path
)
cls.definition_paths = (
[] if definition_paths is None else list(definition_paths)
)
if include_builtins:
cls.definition_paths.append(cls.DEFAULT_BUILTINS_PATH)
# Get the definitions from the main XSY file and put it in the list of
# definitions to be concatenated.
cls.definitions = [XSYBlock.from_file(xsy_path, cls.stylesheet_path)]
# Read the definitions from the other definition files (including the
# builtins file) and add then to the list.
cls.definitions.extend(
XSYBlock.from_file(path, cls.stylesheet_path)
for path in cls.definition_paths
)
# Concatenate the dataframes in the list.
return cls(pd.concat(cls.definitions))
@dataclass
class XSY:
"""Object representing a ControlExpert variable exchange (XSY) file."""
datablock: DataBlock
definitions: Definitions
mwvoea: bool
def compile_datablock(self, datablock: DataFrame | None = None) -> DataFrame:
"""Compile a cross-joined and queried DataBlock by combining the columns
from the datablock with the columns from the definitions."""
datablock_compiled = DataFrame()
datablock_compiled["name"] = datablock.apply(
lambda row: f"{row.name_def}.{row.name}", axis=1
)
datablock_compiled["parent"] = ""
datablock_compiled["type"] = datablock.type_def
datablock_compiled["address"] = datablock.address
datablock_compiled["bitrank"] = datablock.bitrank_def
datablock_compiled["save"] = datablock.save
datablock_compiled["comment"] = datablock.apply(
lambda row: f"{row.comment_def}: {row.comment}", axis=1
)
return datablock_compiled
def expand_datablock(
self,
datablock: DataBlock | None = None,
definitions: Definitions | None = None,
max_recursion: int = MAX_RECURSION,
current_recursion: int = 0,
) -> DataFrame:
"""Recursively expand the UDTs in `datablock` based on the UDT
definitions in `definitions` and return the resulting DataFrame.
"""
datablock = self.datablock if datablock is None else datablock
definitions = self.definitions if definitions is None else definitions
datablock_joined = datablock.join(
definitions, how="cross", rsuffix="_def"
)
datablock_queried = datablock_joined[
datablock_joined.type == datablock_joined.parent_def
]
datablock_compiled = self.compile_datablock(datablock_queried)
if all(
get_data_length(data_type, DataUnit.WORD) != -1
for data_type in datablock_compiled.type
):
datablock_finished = datablock_compiled
elif current_recursion >= max_recursion:
warnings.warn("Maximum recursion depth reached. Returning now.")
datablock_finished = datablock_compiled
else:
datablock_finished = self.expand_datablock(
datablock_compiled, definitions, max_recursion, current_recursion + 1
)
return datablock_finished
class XSYReader(Format):
"""Class for manipulating Schneider Electric EcoStruxure Control Expert
variable exchange (XSY) files. Can be re-used to read multiple XSY files
using common stylesheets and UDT definitions.
"""
def __init__(
self,
def_paths: Iterable[os.path] = [],
builtins_path: os.path | None = None,
db_ss_path: os.path | None = None,
ddt_ss_path: os.path | None = None,
definition_paths: Iterable[os.path] | None = None,
datablock_ss_path: os.path | None = None,
definitions_ss_path: os.path | None = None,
mwvoea: bool = True,
):
self.defs = None
self.definition_paths = def_paths
"""Initialize XSYReader object.
def read(
self, xsy_path: os.path, expand: bool = True
) -> tuple[DataFrame, DataFrame]:
"""Read the dataBlock and definitions of an XSY file into a dataframe."""
self.datablock = DataBlock(xsy_path)
self.definitions = Definitions(xsy_path)
# if not expand:
return (self.datablock, self.definitions)
Parameters
----------
definition_paths : iterable of pathlike (optional)
List of additional XSY files to read UDT (DDT) definitions from.
db_ss_path: pathlike (optional)
Path to XSLT stylesheet to flatten the XSY file and extract the
dataBlock node before importing into pandas.
ddt_ss_path: pathlike (optional)
Path to XSLT stylesheet to flatten the XSY file and extract the
DDTSource nodes before importing into pandas.
"""
self.definition_paths = [] if definition_paths is None else definition_paths
self.datablock_ss_path = datablock_ss_path
self.definitions_ss_path = definitions_ss_path
self.mwvoea = mwvoea
"""Dict for storing the length of all the UDTs included in the
definitions.
"""
def read(self, xsy_path: os.path, expand: bool = True) -> XSY:
"""Read the dataBlock and definitions of an XSY file into an XSY object."""
self.datablock = DataBlock.from_file(xsy_path, self.datablock_ss_path)
self.definitions = Definitions.from_file(
xsy_path, self.definitions_ss_path, self.definition_paths
)
return XSY(self.datablock, self.definitions, self.mwvoea)
def write(self):
"""Write dataframe to XSY file."""
"""Write XSY object to file."""
raise NotImplementedError(
"Writing to XSY is not currently (or probably ever) implemented."
)

View File

@@ -10,32 +10,76 @@ desc: Unit tests for the AuDaGe XSY module.
import os
import unittest
from importlib import resources
# from timeit import default_timer as timer
from AuDaGe.formats.controlexpert.xsy import XSY
import output
IN_PATH = "tests/assets"
OUT_PATH = "tests/output"
import assets
from AuDaGe.formats.controlexpert.xsy import *
ASSETS_PATH = "assets"
OUTPUT_PATH = "output"
class TestXSY(unittest.TestCase):
"""This test case tests the XSYBlock, DataBlock, and Definitions classes in
the xsy module.
"""
def setUp(self):
self.in_paths = [
file
for file in resources.files(assets).iterdir()
if os.path.splitext(file)[-1].lower() == ".xsy"
]
def test_DataBlock(self):
for in_path in self.in_paths:
datablock = DataBlock.from_file(in_path)
self.assertIsInstance(datablock, DataBlock)
self.assertIsInstance(datablock, XSYBlock)
def test_Definitions(self):
for in_path in self.in_paths:
definitions = Definitions.from_file(in_path)
self.assertIsInstance(definitions, Definitions)
self.assertIsInstance(definitions, XSYBlock)
class TestXSYReader(unittest.TestCase):
def setUp(self):
self.xsy_reader = XSYReader()
self.in_paths = [
file
for file in resources.files(assets).iterdir()
if os.path.splitext(file)[-1].lower() == ".xsy"
]
self.out_path = resources.files(output)
def test_init(self):
assert isinstance(XSY(os.path.join(IN_PATH, "hsps.xsy")), XSY)
self.assertIsInstance(self.xsy_reader, XSYReader)
def test_read(self):
for path in self.in_paths:
xsy = self.xsy_reader.read(path)
self.assertIsInstance(xsy, XSY)
def test_export(self):
xsy = XSY()
xsy.read(os.path.join(IN_PATH, "hsps.xsy"), expand=False)
xsy.datablock.dataframe.to_csv(
os.path.join(OUT_PATH, "datablock.csv"), index=False
)
xsy.definitions.dataframe.to_csv(
os.path.join(OUT_PATH, "defs.csv"), index=False
)
# xsy.expand_datablock(datablock).to_csv(
# os.path.join(OUT_PATH, "expanded.csv"),
# index=False
# )
for path in self.in_paths:
file_name = os.path.splitext(os.path.split(path)[-1])[0]
xsy = self.xsy_reader.read(path, expand=False)
xsy.datablock.to_csv(
self.out_path.joinpath(f"{file_name}_datablock.csv"), index=False
)
xsy.definitions.to_csv(
self.out_path.joinpath(f"{file_name}_definitions.csv"), index=False
)
xsy.datablock.update(xsy.expand_datablock())
xsy.datablock.to_csv(
self.out_path.joinpath(f"{file_name}_expanded.csv"), index=False
)
if __name__ == "__main__":
__package__ = "test_xsy"
unittest.main(failfast=True)