Unify format and audage_frame into one module & interface.

This commit is contained in:
Joshua Lucas
2026-10-14 21:24:52 -05:00
parent 392726a906
commit cef7398848
5 changed files with 204 additions and 95 deletions

View File

@@ -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() == []

View File

@@ -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

199
src/AuDaGe/frame.py Normal file
View File

@@ -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."""

View File

@@ -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

View File

@@ -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__":