From cef739884830e4476a0b035e565ce7b810bd1506 Mon Sep 17 00:00:00 2001 From: Joshua Lucas Date: Wed, 14 Oct 2026 21:24:52 -0500 Subject: [PATCH] Unify format and audage_frame into one module & interface. --- src/AuDaGe/audage_frame.py | 56 ----- src/AuDaGe/format.py | 23 -- src/AuDaGe/frame.py | 199 ++++++++++++++++++ tests/test_format.py | 11 - tests/{test_audage_frame.py => test_frame.py} | 10 +- 5 files changed, 204 insertions(+), 95 deletions(-) delete mode 100644 src/AuDaGe/audage_frame.py delete mode 100644 src/AuDaGe/format.py create mode 100644 src/AuDaGe/frame.py delete mode 100644 tests/test_format.py rename tests/{test_audage_frame.py => test_frame.py} (68%) diff --git a/src/AuDaGe/audage_frame.py b/src/AuDaGe/audage_frame.py deleted file mode 100644 index c1cdbcd..0000000 --- a/src/AuDaGe/audage_frame.py +++ /dev/null @@ -1,56 +0,0 @@ -""" -AuDaGe DataFrame extensions - -name: audage_frame.py -by: Josh Lucas -date: 2026-09-14 - -desc: Extensions to DataFrame for AuDaGe purposes. -""" - -from collections.abc import Sequence -from enum import StrEnum, auto - -from pandas import DataFrame - -type DataFrameLike = DataFrame | Sequence[Sequence] - -type Frame = dict[str, list[any]] -"""A mutable data structure for importing from and exporting to DataFrames.""" - - -class MandatoryColumns(StrEnum): - """Enum of columns that are mandatory for a valid AuDaGe DataFrame.""" - - NAME = auto() - TYPE = auto() - ADDRESS = auto() - COMMENT = auto() - - -class AuDaGeFrame(DataFrame): - """DataFrame wrapped for AuDaGe purposes.""" - - def __init__( - self, data: DataFrameLike, validate: bool = True, name: str = "" - ): - super().__init__(data) - self._name = name - missing_columns = self.missing_columns() - if validate and missing_columns != []: - raise ValueError( - f"The provided data is missing the following columns " - f"required by AuDaGe:\n{'\n'.join(missing_columns)}" - ) - - def missing_columns(self) -> list[MandatoryColumns]: - """Return a list of mandatory columns that are missing from this - DataFrame. - """ - return [ - label for label in MandatoryColumns if not label in self.columns - ] - - def is_valid(self) -> bool: - """Check whether the DataFrame contains all mandatory columns.""" - return self.missing_columns() == [] diff --git a/src/AuDaGe/format.py b/src/AuDaGe/format.py deleted file mode 100644 index 233c4d5..0000000 --- a/src/AuDaGe/format.py +++ /dev/null @@ -1,23 +0,0 @@ -""" -AuDaGe format module - -name: format.py -by: Josh Lucas -date: 2026-09-14 - -desc: Abstract base class for AuDaGe import and export formats. -""" - -from abc import ABC, abstractmethod - - -class Format(ABC): - """Abstract base class for AuDaGe import and export formats.""" - - @abstractmethod - def read(self): - pass - - @abstractmethod - def write(self): - pass diff --git a/src/AuDaGe/frame.py b/src/AuDaGe/frame.py new file mode 100644 index 0000000..e439966 --- /dev/null +++ b/src/AuDaGe/frame.py @@ -0,0 +1,199 @@ +""" +AuDaGe DataFrame extensions + +name: frame.py +by: Josh Lucas +date: 2026-09-14 + +desc: Extensions to DataFrame for AuDaGe purposes. +""" + +import os +from abc import ABC, abstractmethod +from collections.abc import Callable, Sequence + +import pandas as pd + +from AuDaGe.better_enum import BetterStrEnum +from AuDaGe.debug_tools import MeasureTime + +type DataFrameLike = pd.DataFrame | Sequence[Sequence] + +type Translator[T] = Callable[pd.Series, T] | T +"""Type that provides a value for a DataFrame cell by providing either a +Callable that generates a value from a pandas Series (i.e. DataFrame row) or a +constant default value. +""" + +type Translators = dict[str, Translator[any]] +"""A mapping of column names to Translators.""" + + +def verb(value: any) -> any: + """Returns the input *verb*atim.""" + return value + + +class MetaFrame(type): + """Metaclass for creating Frame objects that allows us to set + mandatory_columns from the class declaration. + """ + + def __new__( + cls, + clsname, + bases, + attrs, + mandatory_columns: tuple[str] = (), + translators_from_af: Translators | None = None, + translators_to_af: Translators | None = None, + ): + attrs["mandatory_columns"] = mandatory_columns + attrs["translators_from_af"] = ( + {} if translators_from_af is None else translators_from_af + ) + attrs["translators_to_af"] = ( + {} if translators_to_af is None else translators_to_af + ) + return super().__new__(cls, clsname, bases, attrs) + + +class Frame(pd.DataFrame, metaclass=MetaFrame): + """Base class for creating dataframes that enforce a certain column format + and provides methods for converting to and from AuDaGeFrame and importing + and exporting to files. Base class for all other Frame classes.""" + + def __init__( + self, + data: DataFrameLike = None, + validate: bool = True, + name: str = "", + translators_from_af: Translators | None = None, + translators_to_af: Translators | None = None, + ): + # Initialization + if data is None: + data = {key: [] for key in self.mandatory_columns} + super().__init__(data) + # Add (union) the translators from __init__ to the default translators + # from the metaclass. + self.translators_from_af |= ( + {} if translators_from_af is None else translators_from_af + ) + self.translators_to_af |= ( + {} if translators_to_af is None else translators_to_af + ) + # Validation + missing_columns = self.missing_columns() + if validate and missing_columns != []: + raise ValueError( + f"The provided data is missing the following columns " + f"required by {self.__class__.__name__}:\n" + f"{'\n'.join(missing_columns)}" + ) + + def missing_columns(self) -> list[str]: + """Return a list of mandatory columns that are missing from this + DataFrame. + """ + return [ + label + for label in self.mandatory_columns + if not label in self.columns + ] + + def is_valid(self) -> bool: + """Check whether the DataFrame contains all mandatory columns.""" + return self.missing_columns() == [] + + @staticmethod + def translate( + output_format: Callable[DataFrameLike, any], + input_frame: pd.DataFrame, + translators: Translators, + ): + frame_dict = {} + for key in translators: + with MeasureTime( + do_print=True, + message=( + f"Column {key} translation completed in " + + "{time:.3f} {unit}" + ), + ): + # Translator is a column name. + if ( + isinstance(translators[key], str) + and translators[key] in input_frame.columns + ): + frame_dict[key] = input_frame[translators[key]] + # Translator is a callable. + elif isinstance(translators[key], Callable): + frame_dict[key] = input_frame.apply( + translators[key], axis=1 + ) + # Translator is a constant. + else: + frame_dict[key] = translators[key] + return output_format(frame_dict) + + @classmethod + def from_AF( + cls, + frame: AuDaGeFrame, + translators: Translators | None = None, + ) -> Frame: + if translators is None: + translators = cls.translators_from_af + return cls.translate(cls, frame, translators) + + @classmethod + def from_file(cls, path: os.PathLike) -> Frame: + """Minimal implementation of the `from_file` method. Reads `path` as a + CSV file into a dataframe and returns the latter. + """ + return cls(pd.read_csv(path)) + + def to_AF( + self, + translators: Translators | None = None, + ) -> AuDaGeFrame: + if translators is None: + translators = self.translators_to_af + return self.translate(AuDaGeFrame, self, translators) + + def to_file(self, path: os.PathLike): + """Minimal implementation of `to_file` method. Writes `frame` to `path` + as a CSV. + """ + self.to_csv(path, index=False) + + +class AuDaGeColumns(BetterStrEnum): + """Enum of columns required by AuDaGeFrame.""" + + NAME = "name" + TYPE = "type" + ADDRESS = "address" + COMMENT = "comment" + + +class AuDaGeFrame(Frame, mandatory_columns=AuDaGeColumns.values()): + """DataFrame that enforces the presence of columns matching the names in + `AuDaGeColumns`. Used as intermediate format for converting between other + data formats. + """ + + +class Reader(ABC): + """ABC for objects that facilitate reading and writing to multiple files in + succession using a shared configuration. + """ + + @abstractmethod + def read(self, path: os.PathLike) -> Frame: + """Read a file into a Frame.""" + + @abstractmethod + def write(self, path: os.PathLike): + """Write a Frame to a file.""" diff --git a/tests/test_format.py b/tests/test_format.py deleted file mode 100644 index f320d2f..0000000 --- a/tests/test_format.py +++ /dev/null @@ -1,11 +0,0 @@ -""" -AuDaGe format tests - -name: test_format.py -by: Josh Lucas -date: 2026-09-14 - -desc: Unit tests for the AuDaGe format module. -""" - -import unittest diff --git a/tests/test_audage_frame.py b/tests/test_frame.py similarity index 68% rename from tests/test_audage_frame.py rename to tests/test_frame.py index e77025a..b5f46d8 100644 --- a/tests/test_audage_frame.py +++ b/tests/test_frame.py @@ -1,24 +1,24 @@ import unittest -from AuDaGe.audage_frame import AuDaGeFrame +from AuDaGe.frame import AuDaGeFrame class TestAuDaGeFrame(unittest.TestCase): def test_init(self): - valid_adf = { + valid_af = { "name": ["a", "b", "c"], "type": ["d", "e", "f"], "address": [1, 2, 3], "comment": ["g", "h", "i"], } - self.assertTrue(AuDaGeFrame(valid_adf).is_valid()) - invalid_adf = { + self.assertTrue(AuDaGeFrame(valid_af).is_valid()) + invalid_af = { "name": ["a", "b", "c"], # "type": ["d", "e", "f"], "address": [1, 2, 3], "comment": ["g", "h", "i"], } - self.assertRaises(ValueError, AuDaGeFrame, invalid_adf) + self.assertRaises(ValueError, AuDaGeFrame, invalid_af) if __name__ == "__main__":