Skip to content

omnipy.components.pandas.models

Pandas-backed data models for tabular Omnipy data files.

CLASS DESCRIPTION
PandasModel

Represent tabular content as a pandas-backed Omnipy model.

AnyJsonTableType module-attribute 

AnyJsonTableType = (
    RowWiseTableModel
    | RowWiseTableWithColNamesModel
    | ColumnWiseTableWithColNamesAndIndexModel
    | JsonScalarColumnWiseTableWithColNamesModel
)

PandasModel

Bases: Model['pd.DataFrame | pd.Series | AnyJsonTableType'], PrintableTable


              flowchart BT
              omnipy.components.pandas.models.PandasModel[PandasModel]
              omnipy.data.model.Model[Model]
              omnipy.data._mixins.display.ModelDisplayMixin[ModelDisplayMixin]
              omnipy.data._mixins.display.BaseDisplayMixin[BaseDisplayMixin]
              omnipy.data._data_class_creator.DataClassBase[DataClassBase]
              omnipy.components.tables.models.PrintableTable[PrintableTable]

                              omnipy.data.model.Model --> omnipy.components.pandas.models.PandasModel
                                omnipy.data._mixins.display.ModelDisplayMixin --> omnipy.data.model.Model
                                omnipy.data._mixins.display.BaseDisplayMixin --> omnipy.data._mixins.display.ModelDisplayMixin
                

                omnipy.data._data_class_creator.DataClassBase --> omnipy.data.model.Model
                
                omnipy.util.pydantic.GenericModel --> omnipy.data.model.Model
                

                omnipy.components.tables.models.PrintableTable --> omnipy.components.pandas.models.PandasModel
                


              click omnipy.components.pandas.models.PandasModel href "" "omnipy.components.pandas.models.PandasModel"
              click omnipy.data.model.Model href "" "omnipy.data.model.Model"
              click omnipy.data._mixins.display.ModelDisplayMixin href "" "omnipy.data._mixins.display.ModelDisplayMixin"
              click omnipy.data._mixins.display.BaseDisplayMixin href "" "omnipy.data._mixins.display.BaseDisplayMixin"
              click omnipy.data._data_class_creator.DataClassBase href "" "omnipy.data._data_class_creator.DataClassBase"
              click omnipy.components.tables.models.PrintableTable href "" "omnipy.components.tables.models.PrintableTable"

Represent tabular content as a pandas-backed Omnipy model.

PARAMETER DESCRIPTION
data

Pandas DataFrame/Series or a supported JSON-like table structure that can be converted to a DataFrame.
RETURNS DESCRIPTION
PandasModel

Model instance containing validated pandas tabular data.
RAISES DESCRIPTION
Exception

Propagates conversion and validation errors raised while parsing input data.
Returned by: Subclassed by: Used by:
METHOD DESCRIPTION
from_data

Replace model content from iterable table data.
from_json

Replace model content by parsing JSON table content.
to_data

Convert pandas content to plain Python data structures.
to_json

Serialize model content to JSON.
Source code in src/omnipy/components/pandas/models.py 
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
class PandasModel(Model['pd.DataFrame | pd.Series | AnyJsonTableType'], PrintableTable):
    """Represent tabular content as a pandas-backed Omnipy model.

    Args:
        data: Pandas ``DataFrame``/``Series`` or a supported JSON-like table
            structure that can be converted to a DataFrame.

    Returns:
        PandasModel: Model instance containing validated pandas tabular data.

    Raises:
        Exception: Propagates conversion and validation errors raised while
            parsing input data.
    """

    if TYPE_CHECKING:

        def __new__(cls, *args: Any, **kwargs: Any) -> 'PandasModel_DataFrame':
            ...

    @classmethod
    def _parse_data(
        cls,
        data: 'pd.DataFrame | pd.Series | AnyJsonTableType',
    ) -> 'pd.DataFrame | pd.Series':
        """Parse supported tabular input into pandas-native content.

        Args:
            data: Pandas object or table-like content accepted by
                ``pandas.DataFrame``.

        Returns:
            Parsed pandas ``DataFrame`` or ``Series``.

    Raises:
        Exception: Propagates conversion errors raised by pandas.
        """

        from .lazy_import import pd

        if isinstance(data, pd.DataFrame) or isinstance(data, pd.Series):
            return data

        return cls._from_iterable(data)

    # @staticmethod
    # def _data_column_names_are_strings(data: pd.DataFrame) -> None:
    #     for column in data.columns:
    #         assert isinstance(column, str)

    # @staticmethod
    # def _data_not_empty_object(data: pd.DataFrame) -> None:
    #     assert not any(data.isna().all(axis=1))
    #

    @classmethod
    def _from_iterable(cls, data: Iterable) -> 'pd.DataFrame':
        """Build a DataFrame from iterable tabular data.

        Args:
            data: Iterable rows or a model wrapping iterable row content.

        Returns:
            DataFrame with pandas nullable dtypes inferred.

    Raises:
        Exception: Propagates DataFrame construction errors raised by
            pandas.
        """

        from .lazy_import import pd
        return pd.DataFrame(data.content if is_model_instance(data) else data).convert_dtypes()

    def to_data(self) -> Any:
        """Convert pandas content to plain Python data structures.

        Returns:
            For DataFrames, a list of row dictionaries. For Series, a key-value
            dictionary.

        Raises:
            Exception: Propagates serialization errors raised by pandas.

        """

        from .lazy_import import pd

        df = self.content.replace({pd.NA: None})
        if isinstance(df, pd.DataFrame):
            # return df.to_dict(orient='records')
            return df.to_dict(orient='list')
        elif isinstance(df, pd.Series):
            return df.to_dict()

    def from_data(self, data: Iterable) -> None:
        """Replace model content from iterable table data.

        Args:
            data: Iterable rows that can be converted to a pandas DataFrame.

        Raises:
            Exception: Propagates validation or conversion errors raised during
                update.
        """

        self._validate_and_set_value(self._from_iterable(data))

    def from_json(self, json_content: str) -> None:
        """Replace model content by parsing JSON table content.

        Args:
            json_content: JSON string accepted by ``pandas.read_json``.

        Raises:
            ValueError: If ``json_content`` cannot be parsed as a table.
            Exception: Propagates pandas parsing or validation errors.
        """

        from .lazy_import import pd

        self._validate_and_set_value(pd.read_json(StringIO(json_content)).convert_dtypes())

    def to_json(self, pretty=True) -> str:
        """Serialize model content to JSON.

        Args:
            pretty: Reserved compatibility argument. The current implementation
                always returns compact pandas JSON output.

        Returns:
            JSON string representation of the underlying pandas object.

    Raises:
        ShouldNotOccurException: If model content is neither DataFrame nor
            Series.
        """

        from .lazy_import import pd

        if isinstance(self.content, pd.DataFrame):
            return self.content.to_json(orient='records')
        elif isinstance(self.content, pd.Series):
            return self.content.to_json()
        else:
            raise ShouldNotOccurException()

from_data 

from_data(data: Iterable) -> None

Replace model content from iterable table data.

PARAMETER DESCRIPTION
data

Iterable rows that can be converted to a pandas DataFrame.

TYPE: Iterable

RAISES DESCRIPTION
Exception

Propagates validation or conversion errors raised during update.
Source code in src/omnipy/components/pandas/models.py 
121
122
123
124
125
126
127
128
129
130
131
132
def from_data(self, data: Iterable) -> None:
    """Replace model content from iterable table data.

    Args:
        data: Iterable rows that can be converted to a pandas DataFrame.

    Raises:
        Exception: Propagates validation or conversion errors raised during
            update.
    """

    self._validate_and_set_value(self._from_iterable(data))

from_json 

from_json(json_content: str) -> None

Replace model content by parsing JSON table content.

PARAMETER DESCRIPTION
json_content

JSON string accepted by pandas.read_json.

TYPE: str

RAISES DESCRIPTION
ValueError

If json_content cannot be parsed as a table.
Exception

Propagates pandas parsing or validation errors.
Source code in src/omnipy/components/pandas/models.py 
134
135
136
137
138
139
140
141
142
143
144
145
146
147
def from_json(self, json_content: str) -> None:
    """Replace model content by parsing JSON table content.

    Args:
        json_content: JSON string accepted by ``pandas.read_json``.

    Raises:
        ValueError: If ``json_content`` cannot be parsed as a table.
        Exception: Propagates pandas parsing or validation errors.
    """

    from .lazy_import import pd

    self._validate_and_set_value(pd.read_json(StringIO(json_content)).convert_dtypes())

to_data 

to_data() -> Any

Convert pandas content to plain Python data structures.

RETURNS DESCRIPTION
Any

For DataFrames, a list of row dictionaries. For Series, a key-value dictionary.
RAISES DESCRIPTION
Exception

Propagates serialization errors raised by pandas.
Source code in src/omnipy/components/pandas/models.py 
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
def to_data(self) -> Any:
    """Convert pandas content to plain Python data structures.

    Returns:
        For DataFrames, a list of row dictionaries. For Series, a key-value
        dictionary.

    Raises:
        Exception: Propagates serialization errors raised by pandas.

    """

    from .lazy_import import pd

    df = self.content.replace({pd.NA: None})
    if isinstance(df, pd.DataFrame):
        # return df.to_dict(orient='records')
        return df.to_dict(orient='list')
    elif isinstance(df, pd.Series):
        return df.to_dict()

to_json 

to_json(pretty=True) -> str

Serialize model content to JSON.

Args:
    pretty: Reserved compatibility argument. The current implementation
        always returns compact pandas JSON output.

Returns:
    JSON string representation of the underlying pandas object.
RAISES DESCRIPTION
ShouldNotOccurException

If model content is neither DataFrame nor Series.
Source code in src/omnipy/components/pandas/models.py 
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
def to_json(self, pretty=True) -> str:
    """Serialize model content to JSON.

    Args:
        pretty: Reserved compatibility argument. The current implementation
            always returns compact pandas JSON output.

    Returns:
        JSON string representation of the underlying pandas object.

Raises:
    ShouldNotOccurException: If model content is neither DataFrame nor
        Series.
    """

    from .lazy_import import pd

    if isinstance(self.content, pd.DataFrame):
        return self.content.to_json(orient='records')
    elif isinstance(self.content, pd.Series):
        return self.content.to_json()
    else:
        raise ShouldNotOccurException()

PandasModel_DataFrame

Bases: PandasModel, pd.DataFrame


              flowchart BT
              omnipy.components.pandas.models.PandasModel_DataFrame[PandasModel_DataFrame]
              omnipy.components.pandas.models.PandasModel[PandasModel]
              omnipy.data.model.Model[Model]
              omnipy.data._mixins.display.ModelDisplayMixin[ModelDisplayMixin]
              omnipy.data._mixins.display.BaseDisplayMixin[BaseDisplayMixin]
              omnipy.data._data_class_creator.DataClassBase[DataClassBase]
              omnipy.components.tables.models.PrintableTable[PrintableTable]

                              omnipy.components.pandas.models.PandasModel --> omnipy.components.pandas.models.PandasModel_DataFrame
                                omnipy.data.model.Model --> omnipy.components.pandas.models.PandasModel
                                omnipy.data._mixins.display.ModelDisplayMixin --> omnipy.data.model.Model
                                omnipy.data._mixins.display.BaseDisplayMixin --> omnipy.data._mixins.display.ModelDisplayMixin
                

                omnipy.data._data_class_creator.DataClassBase --> omnipy.data.model.Model
                
                omnipy.util.pydantic.GenericModel --> omnipy.data.model.Model
                

                omnipy.components.tables.models.PrintableTable --> omnipy.components.pandas.models.PandasModel
                



              click omnipy.components.pandas.models.PandasModel_DataFrame href "" "omnipy.components.pandas.models.PandasModel_DataFrame"
              click omnipy.components.pandas.models.PandasModel href "" "omnipy.components.pandas.models.PandasModel"
              click omnipy.data.model.Model href "" "omnipy.data.model.Model"
              click omnipy.data._mixins.display.ModelDisplayMixin href "" "omnipy.data._mixins.display.ModelDisplayMixin"
              click omnipy.data._mixins.display.BaseDisplayMixin href "" "omnipy.data._mixins.display.BaseDisplayMixin"
              click omnipy.data._data_class_creator.DataClassBase href "" "omnipy.data._data_class_creator.DataClassBase"
              click omnipy.components.tables.models.PrintableTable href "" "omnipy.components.tables.models.PrintableTable"
Source code in src/omnipy/components/pandas/models.py 
184
185
class PandasModel_DataFrame(PandasModel, pd.DataFrame):
    ...