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

aspose/cells/range.py

@@ -0,0 +1,210 @@
+"""
+Range implementation for operating on multiple cells as a group.
+"""
+
+from typing import List, Iterator, Tuple, Union, TYPE_CHECKING
+from .formats import CellValue
+from .utils import parse_range, InvalidCoordinateError
+from .style import Style, Font, Fill
+
+if TYPE_CHECKING:
+    from .worksheet import Worksheet
+    from .cell import Cell
+
+
+class Range:
+    """Excel range representing a rectangular area of cells."""
+    
+    def __init__(self, worksheet: 'Worksheet', range_string: str):
+        self._worksheet = worksheet
+        self._range_string = range_string.upper()
+        
+        try:
+            (self._start_row, self._start_col), (self._end_row, self._end_col) = parse_range(range_string)
+        except Exception as e:
+            raise InvalidCoordinateError(f"Invalid range format: {range_string}") from e
+        
+        # Ensure start <= end
+        if self._start_row > self._end_row:
+            self._start_row, self._end_row = self._end_row, self._start_row
+        if self._start_col > self._end_col:
+            self._start_col, self._end_col = self._end_col, self._start_col
+    
+    @property
+    def coordinate(self) -> str:
+        """Range coordinate string."""
+        return self._range_string
+    
+    @property
+    def min_row(self) -> int:
+        """Minimum row in range."""
+        return self._start_row
+    
+    @property
+    def max_row(self) -> int:
+        """Maximum row in range."""
+        return self._end_row
+    
+    @property
+    def min_column(self) -> int:
+        """Minimum column in range."""
+        return self._start_col
+    
+    @property
+    def max_column(self) -> int:
+        """Maximum column in range."""
+        return self._end_col
+    
+    @property
+    def row_count(self) -> int:
+        """Number of rows in range."""
+        return self._end_row - self._start_row + 1
+    
+    @property
+    def column_count(self) -> int:
+        """Number of columns in range."""
+        return self._end_col - self._start_col + 1
+    
+    @property
+    def size(self) -> Tuple[int, int]:
+        """Range size as (rows, columns)."""
+        return self.row_count, self.column_count
+    
+    def cells(self) -> Iterator['Cell']:
+        """Iterate over all cells in range."""
+        for row in range(self._start_row, self._end_row + 1):
+            for col in range(self._start_col, self._end_col + 1):
+                yield self._worksheet.cell(row, col)
+    
+    def rows_iter(self) -> Iterator[List['Cell']]:
+        """Iterate over rows of cells."""
+        for row in range(self._start_row, self._end_row + 1):
+            row_cells = []
+            for col in range(self._start_col, self._end_col + 1):
+                row_cells.append(self._worksheet.cell(row, col))
+            yield row_cells
+    
+    def columns_iter(self) -> Iterator[List['Cell']]:
+        """Iterate over columns of cells."""
+        for col in range(self._start_col, self._end_col + 1):
+            col_cells = []
+            for row in range(self._start_row, self._end_row + 1):
+                col_cells.append(self._worksheet.cell(row, col))
+            yield col_cells
+    
+    def rows(self) -> Iterator[List['Cell']]:
+        """Iterate over rows of cells (alias for rows_iter for test compatibility)."""
+        return self.rows_iter()
+    
+    def columns(self) -> Iterator[List['Cell']]:
+        """Iterate over columns of cells (alias for columns_iter for test compatibility)."""
+        return self.columns_iter()
+    
+    @property
+    def values(self) -> List[List[CellValue]]:
+        """Get all values as nested list."""
+        result = []
+        for row in range(self._start_row, self._end_row + 1):
+            row_values = []
+            for col in range(self._start_col, self._end_col + 1):
+                cell = self._worksheet.cell(row, col)
+                row_values.append(cell.value)
+            result.append(row_values)
+        return result
+    
+    @values.setter
+    def values(self, data: Union[List[List[CellValue]], List[CellValue], CellValue]):
+        """Set values from nested list or single value."""
+        if not isinstance(data, list):
+            # Single value - apply to all cells
+            for cell in self.cells():
+                cell.value = data
+            return
+        
+        if not data:
+            return
+        
+        # Check if it's a list of lists (2D) or single list (1D)
+        if isinstance(data[0], list):
+            # 2D data
+            for row_idx, row_data in enumerate(data):
+                if row_idx >= self.row_count:
+                    break
+                for col_idx, value in enumerate(row_data):
+                    if col_idx >= self.column_count:
+                        break
+                    cell = self._worksheet.cell(
+                        self._start_row + row_idx,
+                        self._start_col + col_idx
+                    )
+                    cell.value = value
+        else:
+            # 1D data - fill row by row
+            flat_index = 0
+            for row in range(self._start_row, self._end_row + 1):
+                for col in range(self._start_col, self._end_col + 1):
+                    if flat_index >= len(data):
+                        return
+                    cell = self._worksheet.cell(row, col)
+                    cell.value = data[flat_index]
+                    flat_index += 1
+    
+    @property
+    def font(self) -> Font:
+        """Get font of first cell (for styling entire range)."""
+        first_cell = self._worksheet.cell(self._start_row, self._start_col)
+        return first_cell.font
+    
+    @font.setter
+    def font(self, value: Font):
+        """Apply font to entire range."""
+        for cell in self.cells():
+            cell.style.font = value.copy()
+    
+    @property
+    def fill(self) -> Fill:
+        """Get fill of first cell (for styling entire range)."""
+        first_cell = self._worksheet.cell(self._start_row, self._start_col)
+        return first_cell.fill
+    
+    @fill.setter
+    def fill(self, value: Fill):
+        """Apply fill to entire range."""
+        for cell in self.cells():
+            cell.style.fill = value.copy()
+    
+    def apply_style(self, style: Style):
+        """Apply complete style to entire range."""
+        for cell in self.cells():
+            cell.style = style.copy()
+    
+    def clear(self):
+        """Clear all values and formatting in range."""
+        for cell in self.cells():
+            cell.clear()
+    
+    def merge(self):
+        """Mark range for merging (implementation depends on writer)."""
+        if hasattr(self._worksheet, '_merged_ranges'):
+            self._worksheet._merged_ranges.add(self._range_string)
+    
+    def unmerge(self):
+        """Unmerge previously merged range."""
+        if hasattr(self._worksheet, '_merged_ranges'):
+            self._worksheet._merged_ranges.discard(self._range_string)
+    
+    def __str__(self) -> str:
+        """String representation."""
+        return f"Range({self._range_string})"
+    
+    def __repr__(self) -> str:
+        """Debug representation."""
+        return f"Range('{self._range_string}', {self.row_count}x{self.column_count})"
+    
+    def __iter__(self) -> Iterator['Cell']:
+        """Iterate over cells."""
+        return self.cells()
+    
+    def __len__(self) -> int:
+        """Number of cells in range."""
+        return self.row_count * self.column_count

aspose/cells/style.py

@@ -0,0 +1,287 @@
+"""
+Simplified styling system for Excel cells and ranges.
+"""
+
+from typing import Optional, Union
+
+
+class Font:
+    """Font styling properties."""
+    
+    def __init__(self):
+        self.name: str = "Calibri"
+        self.size: Union[int, float] = 11
+        self.bold: bool = False
+        self.italic: bool = False
+        self.underline: bool = False
+        self.color: str = "black"
+    
+    def copy(self) -> 'Font':
+        """Create a copy of this font."""
+        new_font = Font()
+        new_font.name = self.name
+        new_font.size = self.size
+        new_font.bold = self.bold
+        new_font.italic = self.italic
+        new_font.underline = self.underline
+        new_font.color = self.color
+        return new_font
+
+
+class Fill:
+    """Fill/background styling properties."""
+    
+    def __init__(self):
+        self.color: str = "white"
+        self.pattern: str = "none"
+        self.gradient: Optional[str] = None
+    
+    def copy(self) -> 'Fill':
+        """Create a copy of this fill."""
+        new_fill = Fill()
+        new_fill.color = self.color
+        new_fill.pattern = self.pattern
+        new_fill.gradient = self.gradient
+        return new_fill
+
+
+class BorderSide:
+    """Individual border side styling."""
+    
+    def __init__(self):
+        self.style: str = "none"  # none, thin, thick, medium, dashed, dotted, double
+        self.color: str = "black"
+    
+    def copy(self) -> 'BorderSide':
+        """Create a copy of this border side."""
+        new_side = BorderSide()
+        new_side.style = self.style
+        new_side.color = self.color
+        return new_side
+
+
+class Border:
+    """Comprehensive border styling properties."""
+    
+    def __init__(self):
+        self._left: Optional[BorderSide] = None
+        self._right: Optional[BorderSide] = None
+        self._top: Optional[BorderSide] = None
+        self._bottom: Optional[BorderSide] = None
+        self._diagonal: Optional[BorderSide] = None
+        self._diagonal_up: bool = False
+        self._diagonal_down: bool = False
+    
+    @property
+    def left(self) -> BorderSide:
+        """Get or create left border."""
+        if self._left is None:
+            self._left = BorderSide()
+        return self._left
+    
+    @left.setter
+    def left(self, value: BorderSide):
+        """Set left border."""
+        self._left = value
+    
+    @property
+    def right(self) -> BorderSide:
+        """Get or create right border."""
+        if self._right is None:
+            self._right = BorderSide()
+        return self._right
+    
+    @right.setter
+    def right(self, value: BorderSide):
+        """Set right border."""
+        self._right = value
+    
+    @property
+    def top(self) -> BorderSide:
+        """Get or create top border."""
+        if self._top is None:
+            self._top = BorderSide()
+        return self._top
+    
+    @top.setter
+    def top(self, value: BorderSide):
+        """Set top border."""
+        self._top = value
+    
+    @property
+    def bottom(self) -> BorderSide:
+        """Get or create bottom border."""
+        if self._bottom is None:
+            self._bottom = BorderSide()
+        return self._bottom
+    
+    @bottom.setter
+    def bottom(self, value: BorderSide):
+        """Set bottom border."""
+        self._bottom = value
+    
+    @property
+    def diagonal(self) -> BorderSide:
+        """Get or create diagonal border."""
+        if self._diagonal is None:
+            self._diagonal = BorderSide()
+        return self._diagonal
+    
+    @diagonal.setter
+    def diagonal(self, value: BorderSide):
+        """Set diagonal border."""
+        self._diagonal = value
+    
+    def set_all_borders(self, style: str = "thin", color: str = "black"):
+        """Set all borders to the same style and color."""
+        for side in ['left', 'right', 'top', 'bottom']:
+            border_side = getattr(self, side)
+            border_side.style = style
+            border_side.color = color
+    
+    def set_outline(self, style: str = "thin", color: str = "black"):
+        """Set outline borders (all four sides)."""
+        self.set_all_borders(style, color)
+    
+    def remove_all_borders(self):
+        """Remove all borders."""
+        self._left = None
+        self._right = None
+        self._top = None
+        self._bottom = None
+        self._diagonal = None
+    
+    def copy(self) -> 'Border':
+        """Create a copy of this border."""
+        new_border = Border()
+        if self._left:
+            new_border._left = self._left.copy()
+        if self._right:
+            new_border._right = self._right.copy()
+        if self._top:
+            new_border._top = self._top.copy()
+        if self._bottom:
+            new_border._bottom = self._bottom.copy()
+        if self._diagonal:
+            new_border._diagonal = self._diagonal.copy()
+        new_border._diagonal_up = self._diagonal_up
+        new_border._diagonal_down = self._diagonal_down
+        return new_border
+
+
+class Alignment:
+    """Text alignment properties."""
+    
+    def __init__(self):
+        self.horizontal: str = "general"
+        self.vertical: str = "bottom"
+        self.wrap_text: bool = False
+        self.shrink_to_fit: bool = False
+        self.indent: int = 0
+        self.text_rotation: int = 0
+    
+    def copy(self) -> 'Alignment':
+        """Create a copy of this alignment."""
+        new_alignment = Alignment()
+        new_alignment.horizontal = self.horizontal
+        new_alignment.vertical = self.vertical
+        new_alignment.wrap_text = self.wrap_text
+        new_alignment.shrink_to_fit = self.shrink_to_fit
+        new_alignment.indent = self.indent
+        new_alignment.text_rotation = self.text_rotation
+        return new_alignment
+
+
+class Style:
+    """Complete cell style container."""
+    
+    def __init__(self):
+        self._font: Optional[Font] = None
+        self._fill: Optional[Fill] = None
+        self._border: Optional[Border] = None
+        self._alignment: Optional[Alignment] = None
+        self._number_format: str = "General"
+        self._protection: bool = True
+    
+    @property
+    def font(self) -> Font:
+        """Get or create font styling."""
+        if self._font is None:
+            self._font = Font()
+        return self._font
+    
+    @font.setter
+    def font(self, value: Font):
+        """Set font styling."""
+        self._font = value
+    
+    @property
+    def fill(self) -> Fill:
+        """Get or create fill styling."""
+        if self._fill is None:
+            self._fill = Fill()
+        return self._fill
+    
+    @fill.setter
+    def fill(self, value: Fill):
+        """Set fill styling."""
+        self._fill = value
+    
+    @property
+    def border(self) -> Border:
+        """Get or create border styling."""
+        if self._border is None:
+            self._border = Border()
+        return self._border
+    
+    @border.setter
+    def border(self, value: Border):
+        """Set border styling."""
+        self._border = value
+    
+    @property
+    def alignment(self) -> Alignment:
+        """Get or create alignment styling."""
+        if self._alignment is None:
+            self._alignment = Alignment()
+        return self._alignment
+    
+    @alignment.setter
+    def alignment(self, value: Alignment):
+        """Set alignment styling."""
+        self._alignment = value
+    
+    @property
+    def number_format(self) -> str:
+        """Get number format."""
+        return self._number_format
+    
+    @number_format.setter
+    def number_format(self, value: str):
+        """Set number format."""
+        self._number_format = value
+    
+    @property
+    def protection(self) -> bool:
+        """Get protection status."""
+        return self._protection
+    
+    @protection.setter
+    def protection(self, value: bool):
+        """Set protection status."""
+        self._protection = value
+    
+    def copy(self) -> 'Style':
+        """Create a deep copy of this style."""
+        new_style = Style()
+        if self._font:
+            new_style._font = self._font.copy()
+        if self._fill:
+            new_style._fill = self._fill.copy()
+        if self._border:
+            new_style._border = self._border.copy()
+        if self._alignment:
+            new_style._alignment = self._alignment.copy()
+        new_style._number_format = self._number_format
+        new_style._protection = self._protection
+        return new_style

aspose/cells/utils/__init__.py

@@ -0,0 +1,54 @@
+"""
+Utility functions and classes for Excel operations.
+"""
+
+from .coordinates import (
+    column_index_to_letter,
+    column_letter_to_index,
+    coordinate_to_tuple,
+    tuple_to_coordinate,
+    parse_range
+)
+from .validation import (
+    is_numeric_string,
+    is_formula,
+    is_date_value,
+    infer_data_type,
+    validate_sheet_name,
+    sanitize_sheet_name,
+    convert_value
+)
+from .exceptions import (
+    AsposeException,
+    FileFormatError,
+    InvalidCoordinateError,
+    WorksheetNotFoundError,
+    CellValueError,
+    ExportError
+)
+
+__all__ = [
+    # Coordinates
+    "column_index_to_letter",
+    "column_letter_to_index", 
+    "coordinate_to_tuple",
+    "tuple_to_coordinate",
+    "parse_range",
+    
+    # Validation
+    "is_numeric_string",
+    "is_formula",
+    "is_date_value",
+    "infer_data_type",
+    "validate_sheet_name",
+    "sanitize_sheet_name",
+    "convert_value",
+    
+    # Exceptions
+    "AsposeException",
+    "FileFormatError",
+    "InvalidCoordinateError",
+    "WorksheetNotFoundError",
+    "CellValueError",
+    "ExportError"
+]

aspose/cells/utils/coordinates.py

@@ -0,0 +1,68 @@
+"""
+Coordinate conversion utilities for Excel cell addressing.
+"""
+
+import re
+from typing import Tuple
+from .exceptions import InvalidCoordinateError
+
+
+def column_index_to_letter(index: int) -> str:
+    """Convert 1-based column index to Excel letter (1 -> A, 27 -> AA)."""
+    if index < 1:
+        raise InvalidCoordinateError(f"Column index must be >= 1, got {index}")
+    
+    result = ""
+    while index > 0:
+        index -= 1
+        result = chr(65 + index % 26) + result
+        index //= 26
+    return result
+
+
+def column_letter_to_index(letter: str) -> int:
+    """Convert Excel column letter to 1-based index (A -> 1, AA -> 27)."""
+    if not letter or not letter.isalpha():
+        raise InvalidCoordinateError(f"Invalid column letter: {letter}")
+    
+    result = 0
+    for char in letter.upper():
+        result = result * 26 + (ord(char) - ord('A') + 1)
+    return result
+
+
+def coordinate_to_tuple(coordinate: str) -> Tuple[int, int]:
+    """Convert Excel coordinate to (row, column) tuple (A1 -> (1, 1))."""
+    match = re.match(r'^([A-Z]+)(\d+)$', coordinate.upper())
+    if not match:
+        raise InvalidCoordinateError(f"Invalid coordinate format: {coordinate}")
+    
+    col_letter, row_str = match.groups()
+    row = int(row_str)
+    col = column_letter_to_index(col_letter)
+    
+    if row < 1:
+        raise InvalidCoordinateError(f"Row number must be >= 1, got {row}")
+    
+    return row, col
+
+
+def tuple_to_coordinate(row: int, column: int) -> str:
+    """Convert (row, column) tuple to Excel coordinate ((1, 1) -> A1)."""
+    if row < 1 or column < 1:
+        raise InvalidCoordinateError(f"Row and column must be >= 1, got ({row}, {column})")
+    
+    col_letter = column_index_to_letter(column)
+    return f"{col_letter}{row}"
+
+
+def parse_range(range_str: str) -> Tuple[Tuple[int, int], Tuple[int, int]]:
+    """Parse Excel range to ((start_row, start_col), (end_row, end_col))."""
+    if ':' not in range_str:
+        raise InvalidCoordinateError(f"Range must contain ':', got: {range_str}")
+    
+    start_cell, end_cell = range_str.split(':', 1)
+    start_coord = coordinate_to_tuple(start_cell.strip())
+    end_coord = coordinate_to_tuple(end_cell.strip())
+    
+    return start_coord, end_coord

aspose/cells/utils/exceptions.py

@@ -0,0 +1,43 @@
+"""
+Custom exception classes for Aspose.Cells operations.
+"""
+
+
+class AsposeException(Exception):
+    """Base exception for all Aspose.Cells errors."""
+    pass
+
+
+class FileFormatError(AsposeException):
+    """Raised when file format is not supported or invalid."""
+    pass
+
+
+class InvalidCoordinateError(AsposeException):
+    """Raised when cell coordinate is invalid."""
+    pass
+
+
+class WorksheetNotFoundError(AsposeException):
+    """Raised when worksheet cannot be found."""
+    pass
+
+
+class CellValueError(AsposeException):
+    """Raised when cell value operation fails."""
+    pass
+
+
+class ExportError(AsposeException):
+    """Raised when data export operation fails."""
+    pass
+
+
+class ExcelValidationError(AsposeException):
+    """Raised when Excel data validation fails."""
+    pass
+
+
+class CellRangeError(AsposeException):
+    """Raised when cell range operation fails."""
+    pass