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

aspose_cells/xml_autofilter_saver.py

@@ -0,0 +1,173 @@
+"""
+Aspose.Cells for Python - XML AutoFilter Saver Module
+
+This module provides the AutoFilterXMLWriter class which handles saving
+autofilter data to XML format according to ECMA-376 specification.
+
+ECMA-376 Section 18.3.1.2 defines the autoFilter element structure.
+"""
+
+
+class AutoFilterXMLWriter:
+    """
+    Handles writing autofilter data to XML format for .xlsx files.
+
+    The AutoFilterXMLWriter class is responsible for creating the XML
+    representation of autofilter settings including filter columns,
+    filter values, custom filters, color filters, dynamic filters,
+    top10 filters, and sort state.
+
+    Examples:
+        >>> writer = AutoFilterXMLWriter()
+        >>> xml = writer.format_auto_filter_xml(worksheet.auto_filter)
+    """
+
+    def __init__(self, escape_xml_func):
+        """
+        Initializes a new instance of the AutoFilterXMLWriter class.
+
+        Args:
+            escape_xml_func: A function to escape XML special characters.
+        """
+        self._escape_xml = escape_xml_func
+
+    def format_auto_filter_xml(self, auto_filter):
+        """
+        Formats auto filter settings as XML according to ECMA-376 specification.
+
+        ECMA-376 Section 18.3.1.2 defines the autoFilter element structure:
+        - autoFilter: Main element with ref attribute (filter range)
+        - filterColumn: Represents filter settings for a column (colId attribute)
+        - filters: Contains filter values
+        - filter: Individual filter value (val attribute)
+        - customFilters: Contains custom filter criteria
+        - customFilter: Custom filter criterion (operator and val attributes)
+        - colorFilter: Color filter settings
+        - dynamicFilter: Dynamic filter settings (type and val attributes)
+        - top10: Top 10 filter settings (top, percent, and val attributes)
+        - sortState: Sort state settings (columnOffset and order attributes)
+
+        Args:
+            auto_filter (AutoFilter): The AutoFilter object to format.
+
+        Returns:
+            str: XML representation of the auto filter settings.
+        """
+        xml = f'    <autoFilter ref="{auto_filter.range}">\n'
+
+        # Write filter columns
+        for col_id, filter_col in sorted(auto_filter.filter_columns.items()):
+            xml += f'        <filterColumn colId="{col_id}"'
+
+            # Add hiddenButton attribute if filter button is hidden
+            if not filter_col.filter_button:
+                xml += ' hiddenButton="1"'
+
+            # Check if this column has any filters
+            has_filters = (len(filter_col.filters) > 0 or
+                          len(filter_col.custom_filters) > 0 or
+                          filter_col.color_filter is not None or
+                          filter_col.dynamic_filter is not None or
+                          filter_col.top10_filter is not None)
+
+            if not has_filters:
+                xml += '/>\n'
+                continue
+
+            xml += '>\n'
+
+            # Write filters (value filters)
+            if len(filter_col.filters) > 0:
+                xml += f'            <filters>\n'
+                for filter_value in filter_col.filters:
+                    escaped_value = self._escape_xml(str(filter_value))
+                    xml += f'                <filter val="{escaped_value}"/>\n'
+                xml += f'            </filters>\n'
+
+            # Write custom filters
+            if len(filter_col.custom_filters) > 0:
+                xml += f'            <customFilters>\n'
+                for operator, value in filter_col.custom_filters:
+                    escaped_value = self._escape_xml(str(value))
+                    xml += f'                <customFilter operator="{operator}" val="{escaped_value}"/>\n'
+                xml += f'            </customFilters>\n'
+
+            # Write color filter
+            if filter_col.color_filter is not None:
+                color_data = filter_col.color_filter
+                cell_color_attr = ' cellColor="1"' if color_data['cell_color'] else ' cellColor="0"'
+                xml += f'            <colorFilter rgb="{color_data["color"]}"{cell_color_attr}/>\n'
+
+            # Write dynamic filter
+            if filter_col.dynamic_filter is not None:
+                dynamic_data = filter_col.dynamic_filter
+                xml += f'            <dynamicFilter type="{dynamic_data["type"]}"'
+                if dynamic_data['value'] is not None:
+                    escaped_value = self._escape_xml(str(dynamic_data['value']))
+                    xml += f' val="{escaped_value}"'
+                xml += '/>\n'
+
+            # Write top10 filter
+            if filter_col.top10_filter is not None:
+                top10_data = filter_col.top10_filter
+                top_attr = ' top="1"' if top10_data['top'] else ' top="0"'
+                percent_attr = ' percent="1"' if top10_data['percent'] else ' percent="0"'
+                xml += f'            <top10{top_attr}{percent_attr} val="{top10_data["val"]}"/>\n'
+
+            xml += f'        </filterColumn>\n'
+
+        # Write sort state (ECMA-376 Section 18.3.1.92)
+        if auto_filter.sort_state is not None and auto_filter.range is not None:
+            sort_data = auto_filter.sort_state
+            # Calculate sortState ref and sortCondition ref from autoFilter range
+            sort_state_ref, sort_condition_ref = self._calculate_sort_refs(
+                auto_filter.range, sort_data.get('column_index', 0)
+            )
+            xml += f'        <sortState ref="{sort_state_ref}">\n'
+            # Build sortCondition with ref attribute
+            descending_attr = ' descending="1"' if sort_data.get('descending', False) else ''
+            xml += f'            <sortCondition ref="{sort_condition_ref}"{descending_attr}/>\n'
+            xml += f'        </sortState>\n'
+
+        xml += f'    </autoFilter>\n'
+
+        return xml
+
+    def _calculate_sort_refs(self, filter_range, column_index):
+        """
+        Calculates sortState ref and sortCondition ref from autoFilter range.
+
+        According to ECMA-376:
+        - sortState ref: The data range being sorted (excludes header row)
+        - sortCondition ref: The specific column range being sorted
+
+        Args:
+            filter_range (str): The autoFilter range (e.g., "A1:D10")
+            column_index (int): Zero-based column index within the filter range
+
+        Returns:
+            tuple: (sort_state_ref, sort_condition_ref)
+        """
+        from .cells import Cells
+
+        # Parse the filter range
+        if ':' in filter_range:
+            start_ref, end_ref = filter_range.split(':')
+        else:
+            start_ref = end_ref = filter_range
+
+        start_row, start_col = Cells.coordinate_from_string(start_ref)
+        end_row, end_col = Cells.coordinate_from_string(end_ref)
+
+        # sortState ref excludes header row (start from row after header)
+        data_start_row = start_row + 1
+        start_col_letter = Cells.column_letter_from_index(start_col)
+        end_col_letter = Cells.column_letter_from_index(end_col)
+        sort_state_ref = f"{start_col_letter}{data_start_row}:{end_col_letter}{end_row}"
+
+        # sortCondition ref is for the specific column being sorted
+        sort_col = start_col + column_index
+        sort_col_letter = Cells.column_letter_from_index(sort_col)
+        sort_condition_ref = f"{sort_col_letter}{data_start_row}:{sort_col_letter}{end_row}"
+
+        return sort_state_ref, sort_condition_ref

aspose_cells/xml_conditional_format_loader.py

@@ -0,0 +1,215 @@
+"""
+Aspose.Cells for Python - XML Conditional Formatting Loader Module
+
+This module provides the ConditionalFormatXMLLoader class which handles loading
+conditional formatting data from XML format according to ECMA-376 specification.
+
+ECMA-376 Section 18.3.1.18 defines the conditionalFormatting element structure.
+"""
+
+
+class ConditionalFormatXMLLoader:
+    """
+    Handles loading conditional formatting data from XML format for .xlsx files.
+
+    The ConditionalFormatXMLLoader class is responsible for parsing 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:
+        >>> loader = ConditionalFormatXMLLoader(namespaces, workbook)
+        >>> loader.load_conditional_formatting(worksheet, worksheet_root)
+    """
+
+    def __init__(self, namespaces, workbook):
+        """
+        Initializes a new instance of the ConditionalFormatXMLLoader class.
+
+        Args:
+            namespaces: XML namespaces dictionary for parsing.
+            workbook: The workbook instance for accessing dxf styles.
+        """
+        self.ns = namespaces
+        self.workbook = workbook
+
+    def load_conditional_formatting(self, worksheet, worksheet_root):
+        """
+        Loads conditional formatting from worksheet XML according to ECMA-376 specification.
+
+        ECMA-376 Section 18.3.1.18 defines the conditionalFormatting element and its children:
+        - conditionalFormatting: Main element with sqref attribute
+        - cfRule: Individual conditional formatting rule
+
+        Args:
+            worksheet (Worksheet): The worksheet object to load data into.
+            worksheet_root: The XML root element of the worksheet.
+        """
+        from .conditional_format import ConditionalFormat
+
+        # Find all conditionalFormatting elements
+        cf_elements = worksheet_root.findall('.//main:conditionalFormatting', namespaces=self.ns)
+
+        for cf_elem in cf_elements:
+            sqref = cf_elem.get('sqref')
+            if not sqref:
+                continue
+
+            # Load each cfRule within this conditionalFormatting element
+            for rule_elem in cf_elem.findall('main:cfRule', namespaces=self.ns):
+                cf = ConditionalFormat()
+                cf._range = sqref
+
+                # Parse rule attributes
+                rule_type = rule_elem.get('type')
+                cf._type = rule_type
+
+                # Parse priority
+                priority = rule_elem.get('priority')
+                if priority:
+                    cf._priority = int(priority)
+
+                # Parse stopIfTrue
+                stop_if_true = rule_elem.get('stopIfTrue')
+                cf._stop_if_true = stop_if_true == '1'
+
+                # Parse dxfId for loading formatting later
+                dxf_id = rule_elem.get('dxfId')
+                if dxf_id:
+                    cf._dxf_id = int(dxf_id)
+
+                # Parse operator for cellIs type
+                operator = rule_elem.get('operator')
+                if operator:
+                    cf._operator = operator
+
+                # Parse text attribute for text-based rules
+                text = rule_elem.get('text')
+                if text:
+                    cf._formula1 = text
+
+                # Parse timePeriod attribute
+                time_period = rule_elem.get('timePeriod')
+                if time_period:
+                    cf._operator = time_period
+
+                # Parse top10 attributes
+                if rule_type == 'top10':
+                    bottom = rule_elem.get('bottom')
+                    cf._top = bottom != '1'
+                    percent = rule_elem.get('percent')
+                    cf._percent = percent == '1'
+                    rank = rule_elem.get('rank')
+                    if rank:
+                        cf._rank = int(rank)
+
+                # Parse aboveAverage attributes
+                if rule_type == 'aboveAverage':
+                    above_average = rule_elem.get('aboveAverage', '1')
+                    cf._above = above_average != '0'
+                    std_dev = rule_elem.get('stdDev')
+                    if std_dev:
+                        cf._std_dev = int(std_dev)
+
+                # Parse formula elements based on rule type
+                formula_elems = rule_elem.findall('main:formula', namespaces=self.ns)
+                if rule_type == 'expression':
+                    # Expression rules store formula in _formula property
+                    if len(formula_elems) > 0 and formula_elems[0].text:
+                        cf._formula = formula_elems[0].text
+                elif rule_type == 'cellIs':
+                    # Cell value rules use _formula1 and _formula2
+                    if len(formula_elems) > 0 and formula_elems[0].text:
+                        cf._formula1 = formula_elems[0].text
+                    if len(formula_elems) > 1 and formula_elems[1].text:
+                        cf._formula2 = formula_elems[1].text
+                elif rule_type in ('containsText', 'notContainsText', 'beginsWith', 'endsWith'):
+                    # Text rules: the text attribute is already parsed above
+                    # The formula element contains the Excel formula, not the text value
+                    # We use the text attribute value which was set earlier
+                    pass
+                else:
+                    # Default: store in _formula1
+                    if len(formula_elems) > 0 and formula_elems[0].text:
+                        cf._formula1 = formula_elems[0].text
+                    if len(formula_elems) > 1 and formula_elems[1].text:
+                        cf._formula2 = formula_elems[1].text
+
+                # Parse colorScale element
+                color_scale_elem = rule_elem.find('main:colorScale', namespaces=self.ns)
+                if color_scale_elem is not None:
+                    self._load_color_scale(cf, color_scale_elem)
+
+                # Parse dataBar element
+                data_bar_elem = rule_elem.find('main:dataBar', namespaces=self.ns)
+                if data_bar_elem is not None:
+                    self._load_data_bar(cf, data_bar_elem)
+
+                # Parse iconSet element
+                icon_set_elem = rule_elem.find('main:iconSet', namespaces=self.ns)
+                if icon_set_elem is not None:
+                    self._load_icon_set(cf, icon_set_elem)
+
+                # Add to worksheet's conditional formats
+                worksheet.conditional_formats._formats.append(cf)
+
+        # Load dxf formatting and apply to conditional formats
+        self._apply_dxf_to_conditional_formats(worksheet)
+
+    def _load_color_scale(self, cf, color_scale_elem):
+        """Loads colorScale element data into conditional format."""
+        # Get cfvo elements to determine if 2-color or 3-color
+        cfvo_elems = color_scale_elem.findall('main:cfvo', namespaces=self.ns)
+        cf._color_scale_type = '3-color' if len(cfvo_elems) >= 3 else '2-color'
+
+        # Get color elements
+        color_elems = color_scale_elem.findall('main:color', namespaces=self.ns)
+        if len(color_elems) >= 1:
+            cf._min_color = color_elems[0].get('rgb')
+        if len(color_elems) >= 3:
+            cf._mid_color = color_elems[1].get('rgb')
+            cf._max_color = color_elems[2].get('rgb')
+        elif len(color_elems) >= 2:
+            cf._max_color = color_elems[1].get('rgb')
+
+    def _load_data_bar(self, cf, data_bar_elem):
+        """Loads dataBar element data into conditional format."""
+        # Get color element
+        color_elem = data_bar_elem.find('main:color', namespaces=self.ns)
+        if color_elem is not None:
+            cf._bar_color = color_elem.get('rgb')
+
+    def _load_icon_set(self, cf, icon_set_elem):
+        """Loads iconSet element data into conditional format."""
+        cf._icon_set_type = icon_set_elem.get('iconSet', '3TrafficLights1')
+        cf._reverse_icons = icon_set_elem.get('reverse') == '1'
+        cf._show_icon_only = icon_set_elem.get('showValue') == '0'
+
+    def _apply_dxf_to_conditional_formats(self, worksheet):
+        """Applies differential formatting (dxf) to conditional formats."""
+        # dxf styles are stored in workbook._dxf_styles after loading styles.xml
+        if not hasattr(self.workbook, '_dxf_styles') or not self.workbook._dxf_styles:
+            return
+
+        for cf in worksheet.conditional_formats:
+            if hasattr(cf, '_dxf_id') and cf._dxf_id is not None:
+                if cf._dxf_id < len(self.workbook._dxf_styles):
+                    dxf_data = self.workbook._dxf_styles[cf._dxf_id]
+                    self._apply_dxf_data_to_cf(cf, dxf_data)
+
+    def _apply_dxf_data_to_cf(self, cf, dxf_data):
+        """Applies dxf data to a conditional format."""
+        if 'font' in dxf_data:
+            font = dxf_data['font']
+            cf._font.bold = font.get('bold', False)
+            cf._font.italic = font.get('italic', False)
+            cf._font.underline = font.get('underline', False)
+            cf._font.strikethrough = font.get('strikethrough', False)
+            if 'color' in font:
+                cf._font.color = font['color']
+
+        if 'fill' in dxf_data:
+            fill = dxf_data['fill']
+            cf._fill.pattern_type = fill.get('pattern_type', 'solid')
+            cf._fill.foreground_color = fill.get('fg_color', 'FFFFFFFF')
+            cf._fill.background_color = fill.get('bg_color', 'FFFFFFFF')