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

aspose_cells/xml_datavalidation_saver.py

@@ -0,0 +1,245 @@
+"""
+Aspose.Cells for Python - Data Validation XML Saver
+
+This module handles serialization of DataValidation objects to 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 enum values to XML attribute values
+TYPE_TO_XML = {
+    DataValidationType.NONE: 'none',
+    DataValidationType.WHOLE_NUMBER: 'whole',
+    DataValidationType.DECIMAL: 'decimal',
+    DataValidationType.LIST: 'list',
+    DataValidationType.DATE: 'date',
+    DataValidationType.TIME: 'time',
+    DataValidationType.TEXT_LENGTH: 'textLength',
+    DataValidationType.CUSTOM: 'custom',
+}
+
+OPERATOR_TO_XML = {
+    DataValidationOperator.BETWEEN: 'between',
+    DataValidationOperator.NOT_BETWEEN: 'notBetween',
+    DataValidationOperator.EQUAL: 'equal',
+    DataValidationOperator.NOT_EQUAL: 'notEqual',
+    DataValidationOperator.GREATER_THAN: 'greaterThan',
+    DataValidationOperator.LESS_THAN: 'lessThan',
+    DataValidationOperator.GREATER_THAN_OR_EQUAL: 'greaterThanOrEqual',
+    DataValidationOperator.LESS_THAN_OR_EQUAL: 'lessThanOrEqual',
+}
+
+ALERT_STYLE_TO_XML = {
+    DataValidationAlertStyle.STOP: 'stop',
+    DataValidationAlertStyle.WARNING: 'warning',
+    DataValidationAlertStyle.INFORMATION: 'information',
+}
+
+IME_MODE_TO_XML = {
+    DataValidationImeMode.NO_CONTROL: 'noControl',
+    DataValidationImeMode.OFF: 'off',
+    DataValidationImeMode.ON: 'on',
+    DataValidationImeMode.DISABLED: 'disabled',
+    DataValidationImeMode.HIRAGANA: 'hiragana',
+    DataValidationImeMode.FULL_KATAKANA: 'fullKatakana',
+    DataValidationImeMode.HALF_KATAKANA: 'halfKatakana',
+    DataValidationImeMode.FULL_ALPHA: 'fullAlpha',
+    DataValidationImeMode.HALF_ALPHA: 'halfAlpha',
+    DataValidationImeMode.FULL_HANGUL: 'fullHangul',
+    DataValidationImeMode.HALF_HANGUL: 'halfHangul',
+}
+
+
+class DataValidationXmlSaver:
+    """
+    Saves DataValidation objects to ECMA-376 SpreadsheetML XML format.
+    """
+
+    def __init__(self, namespace='http://schemas.openxmlformats.org/spreadsheetml/2006/main'):
+        """
+        Initializes the DataValidationXmlSaver.
+
+        Args:
+            namespace (str): The SpreadsheetML namespace URI.
+        """
+        self.namespace = namespace
+
+    def save_data_validations(self, validations, parent_element):
+        """
+        Saves a DataValidationCollection to XML as a child of the parent element.
+
+        Args:
+            validations (DataValidationCollection): The validations to save.
+            parent_element (Element): The parent XML element (usually worksheet).
+
+        Returns:
+            Element or None: The created dataValidations element, or None if empty.
+        """
+        if not validations or validations.count == 0:
+            return None
+
+        # Create dataValidations element
+        ns_prefix = '{' + self.namespace + '}'
+        dv_collection = ET.SubElement(parent_element, f'{ns_prefix}dataValidations')
+
+        # Set count attribute
+        dv_collection.set('count', str(validations.count))
+
+        # Set optional attributes
+        if validations.disable_prompts:
+            dv_collection.set('disablePrompts', '1')
+
+        if validations.x_window is not None:
+            dv_collection.set('xWindow', str(validations.x_window))
+
+        if validations.y_window is not None:
+            dv_collection.set('yWindow', str(validations.y_window))
+
+        # Add each validation
+        for validation in validations:
+            self._save_data_validation(validation, dv_collection)
+
+        return dv_collection
+
+    def _save_data_validation(self, validation, parent_element):
+        """
+        Saves a single DataValidation to XML.
+
+        Args:
+            validation (DataValidation): The validation to save.
+            parent_element (Element): The parent dataValidations element.
+
+        Returns:
+            Element: The created dataValidation element.
+        """
+        ns_prefix = '{' + self.namespace + '}'
+        dv = ET.SubElement(parent_element, f'{ns_prefix}dataValidation')
+
+        # Required attribute: sqref
+        if validation.sqref:
+            dv.set('sqref', validation.sqref)
+
+        # Type attribute (only if not default 'none')
+        if validation.type != DataValidationType.NONE:
+            dv.set('type', TYPE_TO_XML.get(validation.type, 'none'))
+
+        # Operator attribute (only if type uses operators and not default 'between')
+        if validation.type in (DataValidationType.WHOLE_NUMBER, DataValidationType.DECIMAL,
+                               DataValidationType.DATE, DataValidationType.TIME,
+                               DataValidationType.TEXT_LENGTH):
+            if validation.operator != DataValidationOperator.BETWEEN:
+                dv.set('operator', OPERATOR_TO_XML.get(validation.operator, 'between'))
+
+        # Error style (only if not default 'stop')
+        if validation.alert_style != DataValidationAlertStyle.STOP:
+            dv.set('errorStyle', ALERT_STYLE_TO_XML.get(validation.alert_style, 'stop'))
+
+        # IME mode (only if not default 'noControl')
+        if validation.ime_mode != DataValidationImeMode.NO_CONTROL:
+            dv.set('imeMode', IME_MODE_TO_XML.get(validation.ime_mode, 'noControl'))
+
+        # Boolean attributes (only if not default)
+        if validation.allow_blank:
+            dv.set('allowBlank', '1')
+
+        # Note: In ECMA-376, showDropDown="1" means HIDE the dropdown (counterintuitive)
+        # So we only set this attribute if we want to HIDE the dropdown
+        if not validation.show_dropdown:
+            dv.set('showDropDown', '1')
+
+        if validation.show_input_message:
+            dv.set('showInputMessage', '1')
+
+        if validation.show_error_message:
+            dv.set('showErrorMessage', '1')
+
+        # String attributes (only if set)
+        if validation.error_title:
+            dv.set('errorTitle', validation.error_title)
+
+        if validation.error_message:
+            dv.set('error', validation.error_message)
+
+        if validation.input_title:
+            dv.set('promptTitle', validation.input_title)
+
+        if validation.input_message:
+            dv.set('prompt', validation.input_message)
+
+        # Formula elements
+        if validation.formula1 is not None:
+            formula1_elem = ET.SubElement(dv, f'{ns_prefix}formula1')
+            formula1_elem.text = validation.formula1
+
+        if validation.formula2 is not None:
+            formula2_elem = ET.SubElement(dv, f'{ns_prefix}formula2')
+            formula2_elem.text = validation.formula2
+
+        return dv
+
+    def create_data_validations_xml(self, validations):
+        """
+        Creates a standalone dataValidations XML element.
+
+        Args:
+            validations (DataValidationCollection): The validations to save.
+
+        Returns:
+            Element: The dataValidations element.
+        """
+        # Create a temporary parent
+        ns_prefix = '{' + self.namespace + '}'
+        temp_parent = ET.Element('temp')
+
+        result = self.save_data_validations(validations, temp_parent)
+
+        if result is not None:
+            return result
+
+        # Return empty element if no validations
+        return ET.Element(f'{ns_prefix}dataValidations', {'count': '0'})
+
+    def to_xml_string(self, validations, include_declaration=False):
+        """
+        Converts validations to an XML string.
+
+        Args:
+            validations (DataValidationCollection): The validations to convert.
+            include_declaration (bool): Whether to include XML declaration.
+
+        Returns:
+            str: The XML string.
+        """
+        elem = self.create_data_validations_xml(validations)
+
+        if include_declaration:
+            return '<?xml version="1.0" encoding="UTF-8"?>\n' + ET.tostring(
+                elem, encoding='unicode')
+        else:
+            return ET.tostring(elem, encoding='unicode')
+
+
+def save_data_validations_to_worksheet_xml(validations, worksheet_element, namespace):
+    """
+    Convenience function to save data validations to a worksheet XML element.
+
+    Args:
+        validations (DataValidationCollection): The validations to save.
+        worksheet_element (Element): The worksheet XML element.
+        namespace (str): The SpreadsheetML namespace.
+
+    Returns:
+        Element or None: The created dataValidations element.
+    """
+    saver = DataValidationXmlSaver(namespace)
+    return saver.save_data_validations(validations, worksheet_element)

aspose_cells/xml_hyperlink_handler.py

@@ -0,0 +1,323 @@
+"""
+Aspose.Cells for Python - Hyperlink XML Handler Module
+
+This module handles loading and saving hyperlinks to/from XLSX XML files
+according to ECMA-376 specification.
+
+ECMA-376 Sections:
+- 18.3.1.48: hyperlink element
+- 18.3.1.49: hyperlinks collection
+- 12.3.2.2: Hyperlink Relationships
+"""
+
+import xml.etree.ElementTree as ET
+
+
+class HyperlinkXMLLoader:
+    """
+    Loads hyperlinks from worksheet XML and relationship files.
+
+    ECMA-376 compliant hyperlink loading from:
+    - xl/worksheets/sheet{n}.xml (hyperlink elements)
+    - xl/worksheets/_rels/sheet{n}.xml.rels (relationship targets)
+    """
+
+    def __init__(self, namespaces):
+        """
+        Initializes the hyperlink loader.
+
+        Args:
+            namespaces (dict): XML namespaces for parsing.
+        """
+        self.ns = namespaces
+
+    def load_hyperlinks(self, worksheet, worksheet_root, zipf, sheet_num):
+        """
+        Loads all hyperlinks from worksheet XML and relationships.
+
+        Args:
+            worksheet: The worksheet object to load hyperlinks into.
+            worksheet_root: The XML root element of the worksheet.
+            zipf: ZipFile object containing the workbook data.
+            sheet_num (int): Worksheet number (1-based).
+
+        Examples:
+            >>> loader.load_hyperlinks(worksheet, root, zipf, 1)
+        """
+        # Load relationships first (for external hyperlinks)
+        relationships = self._load_relationships(zipf, sheet_num)
+
+        # Find hyperlinks element
+        hyperlinks_elem = worksheet_root.find('main:hyperlinks', namespaces=self.ns)
+        if hyperlinks_elem is None:
+            return  # No hyperlinks in this worksheet
+
+        # Load each hyperlink
+        for hyperlink_elem in hyperlinks_elem.findall('main:hyperlink', namespaces=self.ns):
+            self._load_hyperlink(worksheet, hyperlink_elem, relationships)
+
+    def _load_relationships(self, zipf, sheet_num):
+        """
+        Loads relationships from xl/worksheets/_rels/sheet{n}.xml.rels.
+
+        Args:
+            zipf: ZipFile object.
+            sheet_num (int): Worksheet number (1-based).
+
+        Returns:
+            dict: Map of relationship ID to target URL.
+        """
+        relationships = {}
+        rels_path = f'xl/worksheets/_rels/sheet{sheet_num}.xml.rels'
+
+        try:
+            rels_content = zipf.read(rels_path)
+            rels_root = ET.fromstring(rels_content)
+
+            # Namespace for relationships
+            rels_ns = {'rel': 'http://schemas.openxmlformats.org/package/2006/relationships'}
+
+            # Find all hyperlink relationships
+            for rel_elem in rels_root.findall('rel:Relationship', namespaces=rels_ns):
+                rel_type = rel_elem.get('Type', '')
+                if 'hyperlink' in rel_type:
+                    rel_id = rel_elem.get('Id')
+                    target = rel_elem.get('Target', '')
+                    relationships[rel_id] = target
+
+        except KeyError:
+            # No relationships file (no external hyperlinks)
+            pass
+
+        return relationships
+
+    def _load_hyperlink(self, worksheet, hyperlink_elem, relationships):
+        """
+        Loads a single hyperlink element.
+
+        Args:
+            worksheet: The worksheet object.
+            hyperlink_elem: XML element for the hyperlink.
+            relationships (dict): Map of relationship IDs to targets.
+        """
+        # Get hyperlink attributes
+        ref = hyperlink_elem.get('ref')  # Required
+        location = hyperlink_elem.get('location', '')  # Internal link
+        display = hyperlink_elem.get('display', '')
+        tooltip = hyperlink_elem.get('tooltip', '')
+
+        # Get relationship ID (for external links)
+        r_id = hyperlink_elem.get('{http://schemas.openxmlformats.org/officeDocument/2006/relationships}id', '')
+
+        # Determine address (external) or sub_address (internal)
+        address = ""
+        sub_address = ""
+
+        if r_id and r_id in relationships:
+            # External hyperlink
+            address = relationships[r_id]
+        elif location:
+            # Internal hyperlink
+            sub_address = location
+
+        # Add hyperlink to worksheet
+        try:
+            hyperlink = worksheet.hyperlinks.add(
+                range_address=ref,
+                address=address,
+                sub_address=sub_address,
+                text_to_display=display,
+                screen_tip=tooltip
+            )
+            # Store relationship ID for saving
+            if r_id:
+                hyperlink._relationship_id = r_id
+        except ValueError as e:
+            # Skip invalid hyperlinks
+            print(f"Warning: Skipping invalid hyperlink at {ref}: {e}")
+
+
+class HyperlinkXMLSaver:
+    """
+    Saves hyperlinks to worksheet XML and relationship files.
+
+    ECMA-376 compliant hyperlink saving to:
+    - xl/worksheets/sheet{n}.xml (hyperlink elements)
+    - xl/worksheets/_rels/sheet{n}.xml.rels (relationship targets)
+    """
+
+    def __init__(self):
+        """Initializes the hyperlink saver."""
+        self._next_rel_id = 1  # Counter for relationship IDs
+
+    def format_hyperlinks_xml(self, worksheet):
+        """
+        Formats hyperlinks collection as XML.
+
+        ECMA-376 Section: 18.3.1.49 (hyperlinks collection)
+
+        Args:
+            worksheet: The worksheet containing hyperlinks.
+
+        Returns:
+            str: XML representation of hyperlinks, or empty string if none.
+
+        Examples:
+            >>> xml = saver.format_hyperlinks_xml(worksheet)
+        """
+        if worksheet.hyperlinks.count == 0:
+            return ''
+
+        xml = '    <hyperlinks>\n'
+
+        for hyperlink in worksheet.hyperlinks:
+            xml += self._format_hyperlink_xml(hyperlink)
+
+        xml += '    </hyperlinks>\n'
+        return xml
+
+    def _format_hyperlink_xml(self, hyperlink):
+        """
+        Formats a single hyperlink as XML.
+
+        ECMA-376 Section: 18.3.1.48 (hyperlink element)
+
+        Args:
+            hyperlink: The Hyperlink object to format.
+
+        Returns:
+            str: XML representation of the hyperlink.
+        """
+        attrs = [f'ref="{self._escape_xml(hyperlink.range)}"']
+
+        # Add r:id for external links
+        if hyperlink.address:
+            if not hasattr(hyperlink, '_relationship_id') or not hyperlink._relationship_id:
+                # Assign new relationship ID
+                hyperlink._relationship_id = f'rId{self._next_rel_id}'
+                self._next_rel_id += 1
+            attrs.append(f'r:id="{hyperlink._relationship_id}"')
+
+        # Add location for internal links
+        if hyperlink.sub_address:
+            attrs.append(f'location="{self._escape_xml(hyperlink.sub_address)}"')
+
+        # Add display text if present
+        if hyperlink.text_to_display:
+            attrs.append(f'display="{self._escape_xml(hyperlink.text_to_display)}"')
+
+        # Add tooltip if present
+        if hyperlink.screen_tip:
+            attrs.append(f'tooltip="{self._escape_xml(hyperlink.screen_tip)}"')
+
+        return f'        <hyperlink {" ".join(attrs)}/>\n'
+
+    def get_hyperlink_relationships(self, worksheet):
+        """
+        Gets hyperlink relationships for the worksheet.
+
+        Returns a list of relationship entries for external hyperlinks.
+
+        Args:
+            worksheet: The worksheet containing hyperlinks.
+
+        Returns:
+            list: List of (rel_id, target) tuples for external hyperlinks.
+
+        Examples:
+            >>> rels = saver.get_hyperlink_relationships(worksheet)
+            >>> for rel_id, target in rels:
+            ...     print(f"{rel_id}: {target}")
+        """
+        relationships = []
+
+        for hyperlink in worksheet.hyperlinks:
+            if hyperlink.address:  # External hyperlink
+                rel_id = hyperlink._relationship_id
+                target = hyperlink.address
+                relationships.append((rel_id, target))
+
+        return relationships
+
+    def reset_relationship_counter(self):
+        """
+        Resets the relationship ID counter.
+
+        Should be called before processing each worksheet.
+        """
+        self._next_rel_id = 1
+
+    def _escape_xml(self, text):
+        """
+        Escapes special characters for XML.
+
+        Args:
+            text (str): Text to escape.
+
+        Returns:
+            str: XML-escaped text.
+        """
+        if not text:
+            return ""
+        text = str(text)
+        text = text.replace('&', '&amp;')
+        text = text.replace('<', '&lt;')
+        text = text.replace('>', '&gt;')
+        text = text.replace('"', '&quot;')
+        text = text.replace("'", '&apos;')
+        return text
+
+
+class HyperlinkRelationshipWriter:
+    """
+    Writes hyperlink relationships to _rels files.
+
+    Creates or updates xl/worksheets/_rels/sheet{n}.xml.rels with hyperlink relationships.
+    """
+
+    @staticmethod
+    def format_relationships_xml(relationships, existing_rels=None):
+        """
+        Formats relationships as XML.
+
+        Args:
+            relationships (list): List of (rel_id, target) tuples for hyperlinks.
+            existing_rels (list, optional): Existing non-hyperlink relationships to preserve.
+
+        Returns:
+            str: Complete relationships XML content.
+
+        Examples:
+            >>> xml = writer.format_relationships_xml([('rId1', 'https://example.com')])
+        """
+        content = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n'
+        content += '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">\n'
+
+        # Add existing non-hyperlink relationships first
+        if existing_rels:
+            for rel_id, rel_type, target, target_mode in existing_rels:
+                mode_attr = f' TargetMode="{target_mode}"' if target_mode else ''
+                content += f'    <Relationship Id="{rel_id}" Type="{rel_type}" Target="{target}"{mode_attr}/>\n'
+
+        # Add hyperlink relationships
+        for rel_id, target in relationships:
+            escaped_target = HyperlinkRelationshipWriter._escape_xml(target)
+            content += f'    <Relationship Id="{rel_id}" '
+            content += f'Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink" '
+            content += f'Target="{escaped_target}" TargetMode="External"/>\n'
+
+        content += '</Relationships>\n'
+        return content
+
+    @staticmethod
+    def _escape_xml(text):
+        """Escapes special characters for XML."""
+        if not text:
+            return ""
+        text = str(text)
+        text = text.replace('&', '&amp;')
+        text = text.replace('<', '&lt;')
+        text = text.replace('>', '&gt;')
+        text = text.replace('"', '&quot;')
+        text = text.replace("'", '&apos;')
+        return text