@ngocsangairvds/vsaf 4.1.7 → 4.1.9

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

@@ -1,443 +0,0 @@
-"""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

@@ -1,211 +0,0 @@
-"""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"]