exonware-xwsystem 0.1.0.1__py3-none-any.whl → 0.1.0.4__py3-none-any.whl

exonware/xwsystem/io/serialization/format_detector.py

@@ -1,9 +1,10 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/format_detector.py
 #exonware\xwsystem\serialization\format_detector.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generation Date: September 04, 2025
 
 Intelligent format detection for automatic serialization format selection.
@@ -11,7 +12,7 @@ Intelligent format detection for automatic serialization format selection.
 
 import re
 from pathlib import Path
-from typing import Any, Optional, Union
+from typing import Any, Optional
 
 from ...config.logging_setup import get_logger
 
@@ -127,7 +128,7 @@ class FormatDetector:
             ],
         }
     
-    def detect_from_extension(self, file_path: Union[str, Path]) -> list[str]:
+    def detect_from_extension(self, file_path: str | Path) -> list[str]:
         """
         Detect format from file extension.
         
@@ -164,7 +165,7 @@ class FormatDetector:
         
         return []
     
-    def detect_from_content(self, content: Union[str, bytes]) -> dict[str, float]:
+    def detect_from_content(self, content: str | bytes) -> dict[str, float]:
         """
         Detect format from content analysis with confidence scores.
         
@@ -208,8 +209,8 @@ class FormatDetector:
     
     def detect_format(
         self, 
-        file_path: Optional[Union[str, Path]] = None,
-        content: Optional[Union[str, bytes]] = None,
+        file_path: Optional[str | Path] = None,
+        content: Optional[str | bytes] = None,
         data: Optional[bytes] = None
     ) -> dict[str, float]:
         """
@@ -252,8 +253,8 @@ class FormatDetector:
     
     def get_best_format(
         self, 
-        file_path: Optional[Union[str, Path]] = None,
-        content: Optional[Union[str, bytes]] = None,
+        file_path: Optional[str | Path] = None,
+        content: Optional[str | bytes] = None,
         data: Optional[bytes] = None
     ) -> Optional[str]:
         """
@@ -283,8 +284,8 @@ class FormatDetector:
     
     def get_format_suggestions(
         self, 
-        file_path: Optional[Union[str, Path]] = None,
-        content: Optional[Union[str, bytes]] = None,
+        file_path: Optional[str | Path] = None,
+        content: Optional[str | bytes] = None,
         data: Optional[bytes] = None,
         max_suggestions: int = 3
     ) -> list[tuple[str, float]]:
@@ -342,8 +343,8 @@ class FormatDetector:
 _global_detector = FormatDetector()
 
 def detect_format(
-    file_path: Optional[Union[str, Path]] = None,
-    content: Optional[Union[str, bytes]] = None,
+    file_path: Optional[str | Path] = None,
+    content: Optional[str | bytes] = None,
     data: Optional[bytes] = None
 ) -> Optional[str]:
     """
@@ -360,8 +361,8 @@ def detect_format(
     return _global_detector.get_best_format(file_path, content, data)
 
 def get_format_suggestions(
-    file_path: Optional[Union[str, Path]] = None,
-    content: Optional[Union[str, bytes]] = None,
+    file_path: Optional[str | Path] = None,
+    content: Optional[str | bytes] = None,
     data: Optional[bytes] = None,
     max_suggestions: int = 3
 ) -> list[tuple[str, float]]:

exonware/xwsystem/io/serialization/formats/__init__.py

@@ -1,13 +1,16 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/formats/__init__.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generation Date: November 2, 2025
 
-Serialization formats - All format implementations.
-"""
+Serialization formats - Format subpackages.
 
-# Will be populated during migration
-__all__ = []
+Subpackages: .text, .binary, .database, .tabular (pandas). Tabular is not
+imported here so that .text / .binary / .database load without pandas.
+Import tabular explicitly: from ...formats.tabular import ExcelSerializer, ...
+"""
 
+__all__: list[str] = []

exonware/xwsystem/io/serialization/formats/binary/bson.py

@@ -1,8 +1,9 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/formats/binary/bson.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generation Date: November 2, 2025
 
 BSON serialization - Binary JSON format (MongoDB).
@@ -14,7 +15,7 @@ Following I→A pattern:
 """
 
 from importlib import import_module
-from typing import Any, Optional, Union
+from typing import Any, Optional
 
 from ...base import ASerialization
 from ....contracts import EncodeOptions, DecodeOptions
@@ -102,7 +103,7 @@ class BsonSerializer(ASerialization):
     # CORE ENCODE/DECODE (Using bson library)
     # ========================================================================
     
-    def encode(self, value: Any, *, options: Optional[EncodeOptions] = None) -> Union[bytes, str]:
+    def encode(self, value: Any, *, options: Optional[EncodeOptions] = None) -> bytes | str:
         """
         Encode data to BSON bytes.
         
@@ -135,7 +136,7 @@ class BsonSerializer(ASerialization):
                 original_error=e
             )
     
-    def decode(self, repr: Union[bytes, str], *, options: Optional[DecodeOptions] = None) -> Any:
+    def decode(self, repr: bytes | str, *, options: Optional[DecodeOptions] = None) -> Any:
         """
         Decode BSON bytes to data.
         
@@ -146,7 +147,7 @@ class BsonSerializer(ASerialization):
             options: BSON options
         
         Returns:
-            Decoded dict
+            Decoded dict or list (if originally a list, unwrapped from {"data": [...]})
         
         Raises:
             SerializationError: If decoding fails
@@ -159,6 +160,13 @@ class BsonSerializer(ASerialization):
             # Decode from BSON bytes
             data = self._bson.decode(repr)
             
+            # BSON only supports dicts, so lists are wrapped as {"data": [...]}
+            # Unwrap if we detect this pattern to restore original list structure
+            if isinstance(data, dict) and len(data) == 1 and "data" in data:
+                value = data["data"]
+                if isinstance(value, list):
+                    return value
+            
             return data
             
         except Exception as e:
@@ -167,4 +175,5 @@ class BsonSerializer(ASerialization):
                 format_name=self.format_name,
                 original_error=e
             )
-
+    
+    # Note: File operations (save_file, load_file) are inherited from ASerialization base class

exonware/xwsystem/io/serialization/formats/binary/cbor.py

@@ -1,8 +1,9 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/formats/binary/cbor.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generation Date: November 2, 2025
 
 CBOR serialization - Concise Binary Object Representation.
@@ -13,7 +14,7 @@ Following I→A pattern:
 - Concrete: CborSerializer
 """
 
-from typing import Any, Optional, Union
+from typing import Any, Optional
 from pathlib import Path
 
 from ...base import ASerialization
@@ -103,7 +104,7 @@ class CborSerializer(ASerialization):
     # CORE ENCODE/DECODE (Using cbor2 library)
     # ========================================================================
     
-    def encode(self, value: Any, *, options: Optional[EncodeOptions] = None) -> Union[bytes, str]:
+    def encode(self, value: Any, *, options: Optional[EncodeOptions] = None) -> bytes | str:
         """
         Encode data to CBOR bytes.
         
@@ -138,7 +139,7 @@ class CborSerializer(ASerialization):
                 original_error=e
             )
     
-    def decode(self, repr: Union[bytes, str], *, options: Optional[DecodeOptions] = None) -> Any:
+    def decode(self, repr: bytes | str, *, options: Optional[DecodeOptions] = None) -> Any:
         """
         Decode CBOR bytes to data.
         
@@ -170,4 +171,3 @@ class CborSerializer(ASerialization):
                 format_name=self.format_name,
                 original_error=e
             )
-

exonware/xwsystem/io/serialization/formats/binary/marshal.py

@@ -1,8 +1,9 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/formats/binary/marshal.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generation Date: November 2, 2025
 
 Marshal serialization - Python internal serialization.
@@ -14,7 +15,7 @@ Following I→A pattern:
 """
 
 import marshal
-from typing import Any, Optional, Union
+from typing import Any, Optional
 from pathlib import Path
 
 from ...base import ASerialization
@@ -95,7 +96,7 @@ class MarshalSerializer(ASerialization):
     # CORE ENCODE/DECODE (Using marshal module)
     # ========================================================================
     
-    def encode(self, value: Any, *, options: Optional[EncodeOptions] = None) -> Union[bytes, str]:
+    def encode(self, value: Any, *, options: Optional[EncodeOptions] = None) -> bytes | str:
         """
         Encode data to Marshal bytes.
         
@@ -127,7 +128,7 @@ class MarshalSerializer(ASerialization):
                 original_error=e
             )
     
-    def decode(self, repr: Union[bytes, str], *, options: Optional[DecodeOptions] = None) -> Any:
+    def decode(self, repr: bytes | str, *, options: Optional[DecodeOptions] = None) -> Any:
         """
         Decode Marshal bytes to data.
         
@@ -159,4 +160,3 @@ class MarshalSerializer(ASerialization):
                 format_name=self.format_name,
                 original_error=e
             )
-

exonware/xwsystem/io/serialization/formats/binary/msgpack.py

@@ -1,8 +1,9 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/formats/binary/msgpack.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generation Date: November 2, 2025
 
 MessagePack serialization - Efficient binary serialization.
@@ -13,7 +14,7 @@ Following I→A pattern:
 - Concrete: MsgPackSerializer
 """
 
-from typing import Any, Optional, Union
+from typing import Any, Optional
 from pathlib import Path
 
 from ...base import ASerialization
@@ -109,7 +110,7 @@ class MsgPackSerializer(ASerialization):
     # CORE ENCODE/DECODE (Using msgpack library)
     # ========================================================================
     
-    def encode(self, value: Any, *, options: Optional[EncodeOptions] = None) -> Union[bytes, str]:
+    def encode(self, value: Any, *, options: Optional[EncodeOptions] = None) -> bytes | str:
         """
         Encode data to MessagePack bytes.
         
@@ -145,7 +146,7 @@ class MsgPackSerializer(ASerialization):
                 original_error=e
             )
     
-    def decode(self, repr: Union[bytes, str], *, options: Optional[DecodeOptions] = None) -> Any:
+    def decode(self, repr: bytes | str, *, options: Optional[DecodeOptions] = None) -> Any:
         """
         Decode MessagePack bytes to data.
         
@@ -184,4 +185,3 @@ class MsgPackSerializer(ASerialization):
                 format_name=self.format_name,
                 original_error=e
             )
-

exonware/xwsystem/io/serialization/formats/binary/pickle.py

@@ -1,8 +1,9 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/formats/binary/pickle.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generation Date: November 2, 2025
 
 Pickle serialization - Python object serialization.
@@ -14,7 +15,7 @@ Following I→A pattern:
 """
 
 import pickle
-from typing import Any, Optional, Union
+from typing import Any, Optional
 from pathlib import Path
 
 from ...base import ASerialization
@@ -101,7 +102,7 @@ class PickleSerializer(ASerialization):
     # CORE ENCODE/DECODE (Using pickle module)
     # ========================================================================
     
-    def encode(self, value: Any, *, options: Optional[EncodeOptions] = None) -> Union[bytes, str]:
+    def encode(self, value: Any, *, options: Optional[EncodeOptions] = None) -> bytes | str:
         """
         Encode data to Pickle bytes.
         
@@ -136,7 +137,7 @@ class PickleSerializer(ASerialization):
                 original_error=e
             )
     
-    def decode(self, repr: Union[bytes, str], *, options: Optional[DecodeOptions] = None) -> Any:
+    def decode(self, repr: bytes | str, *, options: Optional[DecodeOptions] = None) -> Any:
         """
         Decode Pickle bytes to data.
         
@@ -177,4 +178,3 @@ class PickleSerializer(ASerialization):
                 format_name=self.format_name,
                 original_error=e
             )
-

exonware/xwsystem/io/serialization/formats/binary/plistlib.py

@@ -1,8 +1,9 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/formats/binary/plistlib.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generation Date: November 2, 2025
 
 Plist serialization - Apple property list format.
@@ -14,7 +15,7 @@ Following I→A pattern:
 """
 
 import plistlib
-from typing import Any, Optional, Union
+from typing import Any, Optional
 from pathlib import Path
 
 from ...base import ASerialization
@@ -98,7 +99,7 @@ class PlistSerializer(ASerialization):
     # CORE ENCODE/DECODE (Using plistlib module)
     # ========================================================================
     
-    def encode(self, value: Any, *, options: Optional[EncodeOptions] = None) -> Union[bytes, str]:
+    def encode(self, value: Any, *, options: Optional[EncodeOptions] = None) -> bytes | str:
         """
         Encode data to Plist bytes.
         
@@ -139,7 +140,7 @@ class PlistSerializer(ASerialization):
                 original_error=e
             )
     
-    def decode(self, repr: Union[bytes, str], *, options: Optional[DecodeOptions] = None) -> Any:
+    def decode(self, repr: bytes | str, *, options: Optional[DecodeOptions] = None) -> Any:
         """
         Decode Plist bytes to data.
         
@@ -171,4 +172,3 @@ class PlistSerializer(ASerialization):
                 format_name=self.format_name,
                 original_error=e
             )
-

exonware/xwsystem/io/serialization/formats/database/dbm.py

@@ -1,8 +1,9 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/formats/database/dbm.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generation Date: November 2, 2025
 
 DBM serialization - Unix database manager.
@@ -15,7 +16,7 @@ Following I→A pattern:
 
 import json
 import dbm
-from typing import Any, Optional, Union
+from typing import Any, Optional
 from pathlib import Path
 
 from ...base import ASerialization
@@ -63,11 +64,11 @@ class DbmSerializer(ASerialization):
     def aliases(self) -> list[str]:
         return ["dbm", "DBM"]
     
-    def encode(self, value: Any, *, options: Optional[EncodeOptions] = None) -> Union[bytes, str]:
+    def encode(self, value: Any, *, options: Optional[EncodeOptions] = None) -> bytes | str:
         """DBM encode requires file path - use save_file() instead."""
         raise NotImplementedError("DBM requires file-based operations - use save_file()")
     
-    def decode(self, repr: Union[bytes, str], *, options: Optional[DecodeOptions] = None) -> Any:
+    def decode(self, repr: bytes | str, *, options: Optional[DecodeOptions] = None) -> Any:
         """DBM decode requires file path - use load_file() instead."""
         raise NotImplementedError("DBM requires file-based operations - use load_file()")
 
@@ -75,7 +76,7 @@ class DbmSerializer(ASerialization):
     # FILE-BASED OPERATIONS
     # ---------------------------------------------------------------------
 
-    def save_file(self, data: Any, file_path: Union[str, Path], **options: Any) -> None:
+    def save_file(self, data: Any, file_path: str | Path, **options: Any) -> None:
         """
         Save Python data into a DBM database file.
 
@@ -98,7 +99,7 @@ class DbmSerializer(ASerialization):
                 original_error=e,
             ) from e
 
-    def load_file(self, file_path: Union[str, Path], **options: Any) -> Any:
+    def load_file(self, file_path: str | Path, **options: Any) -> Any:
         """
         Load Python data from a DBM database file.
 
@@ -121,4 +122,3 @@ class DbmSerializer(ASerialization):
                 format_name=self.format_name,
                 original_error=e,
             ) from e
-

exonware/xwsystem/io/serialization/formats/database/shelve.py

@@ -1,8 +1,9 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/formats/database/shelve.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generation Date: November 2, 2025
 
 Shelve serialization - Persistent dictionary storage.
@@ -14,7 +15,7 @@ Following I→A pattern:
 """
 
 import shelve
-from typing import Any, Optional, Union
+from typing import Any, Optional
 from pathlib import Path
 
 from ...base import ASerialization
@@ -62,11 +63,11 @@ class ShelveSerializer(ASerialization):
     def aliases(self) -> list[str]:
         return ["shelve", "Shelve"]
     
-    def encode(self, value: Any, *, options: Optional[EncodeOptions] = None) -> Union[bytes, str]:
+    def encode(self, value: Any, *, options: Optional[EncodeOptions] = None) -> bytes | str:
         """Shelve encode requires file path - use save_file() instead."""
         raise NotImplementedError("Shelve requires file-based operations - use save_file()")
     
-    def decode(self, repr: Union[bytes, str], *, options: Optional[DecodeOptions] = None) -> Any:
+    def decode(self, repr: bytes | str, *, options: Optional[DecodeOptions] = None) -> Any:
         """Shelve decode requires file path - use load_file() instead."""
         raise NotImplementedError("Shelve requires file-based operations - use load_file()")
 
@@ -74,7 +75,7 @@ class ShelveSerializer(ASerialization):
     # FILE-BASED OPERATIONS
     # ---------------------------------------------------------------------
 
-    def save_file(self, data: Any, file_path: Union[str, Path], **options: Any) -> None:
+    def save_file(self, data: Any, file_path: str | Path, **options: Any) -> None:
         """
         Save Python data into a shelve database file.
 
@@ -94,7 +95,7 @@ class ShelveSerializer(ASerialization):
                 original_error=e,
             ) from e
 
-    def load_file(self, file_path: Union[str, Path], **options: Any) -> Any:
+    def load_file(self, file_path: str | Path, **options: Any) -> Any:
         """
         Load Python data from a shelve database file.
 
@@ -116,4 +117,3 @@ class ShelveSerializer(ASerialization):
                 format_name=self.format_name,
                 original_error=e,
             ) from e
-

exonware/xwsystem/io/serialization/formats/database/sqlite3.py

@@ -1,8 +1,9 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/formats/database/sqlite3.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generation Date: November 2, 2025
 
 SQLite3 serialization - Embedded database storage.
@@ -15,7 +16,7 @@ Following I→A pattern:
 
 import json
 import sqlite3
-from typing import Any, Optional, Union
+from typing import Any, Optional
 from pathlib import Path
 
 from ...base import ASerialization
@@ -63,11 +64,11 @@ class Sqlite3Serializer(ASerialization):
     def aliases(self) -> list[str]:
         return ["sqlite3", "sqlite", "db"]
     
-    def encode(self, value: Any, *, options: Optional[EncodeOptions] = None) -> Union[bytes, str]:
+    def encode(self, value: Any, *, options: Optional[EncodeOptions] = None) -> bytes | str:
         """SQLite3 encode requires file path - use save_file() instead."""
         raise NotImplementedError("SQLite3 requires file-based operations - use save_file()")
     
-    def decode(self, repr: Union[bytes, str], *, options: Optional[DecodeOptions] = None) -> Any:
+    def decode(self, repr: bytes | str, *, options: Optional[DecodeOptions] = None) -> Any:
         """SQLite3 decode requires file path - use load_file() instead."""
         raise NotImplementedError("SQLite3 requires file-based operations - use load_file()")
 
@@ -75,7 +76,7 @@ class Sqlite3Serializer(ASerialization):
     # FILE-BASED OPERATIONS (override ASerialization defaults)
     # ---------------------------------------------------------------------
 
-    def save_file(self, data: Any, file_path: Union[str, Path], **options: Any) -> None:
+    def save_file(self, data: Any, file_path: str | Path, **options: Any) -> None:
         """
         Save Python data into a SQLite3 database file.
 
@@ -119,7 +120,7 @@ class Sqlite3Serializer(ASerialization):
                 original_error=e,
             ) from e
 
-    def load_file(self, file_path: Union[str, Path], **options: Any) -> Any:
+    def load_file(self, file_path: str | Path, **options: Any) -> Any:
         """
         Load Python data from a SQLite3 database file.
 
@@ -153,4 +154,3 @@ class Sqlite3Serializer(ASerialization):
                 format_name=self.format_name,
                 original_error=e,
             ) from e
-

exonware/xwsystem/io/serialization/formats/tabular/__init__.py

@@ -0,0 +1,27 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/formats/tabular/__init__.py
+"""
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.4
+Generation Date: January 2025
+
+Tabular serialization formats - Excel, CSV, Google Sheets, DataFrame.
+
+All tabular formats extend ATabularSerialization which provides
+DataFrame conversion capabilities (to_df/from_df methods).
+"""
+
+from .base import ATabularSerialization
+from .excel import ExcelSerializer
+from .csv import CsvSerializer
+from .googlesheets import GoogleSheetsSerializer
+from .df import DataFrameSerializer
+
+__all__ = [
+    'ATabularSerialization',
+    'ExcelSerializer',
+    'CsvSerializer',
+    'GoogleSheetsSerializer',
+    'DataFrameSerializer',
+]

exonware/xwsystem/io/serialization/formats/tabular/base.py

@@ -0,0 +1,89 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/formats/tabular/base.py
+"""
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.4
+Generation Date: January 2025
+
+Tabular serialization base class - ATabularSerialization.
+
+Extends ASerialization to provide DataFrame conversion capabilities.
+All tabular formats (Excel, CSV, Google Sheets, DataFrame) extend this.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Optional, Any
+import pandas as pd
+
+from ...base import ASerialization
+from ....contracts import EncodeOptions, DecodeOptions
+
+
+class ATabularSerialization(ASerialization, ABC):
+    """
+    Abstract base class for tabular data formats.
+    
+    Extends ASerialization to provide DataFrame conversion capabilities.
+    All tabular formats (Excel, CSV, Google Sheets, DataFrame) extend this.
+    
+    Key features:
+    - Convert to/from pandas DataFrame(s)
+    - Support multiple sheets (returns dict of sheet_name: DataFrame)
+    - Integrate with xwsystem serialization framework
+    
+    Examples:
+        >>> # Excel serializer
+        >>> excel_serializer = ExcelSerializer()
+        >>> df = excel_serializer.to_df(excel_bytes)
+        >>> excel_bytes = excel_serializer.from_df(df)
+        
+        >>> # CSV serializer
+        >>> csv_serializer = CsvSerializer()
+        >>> df = csv_serializer.to_df(csv_str)
+        >>> csv_str = csv_serializer.from_df(df)
+    """
+    
+    @abstractmethod
+    def to_df(
+        self, 
+        data: bytes | str | dict, 
+        sheet_name: Optional[str | list[str]] = None,
+        **options
+    ) -> pd.DataFrame | dict[str, pd.DataFrame]:
+        """
+        Convert tabular data to DataFrame(s).
+        
+        Args:
+            data: Input data (bytes, str, or dict depending on format)
+            sheet_name: Specific sheet name(s) to load, or None for all sheets
+            **options: Format-specific options
+        
+        Returns:
+            Single DataFrame if one sheet, or dict of {sheet_name: DataFrame} if multiple
+        
+        Raises:
+            SerializationError: If conversion fails
+        """
+        pass
+    
+    @abstractmethod
+    def from_df(
+        self, 
+        df: pd.DataFrame | dict[str, pd.DataFrame], 
+        **options
+    ) -> bytes | str:
+        """
+        Convert DataFrame(s) to tabular format.
+        
+        Args:
+            df: Single DataFrame or dict of {sheet_name: DataFrame}
+            **options: Format-specific options
+        
+        Returns:
+            Serialized data (bytes for binary formats, str for text formats)
+        
+        Raises:
+            SerializationError: If conversion fails
+        """
+        pass