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
|
import unittest
|
||||||
|
|
||||||
from AuDaGe.audage_frame import AuDaGeFrame
|
from AuDaGe.frame import AuDaGeFrame
|
||||||
|
|
||||||
|
|
||||||
class TestAuDaGeFrame(unittest.TestCase):
|
class TestAuDaGeFrame(unittest.TestCase):
|
||||||
def test_init(self):
|
def test_init(self):
|
||||||
valid_adf = {
|
valid_af = {
|
||||||
"name": ["a", "b", "c"],
|
"name": ["a", "b", "c"],
|
||||||
"type": ["d", "e", "f"],
|
"type": ["d", "e", "f"],
|
||||||
"address": [1, 2, 3],
|
"address": [1, 2, 3],
|
||||||
"comment": ["g", "h", "i"],
|
"comment": ["g", "h", "i"],
|
||||||
}
|
}
|
||||||
self.assertTrue(AuDaGeFrame(valid_adf).is_valid())
|
self.assertTrue(AuDaGeFrame(valid_af).is_valid())
|
||||||
invalid_adf = {
|
invalid_af = {
|
||||||
"name": ["a", "b", "c"],
|
"name": ["a", "b", "c"],
|
||||||
# "type": ["d", "e", "f"],
|
# "type": ["d", "e", "f"],
|
||||||
"address": [1, 2, 3],
|
"address": [1, 2, 3],
|
||||||
"comment": ["g", "h", "i"],
|
"comment": ["g", "h", "i"],
|
||||||
}
|
}
|
||||||
self.assertRaises(ValueError, AuDaGeFrame, invalid_adf)
|
self.assertRaises(ValueError, AuDaGeFrame, invalid_af)
|
||||||
|
|
||||||
|
|
||||||
if __name__ == "__main__":
|
if __name__ == "__main__":
|
||||||
Reference in New Issue
Block a user