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

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

@@ -0,0 +1,319 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/formats/tabular/csv.py
+"""
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.3
+Generation Date: January 2025
+
+CSV serialization - Comma-separated values format.
+
+Following I→A→ATabular pattern:
+- I: ISerialization (interface)
+- A: ASerialization (abstract base)
+- ATabular: ATabularSerialization (tabular base)
+- Concrete: CsvSerializer
+
+Moved from text/csv.py and updated to extend ATabularSerialization.
+"""
+
+import csv
+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 CsvSerializer(ATabularSerialization):
+    """
+    CSV serializer - follows the I→A→ATabular pattern.
+    
+    I: ISerialization (interface)
+    A: ASerialization (abstract base)
+    ATabular: ATabularSerialization (tabular base)
+    Concrete: CsvSerializer
+    
+    Uses Python's built-in csv module and pandas for DataFrame operations.
+    
+    Examples:
+        >>> serializer = CsvSerializer()
+        >>> 
+        >>> # Encode list of dicts
+        >>> csv_str = serializer.encode([
+        ...     {"name": "John", "age": 30},
+        ...     {"name": "Jane", "age": 25}
+        ... ])
+        >>> 
+        >>> # Decode to list of dicts
+        >>> data = serializer.decode(csv_str)
+        >>> 
+        >>> # Convert DataFrame to CSV
+        >>> csv_str = serializer.from_df(df)
+        >>> 
+        >>> # Convert CSV to DataFrame
+        >>> df = serializer.to_df(csv_str)
+        >>> 
+        >>> # Save to file
+        >>> serializer.save_file(rows, "data.csv")
+        >>> 
+        >>> # Load from file
+        >>> rows = serializer.load_file("data.csv")
+    """
+    
+    # ========================================================================
+    # CODEC METADATA
+    # ========================================================================
+    
+    @property
+    def codec_id(self) -> str:
+        return "csv"
+    
+    @property
+    def media_types(self) -> list[str]:
+        return ["text/csv", "application/csv"]
+    
+    @property
+    def file_extensions(self) -> list[str]:
+        return [".csv", ".tsv", ".psv"]
+    
+    @property
+    def format_name(self) -> str:
+        return "CSV"
+    
+    @property
+    def mime_type(self) -> str:
+        return "text/csv"
+    
+    @property
+    def is_binary_format(self) -> bool:
+        return False  # CSV is text-based
+    
+    @property
+    def supports_streaming(self) -> bool:
+        return True  # CSV naturally supports streaming (row by row)
+    
+    @property
+    def capabilities(self) -> CodecCapability:
+        return CodecCapability.BIDIRECTIONAL
+    
+    @property
+    def aliases(self) -> list[str]:
+        return ["csv", "CSV", "tsv", "TSV"]
+    
+    @property
+    def codec_types(self) -> list[str]:
+        """CSV is primarily a data exchange format."""
+        return ["data", "tabular"]
+    
+    # ========================================================================
+    # CORE ENCODE/DECODE (Using csv module)
+    # ========================================================================
+    
+    def encode(self, value: Any, *, options: Optional[EncodeOptions] = None) -> str:
+        """
+        Encode data to CSV string.
+        
+        Uses csv.DictWriter or csv.writer.
+        
+        Args:
+            value: Data to serialize (list of dicts, list of lists, or DataFrame)
+            options: CSV options (delimiter, quoting, etc.)
+        
+        Returns:
+            CSV string
+        
+        Raises:
+            SerializationError: If encoding fails
+        """
+        try:
+            # If DataFrame, use from_df
+            if isinstance(value, pd.DataFrame):
+                return self.from_df(value, **(options or {}))
+            
+            opts = options or {}
+            
+            # Get CSV options
+            delimiter = opts.get('delimiter', ',')
+            quoting = opts.get('quoting', csv.QUOTE_MINIMAL)
+            
+            # Create string buffer
+            output = io.StringIO()
+            
+            if isinstance(value, list) and value:
+                if isinstance(value[0], dict):
+                    # List of dicts - use DictWriter
+                    fieldnames = opts.get('fieldnames', list(value[0].keys()))
+                    writer = csv.DictWriter(
+                        output,
+                        fieldnames=fieldnames,
+                        delimiter=delimiter,
+                        quoting=quoting
+                    )
+                    
+                    # Write header
+                    if opts.get('header', True):
+                        writer.writeheader()
+                    
+                    # Write rows
+                    writer.writerows(value)
+                else:
+                    # List of lists - use regular writer
+                    writer = csv.writer(
+                        output,
+                        delimiter=delimiter,
+                        quoting=quoting
+                    )
+                    writer.writerows(value)
+            
+            return output.getvalue()
+            
+        except Exception as e:
+            raise SerializationError(
+                f"Failed to encode CSV: {e}",
+                format_name=self.format_name,
+                original_error=e
+            )
+    
+    def decode(self, repr: bytes | str, *, options: Optional[DecodeOptions] = None) -> Any:
+        """
+        Decode CSV string to data.
+        
+        Uses csv.DictReader or csv.reader.
+        
+        Args:
+            repr: CSV string (bytes or str)
+            options: CSV options (delimiter, has_header, etc.)
+        
+        Returns:
+            List of dicts (if header) or list of lists
+        
+        Raises:
+            SerializationError: If decoding fails
+        """
+        try:
+            # Convert bytes to str if needed
+            if isinstance(repr, bytes):
+                repr = repr.decode('utf-8')
+            
+            opts = options or {}
+            
+            # Get CSV options
+            delimiter = opts.get('delimiter', ',')
+            has_header = opts.get('header', True)
+            
+            # Create string buffer
+            input_stream = io.StringIO(repr)
+            
+            if has_header:
+                # Use DictReader for header-based CSV
+                reader = csv.DictReader(input_stream, delimiter=delimiter)
+                data = list(reader)
+            else:
+                # Use regular reader for headerless CSV
+                reader = csv.reader(input_stream, delimiter=delimiter)
+                data = list(reader)
+            
+            return data
+            
+        except (Exception, UnicodeDecodeError) as e:
+            raise SerializationError(
+                f"Failed to decode CSV: {e}",
+                format_name=self.format_name,
+                original_error=e
+            )
+    
+    # ========================================================================
+    # TABULAR METHODS (to_df/from_df)
+    # ========================================================================
+    
+    def to_df(
+        self, 
+        csv_content: bytes | str | Path, 
+        sheet_name: Optional[str | list[str]] = None,
+        **options
+    ) -> pd.DataFrame:
+        """
+        Convert CSV content to DataFrame.
+        
+        Note: CSV doesn't support multiple sheets, so sheet_name is ignored.
+        
+        Args:
+            csv_content: CSV content as bytes, string, or file path
+            sheet_name: Ignored (CSV doesn't support multiple sheets)
+            **options: Additional pandas read_csv options (delimiter, header, etc.)
+        
+        Returns:
+            DataFrame
+        
+        Examples:
+            >>> serializer = CsvSerializer()
+            >>> df = serializer.to_df(csv_str)
+            >>> df = serializer.to_df("data.csv")
+        """
+        try:
+            # Handle file path
+            if isinstance(csv_content, (str, Path)):
+                file_path = str(csv_content)
+                return pd.read_csv(file_path, **options)
+            
+            # Handle bytes or string
+            if isinstance(csv_content, bytes):
+                csv_content = csv_content.decode('utf-8')
+            
+            # Use StringIO for in-memory CSV
+            csv_io = io.StringIO(csv_content)
+            return pd.read_csv(csv_io, **options)
+            
+        except Exception as e:
+            raise SerializationError(
+                f"Failed to convert CSV to DataFrame: {e}",
+                format_name=self.format_name,
+                original_error=e
+            )
+    
+    def from_df(
+        self, 
+        df: pd.DataFrame, 
+        **options
+    ) -> str:
+        """
+        Convert DataFrame to CSV string.
+        
+        Note: CSV doesn't support multiple sheets, so dict input is not supported.
+        
+        Args:
+            df: Single DataFrame
+            **options: Additional pandas to_csv options (index, delimiter, etc.)
+        
+        Returns:
+            CSV string
+        
+        Examples:
+            >>> serializer = CsvSerializer()
+            >>> csv_str = serializer.from_df(df)
+        """
+        try:
+            if isinstance(df, dict):
+                raise ValueError("CSV format does not support multiple sheets. Use a single DataFrame.")
+            
+            # Use StringIO to capture CSV output
+            output = io.StringIO()
+            df.to_csv(
+                output,
+                index=options.get('index', False),
+                **{k: v for k, v in options.items() if k != 'index'}
+            )
+            return output.getvalue()
+            
+        except Exception as e:
+            raise SerializationError(
+                f"Failed to convert DataFrame to CSV: {e}",
+                format_name=self.format_name,
+                original_error=e
+            )

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

@@ -0,0 +1,249 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/formats/tabular/df.py
+"""
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.3
+Generation Date: January 2025
+
+DataFrame serialization - Direct pandas DataFrame operations.
+
+Following I→A→ATabular pattern:
+- I: ISerialization (interface)
+- A: ASerialization (abstract base)
+- ATabular: ATabularSerialization (tabular base)
+- Concrete: DataFrameSerializer
+
+Useful for intermediate DataFrame processing and format conversion.
+"""
+
+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 DataFrameSerializer(ATabularSerialization):
+    """
+    DataFrame serializer - follows the I→A→ATabular pattern.
+    
+    I: ISerialization (interface)
+    A: ASerialization (abstract base)
+    ATabular: ATabularSerialization (tabular base)
+    Concrete: DataFrameSerializer
+    
+    Direct DataFrame operations - useful for intermediate processing.
+    
+    Examples:
+        >>> serializer = DataFrameSerializer()
+        >>> 
+        >>> # Convert DataFrame to bytes (pickle)
+        >>> df_bytes = serializer.from_df(df)
+        >>> 
+        >>> # Convert bytes to DataFrame
+        >>> df = serializer.to_df(df_bytes)
+        >>> 
+        >>> # Save DataFrame
+        >>> serializer.save_file(df, "data.pkl")
+        >>> 
+        >>> # Load DataFrame
+        >>> df = serializer.load_file("data.pkl")
+    """
+    
+    # ========================================================================
+    # CODEC METADATA
+    # ========================================================================
+    
+    @property
+    def codec_id(self) -> str:
+        return "dataframe"
+    
+    @property
+    def media_types(self) -> list[str]:
+        return [
+            "application/x-pandas-dataframe",
+            "application/x-pickle",
+        ]
+    
+    @property
+    def file_extensions(self) -> list[str]:
+        return [".pkl", ".pickle", ".df"]
+    
+    @property
+    def format_name(self) -> str:
+        return "DataFrame"
+    
+    @property
+    def mime_type(self) -> str:
+        return "application/x-pandas-dataframe"
+    
+    @property
+    def is_binary_format(self) -> bool:
+        return True  # DataFrame pickle is binary
+    
+    @property
+    def supports_streaming(self) -> bool:
+        return False  # DataFrames don't naturally support streaming
+    
+    @property
+    def capabilities(self) -> CodecCapability:
+        return CodecCapability.BIDIRECTIONAL
+    
+    @property
+    def aliases(self) -> list[str]:
+        return ["dataframe", "DataFrame", "df", "pandas", "pkl"]
+    
+    @property
+    def codec_types(self) -> list[str]:
+        """DataFrame is an intermediate data format."""
+        return ["data", "tabular", "intermediate"]
+    
+    # ========================================================================
+    # CORE ENCODE/DECODE (Using pickle)
+    # ========================================================================
+    
+    def encode(self, value: Any, *, options: Optional[EncodeOptions] = None) -> bytes:
+        """
+        Encode DataFrame to pickle bytes.
+        
+        Args:
+            value: DataFrame or dict of {sheet_name: DataFrame}
+            options: Pickle options (protocol, etc.)
+        
+        Returns:
+            Pickled DataFrame as bytes
+        
+        Raises:
+            SerializationError: If encoding fails
+        """
+        try:
+            import pickle
+            
+            opts = options or {}
+            protocol = opts.get('protocol', pickle.HIGHEST_PROTOCOL)
+            
+            return pickle.dumps(value, protocol=protocol)
+            
+        except Exception as e:
+            raise SerializationError(
+                f"Failed to encode DataFrame: {e}",
+                format_name=self.format_name,
+                original_error=e
+            )
+    
+    def decode(self, repr: bytes | str, *, options: Optional[DecodeOptions] = None) -> Any:
+        """
+        Decode pickle bytes to DataFrame(s).
+        
+        Args:
+            repr: Pickled DataFrame as bytes, or file path
+            options: Decode options
+        
+        Returns:
+            DataFrame or dict of {sheet_name: DataFrame}
+        
+        Raises:
+            SerializationError: If decoding fails
+        """
+        try:
+            import pickle
+            
+            # Handle file path
+            if isinstance(repr, (str, Path)):
+                with open(repr, 'rb') as f:
+                    return pickle.load(f)
+            
+            # Handle bytes
+            if isinstance(repr, str):
+                repr = repr.encode('utf-8')
+            
+            return pickle.loads(repr)
+            
+        except Exception as e:
+            raise SerializationError(
+                f"Failed to decode DataFrame: {e}",
+                format_name=self.format_name,
+                original_error=e
+            )
+    
+    # ========================================================================
+    # TABULAR METHODS (to_df/from_df)
+    # ========================================================================
+    
+    def to_df(
+        self, 
+        data: bytes | str | Path, 
+        sheet_name: Optional[str | list[str]] = None,
+        **options
+    ) -> pd.DataFrame | dict[str, pd.DataFrame]:
+        """
+        Convert pickled data to DataFrame(s).
+        
+        Args:
+            data: Pickled DataFrame as bytes, or file path
+            sheet_name: Ignored (pickle preserves structure)
+            **options: Decode options
+        
+        Returns:
+            DataFrame or dict of {sheet_name: DataFrame} (as stored)
+        
+        Examples:
+            >>> serializer = DataFrameSerializer()
+            >>> df = serializer.to_df(pickled_bytes)
+            >>> df = serializer.to_df("data.pkl")
+        """
+        try:
+            # Use decode method
+            result = self.decode(data, **(options or {}))
+            
+            # If sheet_name specified and result is dict, filter
+            if sheet_name is not None and isinstance(result, dict):
+                if isinstance(sheet_name, str):
+                    return result.get(sheet_name)
+                else:
+                    return {name: result.get(name) for name in sheet_name if name in result}
+            
+            return result
+            
+        except Exception as e:
+            raise SerializationError(
+                f"Failed to convert 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 pickle bytes.
+        
+        Args:
+            df: Single DataFrame or dict of {sheet_name: DataFrame}
+            **options: Pickle options (protocol, etc.)
+        
+        Returns:
+            Pickled DataFrame as bytes
+        
+        Examples:
+            >>> serializer = DataFrameSerializer()
+            >>> bytes = serializer.from_df(df)
+            >>> bytes = serializer.from_df({"Sheet1": df1, "Sheet2": df2})
+        """
+        try:
+            # Use encode method
+            return self.encode(df, **(options or {}))
+            
+        except Exception as e:
+            raise SerializationError(
+                f"Failed to convert DataFrame: {e}",
+                format_name=self.format_name,
+                original_error=e
+            )