Extract Hyperlinks from Word Documents in Python

import zipfile
from pathlib import Path
import xml.etree.ElementTree as ET

def extract_hyperlinks_from_docx(filepath: str) -> list[dict]:
    """
    Extract all hyperlinks from a .docx file.
    Returns a list of dicts with 'text' and 'target' keys.
    """
    hyperlinks = []
    with zipfile.ZipFile(Path(filepath), 'r') as docx_zip:
        # Word stores hyperlinks in relationships files and document.xml
        try:
            relationships_xml = docx_zip.read('word/_rels/document.xml.rels')
        except KeyError:
            return hyperlinks
        
        rels_root = ET.fromstring(relationships_xml)
        ns_rels = {'r': 'http://schemas.openxmlformats.org/package/2006/relationships'}
        
        # Build mapping from relationship IDs to target URLs
        id_to_target = {}
        for rel in rels_root.findall('.//r:Relationship', ns_rels):
            rid = rel.get('Id')
            target = rel.get('Target')
            if rid and target:
                id_to_target[rid] = target
        
        # Parse document.xml for hyperlink elements
        try:
            doc_xml = docx_zip.read('word/document.xml')
        except KeyError:
            return hyperlinks
        
        doc_root = ET.fromstring(doc_xml)
        ns_doc = {
            'w': 'http://schemas.openxmlformats.org/wordprocessingml/2006/main',
            'r': 'http://schemas.openxmlformats.org/officeDocument/2006/relationships'
        }
        
        for hyperlink in doc_root.iter('{http://schemas.openxmlformats.org/wordprocessingml/2006/main}hyperlink'):
            rid = hyperlink.get('{http://schemas.openxmlformats.org/officeDocument/2006/relationships}id')
            target = id_to_target.get(rid, '')
            # Collect all text inside the hyperlink
            text_parts = []
            for run in hyperlink.findall('.//w:t', ns_doc):
                if run.text:
                    text_parts.append(run.text)
            text = ''.join(text_parts)
            if target:
                hyperlinks.append({'text': text, 'target': target})
    
    return hyperlinks

if __name__ == "__main__":
    # Example usage
    import sys
    if len(sys.argv) > 1:
        results = extract_hyperlinks_from_docx(sys.argv[1])
        for link in results:
            print(f"Text: {link['text']!r} -> URL: {link['target']}")
    else:
        print("Please provide a .docx file path as argument")