@ngocsangairvds/vsaf 4.0.5 → 4.0.7

package/skills/vds-skill/vds-scripts/excel_orchestrator/src/vds_excel_orchestrator/excel_client.py

@@ -0,0 +1,443 @@
+"""Main Excel client for file and sheet manipulation."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from openpyxl import Workbook, load_workbook
+from openpyxl.cell import Cell
+from openpyxl.worksheet.worksheet import Worksheet
+
+from .errors import (
+    ExcelCellError,
+    ExcelFileError,
+    ExcelFileInvalidError,
+    ExcelFileNotFoundError,
+    ExcelRangeError,
+    ExcelSheetError,
+    ExcelSheetExistsError,
+    ExcelSheetNotFoundError,
+)
+from .logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class ExcelClient:
+    """Main client for Excel file operations."""
+
+    def __init__(self, file_path: str | Path, read_only: bool = False, data_only: bool = False) -> None:
+        """Initialize Excel client.
+
+        Args:
+            file_path: Path to Excel file
+            read_only: Open file in read-only mode
+            data_only: Only read cell values, ignore formulas
+        """
+        self.file_path = Path(file_path)
+        self.read_only = read_only
+        self.data_only = data_only
+        self._workbook: Workbook | None = None
+        self._is_new = False
+
+    def open(self) -> None:
+        """Open existing Excel file."""
+        if not self.file_path.exists():
+            raise ExcelFileNotFoundError(
+                f"Excel file not found: {self.file_path}",
+                context={"path": str(self.file_path)},
+            )
+
+        try:
+            self._workbook = load_workbook(
+                filename=str(self.file_path),
+                read_only=self.read_only,
+                data_only=self.data_only,
+                keep_vba=False,
+            )
+            logger.info("Excel file opened", path=str(self.file_path), read_only=self.read_only)
+        except Exception as exc:
+            raise ExcelFileInvalidError(
+                f"Failed to open Excel file: {exc}",
+                context={"path": str(self.file_path)},
+            ) from exc
+
+    def create(self) -> None:
+        """Create a new Excel workbook."""
+        self._workbook = Workbook()
+        self._is_new = True
+        logger.info("New Excel workbook created")
+
+    def save(self, output_path: str | Path | None = None) -> None:
+        """Save workbook to file.
+
+        Args:
+            output_path: Optional output path (defaults to original file_path)
+        """
+        if self._workbook is None:
+            raise ExcelFileError("No workbook loaded. Call open() or create() first.")
+
+        save_path = Path(output_path) if output_path else self.file_path
+        try:
+            self._workbook.save(str(save_path))
+            logger.info("Excel file saved", path=str(save_path))
+        except Exception as exc:
+            raise ExcelFileError(f"Failed to save Excel file: {exc}", context={"path": str(save_path)}) from exc
+
+    def close(self) -> None:
+        """Close workbook."""
+        if self._workbook:
+            self._workbook.close()
+            self._workbook = None
+            logger.info("Excel workbook closed")
+
+    def __enter__(self) -> ExcelClient:
+        """Context manager entry."""
+        # Check if file exists and has content (valid Excel file)
+        if self.file_path.exists() and self.file_path.stat().st_size > 0:
+            # File exists and has content - try to open it
+            try:
+                self.open()
+            except ExcelFileInvalidError:
+                # File exists but is invalid - create new workbook
+                self.create()
+        else:
+            # File doesn't exist or is empty - create new workbook
+            self.create()
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Context manager exit."""
+        if not self.read_only and self._workbook:
+            self.save()
+        self.close()
+
+    # Sheet operations
+
+    def list_sheets(self) -> list[str]:
+        """List all sheet names.
+
+        Returns:
+            List of sheet names
+        """
+        if self._workbook is None:
+            raise ExcelFileError("No workbook loaded. Call open() or create() first.")
+
+        return self._workbook.sheetnames
+
+    def get_sheet(self, sheet_name: str) -> Worksheet:
+        """Get worksheet by name.
+
+        Args:
+            sheet_name: Name of the sheet
+
+        Returns:
+            Worksheet object
+
+        Raises:
+            ExcelSheetNotFoundError: If sheet doesn't exist
+        """
+        if self._workbook is None:
+            raise ExcelFileError("No workbook loaded. Call open() or create() first.")
+
+        if sheet_name not in self._workbook.sheetnames:
+            raise ExcelSheetNotFoundError(
+                f"Sheet '{sheet_name}' not found",
+                context={"sheet": sheet_name, "available": self._workbook.sheetnames},
+            )
+
+        return self._workbook[sheet_name]
+
+    def create_sheet(self, sheet_name: str, index: int | None = None) -> Worksheet:
+        """Create a new sheet.
+
+        Args:
+            sheet_name: Name for the new sheet
+            index: Optional position index (defaults to end)
+
+        Returns:
+            Created Worksheet object
+
+        Raises:
+            ExcelSheetExistsError: If sheet already exists
+        """
+        if self._workbook is None:
+            raise ExcelFileError("No workbook loaded. Call open() or create() first.")
+
+        if sheet_name in self._workbook.sheetnames:
+            raise ExcelSheetExistsError(f"Sheet '{sheet_name}' already exists", context={"sheet": sheet_name})
+
+        sheet = self._workbook.create_sheet(title=sheet_name, index=index)
+        logger.info("Sheet created", sheet=sheet_name, index=index)
+        return sheet
+
+    def delete_sheet(self, sheet_name: str) -> None:
+        """Delete a sheet.
+
+        Args:
+            sheet_name: Name of sheet to delete
+
+        Raises:
+            ExcelSheetNotFoundError: If sheet doesn't exist
+        """
+        if self._workbook is None:
+            raise ExcelFileError("No workbook loaded. Call open() or create() first.")
+
+        if sheet_name not in self._workbook.sheetnames:
+            raise ExcelSheetNotFoundError(f"Sheet '{sheet_name}' not found", context={"sheet": sheet_name})
+
+        if len(self._workbook.sheetnames) == 1:
+            raise ExcelSheetError(
+                "Cannot delete the last sheet in workbook",
+                context={"sheet": sheet_name},
+            )
+
+        del self._workbook[sheet_name]
+        logger.info("Sheet deleted", sheet=sheet_name)
+
+    def rename_sheet(self, old_name: str, new_name: str) -> None:
+        """Rename a sheet.
+
+        Args:
+            old_name: Current sheet name
+            new_name: New sheet name
+
+        Raises:
+            ExcelSheetNotFoundError: If old sheet doesn't exist
+            ExcelSheetExistsError: If new name already exists
+        """
+        if self._workbook is None:
+            raise ExcelFileError("No workbook loaded. Call open() or create() first.")
+
+        if old_name not in self._workbook.sheetnames:
+            raise ExcelSheetNotFoundError(f"Sheet '{old_name}' not found", context={"sheet": old_name})
+
+        if new_name in self._workbook.sheetnames:
+            raise ExcelSheetExistsError(f"Sheet '{new_name}' already exists", context={"sheet": new_name})
+
+        self._workbook[old_name].title = new_name
+        logger.info("Sheet renamed", old_name=old_name, new_name=new_name)
+
+    def copy_sheet(self, source_name: str, target_name: str) -> Worksheet:
+        """Copy a sheet.
+
+        Args:
+            source_name: Source sheet name
+            target_name: Target sheet name
+
+        Returns:
+            Copied Worksheet object
+
+        Raises:
+            ExcelSheetNotFoundError: If source sheet doesn't exist
+            ExcelSheetExistsError: If target name already exists
+        """
+        if self._workbook is None:
+            raise ExcelFileError("No workbook loaded. Call open() or create() first.")
+
+        if source_name not in self._workbook.sheetnames:
+            raise ExcelSheetNotFoundError(f"Sheet '{source_name}' not found", context={"sheet": source_name})
+
+        if target_name in self._workbook.sheetnames:
+            raise ExcelSheetExistsError(f"Sheet '{target_name}' already exists", context={"sheet": target_name})
+
+        source_sheet = self._workbook[source_name]
+        target_sheet = self._workbook.copy_worksheet(source_sheet)
+        target_sheet.title = target_name
+        logger.info("Sheet copied", source=source_name, target=target_name)
+        return target_sheet
+
+    # Cell operations
+
+    def get_cell(self, sheet_name: str, cell_ref: str) -> Any:
+        """Get cell value.
+
+        Args:
+            sheet_name: Name of the sheet
+            cell_ref: Cell reference (e.g., 'A1')
+
+        Returns:
+            Cell value
+        """
+        sheet = self.get_sheet(sheet_name)
+        try:
+            cell = sheet[cell_ref]
+            return cell.value
+        except Exception as exc:
+            raise ExcelCellError(
+                f"Failed to get cell {cell_ref}: {exc}",
+                context={"sheet": sheet_name, "cell": cell_ref},
+            ) from exc
+
+    def set_cell(self, sheet_name: str, cell_ref: str, value: Any) -> None:
+        """Set cell value.
+
+        Args:
+            sheet_name: Name of the sheet
+            cell_ref: Cell reference (e.g., 'A1')
+            value: Value to set
+        """
+        if self.read_only:
+            raise ExcelFileError("Cannot modify read-only workbook")
+
+        sheet = self.get_sheet(sheet_name)
+        try:
+            sheet[cell_ref] = value
+            logger.debug("Cell set", sheet=sheet_name, cell=cell_ref, value=value)
+        except Exception as exc:
+            raise ExcelCellError(
+                f"Failed to set cell {cell_ref}: {exc}",
+                context={"sheet": sheet_name, "cell": cell_ref, "value": value},
+            ) from exc
+
+    def clear_cell(self, sheet_name: str, cell_ref: str) -> None:
+        """Clear cell value.
+
+        Args:
+            sheet_name: Name of the sheet
+            cell_ref: Cell reference (e.g., 'A1')
+        """
+        if self.read_only:
+            raise ExcelFileError("Cannot modify read-only workbook")
+
+        sheet = self.get_sheet(sheet_name)
+        try:
+            sheet[cell_ref] = None
+            logger.debug("Cell cleared", sheet=sheet_name, cell=cell_ref)
+        except Exception as exc:
+            raise ExcelCellError(
+                f"Failed to clear cell {cell_ref}: {exc}",
+                context={"sheet": sheet_name, "cell": cell_ref},
+            ) from exc
+
+    def get_formula(self, sheet_name: str, cell_ref: str) -> str | None:
+        """Get cell formula.
+
+        Args:
+            sheet_name: Name of the sheet
+            cell_ref: Cell reference (e.g., 'A1')
+
+        Returns:
+            Formula string or None if cell has no formula
+        """
+        sheet = self.get_sheet(sheet_name)
+        try:
+            cell = sheet[cell_ref]
+            return cell.value if isinstance(cell, Cell) and str(cell.value).startswith("=") else None
+        except Exception as exc:
+            raise ExcelCellError(
+                f"Failed to get formula from cell {cell_ref}: {exc}",
+                context={"sheet": sheet_name, "cell": cell_ref},
+            ) from exc
+
+    def set_formula(self, sheet_name: str, cell_ref: str, formula: str) -> None:
+        """Set cell formula.
+
+        Args:
+            sheet_name: Name of the sheet
+            cell_ref: Cell reference (e.g., 'A1')
+            formula: Formula string (with or without '=' prefix)
+        """
+        if self.read_only:
+            raise ExcelFileError("Cannot modify read-only workbook")
+
+        if not formula.startswith("="):
+            formula = f"={formula}"
+
+        sheet = self.get_sheet(sheet_name)
+        try:
+            sheet[cell_ref] = formula
+            logger.debug("Formula set", sheet=sheet_name, cell=cell_ref, formula=formula)
+        except Exception as exc:
+            raise ExcelCellError(
+                f"Failed to set formula in cell {cell_ref}: {exc}",
+                context={"sheet": sheet_name, "cell": cell_ref, "formula": formula},
+            ) from exc
+
+    # Range operations
+
+    def read_range(self, sheet_name: str, range_ref: str) -> list[list[Any]]:
+        """Read range of cells.
+
+        Args:
+            sheet_name: Name of the sheet
+            range_ref: Range reference (e.g., 'A1:C10')
+
+        Returns:
+            2D list of cell values
+        """
+        sheet = self.get_sheet(sheet_name)
+        try:
+            cells = sheet[range_ref]
+            if isinstance(cells, tuple):
+                # Multiple rows
+                return [[cell.value for cell in row] for row in cells]
+            else:
+                # Single row
+                return [[cell.value for cell in cells]]
+        except Exception as exc:
+            raise ExcelRangeError(
+                f"Failed to read range {range_ref}: {exc}",
+                context={"sheet": sheet_name, "range": range_ref},
+            ) from exc
+
+    def write_range(self, sheet_name: str, start_cell: str, data: list[list[Any]]) -> None:
+        """Write data to range of cells.
+
+        Args:
+            sheet_name: Name of the sheet
+            start_cell: Starting cell reference (e.g., 'A1')
+            data: 2D list of values to write
+        """
+        if self.read_only:
+            raise ExcelFileError("Cannot modify read-only workbook")
+
+        sheet = self.get_sheet(sheet_name)
+        try:
+            from openpyxl.utils import get_column_letter
+
+            start_col, start_row = sheet[start_cell].column, sheet[start_cell].row
+
+            for row_idx, row_data in enumerate(data):
+                for col_idx, value in enumerate(row_data):
+                    col_letter = get_column_letter(start_col + col_idx)
+                    cell_ref = f"{col_letter}{start_row + row_idx}"
+                    sheet[cell_ref] = value
+
+            logger.debug("Range written", sheet=sheet_name, start_cell=start_cell, rows=len(data))
+        except Exception as exc:
+            raise ExcelRangeError(
+                f"Failed to write range starting at {start_cell}: {exc}",
+                context={"sheet": sheet_name, "start_cell": start_cell},
+            ) from exc
+
+    def clear_range(self, sheet_name: str, range_ref: str) -> None:
+        """Clear range of cells.
+
+        Args:
+            sheet_name: Name of the sheet
+            range_ref: Range reference (e.g., 'A1:C10')
+        """
+        if self.read_only:
+            raise ExcelFileError("Cannot modify read-only workbook")
+
+        sheet = self.get_sheet(sheet_name)
+        try:
+            cells = sheet[range_ref]
+            if isinstance(cells, tuple):
+                for row in cells:
+                    for cell in row:
+                        cell.value = None
+            else:
+                for cell in cells:
+                    cell.value = None
+            logger.debug("Range cleared", sheet=sheet_name, range=range_ref)
+        except Exception as exc:
+            raise ExcelRangeError(
+                f"Failed to clear range {range_ref}: {exc}",
+                context={"sheet": sheet_name, "range": range_ref},
+            ) from exc
+
+
+__all__ = ["ExcelClient"]

package/skills/vds-skill/vds-scripts/excel_orchestrator/src/vds_excel_orchestrator/formatters.py

@@ -0,0 +1,211 @@
+"""Formatting utilities for Excel cells and ranges."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from openpyxl.styles import Alignment, Border, Font, PatternFill, Side
+from openpyxl.worksheet.worksheet import Worksheet
+
+from .errors import ExcelCellError
+from .logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class CellFormatter:
+    """Utility class for applying formatting to Excel cells."""
+
+    @staticmethod
+    def apply_font(sheet: Worksheet, cell_ref: str, **font_kwargs: Any) -> None:
+        """Apply font formatting to a cell.
+
+        Args:
+            sheet: Worksheet object
+            cell_ref: Cell reference (e.g., 'A1')
+            **font_kwargs: Font properties (name, size, bold, italic, color, etc.)
+        """
+        try:
+            cell = sheet[cell_ref]
+            font = Font(**font_kwargs) if font_kwargs else Font()
+            if cell.font:
+                # Merge with existing font
+                font = Font(
+                    name=font_kwargs.get("name", cell.font.name),
+                    size=font_kwargs.get("size", cell.font.size),
+                    bold=font_kwargs.get("bold", cell.font.bold),
+                    italic=font_kwargs.get("italic", cell.font.italic),
+                    color=font_kwargs.get("color", cell.font.color),
+                )
+            cell.font = font
+            logger.debug("Font applied", cell=cell_ref, font_kwargs=font_kwargs)
+        except Exception as exc:
+            raise ExcelCellError(f"Failed to apply font to {cell_ref}: {exc}", context={"cell": cell_ref}) from exc
+
+    @staticmethod
+    def apply_fill(sheet: Worksheet, cell_ref: str, fill_color: str, pattern_type: str = "solid") -> None:
+        """Apply fill (background color) to a cell.
+
+        Args:
+            sheet: Worksheet object
+            cell_ref: Cell reference (e.g., 'A1')
+            fill_color: Hex color code (e.g., 'FF0000' for red)
+            pattern_type: Fill pattern type (default: 'solid')
+        """
+        try:
+            cell = sheet[cell_ref]
+            fill = PatternFill(start_color=fill_color, end_color=fill_color, fill_type=pattern_type)
+            cell.fill = fill
+            logger.debug("Fill applied", cell=cell_ref, color=fill_color)
+        except Exception as exc:
+            raise ExcelCellError(f"Failed to apply fill to {cell_ref}: {exc}", context={"cell": cell_ref}) from exc
+
+    @staticmethod
+    def apply_alignment(
+        sheet: Worksheet,
+        cell_ref: str,
+        horizontal: str = "general",
+        vertical: str = "bottom",
+        wrap_text: bool = False,
+    ) -> None:
+        """Apply alignment to a cell.
+
+        Args:
+            sheet: Worksheet object
+            cell_ref: Cell reference (e.g., 'A1')
+            horizontal: Horizontal alignment ('left', 'center', 'right', 'general')
+            vertical: Vertical alignment ('top', 'center', 'bottom')
+            wrap_text: Enable text wrapping
+        """
+        try:
+            cell = sheet[cell_ref]
+            alignment = Alignment(horizontal=horizontal, vertical=vertical, wrap_text=wrap_text)
+            cell.alignment = alignment
+            logger.debug(
+                "Alignment applied",
+                cell=cell_ref,
+                horizontal=horizontal,
+                vertical=vertical,
+            )
+        except Exception as exc:
+            raise ExcelCellError(
+                f"Failed to apply alignment to {cell_ref}: {exc}",
+                context={"cell": cell_ref},
+            ) from exc
+
+    @staticmethod
+    def apply_border(
+        sheet: Worksheet,
+        cell_ref: str,
+        border_style: str = "thin",
+        color: str = "000000",
+    ) -> None:
+        """Apply border to a cell.
+
+        Args:
+            sheet: Worksheet object
+            cell_ref: Cell reference (e.g., 'A1')
+            border_style: Border style ('thin', 'medium', 'thick', etc.)
+            color: Border color hex code
+        """
+        try:
+            cell = sheet[cell_ref]
+            side = Side(style=border_style, color=color)
+            border = Border(left=side, right=side, top=side, bottom=side)
+            cell.border = border
+            logger.debug("Border applied", cell=cell_ref, style=border_style)
+        except Exception as exc:
+            raise ExcelCellError(
+                f"Failed to apply border to {cell_ref}: {exc}",
+                context={"cell": cell_ref},
+            ) from exc
+
+    @staticmethod
+    def apply_number_format(sheet: Worksheet, cell_ref: str, number_format: str) -> None:
+        """Apply number format to a cell.
+
+        Args:
+            sheet: Worksheet object
+            cell_ref: Cell reference (e.g., 'A1')
+            number_format: Number format string (e.g., '#,##0.00', 'mm/dd/yyyy', '0%')
+        """
+        try:
+            cell = sheet[cell_ref]
+            cell.number_format = number_format
+            logger.debug("Number format applied", cell=cell_ref, format=number_format)
+        except Exception as exc:
+            raise ExcelCellError(
+                f"Failed to apply number format to {cell_ref}: {exc}",
+                context={"cell": cell_ref},
+            ) from exc
+
+    @staticmethod
+    def apply_date_format(sheet: Worksheet, cell_ref: str) -> None:
+        """Apply date format to a cell.
+
+        Args:
+            sheet: Worksheet object
+            cell_ref: Cell reference (e.g., 'A1')
+        """
+        CellFormatter.apply_number_format(sheet, cell_ref, "mm/dd/yyyy")
+
+    @staticmethod
+    def apply_currency_format(sheet: Worksheet, cell_ref: str, symbol: str = "$") -> None:
+        """Apply currency format to a cell.
+
+        Args:
+            sheet: Worksheet object
+            cell_ref: Cell reference (e.g., 'A1')
+            symbol: Currency symbol (default: '$')
+        """
+        if symbol == "$":
+            CellFormatter.apply_number_format(sheet, cell_ref, '"$"#,##0.00')
+        else:
+            CellFormatter.apply_number_format(sheet, cell_ref, f'"{symbol}"#,##0.00')
+
+    @staticmethod
+    def apply_percentage_format(sheet: Worksheet, cell_ref: str, decimals: int = 0) -> None:
+        """Apply percentage format to a cell.
+
+        Args:
+            sheet: Worksheet object
+            cell_ref: Cell reference (e.g., 'A1')
+            decimals: Number of decimal places (default: 0)
+        """
+        format_str = f"0.{'0' * decimals}%" if decimals > 0 else "0%"
+        CellFormatter.apply_number_format(sheet, cell_ref, format_str)
+
+    @staticmethod
+    def apply_style(
+        sheet: Worksheet,
+        cell_ref: str,
+        font: dict[str, Any] | None = None,
+        fill: dict[str, Any] | None = None,
+        alignment: dict[str, Any] | None = None,
+        border: dict[str, Any] | None = None,
+        number_format: str | None = None,
+    ) -> None:
+        """Apply multiple formatting styles at once.
+
+        Args:
+            sheet: Worksheet object
+            cell_ref: Cell reference (e.g., 'A1')
+            font: Font properties dict
+            fill: Fill properties dict
+            alignment: Alignment properties dict
+            border: Border properties dict
+            number_format: Number format string
+        """
+        if font:
+            CellFormatter.apply_font(sheet, cell_ref, **font)
+        if fill:
+            CellFormatter.apply_fill(sheet, cell_ref, **fill)
+        if alignment:
+            CellFormatter.apply_alignment(sheet, cell_ref, **alignment)
+        if border:
+            CellFormatter.apply_border(sheet, cell_ref, **border)
+        if number_format:
+            CellFormatter.apply_number_format(sheet, cell_ref, number_format)
+
+
+__all__ = ["CellFormatter"]