Unify format and audage_frame into one module & interface.
This commit is contained in:
@@ -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() == []
|
||||
@@ -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
199
src/AuDaGe/frame.py
Normal 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."""
|
||||
@@ -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
|
||||
@@ -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__":
|
||||
Reference in New Issue
Block a user