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

aspose_cells/xml_conditional_format_saver.py

@@ -0,0 +1,351 @@
+"""
+Aspose.Cells for Python - XML Conditional Formatting Saver Module
+
+This module provides the ConditionalFormatXMLWriter class which handles saving
+conditional formatting data to XML format according to ECMA-376 specification.
+
+ECMA-376 Section 18.3.1.18 defines the conditionalFormatting element structure.
+"""
+
+
+class ConditionalFormatXMLWriter:
+    """
+    Handles writing conditional formatting data to XML format for .xlsx files.
+
+    The ConditionalFormatXMLWriter class is responsible for creating the XML
+    representation of conditional formatting rules including cell value rules,
+    text rules, date rules, formula rules, color scales, data bars, icon sets,
+    and more.
+
+    Examples:
+        >>> writer = ConditionalFormatXMLWriter(escape_xml_func)
+        >>> xml = writer.format_conditional_formatting_xml(worksheet.conditional_formats)
+    """
+
+    def __init__(self, escape_xml_func):
+        """
+        Initializes a new instance of the ConditionalFormatXMLWriter class.
+
+        Args:
+            escape_xml_func: A function to escape XML special characters.
+        """
+        self._escape_xml = escape_xml_func
+
+    def format_conditional_formatting_xml(self, conditional_formats):
+        """
+        Formats conditional formatting as XML according to ECMA-376 specification.
+
+        ECMA-376 Section 18.3.1.18 defines the conditionalFormatting element structure:
+        - conditionalFormatting: Main element with sqref attribute (cell ranges)
+        - cfRule: Individual conditional formatting rule
+
+        Args:
+            conditional_formats (ConditionalFormatCollection): The collection of conditional formats.
+
+        Returns:
+            str: XML representation of the conditional formatting.
+        """
+        xml = ''
+
+        # Group conditional formats by range (sqref)
+        formats_by_range = {}
+        for cf in conditional_formats:
+            if cf.range is None:
+                continue
+            if cf.range not in formats_by_range:
+                formats_by_range[cf.range] = []
+            formats_by_range[cf.range].append(cf)
+
+        # Write conditionalFormatting elements
+        for sqref, formats in formats_by_range.items():
+            xml += f'    <conditionalFormatting sqref="{sqref}">\n'
+
+            for cf in formats:
+                xml += self._format_cf_rule_xml(cf)
+
+            xml += '    </conditionalFormatting>\n'
+
+        return xml
+
+    def _format_cf_rule_xml(self, cf):
+        """
+        Formats a single conditional formatting rule as XML.
+
+        Args:
+            cf (ConditionalFormat): The conditional format object.
+
+        Returns:
+            str: XML representation of the cfRule element.
+        """
+        # Map user-friendly type names to ECMA-376 XML type names
+        type_map = {
+            'cellValue': 'cellIs',
+            'text': 'containsText',
+            'date': 'timePeriod',
+            'formula': 'expression',
+            'duplicateValues': 'duplicateValues',
+            'uniqueValues': 'uniqueValues',
+            'top10': 'top10',
+            'bottom10': 'top10',  # ECMA-376: both use 'top10' type, distinguished by bottom attribute
+            'aboveAverage': 'aboveAverage',
+            'belowAverage': 'aboveAverage',  # ECMA-376: both use 'aboveAverage' type, distinguished by aboveAverage attribute
+            'colorScale': 'colorScale',
+            'dataBar': 'dataBar',
+            'iconSet': 'iconSet',
+            'containsText': 'containsText',
+            'notContainsText': 'notContainsText',
+            'beginsWith': 'beginsWith',
+            'endsWith': 'endsWith',
+            'containsBlanks': 'containsBlanks',
+            'notContainsBlanks': 'notContainsBlanks',
+            'containsErrors': 'containsErrors',
+            'notContainsErrors': 'notContainsErrors',
+            'timePeriod': 'timePeriod',
+            'expression': 'expression',
+            'cellIs': 'cellIs'
+        }
+
+        rule_type = type_map.get(cf._type, cf._type)
+        if rule_type is None:
+            return ''
+
+        # Build cfRule attributes
+        attrs = [f'type="{rule_type}"']
+
+        # Add dxfId if formatting is applied (will be set during dxf registration)
+        if hasattr(cf, '_dxf_id') and cf._dxf_id is not None:
+            attrs.append(f'dxfId="{cf._dxf_id}"')
+
+        attrs.append(f'priority="{cf.priority}"')
+
+        if cf.stop_if_true:
+            attrs.append('stopIfTrue="1"')
+
+        # Add operator for cellIs type
+        if rule_type == 'cellIs' and cf.operator:
+            attrs.append(f'operator="{cf.operator}"')
+
+        # Add text attribute for text-based rules
+        if rule_type in ('containsText', 'notContainsText', 'beginsWith', 'endsWith'):
+            if cf._formula1:
+                escaped_text = self._escape_xml(str(cf._formula1))
+                attrs.append(f'text="{escaped_text}"')
+
+        # Add timePeriod attribute
+        if rule_type == 'timePeriod' and cf._operator:
+            attrs.append(f'timePeriod="{cf._operator}"')
+
+        # Add top10 attributes
+        if rule_type == 'top10':
+            # Handle both 'top10' and 'bottom10' user types
+            # Both map to ECMA-376 'top10' type, distinguished by bottom attribute
+            if cf.top is not None:
+                attrs.append('bottom="0"' if cf.top else 'bottom="1"')
+            elif cf._type == 'bottom10':
+                # For bottom10 type, explicitly set bottom="1"
+                attrs.append('bottom="1"')
+            if cf.percent is not None:
+                attrs.append('percent="1"' if cf.percent else 'percent="0"')
+            if cf.rank is not None:
+                attrs.append(f'rank="{cf.rank}"')
+
+        # Add aboveAverage attributes
+        if rule_type == 'aboveAverage':
+            # Handle both 'aboveAverage' and 'belowAverage' user types
+            # Both map to ECMA-376 'aboveAverage' type, distinguished by aboveAverage attribute
+            if cf.above is not None:
+                attrs.append('aboveAverage="1"' if cf.above else 'aboveAverage="0"')
+            elif cf._type == 'belowAverage':
+                # For belowAverage type, explicitly set aboveAverage="0"
+                attrs.append('aboveAverage="0"')
+            if cf.std_dev is not None:
+                attrs.append(f'stdDev="{cf.std_dev}"')
+
+        xml = f'        <cfRule {" ".join(attrs)}'
+
+        # Check if we need child elements
+        has_children = False
+        children_xml = ''
+
+        # Add formula elements based on rule type
+        if rule_type == 'expression':
+            # Expression (formula) rules use the _formula property
+            formula_value = cf._formula if cf._formula is not None else cf._formula1
+            if formula_value is not None:
+                formula_text = str(formula_value)
+                # Remove leading '=' if present
+                if formula_text.startswith('='):
+                    formula_text = formula_text[1:]
+                escaped_formula = self._escape_xml(formula_text)
+                children_xml += f'            <formula>{escaped_formula}</formula>\n'
+                has_children = True
+        elif rule_type == 'cellIs':
+            # Cell value rules use _formula1 and _formula2
+            if cf._formula1 is not None:
+                formula_text = str(cf._formula1)
+                if formula_text.startswith('='):
+                    formula_text = formula_text[1:]
+                escaped_formula = self._escape_xml(formula_text)
+                children_xml += f'            <formula>{escaped_formula}</formula>\n'
+                has_children = True
+            if cf._formula2 is not None:
+                formula_text = str(cf._formula2)
+                if formula_text.startswith('='):
+                    formula_text = formula_text[1:]
+                escaped_formula = self._escape_xml(formula_text)
+                children_xml += f'            <formula>{escaped_formula}</formula>\n'
+                has_children = True
+        elif rule_type in ('containsText', 'notContainsText', 'beginsWith', 'endsWith'):
+            # Text rules need a proper Excel formula
+            # Get the first cell of the range to build the formula
+            text_value = cf._formula1 if cf._formula1 is not None else ''
+            first_cell = self._get_first_cell_from_range(cf.range)
+            formula_text = self._build_text_rule_formula(rule_type, text_value, first_cell)
+            if formula_text:
+                escaped_formula = self._escape_xml(formula_text)
+                children_xml += f'            <formula>{escaped_formula}</formula>\n'
+                has_children = True
+
+        # Add colorScale element
+        if rule_type == 'colorScale':
+            children_xml += self._format_color_scale_xml(cf)
+            has_children = True
+
+        # Add dataBar element
+        if rule_type == 'dataBar':
+            children_xml += self._format_data_bar_xml(cf)
+            has_children = True
+
+        # Add iconSet element
+        if rule_type == 'iconSet':
+            children_xml += self._format_icon_set_xml(cf)
+            has_children = True
+
+        if has_children:
+            xml += '>\n'
+            xml += children_xml
+            xml += '        </cfRule>\n'
+        else:
+            xml += '/>\n'
+
+        return xml
+
+    def _format_color_scale_xml(self, cf):
+        """Formats a colorScale element for conditional formatting."""
+        xml = '            <colorScale>\n'
+
+        # Determine if 2-color or 3-color scale
+        is_3_color = cf.mid_color is not None or cf.color_scale_type == '3-color'
+
+        # Add cfvo elements (conditional format value objects)
+        xml += '                <cfvo type="min"/>\n'
+        if is_3_color:
+            xml += '                <cfvo type="percentile" val="50"/>\n'
+        xml += '                <cfvo type="max"/>\n'
+
+        # Add color elements
+        min_color = cf.min_color or 'FFF8696B'  # Default red
+        max_color = cf.max_color or 'FF63BE7B'  # Default green
+        mid_color = cf.mid_color or 'FFFFEB84'  # Default yellow
+
+        xml += f'                <color rgb="{min_color}"/>\n'
+        if is_3_color:
+            xml += f'                <color rgb="{mid_color}"/>\n'
+        xml += f'                <color rgb="{max_color}"/>\n'
+
+        xml += '            </colorScale>\n'
+        return xml
+
+    def _format_data_bar_xml(self, cf):
+        """Formats a dataBar element for conditional formatting."""
+        xml = '            <dataBar>\n'
+
+        # Add cfvo elements
+        xml += '                <cfvo type="min"/>\n'
+        xml += '                <cfvo type="max"/>\n'
+
+        # Add color element
+        bar_color = cf.bar_color or 'FF638EC6'  # Default blue
+        xml += f'                <color rgb="{bar_color}"/>\n'
+
+        xml += '            </dataBar>\n'
+        return xml
+
+    def _format_icon_set_xml(self, cf):
+        """Formats an iconSet element for conditional formatting."""
+        icon_set_type = cf.icon_set_type or '3TrafficLights1'
+
+        attrs = [f'iconSet="{icon_set_type}"']
+        if cf.reverse_icons:
+            attrs.append('reverse="1"')
+        if cf.show_icon_only:
+            attrs.append('showValue="0"')
+
+        xml = f'            <iconSet {" ".join(attrs)}>\n'
+
+        # Add cfvo elements based on icon set type
+        # Determine number of icons
+        num_icons = 3
+        if icon_set_type.startswith('4'):
+            num_icons = 4
+        elif icon_set_type.startswith('5'):
+            num_icons = 5
+
+        # Add cfvo elements with percent thresholds
+        for i in range(num_icons):
+            percent_val = int(100 * i / num_icons)
+            xml += f'                <cfvo type="percent" val="{percent_val}"/>\n'
+
+        xml += '            </iconSet>\n'
+        return xml
+
+    def _get_first_cell_from_range(self, cell_range):
+        """
+        Gets the first cell reference from a range.
+
+        Args:
+            cell_range (str): Cell range (e.g., "A1:A10" or "A1")
+
+        Returns:
+            str: First cell reference (e.g., "A1")
+        """
+        if not cell_range:
+            return 'A1'
+        if ':' in cell_range:
+            return cell_range.split(':')[0]
+        return cell_range
+
+    def _build_text_rule_formula(self, rule_type, text_value, first_cell):
+        """
+        Builds the Excel formula for text-based conditional formatting rules.
+
+        According to ECMA-376, text rules require specific Excel formulas:
+        - containsText: NOT(ISERROR(SEARCH("text",A1)))
+        - notContainsText: ISERROR(SEARCH("text",A1))
+        - beginsWith: LEFT(A1,LEN("text"))="text"
+        - endsWith: RIGHT(A1,LEN("text"))="text"
+
+        Args:
+            rule_type (str): The rule type
+            text_value (str): The text to search for
+            first_cell (str): The first cell of the range
+
+        Returns:
+            str: The Excel formula
+        """
+        if not text_value:
+            return ''
+
+        # Escape double quotes in text value for Excel formula
+        escaped_text = str(text_value).replace('"', '""')
+
+        if rule_type == 'containsText':
+            return f'NOT(ISERROR(SEARCH("{escaped_text}",{first_cell})))'
+        elif rule_type == 'notContainsText':
+            return f'ISERROR(SEARCH("{escaped_text}",{first_cell}))'
+        elif rule_type == 'beginsWith':
+            return f'LEFT({first_cell},LEN("{escaped_text}"))="{escaped_text}"'
+        elif rule_type == 'endsWith':
+            return f'RIGHT({first_cell},LEN("{escaped_text}"))="{escaped_text}"'
+
+        return ''

aspose_cells/xml_datavalidation_loader.py

@@ -0,0 +1,239 @@
+"""
+Aspose.Cells for Python - Data Validation XML Loader
+
+This module handles deserialization of DataValidation objects from ECMA-376 SpreadsheetML XML.
+
+References:
+- ECMA-376 Part 4, Section 3.3.1.30 (dataValidation)
+- ECMA-376 Part 4, Section 3.3.1.31 (dataValidations)
+"""
+
+import xml.etree.ElementTree as ET
+from .data_validation import (
+    DataValidation, DataValidationCollection,
+    DataValidationType, DataValidationOperator,
+    DataValidationAlertStyle, DataValidationImeMode
+)
+
+
+# Mapping from XML attribute values to enum values
+XML_TO_TYPE = {
+    'none': DataValidationType.NONE,
+    'whole': DataValidationType.WHOLE_NUMBER,
+    'decimal': DataValidationType.DECIMAL,
+    'list': DataValidationType.LIST,
+    'date': DataValidationType.DATE,
+    'time': DataValidationType.TIME,
+    'textLength': DataValidationType.TEXT_LENGTH,
+    'custom': DataValidationType.CUSTOM,
+}
+
+XML_TO_OPERATOR = {
+    'between': DataValidationOperator.BETWEEN,
+    'notBetween': DataValidationOperator.NOT_BETWEEN,
+    'equal': DataValidationOperator.EQUAL,
+    'notEqual': DataValidationOperator.NOT_EQUAL,
+    'greaterThan': DataValidationOperator.GREATER_THAN,
+    'lessThan': DataValidationOperator.LESS_THAN,
+    'greaterThanOrEqual': DataValidationOperator.GREATER_THAN_OR_EQUAL,
+    'lessThanOrEqual': DataValidationOperator.LESS_THAN_OR_EQUAL,
+}
+
+XML_TO_ALERT_STYLE = {
+    'stop': DataValidationAlertStyle.STOP,
+    'warning': DataValidationAlertStyle.WARNING,
+    'information': DataValidationAlertStyle.INFORMATION,
+}
+
+XML_TO_IME_MODE = {
+    'noControl': DataValidationImeMode.NO_CONTROL,
+    'off': DataValidationImeMode.OFF,
+    'on': DataValidationImeMode.ON,
+    'disabled': DataValidationImeMode.DISABLED,
+    'hiragana': DataValidationImeMode.HIRAGANA,
+    'fullKatakana': DataValidationImeMode.FULL_KATAKANA,
+    'halfKatakana': DataValidationImeMode.HALF_KATAKANA,
+    'fullAlpha': DataValidationImeMode.FULL_ALPHA,
+    'halfAlpha': DataValidationImeMode.HALF_ALPHA,
+    'fullHangul': DataValidationImeMode.FULL_HANGUL,
+    'halfHangul': DataValidationImeMode.HALF_HANGUL,
+}
+
+
+class DataValidationXmlLoader:
+    """
+    Loads DataValidation objects from ECMA-376 SpreadsheetML XML format.
+    """
+
+    def __init__(self, namespace='http://schemas.openxmlformats.org/spreadsheetml/2006/main'):
+        """
+        Initializes the DataValidationXmlLoader.
+
+        Args:
+            namespace (str): The SpreadsheetML namespace URI.
+        """
+        self.namespace = namespace
+        self.ns_prefix = '{' + namespace + '}'
+
+    def load_data_validations(self, parent_element):
+        """
+        Loads a DataValidationCollection from a parent XML element.
+
+        Args:
+            parent_element (Element): The parent XML element containing dataValidations.
+
+        Returns:
+            DataValidationCollection: The loaded validations.
+        """
+        validations = DataValidationCollection()
+
+        # Find dataValidations element
+        dv_collection = parent_element.find(f'{self.ns_prefix}dataValidations')
+
+        if dv_collection is None:
+            # Try without namespace
+            dv_collection = parent_element.find('dataValidations')
+
+        if dv_collection is None:
+            return validations
+
+        # Load collection-level attributes
+        disable_prompts = dv_collection.get('disablePrompts', '0')
+        validations.disable_prompts = disable_prompts == '1' or disable_prompts.lower() == 'true'
+
+        x_window = dv_collection.get('xWindow')
+        if x_window is not None:
+            validations.x_window = int(x_window)
+
+        y_window = dv_collection.get('yWindow')
+        if y_window is not None:
+            validations.y_window = int(y_window)
+
+        # Load each dataValidation element
+        for dv_elem in dv_collection.findall(f'{self.ns_prefix}dataValidation'):
+            validation = self._load_data_validation(dv_elem)
+            validations.add_validation(validation)
+
+        # Try without namespace if none found
+        if validations.count == 0:
+            for dv_elem in dv_collection.findall('dataValidation'):
+                validation = self._load_data_validation(dv_elem)
+                validations.add_validation(validation)
+
+        return validations
+
+    def _load_data_validation(self, dv_elem):
+        """
+        Loads a single DataValidation from an XML element.
+
+        Args:
+            dv_elem (Element): The dataValidation XML element.
+
+        Returns:
+            DataValidation: The loaded validation.
+        """
+        # Get sqref (required)
+        sqref = dv_elem.get('sqref', '')
+        validation = DataValidation(sqref)
+
+        # Load type
+        type_str = dv_elem.get('type', 'none')
+        validation.type = XML_TO_TYPE.get(type_str, DataValidationType.NONE)
+
+        # Load operator
+        operator_str = dv_elem.get('operator', 'between')
+        validation.operator = XML_TO_OPERATOR.get(operator_str, DataValidationOperator.BETWEEN)
+
+        # Load error style
+        error_style_str = dv_elem.get('errorStyle', 'stop')
+        validation.alert_style = XML_TO_ALERT_STYLE.get(error_style_str, DataValidationAlertStyle.STOP)
+
+        # Load IME mode
+        ime_mode_str = dv_elem.get('imeMode', 'noControl')
+        validation.ime_mode = XML_TO_IME_MODE.get(ime_mode_str, DataValidationImeMode.NO_CONTROL)
+
+        # Load boolean attributes
+        allow_blank = dv_elem.get('allowBlank', '0')
+        validation.allow_blank = allow_blank == '1' or allow_blank.lower() == 'true'
+
+        # Note: In ECMA-376, showDropDown="1" means HIDE the dropdown (counterintuitive)
+        show_dropdown = dv_elem.get('showDropDown', '0')
+        validation.show_dropdown = not (show_dropdown == '1' or show_dropdown.lower() == 'true')
+
+        show_input = dv_elem.get('showInputMessage', '0')
+        validation.show_input_message = show_input == '1' or show_input.lower() == 'true'
+
+        show_error = dv_elem.get('showErrorMessage', '0')
+        validation.show_error_message = show_error == '1' or show_error.lower() == 'true'
+
+        # Load string attributes
+        validation.error_title = dv_elem.get('errorTitle')
+        validation.error_message = dv_elem.get('error')
+        validation.input_title = dv_elem.get('promptTitle')
+        validation.input_message = dv_elem.get('prompt')
+
+        # Load formula elements
+        formula1_elem = dv_elem.find(f'{self.ns_prefix}formula1')
+        if formula1_elem is None:
+            formula1_elem = dv_elem.find('formula1')
+        if formula1_elem is not None and formula1_elem.text:
+            validation.formula1 = formula1_elem.text
+
+        formula2_elem = dv_elem.find(f'{self.ns_prefix}formula2')
+        if formula2_elem is None:
+            formula2_elem = dv_elem.find('formula2')
+        if formula2_elem is not None and formula2_elem.text:
+            validation.formula2 = formula2_elem.text
+
+        return validation
+
+    def load_from_xml_string(self, xml_string):
+        """
+        Loads validations from an XML string.
+
+        Args:
+            xml_string (str): The XML string containing dataValidations.
+
+        Returns:
+            DataValidationCollection: The loaded validations.
+        """
+        # Parse the XML
+        root = ET.fromstring(xml_string)
+
+        # Check if root is dataValidations
+        if root.tag.endswith('dataValidations'):
+            # Create a temporary parent
+            temp_parent = ET.Element('temp')
+            temp_parent.append(root)
+            return self.load_data_validations(temp_parent)
+
+        return self.load_data_validations(root)
+
+    def load_from_file(self, file_path):
+        """
+        Loads validations from an XML file.
+
+        Args:
+            file_path (str): Path to the XML file.
+
+        Returns:
+            DataValidationCollection: The loaded validations.
+        """
+        tree = ET.parse(file_path)
+        root = tree.getroot()
+        return self.load_data_validations(root)
+
+
+def load_data_validations_from_worksheet_xml(worksheet_element, namespace):
+    """
+    Convenience function to load data validations from a worksheet XML element.
+
+    Args:
+        worksheet_element (Element): The worksheet XML element.
+        namespace (str): The SpreadsheetML namespace.
+
+    Returns:
+        DataValidationCollection: The loaded validations.
+    """
+    loader = DataValidationXmlLoader(namespace)
+    return loader.load_data_validations(worksheet_element)