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

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

@@ -0,0 +1,291 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/formats/tabular/excel.py
+"""
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.4
+Generation Date: January 2025
+
+Excel serialization - .xlsx, .xls format.
+
+Following I→A→XW pattern:
+- I: ISerialization (interface)
+- A: ASerialization (abstract base)
+- ATabular: ATabularSerialization (tabular base)
+- Concrete: ExcelSerializer
+"""
+
+import io
+from typing import Any, Optional
+from pathlib import Path
+
+import pandas as pd
+
+from .base import ATabularSerialization
+from ....contracts import EncodeOptions, DecodeOptions
+from ....defs import CodecCapability
+from ....errors import SerializationError
+
+
+class ExcelSerializer(ATabularSerialization):
+    """
+    Excel serializer - follows the I→A→ATabular pattern.
+    
+    I: ISerialization (interface)
+    A: ASerialization (abstract base)
+    ATabular: ATabularSerialization (tabular base)
+    Concrete: ExcelSerializer
+    
+    Supports .xlsx and .xls formats via pandas/openpyxl/xlrd.
+    
+    Examples:
+        >>> serializer = ExcelSerializer()
+        >>> 
+        >>> # Convert Excel bytes to DataFrame
+        >>> df = serializer.to_df(excel_bytes)
+        >>> 
+        >>> # Convert DataFrame to Excel bytes
+        >>> excel_bytes = serializer.from_df(df)
+        >>> 
+        >>> # Save to file
+        >>> serializer.save_file(df, "data.xlsx")
+        >>> 
+        >>> # Load from file
+        >>> df = serializer.load_file("data.xlsx")
+    """
+    
+    # ========================================================================
+    # CODEC METADATA
+    # ========================================================================
+    
+    @property
+    def codec_id(self) -> str:
+        return "excel"
+    
+    @property
+    def media_types(self) -> list[str]:
+        return [
+            "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",  # .xlsx
+            "application/vnd.ms-excel",  # .xls
+        ]
+    
+    @property
+    def file_extensions(self) -> list[str]:
+        return [".xlsx", ".xls"]
+    
+    @property
+    def format_name(self) -> str:
+        return "Excel"
+    
+    @property
+    def mime_type(self) -> str:
+        return "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+    
+    @property
+    def is_binary_format(self) -> bool:
+        return True  # Excel is binary
+    
+    @property
+    def supports_streaming(self) -> bool:
+        return False  # Excel doesn't naturally support streaming
+    
+    @property
+    def capabilities(self) -> CodecCapability:
+        return CodecCapability.BIDIRECTIONAL
+    
+    @property
+    def aliases(self) -> list[str]:
+        return ["excel", "Excel", "xlsx", "XLSX", "xls", "XLS"]
+    
+    @property
+    def codec_types(self) -> list[str]:
+        """Excel is a data exchange format."""
+        return ["data", "tabular"]
+    
+    # ========================================================================
+    # CORE ENCODE/DECODE (Using pandas)
+    # ========================================================================
+    
+    def encode(self, value: Any, *, options: Optional[EncodeOptions] = None) -> bytes:
+        """
+        Encode data to Excel bytes.
+        
+        Args:
+            value: DataFrame or dict of {sheet_name: DataFrame}
+            options: Excel options (engine, sheet_name, etc.)
+        
+        Returns:
+            Excel file as bytes
+        
+        Raises:
+            SerializationError: If encoding fails
+        """
+        try:
+            # If value is already a DataFrame or dict, use from_df
+            if isinstance(value, (pd.DataFrame, dict)):
+                return self.from_df(value, **(options or {}))
+            
+            # Otherwise, try to serialize as-is (fallback)
+            raise SerializationError(
+                f"Excel encoding requires DataFrame or dict of DataFrames, got {type(value)}",
+                format_name=self.format_name
+            )
+            
+        except Exception as e:
+            raise SerializationError(
+                f"Failed to encode Excel: {e}",
+                format_name=self.format_name,
+                original_error=e
+            )
+    
+    def decode(self, repr: bytes | str, *, options: Optional[DecodeOptions] = None) -> Any:
+        """
+        Decode Excel bytes to DataFrame(s).
+        
+        Args:
+            repr: Excel file as bytes
+            options: Excel options (sheet_name, engine, etc.)
+        
+        Returns:
+            DataFrame or dict of {sheet_name: DataFrame}
+        
+        Raises:
+            SerializationError: If decoding fails
+        """
+        try:
+            if isinstance(repr, str):
+                # If string, treat as file path
+                return self.load_file(repr, **(options or {}))
+            
+            # Use to_df for bytes
+            return self.to_df(repr, **(options or {}))
+            
+        except Exception as e:
+            raise SerializationError(
+                f"Failed to decode Excel: {e}",
+                format_name=self.format_name,
+                original_error=e
+            )
+    
+    # ========================================================================
+    # TABULAR METHODS (to_df/from_df)
+    # ========================================================================
+    
+    def to_df(
+        self, 
+        excel_content: bytes | str | Path, 
+        sheet_name: Optional[str | list[str]] = None,
+        **options
+    ) -> pd.DataFrame | dict[str, pd.DataFrame]:
+        """
+        Convert Excel content to DataFrame(s).
+        
+        Args:
+            excel_content: Excel file as bytes, file path, or Path object
+            sheet_name: Specific sheet name(s) to load, or None for all sheets
+            **options: Additional pandas read_excel options (engine, header, etc.)
+        
+        Returns:
+            Single DataFrame if one sheet, or dict of {sheet_name: DataFrame} if multiple
+        
+        Examples:
+            >>> serializer = ExcelSerializer()
+            >>> df = serializer.to_df(excel_bytes)  # Single sheet
+            >>> sheets = serializer.to_df(excel_bytes)  # All sheets (dict)
+            >>> df = serializer.to_df(excel_bytes, sheet_name="Sheet1")  # Specific sheet
+        """
+        try:
+            # Handle file path
+            if isinstance(excel_content, (str, Path)):
+                file_path = str(excel_content)
+                if sheet_name is None:
+                    # Read all sheets
+                    return pd.read_excel(file_path, sheet_name=None, **options)
+                else:
+                    # Read specific sheet(s)
+                    return pd.read_excel(file_path, sheet_name=sheet_name, **options)
+            
+            # Handle bytes
+            if not excel_content:
+                raise ValueError("Excel content cannot be empty")
+            
+            excel_io = io.BytesIO(excel_content)
+            
+            # Determine engine based on options or file extension
+            engine = options.get('engine', 'openpyxl')  # Default to openpyxl for .xlsx
+            
+            if sheet_name is None:
+                # Read all sheets
+                return pd.read_excel(excel_io, sheet_name=None, engine=engine, **{k: v for k, v in options.items() if k != 'engine'})
+            else:
+                # Read specific sheet(s)
+                result = pd.read_excel(excel_io, sheet_name=sheet_name, engine=engine, **{k: v for k, v in options.items() if k != 'engine'})
+                
+                # If single sheet name, return DataFrame directly
+                if isinstance(sheet_name, str):
+                    return result
+                # If list of sheet names, result is already a dict
+                return result
+            
+        except Exception as e:
+            raise SerializationError(
+                f"Failed to convert Excel to DataFrame: {e}",
+                format_name=self.format_name,
+                original_error=e
+            )
+    
+    def from_df(
+        self, 
+        df: pd.DataFrame | dict[str, pd.DataFrame], 
+        **options
+    ) -> bytes:
+        """
+        Convert DataFrame(s) to Excel bytes.
+        
+        Args:
+            df: Single DataFrame or dict of {sheet_name: DataFrame}
+            **options: Additional pandas to_excel options (engine, index, etc.)
+        
+        Returns:
+            Excel file as bytes
+        
+        Examples:
+            >>> serializer = ExcelSerializer()
+            >>> excel_bytes = serializer.from_df(df)  # Single sheet
+            >>> excel_bytes = serializer.from_df({"Sheet1": df1, "Sheet2": df2})  # Multiple sheets
+        """
+        try:
+            excel_io = io.BytesIO()
+            
+            # Determine engine
+            engine = options.get('engine', 'openpyxl')  # Default to openpyxl
+            
+            if isinstance(df, dict):
+                # Multiple sheets
+                with pd.ExcelWriter(excel_io, engine=engine) as writer:
+                    for sheet_name, sheet_df in df.items():
+                        sheet_df.to_excel(
+                            writer, 
+                            sheet_name=sheet_name,
+                            index=options.get('index', False),
+                            **{k: v for k, v in options.items() if k not in ('engine', 'index')}
+                        )
+            else:
+                # Single sheet
+                df.to_excel(
+                    excel_io,
+                    engine=engine,
+                    index=options.get('index', False),
+                    sheet_name=options.get('sheet_name', 'Sheet1'),
+                    **{k: v for k, v in options.items() if k not in ('engine', 'index', 'sheet_name')}
+                )
+            
+            excel_io.seek(0)
+            return excel_io.read()
+            
+        except Exception as e:
+            raise SerializationError(
+                f"Failed to convert DataFrame to Excel: {e}",
+                format_name=self.format_name,
+                original_error=e
+            )

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

@@ -0,0 +1,374 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/formats/tabular/googlesheets.py
+"""
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.4
+Generation Date: January 2025
+
+Google Sheets serialization.
+
+Following I→A→ATabular pattern:
+- I: ISerialization (interface)
+- A: ASerialization (abstract base)
+- ATabular: ATabularSerialization (tabular base)
+- Concrete: GoogleSheetsSerializer
+
+Note: For local saving, convert to Excel or CSV first.
+For cloud saving, use xwstorage (avoids circular dependencies).
+"""
+
+from typing import Any, Optional
+from pathlib import Path
+
+import pandas as pd
+
+from .base import ATabularSerialization
+from ....contracts import EncodeOptions, DecodeOptions
+from ....defs import CodecCapability
+from ....errors import SerializationError
+
+
+class GoogleSheetsSerializer(ATabularSerialization):
+    """
+    Google Sheets serializer - follows the I→A→ATabular pattern.
+    
+    I: ISerialization (interface)
+    A: ASerialization (abstract base)
+    ATabular: ATabularSerialization (tabular base)
+    Concrete: GoogleSheetsSerializer
+    
+    Uses gspread library for Google Sheets API access.
+    
+    Local saving: Convert to Excel or CSV first, then save.
+    Cloud saving: Use xwstorage (avoids circular dependencies).
+    
+    Examples:
+        >>> serializer = GoogleSheetsSerializer(credentials_path="path/to/credentials.json")
+        >>> 
+        >>> # Read from Google Sheets
+        >>> df = serializer.to_df(spreadsheet_url, sheet_name="Sheet1")
+        >>> sheets = serializer.to_df(spreadsheet_url)  # All sheets
+        >>> 
+        >>> # Write to Google Sheets
+        >>> serializer.from_df(df, spreadsheet_url, sheet_name="Sheet1")
+        >>> serializer.from_df({"Sheet1": df1, "Sheet2": df2}, spreadsheet_url)  # Multiple sheets
+    """
+    
+    def __init__(
+        self, 
+        credentials_path: Optional[str | Path] = None,
+        max_depth: Optional[int] = None, 
+        max_size_mb: Optional[float] = None
+    ):
+        """
+        Initialize Google Sheets serializer.
+        
+        Args:
+            credentials_path: Path to Google service account credentials JSON file
+            max_depth: Maximum nesting depth (inherited from ASerialization)
+            max_size_mb: Maximum size in MB (inherited from ASerialization)
+        """
+        super().__init__(max_depth=max_depth, max_size_mb=max_size_mb)
+        self._credentials_path = str(credentials_path) if credentials_path else None
+        self._client = None
+    
+    def _get_client(self):
+        """Get or create gspread client (lazy initialization)."""
+        if self._client is None:
+            import importlib.util
+            _gspread_spec = importlib.util.find_spec('gspread')
+            _oauth2client_spec = importlib.util.find_spec('oauth2client')
+            
+            if _gspread_spec is None or _oauth2client_spec is None:
+                raise ImportError(
+                    "gspread and oauth2client are required for Google Sheets support. "
+                    "Install with: pip install gspread oauth2client"
+                )
+            
+            import gspread
+            from oauth2client.service_account import ServiceAccountCredentials
+            
+            if not self._credentials_path:
+                raise ValueError("credentials_path is required for Google Sheets access")
+            
+            scope = 'https://www.googleapis.com/auth/spreadsheets'
+            creds = ServiceAccountCredentials.from_json_keyfile_name(
+                self._credentials_path, scope
+            )
+            self._client = gspread.authorize(creds)
+        
+        return self._client
+    
+    # ========================================================================
+    # CODEC METADATA
+    # ========================================================================
+    
+    @property
+    def codec_id(self) -> str:
+        return "googlesheets"
+    
+    @property
+    def media_types(self) -> list[str]:
+        return ["application/vnd.google-apps.spreadsheet"]
+    
+    @property
+    def file_extensions(self) -> list[str]:
+        return []  # Google Sheets don't have local file extensions
+    
+    @property
+    def format_name(self) -> str:
+        return "Google Sheets"
+    
+    @property
+    def mime_type(self) -> str:
+        return "application/vnd.google-apps.spreadsheet"
+    
+    @property
+    def is_binary_format(self) -> bool:
+        return False  # Google Sheets API uses JSON
+    
+    @property
+    def supports_streaming(self) -> bool:
+        return False  # Google Sheets API doesn't support streaming
+    
+    @property
+    def capabilities(self) -> CodecCapability:
+        return CodecCapability.BIDIRECTIONAL
+    
+    @property
+    def aliases(self) -> list[str]:
+        return ["googlesheets", "GoogleSheets", "gsheet", "gsheets"]
+    
+    @property
+    def codec_types(self) -> list[str]:
+        """Google Sheets is a cloud data format."""
+        return ["data", "tabular", "cloud"]
+    
+    # ========================================================================
+    # CORE ENCODE/DECODE
+    # ========================================================================
+    
+    def encode(self, value: Any, *, options: Optional[EncodeOptions] = None) -> str:
+        """
+        Encode data to Google Sheets format.
+        
+        Note: This is a placeholder. Use from_df() with spreadsheet_url instead.
+        
+        Args:
+            value: DataFrame or dict of DataFrames
+            options: Options including spreadsheet_url and sheet_name
+        
+        Returns:
+            Spreadsheet URL (as string representation)
+        
+        Raises:
+            SerializationError: If encoding fails
+        """
+        try:
+            opts = options or {}
+            spreadsheet_url = opts.get('spreadsheet_url')
+            if not spreadsheet_url:
+                raise ValueError("spreadsheet_url is required in options")
+            
+            # Use from_df for actual encoding
+            if isinstance(value, (pd.DataFrame, dict)):
+                self.from_df(value, spreadsheet_url=spreadsheet_url, **(opts or {}))
+                return spreadsheet_url
+            
+            raise ValueError(f"Google Sheets encoding requires DataFrame or dict, got {type(value)}")
+            
+        except Exception as e:
+            raise SerializationError(
+                f"Failed to encode Google Sheets: {e}",
+                format_name=self.format_name,
+                original_error=e
+            )
+    
+    def decode(self, repr: bytes | str, *, options: Optional[DecodeOptions] = None) -> Any:
+        """
+        Decode Google Sheets to DataFrame(s).
+        
+        Args:
+            repr: Spreadsheet URL (as string)
+            options: Options including sheet_name
+        
+        Returns:
+            DataFrame or dict of {sheet_name: DataFrame}
+        
+        Raises:
+            SerializationError: If decoding fails
+        """
+        try:
+            if isinstance(repr, bytes):
+                repr = repr.decode('utf-8')
+            
+            opts = options or {}
+            sheet_name = opts.get('sheet_name')
+            
+            return self.to_df(repr, sheet_name=sheet_name, **(opts or {}))
+            
+        except Exception as e:
+            raise SerializationError(
+                f"Failed to decode Google Sheets: {e}",
+                format_name=self.format_name,
+                original_error=e
+            )
+    
+    # ========================================================================
+    # TABULAR METHODS (to_df/from_df)
+    # ========================================================================
+    
+    def to_df(
+        self, 
+        spreadsheet_url: str, 
+        sheet_name: Optional[str | list[str]] = None,
+        header: int = 0,
+        **options
+    ) -> pd.DataFrame | dict[str, pd.DataFrame]:
+        """
+        Convert Google Sheet to DataFrame(s).
+        
+        Args:
+            spreadsheet_url: Google Sheets URL
+            sheet_name: Specific sheet name(s) to load, or None for all sheets
+            header: Row index to use as header (default: 0)
+            **options: Additional options
+        
+        Returns:
+            Single DataFrame if one sheet, or dict of {sheet_name: DataFrame} if multiple
+        
+        Examples:
+            >>> serializer = GoogleSheetsSerializer(credentials_path="creds.json")
+            >>> df = serializer.to_df(spreadsheet_url, sheet_name="Sheet1")
+            >>> sheets = serializer.to_df(spreadsheet_url)  # All sheets
+        """
+        try:
+            from gspread_dataframe import get_as_dataframe
+            
+            client = self._get_client()
+            spreadsheet = client.open_by_url(spreadsheet_url)
+            
+            if sheet_name is None:
+                # Read all sheets
+                result = {}
+                for worksheet in spreadsheet.worksheets():
+                    try:
+                        df = get_as_dataframe(worksheet, header=header, **options)
+                        result[worksheet.title] = df
+                    except Exception as e:
+                        # Skip sheets that can't be read
+                        continue
+                return result
+            
+            elif isinstance(sheet_name, str):
+                # Read single sheet
+                try:
+                    worksheet = spreadsheet.worksheet(sheet_name)
+                    return get_as_dataframe(worksheet, header=header, **options)
+                except Exception as e:
+                    raise SerializationError(
+                        f"Failed to read sheet '{sheet_name}': {e}",
+                        format_name=self.format_name,
+                        original_error=e
+                    )
+            
+            else:
+                # Read multiple specific sheets
+                result = {}
+                for name in sheet_name:
+                    try:
+                        worksheet = spreadsheet.worksheet(name)
+                        df = get_as_dataframe(worksheet, header=header, **options)
+                        result[name] = df
+                    except Exception as e:
+                        # Skip sheets that can't be read
+                        continue
+                return result
+            
+        except Exception as e:
+            raise SerializationError(
+                f"Failed to convert Google Sheet to DataFrame: {e}",
+                format_name=self.format_name,
+                original_error=e
+            )
+    
+    def from_df(
+        self, 
+        df: pd.DataFrame | dict[str, pd.DataFrame], 
+        spreadsheet_url: str,
+        sheet_name: Optional[str] = None,
+        **options
+    ) -> None:
+        """
+        Convert DataFrame(s) to Google Sheet.
+        
+        Note: This writes directly to Google Sheets (cloud).
+        For local saving, convert to Excel or CSV first.
+        
+        Args:
+            df: Single DataFrame or dict of {sheet_name: DataFrame}
+            spreadsheet_url: Google Sheets URL
+            sheet_name: Sheet name (required if df is single DataFrame)
+            **options: Additional options
+        
+        Examples:
+            >>> serializer = GoogleSheetsSerializer(credentials_path="creds.json")
+            >>> serializer.from_df(df, spreadsheet_url, sheet_name="Sheet1")
+            >>> serializer.from_df({"Sheet1": df1, "Sheet2": df2}, spreadsheet_url)
+        """
+        try:
+            from gspread_dataframe import set_with_dataframe
+            
+            client = self._get_client()
+            spreadsheet = client.open_by_url(spreadsheet_url)
+            
+            if isinstance(df, dict):
+                # Multiple sheets
+                for name, sheet_df in df.items():
+                    try:
+                        try:
+                            worksheet = spreadsheet.worksheet(name)
+                            worksheet.clear()
+                        except Exception:
+                            # Create worksheet if it doesn't exist
+                            worksheet = spreadsheet.add_worksheet(
+                                title=name, rows="2000", cols="30"
+                            )
+                        
+                        set_with_dataframe(worksheet, sheet_df, **options)
+                    except Exception as e:
+                        raise SerializationError(
+                            f"Failed to write sheet '{name}': {e}",
+                            format_name=self.format_name,
+                            original_error=e
+                        )
+            else:
+                # Single sheet
+                if not sheet_name:
+                    raise ValueError("sheet_name is required when writing a single DataFrame")
+                
+                try:
+                    try:
+                        worksheet = spreadsheet.worksheet(sheet_name)
+                        worksheet.clear()
+                    except Exception:
+                        # Create worksheet if it doesn't exist
+                        worksheet = spreadsheet.add_worksheet(
+                            title=sheet_name, rows="2000", cols="30"
+                        )
+                    
+                    set_with_dataframe(worksheet, df, **options)
+                except Exception as e:
+                    raise SerializationError(
+                        f"Failed to write sheet '{sheet_name}': {e}",
+                        format_name=self.format_name,
+                        original_error=e
+                    )
+            
+        except Exception as e:
+            raise SerializationError(
+                f"Failed to convert DataFrame to Google Sheet: {e}",
+                format_name=self.format_name,
+                original_error=e
+            )

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

@@ -1,3 +1,4 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/formats/text/__init__.py
 """Text-based serialization formats."""
 
 from .json import JsonSerializer
@@ -24,4 +25,3 @@ __all__ = [
     "FormDataSerializer",
     "MultipartSerializer",
 ]
-