aspose-cells-foss 25.12.1__py3-none-any.whl

aspose/cells/utils/validation.py

@@ -0,0 +1,102 @@
+"""
+Data validation utilities for Excel operations.
+"""
+
+from typing import Union
+from datetime import datetime
+import re
+
+from ..formats import CellValue
+from ..constants import (
+    MAX_SHEET_NAME_LENGTH, INVALID_SHEET_NAME_CHARS,
+    CELL_REF_PATTERN, DEFAULT_SHEET_NAME
+)
+
+
+def is_numeric_string(value: str) -> bool:
+    """Check if string represents a numeric value."""
+    try:
+        float(value)
+        return True
+    except (ValueError, TypeError):
+        return False
+
+
+def is_formula(value: str) -> bool:
+    """Check if string represents an Excel formula."""
+    return isinstance(value, str) and value.startswith('=')
+
+
+def is_date_value(value: CellValue) -> bool:
+    """Check if value represents a date."""
+    return isinstance(value, datetime)
+
+
+def infer_data_type(value: CellValue) -> str:
+    """Infer Excel data type from Python value."""
+    if value is None:
+        return 'empty'
+    elif isinstance(value, bool):
+        return 'boolean'
+    elif isinstance(value, (int, float)):
+        return 'number'
+    elif isinstance(value, datetime):
+        return 'date'
+    elif isinstance(value, str):
+        if is_formula(value):
+            return 'formula'
+        elif is_numeric_string(value):
+            return 'number'
+        else:
+            return 'string'
+    else:
+        return 'string'
+
+
+def validate_sheet_name(name: str) -> bool:
+    """Validate Excel worksheet name."""
+    if not name or len(name) > MAX_SHEET_NAME_LENGTH:
+        return False
+    
+    return not any(char in name for char in INVALID_SHEET_NAME_CHARS)
+
+
+def sanitize_sheet_name(name: str) -> str:
+    """Sanitize worksheet name for Excel compatibility."""
+    if not name:
+        return DEFAULT_SHEET_NAME + "1"
+    
+    # Remove invalid characters
+    for char in INVALID_SHEET_NAME_CHARS:
+        name = name.replace(char, '_')
+    
+    # Truncate to maximum length
+    if len(name) > MAX_SHEET_NAME_LENGTH:
+        name = name[:MAX_SHEET_NAME_LENGTH]
+    
+    return name or DEFAULT_SHEET_NAME + "1"
+
+
+def validate_cell_reference(ref: str) -> bool:
+    """Validate Excel cell reference format (e.g., A1, Z99, AA100)."""
+    if not ref or not isinstance(ref, str):
+        return False
+    
+    return bool(re.match(CELL_REF_PATTERN, ref.upper()))
+
+
+def convert_value(value: CellValue, target_type: str, default: CellValue = None) -> CellValue:
+    """Convert value to target type with fallback to default."""
+    try:
+        if target_type == 'string':
+            return str(value) if value is not None else ""
+        elif target_type == 'int':
+            return int(float(str(value)))
+        elif target_type == 'float':
+            return float(value)
+        elif target_type == 'bool':
+            return bool(value)
+        else:
+            return value
+    except (ValueError, TypeError):
+        return default

aspose/cells/workbook.py

@@ -0,0 +1,352 @@
+"""
+Workbook implementation with unified API and multiple file format support.
+"""
+
+from typing import Dict, List, Optional, Union
+from pathlib import Path
+
+from .worksheet import Worksheet
+from .formats import FileFormat, ConversionOptions
+from .utils import (
+    sanitize_sheet_name,
+    WorksheetNotFoundError,
+    FileFormatError,
+    ExportError
+)
+from .io.factory import FormatHandlerFactory
+from .io.models import WorkbookData
+
+
+
+
+class WorksheetCollection:
+    """Collection manager for worksheets with multiple access patterns."""
+    
+    def __init__(self, workbook: 'Workbook'):
+        self._workbook = workbook
+    
+    def add(self, name: str) -> Worksheet:
+        """Add new worksheet with specified name."""
+        clean_name = sanitize_sheet_name(name)
+        if clean_name in self._workbook._worksheets:
+            # Generate unique name
+            counter = 1
+            base_name = clean_name
+            while clean_name in self._workbook._worksheets:
+                clean_name = f"{base_name}_{counter}"
+                counter += 1
+        
+        worksheet = Worksheet(self._workbook, clean_name)
+        self._workbook._worksheets[clean_name] = worksheet
+        return worksheet
+    
+    def remove(self, name: Union[str, int, Worksheet]):
+        """Remove worksheet by name, index, or object."""
+        if isinstance(name, Worksheet):
+            name = name.name
+        elif isinstance(name, int):
+            sheets = list(self._workbook._worksheets.values())
+            if 0 <= name < len(sheets):
+                name = sheets[name].name
+            else:
+                raise WorksheetNotFoundError(f"Worksheet index {name} out of range")
+        
+        if name not in self._workbook._worksheets:
+            raise WorksheetNotFoundError(f"Worksheet '{name}' not found")
+        
+        # Don't allow removing the last worksheet
+        if len(self._workbook._worksheets) <= 1:
+            raise WorksheetNotFoundError("Cannot remove the last worksheet")
+        
+        # Update active sheet if necessary
+        if self._workbook._active_sheet and self._workbook._active_sheet.name == name:
+            remaining_sheets = [ws for ws in self._workbook._worksheets.values() if ws.name != name]
+            self._workbook._active_sheet = remaining_sheets[0]
+        
+        del self._workbook._worksheets[name]
+    
+    def __getitem__(self, key: Union[str, int]) -> Worksheet:
+        """Get worksheet by name or index."""
+        if isinstance(key, str):
+            if key not in self._workbook._worksheets:
+                raise WorksheetNotFoundError(f"Worksheet '{key}' not found")
+            return self._workbook._worksheets[key]
+        elif isinstance(key, int):
+            sheets = list(self._workbook._worksheets.values())
+            if 0 <= key < len(sheets):
+                return sheets[key]
+            else:
+                raise WorksheetNotFoundError(f"Worksheet index {key} out of range")
+        else:
+            raise WorksheetNotFoundError(f"Invalid worksheet key: {key}")
+    
+    def __len__(self) -> int:
+        """Number of worksheets."""
+        return len(self._workbook._worksheets)
+    
+    def __iter__(self):
+        """Iterate over worksheets."""
+        return iter(self._workbook._worksheets.values())
+    
+    def __contains__(self, name: str) -> bool:
+        """Check if worksheet exists."""
+        return name in self._workbook._worksheets
+
+
+class Workbook:
+    """Excel workbook with unified API and multiple access patterns."""
+    
+    def __init__(self, filename: Optional[Union[str, Path]] = None):
+        self._filename: Optional[Path] = None
+        self._worksheets: Dict[str, Worksheet] = {}
+        self._active_sheet: Optional[Worksheet] = None
+        self._shared_strings: List[str] = []
+        self._properties: Dict[str, Union[str, int, float, bool]] = {}
+        
+        # Initialize with default worksheet
+        default_sheet = Worksheet(self, "Sheet1")
+        self._worksheets["Sheet1"] = default_sheet
+        self._active_sheet = default_sheet
+        
+        if filename:
+            self._load_from_file(filename)
+    
+    @classmethod
+    def load(cls, filename: Union[str, Path]) -> 'Workbook':
+        """Load workbook from file."""
+        return cls(filename)
+    
+    @property
+    def active(self) -> Worksheet:
+        """Get active worksheet."""
+        if self._active_sheet is None and self._worksheets:
+            self._active_sheet = next(iter(self._worksheets.values()))
+        return self._active_sheet
+    
+    @active.setter
+    def active(self, value: Union[Worksheet, str, int]):
+        """Set active worksheet by object, name, or index."""
+        if isinstance(value, Worksheet):
+            if value in self._worksheets.values():
+                self._active_sheet = value
+            else:
+                raise WorksheetNotFoundError("Worksheet not in this workbook")
+        elif isinstance(value, str):
+            if value in self._worksheets:
+                self._active_sheet = self._worksheets[value]
+            else:
+                raise WorksheetNotFoundError(f"Worksheet '{value}' not found")
+        elif isinstance(value, int):
+            sheets = list(self._worksheets.values())
+            if 0 <= value < len(sheets):
+                self._active_sheet = sheets[value]
+            else:
+                raise WorksheetNotFoundError(f"Worksheet index {value} out of range")
+        else:
+            raise WorksheetNotFoundError(f"Invalid active sheet value: {value}")
+    
+    @property
+    def worksheets(self) -> WorksheetCollection:
+        """Get worksheet collection manager."""
+        return WorksheetCollection(self)
+    
+    @property
+    def sheetnames(self) -> List[str]:
+        """Get list of worksheet names."""
+        return list(self._worksheets.keys())
+    
+    def create_sheet(self, name: str = None, index: int = None) -> Worksheet:
+        """Create new worksheet with optional name and position."""
+        if name is None:
+            # Generate default name
+            counter = len(self._worksheets) + 1
+            while f"Sheet{counter}" in self._worksheets:
+                counter += 1
+            name = f"Sheet{counter}"
+        
+        worksheet = self.worksheets.add(name)
+        
+        # Handle index positioning if specified
+        if index is not None and 0 <= index < len(self._worksheets):
+            # Re-order worksheets to insert at specific position
+            sheet_items = list(self._worksheets.items())
+            # Remove the newly added sheet from its current position (last)
+            new_sheet_item = sheet_items.pop()
+            # Insert it at the specified index
+            sheet_items.insert(index, new_sheet_item)
+            # Rebuild the ordered dictionary
+            self._worksheets.clear()
+            for sheet_name, sheet_obj in sheet_items:
+                self._worksheets[sheet_name] = sheet_obj
+        
+        return worksheet
+    
+    def _load_from_file(self, filename: Union[str, Path]):
+        """Load workbook from file using unified format factory."""
+        self._filename = Path(filename)
+        
+        if not self._filename.exists():
+            raise FileFormatError(f"File not found: {filename}")
+        
+        # Try unified format handler first
+        handler = FormatHandlerFactory.get_handler(str(filename))
+        if handler:
+            handler.load_workbook(self, str(filename))
+        else:
+            # Fall back to legacy reader for unsupported formats
+            if self._filename.suffix.lower() not in ['.xlsx', '.xlsm', '.xltx', '.xltm']:
+                raise FileFormatError(f"Unsupported file format: {self._filename.suffix}")
+            
+            from .io.xlsx.reader import XlsxReader
+            reader = XlsxReader()
+            reader.load_workbook(self, str(filename))
+    
+    def save(self, filename: Optional[Union[str, Path]] = None, 
+             format: Optional[Union[str, FileFormat]] = None, **kwargs):
+        """Save workbook to file with specified format using unified factory."""
+        if filename is None:
+            if self._filename is None:
+                raise FileFormatError("No filename specified and no previous filename available")
+            filename = self._filename
+        else:
+            filename = Path(filename)
+        
+        # If format is specified, modify filename extension
+        if format is not None:
+            if isinstance(format, str):
+                # Convert string to FileFormat enum if possible
+                try:
+                    format_enum = FileFormat(format)
+                    filename = filename.with_suffix(format_enum.extension)
+                except ValueError:
+                    # For unsupported format strings, try to use them directly
+                    if not format.startswith('.'):
+                        format = '.' + format
+                    filename = filename.with_suffix(format)
+            else:
+                filename = filename.with_suffix(format.extension)
+        
+        # Try unified format handler first
+        handler = FormatHandlerFactory.get_handler(str(filename))
+        if handler:
+            handler.save_workbook(self, str(filename), **kwargs)
+        else:
+            # Fall back to legacy writer
+            if format is None:
+                format = FileFormat.from_extension(filename)
+            elif isinstance(format, str):
+                try:
+                    format = FileFormat(format)
+                except ValueError:
+                    raise FileFormatError(f"Unsupported format: {format}")
+            
+            from .io.xlsx.writer import XlsxWriter
+            writer = XlsxWriter()
+            writer.save_workbook(self, str(filename), **kwargs)
+        
+        self._filename = Path(filename)
+    
+    def exportAs(self, format: Union[str, FileFormat], **kwargs) -> str:
+        """Export workbook as string in specified format."""
+        # Convert string to FileFormat enum if needed
+        if isinstance(format, str):
+            try:
+                format_enum = FileFormat(format)
+            except ValueError:
+                raise ExportError(f"Unsupported export format: {format}")
+        else:
+            format_enum = format
+        
+        if format_enum == FileFormat.JSON:
+            from .converters.json_converter import JsonConverter
+            converter = JsonConverter()
+            return converter.convert_workbook(self, **kwargs)
+        elif format_enum == FileFormat.CSV:
+            from .converters.csv_converter import CsvConverter
+            converter = CsvConverter()
+            return converter.convert_workbook(self, **kwargs)
+        elif format_enum == FileFormat.MARKDOWN:
+            from .converters.markdown_converter import MarkdownConverter
+            converter = MarkdownConverter()
+            return converter.convert_workbook(self, **kwargs)
+        else:
+            raise ExportError(f"Unsupported export format: {format_enum.value}")
+    
+    def copy_worksheet(self, from_worksheet: Union[Worksheet, str]) -> Worksheet:
+        """Create a copy of existing worksheet."""
+        if isinstance(from_worksheet, str):
+            if from_worksheet not in self._worksheets:
+                raise WorksheetNotFoundError(f"Source worksheet '{from_worksheet}' not found")
+            source = self._worksheets[from_worksheet]
+        else:
+            source = from_worksheet
+        
+        # Generate new name
+        base_name = f"Copy of {source.name}"
+        new_name = base_name
+        counter = 1
+        while new_name in self._worksheets:
+            new_name = f"{base_name} ({counter})"
+            counter += 1
+        
+        # Create new worksheet
+        new_worksheet = self.create_sheet(new_name)
+        
+        # Copy all cell data and formatting
+        for coord, cell in source._cells.items():
+            row, col = coord
+            new_cell = new_worksheet.cell(row, col, cell.value)
+            if cell._style:
+                new_cell._style = cell._style.copy()
+            new_cell._number_format = cell._number_format
+            new_cell._hyperlink = cell._hyperlink
+            new_cell._comment = cell._comment
+        
+        # Copy other properties
+        new_worksheet._merged_ranges = source._merged_ranges.copy()
+        new_worksheet._row_heights = source._row_heights.copy()
+        new_worksheet._column_widths = source._column_widths.copy()
+        new_worksheet._freeze_panes = source._freeze_panes
+        
+        return new_worksheet
+    
+    def convert_to(self, target_format: str, output_path: str, **options) -> None:
+        """Convert workbook to different format using unified data model."""
+        # Convert workbook to unified data model
+        data = WorkbookData.from_workbook(self)
+        
+        # Get target format handler
+        handler = FormatHandlerFactory.get_handler(output_path)
+        if not handler:
+            raise FileFormatError(f"Unsupported target format: {Path(output_path).suffix}")
+        
+        # Write using unified data model
+        handler.write_from_data(data, output_path, **options)
+    
+    def close(self):
+        """Close workbook and release resources."""
+        self._worksheets.clear()
+        self._active_sheet = None
+        self._shared_strings.clear()
+        self._properties.clear()
+    
+    @property
+    def properties(self) -> Dict[str, Union[str, int, float, bool]]:
+        """Get workbook properties."""
+        return self._properties
+    
+    def __enter__(self):
+        """Context manager entry."""
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit."""
+        self.close()
+    
+    def __str__(self) -> str:
+        """String representation."""
+        return f"Workbook({len(self._worksheets)} sheets)"
+    
+    def __repr__(self) -> str:
+        """Debug representation."""
+        return f"Workbook(sheets={list(self._worksheets.keys())}, active='{self.active.name if self.active else None}')"