Add semantic HTML tag style extraction support

Track semantic tags (b, strong, i, em, u, s, del, strike) and create
synthetic style nodes for style_callback. This allows screen readers
and other accessibility tools to detect text styling from semantic tags.

- Add SEMANTIC_STYLES constant mapping tags to CSS properties
- Track semantic tag stack during parsing
- Create mock elements with style attributes for callback
- Handle nested semantic tags correctly
- Add comprehensive test suite (13 tests)

Author: ctoth

html_to_text.py

@@ -6,7 +6,7 @@
 import posixpath
 import re
 import sys
-from typing import Callable, Dict, Optional, Union
+from typing import Callable, Dict, Optional, Union, Any
 
 from urllib.parse import unquote
 
@@ -82,6 +82,17 @@ class HTMLParser(LXMLParser):
     whitespace_re = re.compile(r"\s+")
     _block = ("p", "div", "center", "blockquote")
     heading_levels = {"h1": 1, "h2": 2, "h3": 3, "h4": 4, "h5": 5, "h6": 6}
+    # Semantic HTML tags that imply styling
+    SEMANTIC_STYLES = {
+        'b': {'font-weight': 'bold'},
+        'strong': {'font-weight': 'bold'},
+        'i': {'font-style': 'italic'},
+        'em': {'font-style': 'italic'},
+        'u': {'text-decoration': 'underline'},
+        's': {'text-decoration': 'line-through'},
+        'strike': {'text-decoration': 'line-through'},
+        'del': {'text-decoration': 'line-through'},
+    }
 
     def __init__(
         self,
@@ -111,6 +122,7 @@ def __init__(
         self.last_start = ""
         self.element_stack: list[tuple[_Element, int]] = []  # Track (element, start_pos)
         self.link_start = 0
+        self.semantic_style_stack: list[dict[str, Any]] = []  # Track active semantic styles
 
         # Set up state machine using enum objects directly
         states = list(ContentState)
@@ -350,6 +362,19 @@ def handle_starttag(self, tag: str, attrs: _Attrib) -> None:  # type: ignore[ove
                 attrs=dict(attrs),
             )
             self.table_stack.append(node)
+        # Track semantic tags for style extraction
+        if tag in self.SEMANTIC_STYLES and self.style_callback:
+            start_pos = (
+                self.output.tell()
+                + self.startpos
+                + (len(self.add) if not self.is_starting else 0)
+                + (1 if self.final_space else 0)
+            )
+            self.semantic_style_stack.append({
+                'tag': tag,
+                'start': start_pos,
+                'styles': self.SEMANTIC_STYLES[tag].copy()
+            })
 
     def handle_endtag(self, tag: str, item: _Element) -> None:  # type: ignore[override]
         if "class" in item.attrib and item.attrib["class"] == "pagenum":
@@ -393,6 +418,32 @@ def handle_endtag(self, tag: str, item: _Element) -> None:  # type: ignore[overr
                     end_pos = self.output.tell() + self.startpos
                     self.style_callback(item, start_pos, end_pos)
 
+        # Process semantic tags for style extraction
+        if tag in self.SEMANTIC_STYLES and self.style_callback and self.semantic_style_stack:
+            # Find matching tag on stack (handle nesting - pop most recent matching tag)
+            for i in range(len(self.semantic_style_stack) - 1, -1, -1):
+                if self.semantic_style_stack[i]['tag'] == tag:
+                    style_info = self.semantic_style_stack.pop(i)
+                    end_pos = self.output.tell() + self.startpos
+
+                    # Only create style node if there's actual content
+                    if end_pos > style_info['start']:
+                        # Create a mock element with style attribute for the callback
+                        # Convert our dict format (font_weight) to CSS format (font-weight)
+                        css_properties = []
+                        for prop_key, prop_value in style_info['styles'].items():
+                            css_prop = prop_key.replace('_', '-')
+                            css_properties.append(f"{css_prop}: {prop_value}")
+                        style_str = '; '.join(css_properties)
+
+                        # Create mock element and set style attribute
+                        mock_element = lxml.etree.Element(tag)
+                        mock_element.set('style', style_str)
+
+                        # Call style callback with mock element
+                        self.style_callback(mock_element, style_info['start'], end_pos)
+                    break
+
         self.last_start = tag
 
     def handle_data(self, data: str, start_tag: Optional[str]) -> None:  # type: ignore[override]

tests/test_semantic_tags.py

@@ -0,0 +1,272 @@
+"""Tests for semantic HTML tag style extraction."""
+import pytest
+from html_to_text import html_to_text
+from lxml import etree
+
+
+def test_bold_tag_creates_style():
+    """Test that <b> tag creates font-weight style."""
+    html = '<html><body><p>This is <b>bold</b> text</p></body></html>'
+
+    styles_found = []
+
+    def style_callback(element, start, end):
+        style = element.get('style')
+        styles_found.append({
+            'tag': element.tag,
+            'style': style,
+            'start': start,
+            'end': end
+        })
+
+    text = html_to_text(html, style_callback=style_callback)
+
+    # Should find one style node for <b>
+    assert len(styles_found) == 1
+    assert 'font-weight: bold' in styles_found[0]['style']
+    assert styles_found[0]['tag'] == 'b'
+
+
+def test_italic_tag_creates_style():
+    """Test that <i> tag creates font-style."""
+    html = '<html><body><p>This is <i>italic</i> text</p></body></html>'
+
+    styles_found = []
+
+    def style_callback(element, start, end):
+        style = element.get('style')
+        styles_found.append({
+            'tag': element.tag,
+            'style': style,
+            'start': start,
+            'end': end
+        })
+
+    text = html_to_text(html, style_callback=style_callback)
+
+    assert len(styles_found) == 1
+    assert 'font-style: italic' in styles_found[0]['style']
+
+
+def test_em_tag_creates_style():
+    """Test that <em> tag creates font-style."""
+    html = '<html><body><p><em>Emphasis</em> text</p></body></html>'
+
+    styles_found = []
+
+    def style_callback(element, start, end):
+        styles_found.append({'style': element.get('style')})
+
+    text = html_to_text(html, style_callback=style_callback)
+
+    assert len(styles_found) == 1
+    assert 'font-style: italic' in styles_found[0]['style']
+
+
+def test_strong_tag_creates_style():
+    """Test that <strong> tag creates font-weight."""
+    html = '<html><body><p><strong>Strong</strong> text</p></body></html>'
+
+    styles_found = []
+
+    def style_callback(element, start, end):
+        styles_found.append({'style': element.get('style')})
+
+    text = html_to_text(html, style_callback=style_callback)
+
+    assert len(styles_found) == 1
+    assert 'font-weight: bold' in styles_found[0]['style']
+
+
+def test_underline_tag_creates_style():
+    """Test that <u> tag creates text-decoration."""
+    html = '<html><body><p><u>Underlined</u> text</p></body></html>'
+
+    styles_found = []
+
+    def style_callback(element, start, end):
+        styles_found.append({'style': element.get('style')})
+
+    text = html_to_text(html, style_callback=style_callback)
+
+    assert len(styles_found) == 1
+    assert 'text-decoration: underline' in styles_found[0]['style']
+
+
+def test_nested_semantic_tags():
+    """Test that nested semantic tags create multiple overlapping styles."""
+    html = '<html><body><p>Text with <b>bold and <i>bold italic</i></b></p></body></html>'
+
+    styles_found = []
+
+    def style_callback(element, start, end):
+        styles_found.append({
+            'tag': element.tag,
+            'style': element.get('style'),
+            'start': start,
+            'end': end,
+            'text_range': (start, end)
+        })
+
+    text = html_to_text(html, style_callback=style_callback)
+
+    # Should have 2 style nodes: one for <b>, one for <i>
+    assert len(styles_found) == 2
+
+    # Find bold and italic styles
+    bold_styles = [s for s in styles_found if 'font-weight: bold' in s['style']]
+    italic_styles = [s for s in styles_found if 'font-style: italic' in s['style']]
+
+    assert len(bold_styles) == 1
+    assert len(italic_styles) == 1
+
+    # The italic range should be contained within the bold range
+    bold_start, bold_end = bold_styles[0]['start'], bold_styles[0]['end']
+    italic_start, italic_end = italic_styles[0]['start'], italic_styles[0]['end']
+
+    assert italic_start >= bold_start
+    assert italic_end <= bold_end
+
+
+def test_multiple_separate_semantic_tags():
+    """Test multiple separate semantic tags in same paragraph."""
+    html = '<html><body><p><b>Bold</b> and <i>italic</i> and <u>underline</u></p></body></html>'
+
+    styles_found = []
+
+    def style_callback(element, start, end):
+        styles_found.append({
+            'tag': element.tag,
+            'style': element.get('style')
+        })
+
+    text = html_to_text(html, style_callback=style_callback)
+
+    # Should have 3 separate style nodes
+    assert len(styles_found) == 3
+
+    tags = [s['tag'] for s in styles_found]
+    assert 'b' in tags
+    assert 'i' in tags
+    assert 'u' in tags
+
+
+def test_semantic_tag_with_existing_style_attribute():
+    """Test that semantic tags work alongside existing style attributes."""
+    html = '<html><body><p><b style="color: red">Bold red</b></p></body></html>'
+
+    styles_found = []
+
+    def style_callback(element, start, end):
+        styles_found.append({
+            'tag': element.tag,
+            'style': element.get('style')
+        })
+
+    text = html_to_text(html, style_callback=style_callback)
+
+    # Should have TWO style callbacks:
+    # 1. One from the original <b style="color: red"> (line 388-394)
+    # 2. One from our semantic tag tracking (new code)
+    assert len(styles_found) == 2
+
+    # One should have color: red, one should have font-weight: bold
+    styles_str = ' '.join([s['style'] for s in styles_found])
+    assert 'color: red' in styles_str
+    assert 'font-weight: bold' in styles_str
+
+
+def test_empty_semantic_tag():
+    """Test that empty semantic tags don't create style nodes."""
+    html = '<html><body><p><b></b>text</p></body></html>'
+
+    styles_found = []
+
+    def style_callback(element, start, end):
+        styles_found.append({'tag': element.tag})
+
+    text = html_to_text(html, style_callback=style_callback)
+
+    # Empty tag should not create a style node (start == end check)
+    assert len(styles_found) == 0
+
+
+def test_semantic_tags_positions():
+    """Test that style positions match text positions correctly."""
+    html = '<html><body><p>Start <b>bold</b> end</p></body></html>'
+
+    styles_found = []
+
+    def style_callback(element, start, end):
+        styles_found.append({
+            'start': start,
+            'end': end
+        })
+
+    text = html_to_text(html, style_callback=style_callback)
+
+    # Text should be "Start bold end"
+    assert text.strip() == "Start bold end"
+
+    # The style should cover "bold" which starts at position 6 (after "Start ")
+    assert len(styles_found) == 1
+    styled_text = text[styles_found[0]['start']:styles_found[0]['end']]
+    assert styled_text == "bold"
+
+
+def test_no_style_callback_no_processing():
+    """Test that semantic tags don't cause errors when no callback provided."""
+    html = '<html><body><p><b>Bold</b> text</p></body></html>'
+
+    # Should not raise any errors
+    text = html_to_text(html)
+    assert text.strip() == "Bold text"
+
+
+def test_strikethrough_tags():
+    """Test strikethrough tags (<s>, <strike>, <del>)."""
+    html = '<html><body><p><s>Strike</s> <del>Deleted</del></p></body></html>'
+
+    styles_found = []
+
+    def style_callback(element, start, end):
+        styles_found.append({
+            'tag': element.tag,
+            'style': element.get('style')
+        })
+
+    text = html_to_text(html, style_callback=style_callback)
+
+    assert len(styles_found) == 2
+    for style_info in styles_found:
+        assert 'text-decoration: line-through' in style_info['style']
+
+
+def test_semantic_tags_with_callback():
+    """Integration test: semantic tags with style callback."""
+    html = '''
+    <html>
+    <body>
+        <h1>Test</h1>
+        <p>This is a <b>test</b></p>
+        <p><em>Emphasis</em> <i>italic</i></p>
+        <p><span style="font-weight: bold">Bold using styles</span></p>
+    </body>
+    </html>
+    '''
+
+    nodes = []
+
+    def callback(element, start, end):
+        style = element.get('style', '')
+        if 'bold' in style or 'italic' in style:
+            nodes.append({
+                'start': start,
+                'end': end,
+                'style': style
+            })
+
+    text = html_to_text(html, style_callback=callback)
+
+    # Should find at least 4 style nodes: <b>, <em>, <i>, and <span>
+    assert len(nodes) >= 4