From 4a9cd7d9f6d01e0a8696a6699d454af9a332c806 Mon Sep 17 00:00:00 2001 From: Silcantar <1491897+Silcantar@users.noreply.github.com> Date: Mon, 21 Sep 2026 16:16:50 -0500 Subject: [PATCH] Rewrite XSY module again. --- src/AuDaGe/formats/controlexpert/xsy.py | 274 ++++++++++++++---------- tests/test_xsy.py | 78 +++++-- 2 files changed, 226 insertions(+), 126 deletions(-) diff --git a/src/AuDaGe/formats/controlexpert/xsy.py b/src/AuDaGe/formats/controlexpert/xsy.py index cd0a94d..6024b48 100644 --- a/src/AuDaGe/formats/controlexpert/xsy.py +++ b/src/AuDaGe/formats/controlexpert/xsy.py @@ -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." ) diff --git a/tests/test_xsy.py b/tests/test_xsy.py index 19ec19b..d6e3da2 100644 --- a/tests/test_xsy.py +++ b/tests/test_xsy.py @@ -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)