html2pic 0.1.1__py3-none-any.whl

html2pic/__init__.py

@@ -0,0 +1,35 @@
+"""
+html2pic: Convert HTML + CSS to images using PicTex
+
+A Python library that translates a subset of HTML and CSS to beautiful images
+without requiring a browser engine. Built on top of PicTex for high-quality
+rendering with flexbox-like layout support.
+
+Example:
+    ```python
+    from html2pic import Html2Pic
+
+    html = '<div class="card"><h1>Hello World</h1></div>'
+    css = '.card { padding: 20px; background: blue; color: white; }'
+    
+    renderer = Html2Pic(html, css)
+    image = renderer.render()
+    image.save("output.png")
+    ```
+"""
+
+from .core import Html2Pic
+from .exceptions import Html2PicError, ParseError, RenderError
+from .warnings_system import (
+    get_warning_collector, reset_warnings, WarningCategory,
+    Html2PicWarning, UnsupportedFeatureWarning, StyleApplicationWarning,
+    TranslationWarning, ParsingWarning
+)
+
+__version__ = "0.1.1"
+__all__ = [
+    "Html2Pic", "Html2PicError", "ParseError", "RenderError",
+    "get_warning_collector", "reset_warnings", "WarningCategory",
+    "Html2PicWarning", "UnsupportedFeatureWarning", "StyleApplicationWarning", 
+    "TranslationWarning", "ParsingWarning"
+]

html2pic/core.py

@@ -0,0 +1,185 @@
+"""
+Core Html2Pic class and main API
+"""
+
+from typing import Dict, Any
+import pictex
+from .html_parser import HtmlParser
+from .css_parser import CssParser
+from .style_engine import StyleEngine
+from .translator import PicTexTranslator
+from .exceptions import ParseError, RenderError
+from .warnings_system import get_warning_collector, reset_warnings
+
+class Html2Pic:
+    """
+    Main class for converting HTML + CSS to images using PicTex.
+    
+    This class orchestrates the entire conversion process:
+    1. Parse HTML into a DOM tree
+    2. Parse CSS into style rules
+    3. Apply styles to DOM nodes (cascading, specificity, inheritance)
+    4. Translate styled DOM tree to PicTex builders
+    5. Render using PicTex
+    
+    Example:
+        ```python
+        html = '<div class="card"><h1>Hello</h1><p>World</p></div>'
+        css = '''
+            .card { 
+                display: flex; 
+                flex-direction: column; 
+                padding: 20px; 
+                background: #f0f0f0; 
+            }
+            h1 { font-size: 24px; color: blue; }
+            p { color: gray; }
+        '''
+        
+        renderer = Html2Pic(html, css)
+        image = renderer.render()
+        image.save("output.png")
+        ```
+    """
+    
+    def __init__(self, html: str, css: str = "", base_font_size: int = 16):
+        """
+        Initialize the HTML to image converter.
+        
+        Args:
+            html: HTML content as a string
+            css: CSS content as a string  
+            base_font_size: Base font size for relative units (default: 16px)
+        """
+        self.html = html
+        self.css = css
+        self.base_font_size = base_font_size
+        
+        # Initialize parsers and engines
+        self.html_parser = HtmlParser()
+        self.css_parser = CssParser()
+        self.style_engine = StyleEngine(base_font_size=base_font_size)
+        self.translator = PicTexTranslator()
+        self.warnings = get_warning_collector()
+        
+        # Reset warnings for this new instance
+        reset_warnings()
+        
+        # Parsed content (lazy loaded)
+        self._dom_tree = None
+        self._style_rules = None
+        self._styled_tree = None
+    
+    @property
+    def dom_tree(self):
+        """Lazily parse and return the DOM tree"""
+        if self._dom_tree is None:
+            try:
+                self._dom_tree = self.html_parser.parse(self.html)
+            except Exception as e:
+                raise ParseError(f"Failed to parse HTML: {e}") from e
+        return self._dom_tree
+    
+    @property  
+    def style_rules(self):
+        """Lazily parse and return the CSS style rules"""
+        if self._style_rules is None:
+            try:
+                self._style_rules = self.css_parser.parse(self.css)
+            except Exception as e:
+                raise ParseError(f"Failed to parse CSS: {e}") from e
+        return self._style_rules
+    
+    @property
+    def styled_tree(self):
+        """Lazily compute and return the styled DOM tree"""
+        if self._styled_tree is None:
+            try:
+                self._styled_tree = self.style_engine.apply_styles(
+                    self.dom_tree, 
+                    self.style_rules
+                )
+            except Exception as e:
+                raise RenderError(f"Failed to apply styles: {e}") from e
+        return self._styled_tree
+    
+    def render(self, crop_mode: pictex.CropMode = pictex.CropMode.SMART) -> pictex.BitmapImage:
+        """
+        Render the HTML + CSS to a bitmap image.
+        
+        Args:
+            crop_mode: How to crop the final image (SMART, CONTENT_BOX, or NONE)
+            
+        Returns:
+            A PicTex BitmapImage object
+            
+        Raises:
+            Html2PicError: If any step in the conversion process fails
+        """
+        try:
+            # Translate styled DOM tree to PicTex builders
+            canvas, root_element = self.translator.translate(self.styled_tree)
+            
+            # Render using PicTex
+            if root_element is None:
+                # Empty document, just render the canvas
+                return canvas.render("", crop_mode=crop_mode)
+            else:
+                return canvas.render(root_element, crop_mode=crop_mode)
+                
+        except Exception as e:
+            raise RenderError(f"Failed to render image: {e}") from e
+    
+    def render_as_svg(self, embed_font: bool = True) -> pictex.VectorImage:
+        """
+        Render the HTML + CSS to an SVG vector image.
+        
+        Args:
+            embed_font: Whether to embed fonts in the SVG (default: True)
+            
+        Returns:
+            A PicTex VectorImage object
+            
+        Raises:
+            Html2PicError: If any step in the conversion process fails
+        """
+        try:
+            # Translate styled DOM tree to PicTex builders  
+            canvas, root_element = self.translator.translate(self.styled_tree)
+            
+            # Render as SVG using PicTex
+            if root_element is None:
+                return canvas.render_as_svg("", embed_font=embed_font)
+            else:
+                return canvas.render_as_svg(root_element, embed_font=embed_font)
+                
+        except Exception as e:
+            raise RenderError(f"Failed to render SVG: {e}") from e
+    
+    def debug_info(self) -> Dict[str, Any]:
+        """
+        Get debugging information about the conversion process.
+        
+        Returns:
+            Dictionary containing DOM tree, style rules, styled tree, and warnings info
+        """
+        return {
+            "dom_tree": self.dom_tree,
+            "style_rules": self.style_rules, 
+            "styled_tree": self.styled_tree,
+            "base_font_size": self.base_font_size,
+            "warnings": self.get_warnings(),
+            "warnings_summary": self.get_warnings_summary()
+        }
+    
+    def get_warnings(self) -> list:
+        """Get all warnings from the conversion process"""
+        return self.warnings.get_warnings()
+    
+    def get_warnings_summary(self) -> dict:
+        """Get a summary of warnings from the conversion process"""
+        return self.warnings.get_summary()
+    
+    def print_warnings(self):
+        """Print a formatted summary of all warnings"""
+        self.warnings.print_summary()

html2pic/css_parser.py

@@ -0,0 +1,290 @@
+"""
+CSS parser using tinycss2 to extract style rules
+"""
+
+from typing import List, Dict
+import tinycss2
+from .models import CSSRule, ParsedSelector, SelectorType
+from .exceptions import ParseError
+from .warnings_system import get_warning_collector, WarningCategory
+
+class CssParser:
+    """
+    Parses CSS content into structured rules for the style engine.
+    
+    Uses tinycss2 for robust CSS parsing and extracts:
+    - Selectors (class, id, tag)
+    - Declarations (property: value pairs)  
+    - Specificity calculations for cascade resolution
+    """
+    
+    def __init__(self):
+        self.warnings = get_warning_collector()
+    
+    def parse(self, css_content: str) -> List[CSSRule]:
+        """
+        Parse CSS string into a list of CSS rules.
+        
+        Args:
+            css_content: CSS content as string
+            
+        Returns:
+            List of CSSRule objects
+            
+        Raises:
+            ParseError: If CSS parsing fails
+        """
+        if not css_content.strip():
+            return []
+            
+        try:
+            # Parse CSS with tinycss2
+            stylesheet = tinycss2.parse_stylesheet(css_content)
+            
+            rules = []
+            for rule in stylesheet:
+                if hasattr(rule, 'prelude') and hasattr(rule, 'content'):
+                    # This is a qualified rule (selector + declarations)
+                    css_rules = self._process_rule(rule)
+                    rules.extend(css_rules)
+            
+            return rules
+            
+        except Exception as e:
+            raise ParseError(f"Failed to parse CSS: {e}") from e
+    
+    def _process_rule(self, rule) -> List[CSSRule]:
+        """
+        Process a tinycss2 QualifiedRule into our CSSRule objects.
+        
+        Args:
+            rule: tinycss2 QualifiedRule object
+            
+        Returns:
+            List of CSSRule objects (one per selector if multiple selectors)
+        """
+        # Extract selectors from the rule prelude
+        selectors = self._extract_selectors(rule.prelude)
+        
+        # Extract declarations from the rule content
+        declarations = self._extract_declarations(rule.content)
+        
+        # Create a CSSRule for each selector
+        css_rules = []
+        for selector in selectors:
+            specificity = self._calculate_specificity(selector)
+            css_rules.append(CSSRule(
+                selector=selector.strip(),
+                declarations=declarations,
+                specificity=specificity
+            ))
+        
+        return css_rules
+    
+    def _extract_selectors(self, prelude) -> List[str]:
+        """
+        Extract selector strings from rule prelude.
+        
+        Handles multiple selectors separated by commas.
+        For now, we only support simple selectors.
+        """
+        selectors = []
+        current_selector = []
+        
+        for token in prelude:
+            if token.type == 'literal' and token.value == ',':
+                # End of current selector, start next one
+                if current_selector:
+                    selector_str = ''.join(t.serialize() for t in current_selector).strip()
+                    if selector_str:
+                        selectors.append(selector_str)
+                    current_selector = []
+            else:
+                current_selector.append(token)
+        
+        # Add the last selector
+        if current_selector:
+            selector_str = ''.join(t.serialize() for t in current_selector).strip()
+            if selector_str:
+                selectors.append(selector_str)
+        
+        return selectors if selectors else ['*']  # Fallback to universal selector
+    
+    def _extract_declarations(self, content) -> Dict[str, str]:
+        """
+        Extract property: value declarations from rule content.
+        
+        Args:
+            content: tinycss2 rule content tokens
+            
+        Returns:
+            Dictionary mapping property names to values
+        """
+        declarations = {}
+        
+        # Parse declarations from the content
+        declaration_list = tinycss2.parse_declaration_list(content)
+        
+        for item in declaration_list:
+            if hasattr(item, 'name') and hasattr(item, 'value'):
+                # This is a Declaration
+                property_name = item.name.lower()
+                property_value = ''.join(token.serialize() for token in item.value).strip()
+                
+                # Check for unsupported properties
+                self._check_unsupported_property(property_name, property_value)
+                
+                # Handle shorthand properties
+                if property_name == 'padding':
+                    padding_values = self._parse_shorthand_values(property_value)
+                    declarations.update(self._expand_padding(padding_values))
+                elif property_name == 'margin':
+                    margin_values = self._parse_shorthand_values(property_value)
+                    declarations.update(self._expand_margin(margin_values))
+                elif property_name == 'border':
+                    border_declarations = self._parse_border_shorthand(property_value)
+                    declarations.update(border_declarations)
+                else:
+                    declarations[property_name] = property_value
+            elif hasattr(item, 'type') and item.type == 'error':
+                # CSS parsing error
+                self.warnings.warn(
+                    f"CSS parsing error in declaration: {getattr(item, 'message', 'unknown error')}",
+                    WarningCategory.CSS_PARSING,
+                    {'error_type': 'declaration_error'}
+                )
+        
+        return declarations
+    
+    def _parse_shorthand_values(self, value: str) -> List[str]:
+        """Parse shorthand values like '10px 20px' into individual values."""
+        values = value.split()
+        
+        if len(values) == 1:
+            # all sides same
+            return [values[0]] * 4
+        elif len(values) == 2:
+            # vertical, horizontal
+            return [values[0], values[1], values[0], values[1]]
+        elif len(values) == 3:
+            # top, horizontal, bottom
+            return [values[0], values[1], values[2], values[1]]
+        elif len(values) >= 4:
+            # top, right, bottom, left
+            return values[:4]
+        else:
+            return ['0px'] * 4
+    
+    def _expand_padding(self, values: List[str]) -> Dict[str, str]:
+        """Expand padding shorthand into individual properties."""
+        return {
+            'padding-top': values[0],
+            'padding-right': values[1], 
+            'padding-bottom': values[2],
+            'padding-left': values[3]
+        }
+    
+    def _expand_margin(self, values: List[str]) -> Dict[str, str]:
+        """Expand margin shorthand into individual properties."""
+        return {
+            'margin-top': values[0],
+            'margin-right': values[1],
+            'margin-bottom': values[2], 
+            'margin-left': values[3]
+        }
+    
+    def _parse_border_shorthand(self, value: str) -> Dict[str, str]:
+        """Parse border shorthand like '1px solid black'."""
+        parts = value.split()
+        declarations = {}
+        
+        for part in parts:
+            part = part.strip()
+            if not part:
+                continue
+                
+            # Check if it's a width (ends with px, em, etc.)
+            if any(part.endswith(unit) for unit in ['px', 'em', 'rem', '%']):
+                declarations['border-width'] = part
+            # Check if it's a style
+            elif part in ['solid', 'dashed', 'dotted', 'none']:
+                declarations['border-style'] = part
+            # Assume it's a color
+            else:
+                declarations['border-color'] = part
+        
+        return declarations
+    
+    def _calculate_specificity(self, selector: str) -> int:
+        """
+        Calculate CSS specificity for a selector.
+        
+        Simplified specificity calculation:
+        - ID: 100 points
+        - Class: 10 points  
+        - Tag: 1 point
+        - Universal (*): 0 points
+        
+        Args:
+            selector: CSS selector string
+            
+        Returns:
+            Specificity score as integer
+        """
+        try:
+            parsed = ParsedSelector.parse(selector)
+            
+            if parsed.selector_type == SelectorType.ID:
+                return 100
+            elif parsed.selector_type == SelectorType.CLASS:
+                return 10
+            elif parsed.selector_type == SelectorType.TAG:
+                return 1
+            else:  # UNIVERSAL
+                return 0
+                
+        except Exception:
+            # Fallback for complex selectors we don't support yet
+            return 1
+    
+    def _check_unsupported_property(self, property_name: str, property_value: str):
+        """Check if a CSS property is unsupported and warn if so"""
+        
+        # Properties we fully support
+        supported_properties = {
+            # Layout
+            'display', 'flex-direction', 'justify-content', 'align-items', 'gap',
+            # Box model
+            'width', 'height', 'padding', 'padding-top', 'padding-right', 'padding-bottom', 'padding-left',
+            'margin', 'margin-top', 'margin-right', 'margin-bottom', 'margin-left',
+            'border', 'border-width', 'border-style', 'border-color', 'border-radius',
+            # Visual
+            'background-color', 'background-image', 'background-size', 'box-shadow', 'text-shadow',
+            # Typography
+            'color', 'font-family', 'font-size', 'font-weight', 'font-style',
+            'text-align', 'line-height', 'text-decoration', 'text-wrap',
+            # Positioning (absolute only)
+            'position', 'left', 'top'
+        }
+        
+        # Properties we partially support or have limitations
+        partially_supported = {
+            'background': 'Use background-color or background-image instead',
+            'font': 'Use individual font properties instead',
+            'border-radius': 'Percentage values supported, individual corners not yet',
+            'right': 'Only left/top positioning supported with position absolute',
+            'bottom': 'Only left/top positioning supported with position absolute',
+        }
+        
+        if property_name not in supported_properties and property_name not in partially_supported:
+            self.warnings.warn_unsupported_css_property(
+                property_name, 
+                property_value,
+                f"Property not supported in html2pic"
+            )
+        elif property_name in partially_supported:
+            self.warnings.warn(
+                f"CSS property '{property_name}' has limited support: {partially_supported[property_name]}",
+                WarningCategory.CSS_PARSING,
+                {'property': property_name, 'value': property_value, 'limitation': partially_supported[property_name]}
+            )

html2pic/exceptions.py

@@ -0,0 +1,19 @@
+"""
+Exception classes for html2pic
+"""
+
+class Html2PicError(Exception):
+    """Base exception for all html2pic errors"""
+    pass
+
+class ParseError(Html2PicError):
+    """Raised when HTML or CSS parsing fails"""
+    pass
+
+class RenderError(Html2PicError):
+    """Raised when rendering to PicTex fails"""
+    pass
+
+class UnsupportedFeatureError(Html2PicError):
+    """Raised when an unsupported HTML/CSS feature is encountered"""
+    pass

html2pic/html_parser.py

@@ -0,0 +1,167 @@
+"""
+HTML parser using BeautifulSoup to create DOM tree
+"""
+
+from typing import Optional
+from bs4 import BeautifulSoup, Tag, NavigableString, Comment
+from .models import DOMNode, NodeType
+from .exceptions import ParseError
+from .warnings_system import get_warning_collector, WarningCategory
+
+class HtmlParser:
+    """
+    Parses HTML content into our internal DOM tree representation.
+    
+    Uses BeautifulSoup under the hood for robust HTML parsing,
+    then converts to our own DOMNode structure for easier processing.
+    """
+    
+    def __init__(self):
+        self.parser = "html.parser"  # Use Python's built-in parser
+        self.warnings = get_warning_collector()
+    
+    def parse(self, html_content: str) -> DOMNode:
+        """
+        Parse HTML string into a DOM tree.
+        
+        Args:
+            html_content: HTML content as string
+            
+        Returns:
+            Root DOMNode representing the document
+            
+        Raises:
+            ParseError: If HTML parsing fails
+        """
+        try:
+            # Parse HTML with BeautifulSoup
+            soup = BeautifulSoup(html_content, self.parser)
+            
+            # Convert BeautifulSoup tree to our DOM tree
+            # We create a virtual root node to hold all top-level elements
+            root = DOMNode(
+                node_type=NodeType.ELEMENT,
+                tag="__root__",  # Special tag for root node
+                attributes={},
+                text_content="",
+                children=[],
+                parent=None
+            )
+            
+            # Process all direct children of the parsed document
+            for element in soup.contents:
+                if isinstance(element, Tag):
+                    child_node = self._convert_element(element)
+                    if child_node:
+                        child_node.parent = root
+                        root.children.append(child_node)
+                elif isinstance(element, NavigableString) and not isinstance(element, Comment):
+                    # Handle top-level text content
+                    text_content = str(element).strip()
+                    if text_content:
+                        text_node = DOMNode(
+                            node_type=NodeType.TEXT,
+                            text_content=text_content,
+                            parent=root
+                        )
+                        root.children.append(text_node)
+            
+            return root
+            
+        except Exception as e:
+            raise ParseError(f"Failed to parse HTML: {e}") from e
+    
+    def _convert_element(self, bs_element: Tag) -> Optional[DOMNode]:
+        """
+        Convert a BeautifulSoup Tag to our DOMNode.
+        
+        Args:
+            bs_element: BeautifulSoup Tag element
+            
+        Returns:
+            DOMNode or None if element should be skipped
+        """
+        # Skip script, style, and other non-visual elements
+        if bs_element.name in ['script', 'style', 'meta', 'link', 'title', 'head']:
+            self.warnings.warn(
+                f"Skipping non-visual element '<{bs_element.name}>'",
+                WarningCategory.HTML_PARSING,
+                {'tag': bs_element.name, 'reason': 'non-visual element'}
+            )
+            return None
+        
+        # Check if element is recognized
+        supported_tags = {
+            'div', 'span', 'p', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 
+            'section', 'article', 'header', 'footer', 'main', 'nav', 'aside',
+            'img', 'br', 'hr', 'strong', 'em', 'b', 'i', 'u', 's',
+            'ul', 'ol', 'li', 'a'
+        }
+        
+        # Warn about potentially unsupported elements
+        unsupported_tags = {
+            'table', 'tr', 'td', 'th', 'thead', 'tbody', 'tfoot',
+            'form', 'input', 'button', 'select', 'textarea', 'label',
+            'video', 'audio', 'canvas', 'svg', 'iframe', 'embed', 'object'
+        }
+        
+        if bs_element.name not in supported_tags:
+            if bs_element.name in unsupported_tags:
+                self.warnings.warn_unsupported_html_tag(
+                    bs_element.name, 
+                    f"May not render correctly - consider using div with appropriate styling"
+                )
+            else:
+                # Completely unrecognized element
+                self.warnings.warn_unsupported_html_tag(
+                    bs_element.name,
+                    f"Unrecognized HTML element - will be treated as a div container"
+                )
+        
+        # Create element node
+        node = DOMNode(
+            node_type=NodeType.ELEMENT,
+            tag=bs_element.name,
+            attributes=dict(bs_element.attrs) if bs_element.attrs else {},
+            text_content="",
+            children=[],
+            parent=None
+        )
+        
+        # Process children
+        for child in bs_element.contents:
+            if isinstance(child, Tag):
+                child_node = self._convert_element(child)
+                if child_node:
+                    child_node.parent = node
+                    node.children.append(child_node)
+                    
+            elif isinstance(child, NavigableString) and not isinstance(child, Comment):
+                # Handle text content
+                text_content = str(child).strip()
+                if text_content:
+                    text_node = DOMNode(
+                        node_type=NodeType.TEXT,
+                        text_content=text_content,
+                        parent=node
+                    )
+                    node.children.append(text_node)
+        
+        return node
+    
+    def _should_skip_element(self, tag_name: str) -> bool:
+        """
+        Determine if an HTML element should be skipped during parsing.
+        
+        Args:
+            tag_name: HTML tag name
+            
+        Returns:
+            True if element should be skipped
+        """
+        # Elements that don't contribute to visual layout
+        skip_tags = {
+            'script', 'style', 'meta', 'link', 'title', 'head',
+            'base', 'noscript', 'template'
+        }
+        return tag_name.lower() in skip_tags